integration.opa-notification-bridge
Bridge implementing the organization-planning CommunicationSendAdapterPort + JobsScheduleAdapterPort over injected email (EmailOutboundProvider), SMS (SmsProvider), and durable job-queue (JobQueue) transports. Feature-flag gated, fail-closed, no secrets in code.
@lssm-tech/integration.opa-notification-bridgebun add @lssm-tech/integration.opa-notification-bridgeManifest declarations describe the current workspace; they do not verify registry publication or runtime execution.
Package guide
Binds the organization-planning communication + jobs adapter ports to injected notification transports — without reimplementing any provider SDK:
CommunicationSendAdapterPort(sendConfirmation/sendReminder/sendFollowUp) → an injectedEmailOutboundProvider(gmail/postmark/resend) for email, or an injectedSmsProvider(Twilio, …) for SMS.JobsScheduleAdapterPort(scheduleReminder) → an injected durableJobQueue(Scaleway SQS / GCP Cloud Tasks / Pub-Sub) — reminders are enqueued so delivery survives restarts; confirmations/follow-ups send immediately.
Posture: feature-flag gated + fail-closed
- Email and SMS sends are gated behind
OPA_NOTIFY_EMAIL/OPA_NOTIFY_SMS(OPA_NOTIFY_FLAGS), both defaulting safe (off). - An unconfigured channel — flag off, transport absent, missing recipient, or no resolved target — yields a no-op receipt (
success: true,outputRefs: ['opa-notify-noop:<reason>']). It never throws. - No secrets in code. Every transport is injected via the constructor.
Usage
import { createOpaNotificationBridge, OPA_NOTIFY_FLAGS } from '@lssm-tech/integration.opa-notification-bridge';
const { communication, jobs } = createOpaNotificationBridge({
email, // e.g. GmailOutboundProvider / PostmarkEmailProvider
sms, // e.g. TwilioSmsProvider
jobs: jobQueue, // e.g. ScalewaySqsQueue / GcpCloudTasksQueue / MemoryJobQueue
defaultFromEmail: 'noreply@yourdomain.example',
flags: { [OPA_NOTIFY_FLAGS.EMAIL]: true, [OPA_NOTIFY_FLAGS.SMS]: false },
resolveNotification: (handoff, kind) => ({
channel: 'email',
email: lookupRecipientEmail(handoff),
body: renderBody(handoff, kind),
}),
});
// worker-1 threads `communication` + `jobs` into buildOpaOps.The host owns resolveNotification (recipient/PII derivation) — the bridge never reads recipient data from the handoff itself.
Booking delivery uses enqueueBookingNotification. Its durable dedupe key is derived from tenant, booking, lifecycle version, kind, and recipient digest. Only manage access, approval, and reminder kinds are accepted: Google sendUpdates=all owns generic auto-confirm create/change/cancel delivery. Outbox payloads contain a protected delivery ref and recipient digest, never a recipient address or manage bearer; the delivery worker dereferences protected material only when sending.
Delivery adapters receive the tenant reference while resolving protected material and receive the same tenant reference plus the durable dedupe key when sending. Hosts must forward that key to the protected sender as its idempotency key. The Postgres host atomically claims canonical outbox rows with an expiring owner lease, then settles or retries only with the same tenant and owner fence. Delivery claims are likewise expiring and token-fenced by tenant and dedupe key: crashed claims are reclaimable, while stale workers cannot complete or release a successor's claim. Immediately before provider dispatch, the host persists a dispatch_ambiguous marker. A lost provider acknowledgement therefore stays fail-closed instead of becoming retryable; an operator must reconcile the exact tenant/dedupe-bound provider receipt before completion resumes without another send.
Relationships
Arrows point from a package to its direct dependency. Counts are derived from captured workspace manifests.
3 declarations
@lssm-tech/lib.contracts-integrationsworkspace:^
Read the package manual ↗@lssm-tech/lib.jobsworkspace:^
Read the package manual ↗@lssm-tech/lib.organization-planning-specworkspace:^
Read the package manual ↗
Declared capabilities
Bridge implementing the organization-planning CommunicationSendAdapterPort + JobsScheduleAdapterPort over injected email (EmailOutboundProvider), SMS (SmsProvider), and durable job-queue (JobQueue) transports. Feature-flag gated, fail-closed, no secrets in code.
Scripts
buildcontractspec-bun-build buildbuild:bundlecontractspec-bun-build transpilebuild:typescontractspec-bun-build typesdevcontractspec-bun-build devcleanrimraf dist .turbolint:checknode ../../../scripts/biome.cjs check .lint:fixnode ../../../scripts/biome.cjs check --write .testbun testprebuildcontractspec-bun-build prebuildtypechecktsgo --noEmit