integration.provider-email
Email provider implementations for ContractSpec.
@lssm-tech/integration.provider-emailbun add @lssm-tech/integration.provider-emailManifest declarations describe the current workspace; they do not verify registry publication or runtime execution.
Package guide
Website: https://contractspec.io
Email provider implementations for ContractSpec.
Usage
Import the root entrypoint for the domain surface, or import a concrete implementation from the ./impls/* subpaths.
Included Providers
GmailInboundProviderfor thread and message sync.listThreadsPagekeeps the provider continuation; message metadata recordstimestampSource(provider_internal_date,date_headerorobserved_at_fetch) instead of presenting a fetch time as an observed provider time, and attachments are referenced by stable MIME part id (the Gmail attachment handle is volatile).GmailMailboxReader(./impls/gmail-mailbox-reader) is the read port for durable synchronization: mailbox profile and history baseline, keyed message paging, history changes (added, deleted, label changes) with a typedhistory_expiredfailure, and verified send-as identities. A message payload that cannot be transformed raises non-retryablepayload_invalid. Its additivegetMessageMetadatamethod is compatible withgmail.metadata: only From/Subject/Date headers, provider receipt time, IDs and labels are requested and returned. Message snippets, bodies and attachment data are never included; deleted messages returnnulland a missing provider time stays absent.createDeferredGmailOAuth2Client(./impls/gmail-auth) loads the mailbox credential from custody on first use and on every refresh (a reconnect is picked up, no refresh token in configuration); a missing credential isreauthorization_required.GmailAttachmentOriginalReader(./impls/gmail-attachments) acquires original attachment bytes by message + part identity with size bounds and a SHA-256 digest, producing aGmailAttachmentOriginalHandOffrecord (./impls/gmail-evidence) for the document-custody port. Equal bytes from two mailboxes share a digest but keep separate account-bound source keys.GmailOutboundProviderfor Gmail-based outbound delivery. Messages are built by./impls/gmail-mime(RFC 2047 Unicode headers, Bcc, base64 parts); caller headers cannot set sender or envelope fields. MetadatagmailThreadId,gmailInReplyToandgmailReferencesproduce a correctly threaded reply. A response without a message id raisesresponse_unverified.GmailMailboxOperations(./impls/gmail-mailbox) for native drafts (create/update/get/send), label changes, archive (removesINBOXonly) and read state. These are provider drivers; agent-initiated calls must arrive through Runtime Node authority.parseGmailPushNotificationandGmailWatchOperations(./impls/gmail-push) treat Gmail push as a wake signal only; changes are fetched through history.MicrosoftGraphOutboundProviderfor delegated Microsoft user mail. Graph202 Acceptedis represented as queued acceptance without a provider message id; ambiguous responses retain only sanitized diagnostic correlations.MicrosoftGraphInboundProviderfor folder-scoped message delta sync. Complete opaque next/delta links are mailbox-bound, and deletion tombstones remain explicit reconciliation inputs.MicrosoftGraphMessageSubscriptionManagerfor bounded create, renewal, and deletion of Outlook message subscriptions. Notification batches require exact subscription/client-state binding; missed lifecycle events require delta sync.PostmarkEmailProviderfor transactional email deliveryResendEmailProviderfor outbound delivery with provider-native retry idempotency through a boundedEmailOutboundMessage.idempotencyKeyMailerSendEmailProviderfor outbound text, HTML, template, scheduled, bulk, personalized, tagged, header, CC/BCC/reply-to, and inline/regular attachment delivery through the official MailerSend REST APIMailerSendInboundProviderfor official inbound-route list/get/create/update/ delete operations with email and webhook forwardsingestMailerSendWebhookandauthenticateMailerSendWebhookfor raw-body HMAC-SHA256 verification, delivery receipts, inbound MIME projections, test callbacks, replay suppression, and non-regressing delivery statusingestResendWebhookfor raw-body signature verification andsvix-idreplay deduplication plus non-regressing provider-message status projection through a caller-owned atomic event store. Results expose only a deterministicprovider-message:sha256:*reference; raw provider message ids remain transient.SqlResendWebhookEventStore(./impls/resend-webhook-sql-store) is the durable SQL implementation of that store for a pg-compatible pool (nopgdependency): one transaction inserts into the host's replay ledger, rejects an event id reused for different content, advances the per-message status only for a higherRESEND_DELIVERY_STATUS_RANKSrank or a later equal-rank event, and runs an optionalonStatusAppliedhost hook in the same transaction. Hosts own the two tables (validated plain identifiers) and their migrations; every failure surfaces as retryableResendWebhookStoreUnavailableError.
MailerSend
Use the focused exports so browser bundles never pull server-only provider code:
import { MailerSendEmailProvider } from
"@lssm-tech/integration.provider-email/impls/mailersend-email";
import { MailerSendInboundProvider } from
"@lssm-tech/integration.provider-email/impls/mailersend-inbound";
import { ingestMailerSendWebhook } from
"@lssm-tech/integration.provider-email/impls/mailersend-webhook";The caller supplies apiKey and may inject baseUrl and fetch. Credentials must remain in a server-side vault; provider errors expose only status and a normalized code. Webhooks must pass the exact raw request body and Signature header with the endpoint signing secret. A successful handler should respond within three seconds; durable stores must deduplicate event ids because MailerSend retries failed delivery.
Inbound webhook projections preserve text, HTML, raw MIME, recipients, headers, SPF/DKIM results, and inline/regular attachments. Application code remains responsible for retention, attachment storage, malware scanning, and workspace policy before content enters CommunicationOS projections or AI context.
Compatibility
This package owns the email implementation slice split out of @lssm-tech/integration.providers-impls. The legacy package continues to re-export these subpaths for existing consumers.
Gmail convergence (TS-01-P-EMAIL)
GmailReadonlyReader(./impls/gmail-readonly-reader): scope-gatedgmail.readonlylist/history/message/profile with bounded requests, RFC 2047 subjects, bounded plain-text excerpts andhistory_expired→ full resync.GmailDelivery(./impls/gmail-delivery): one-attempt send of fixed MIME bytes (caller Message-ID + sha256), outcomes accepted/rejected/uncertain,findSentByMessageIdand read-onlyreconcile.createGmailControlledMailbox(./impls/gmail-fixture): zero-network controlled mailbox serving the Gmail REST routes through an injected fetch (tests and fixture qualification only).
Relationships
Arrows point from a package to its direct dependency. Counts are derived from captured workspace manifests.
4 declarations
@lssm-tech/integration.runtimeworkspace:^
Read the package manual ↗@lssm-tech/lib.contracts-integrationsworkspace:^
Read the package manual ↗googleapiscatalog:integrations
resend^6.28.1
Declared capabilities
Email provider implementations for ContractSpec.
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 --unsafe --only=nursery/useSortedClasses . && node ../../../scripts/biome.cjs check --write .testbun testprebuildcontractspec-bun-build prebuildtypechecktsgo --noEmit