@openlup/platform 0.16.0 → 0.18.0

package/dist/communications/emailTransport.js

@@ -0,0 +1,95 @@
+import { admitPolicyEnforcedEmailTransport } from "./emailEgress.js";
+/** Converts the transport's legacy identifier field at the transport boundary. */
+export function emailTransportMessageId(outcome) {
+    return outcome.resendId;
+}
+/** Maps the neutral message identifier onto the deployed ledger's legacy field. */
+export function emailTransportLedgerIdentifier(messageId) {
+    return { resend_id: messageId };
+}
+/** Synthesizes the canonical terminal transport shape when `send` throws. */
+export function failedEmailTransportResult() {
+    return {
+        outcome: { ok: false, resendId: null, httpStatus: 0, providerError: "provider_transport_threw", aborted: false },
+        providerResponse: { exception: true },
+    };
+}
+/** One truth projection for every Node email ledger, timeline and caller. */
+export function classifyEmailSendOutcome(outcome) {
+    const skipReason = outcome.skipReason
+        ?? (outcome.adminDisabled ? "admin_disabled" : null)
+        ?? (outcome.suppressed === "drop" ? "egress_suppressed" : null);
+    if (skipReason) {
+        return {
+            skipReason,
+            timelineStatus: "skipped",
+            ledgerStatus: "skipped",
+            sentAtEligible: false,
+            lastErrorCode: skipReason,
+        };
+    }
+    // `ok` deliberately remains the transport-acceptance contract. In particular,
+    // this wave does not turn a historical 2xx-without-id answer into a retry.
+    if (outcome.ok) {
+        return {
+            skipReason: null,
+            timelineStatus: "sent",
+            ledgerStatus: "sent",
+            sentAtEligible: true,
+            lastErrorCode: null,
+        };
+    }
+    if (outcome.aborted) {
+        return {
+            skipReason: null,
+            timelineStatus: "delivery_delayed",
+            ledgerStatus: "failed",
+            sentAtEligible: false,
+            lastErrorCode: "provider_request_aborted",
+        };
+    }
+    return {
+        skipReason: null,
+        timelineStatus: "failed",
+        ledgerStatus: "failed",
+        sentAtEligible: false,
+        lastErrorCode: normalizeEmailFailureCode(outcome.providerError),
+    };
+}
+/** Adds a provider-neutral skip reason without changing ordinary wire shapes. */
+export function withEmailSendSkipReason(outcome) {
+    const skipReason = classifyEmailSendOutcome(outcome).skipReason;
+    return skipReason ? { ...outcome, skipReason } : outcome;
+}
+function normalizeEmailFailureCode(value) {
+    if (!value)
+        return "provider_send_failed";
+    const normalized = value
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "_")
+        .replace(/^_+|_+$/g, "")
+        .slice(0, 80);
+    return normalized || "provider_send_failed";
+}
+/**
+ * Reference capture transport: captures sends in memory and never makes a
+ * network call. Proves the seam is real — a port wired to this sends email with
+ * no HTTP client — and doubles as the substitute an OSS fork starts from
+ * before writing its own SES/SMTP adapter.
+ */
+export function createInMemoryEmailTransport(opts) {
+    const sent = [];
+    const prefix = opts?.idPrefix ?? "in-memory";
+    return admitPolicyEnforcedEmailTransport({
+        providerKind: "in-memory",
+        sent,
+        async send(message) {
+            sent.push(message);
+            const id = `${prefix}-${sent.length}`;
+            return {
+                outcome: { ok: true, resendId: id, httpStatus: 200, providerError: null, aborted: false },
+                providerResponse: { id },
+            };
+        },
+    });
+}

package/dist/communications/errors.d.ts

@@ -0,0 +1,15 @@
+export declare class CommunicationRecipientNotFoundError extends Error {
+    constructor(message?: string);
+}
+export declare class CommunicationTemplateNotFoundError extends Error {
+    constructor(message?: string);
+}
+export declare class CommunicationConflictError extends Error {
+    constructor(message?: string);
+}
+export declare class CommunicationValidationError extends Error {
+    constructor(message?: string);
+}
+export declare class CommunicationUnavailableError extends Error {
+    constructor(message?: string);
+}

package/dist/communications/errors.js

@@ -0,0 +1,30 @@
+export class CommunicationRecipientNotFoundError extends Error {
+    constructor(message = "Communication recipient not found") {
+        super(message);
+        this.name = "CommunicationRecipientNotFoundError";
+    }
+}
+export class CommunicationTemplateNotFoundError extends Error {
+    constructor(message = "Communication template not found") {
+        super(message);
+        this.name = "CommunicationTemplateNotFoundError";
+    }
+}
+export class CommunicationConflictError extends Error {
+    constructor(message = "Communication request conflicts with current state") {
+        super(message);
+        this.name = "CommunicationConflictError";
+    }
+}
+export class CommunicationValidationError extends Error {
+    constructor(message = "Communication request is invalid") {
+        super(message);
+        this.name = "CommunicationValidationError";
+    }
+}
+export class CommunicationUnavailableError extends Error {
+    constructor(message = "Communication capability is unavailable") {
+        super(message);
+        this.name = "CommunicationUnavailableError";
+    }
+}

package/dist/communications/index.d.ts

@@ -0,0 +1,47 @@
+export * from "./accountingDocumentDelivery.js";
+export * from "./authEmailError.js";
+export * from "./authSendEmailHook.js";
+export * from "./capturedTransactionalDelivery.js";
+export * from "./communicationSync.js";
+export * from "./communicationSyncWorker.js";
+export * from "./consentPolicy.js";
+export * from "./deliveryReconciliation.js";
+export * from "./contribution.js";
+export * from "./emailHealthAssessment.js";
+export * from "./emailHealthMetricsPort.js";
+export * from "./emailNotificationControl.js";
+export * from "./emailObservation.js";
+export * from "./emailTransport.js";
+export * from "./emailEgress.js";
+export * from "./errors.js";
+export * from "./integrationEventSignature.js";
+export * from "./managedTransactionalDeliveryStore.js";
+export * from "./newsletterIntegrationContracts.js";
+export * from "./newsletterWebhookPort.js";
+export * from "./originPolicy.js";
+export * from "./postgresTransactionalDeliveryStore.js";
+export * from "./preferencesToken.js";
+export * from "./publicPreferenceToken.js";
+export * from "./shipmentNotifications.js";
+export * from "./sql.js";
+export * from "./standardWebhooks.js";
+export * from "./status.js";
+export * from "./transactionalDelivery.js";
+export * from "./transactionalDeliveryIdentifier.js";
+export * from "./unsubscribeToken.js";
+export type * from "./contracts/authEmail.js";
+export type * from "./contracts/email.js";
+export type * from "./contracts/publicIntake.js";
+export type * from "./contracts/transactionalDelivery.js";
+export type * from "./contracts/newsletterWebhook.js";
+export type { NewsletterSyncProviderPort, NewsletterSyncOutcome, NewsletterSyncReconcileOutcome } from "./contracts/newsletter.js";
+export * from "./consentPurposeRegistry.js";
+export type * from "./contracts/consent.js";
+export type * from "./contracts/marketingAutomation.js";
+export * from "./newsletterWebhookProcessing.js";
+export * from "./nativeOperations.js";
+export * from "./postgresDeliveryReconciliation.js";
+export * from "./postgresCommunicationSync.js";
+export * from "./postgresNotificationRecipients.js";
+export * from "./postgresConsentEvaluator.js";
+export type * from "./contracts/marketingSync.js";

package/dist/communications/index.js

@@ -0,0 +1,38 @@
+export * from "./accountingDocumentDelivery.js";
+export * from "./authEmailError.js";
+export * from "./authSendEmailHook.js";
+export * from "./capturedTransactionalDelivery.js";
+export * from "./communicationSync.js";
+export * from "./communicationSyncWorker.js";
+export * from "./consentPolicy.js";
+export * from "./deliveryReconciliation.js";
+export * from "./contribution.js";
+export * from "./emailHealthAssessment.js";
+export * from "./emailHealthMetricsPort.js";
+export * from "./emailNotificationControl.js";
+export * from "./emailObservation.js";
+export * from "./emailTransport.js";
+export * from "./emailEgress.js";
+export * from "./errors.js";
+export * from "./integrationEventSignature.js";
+export * from "./managedTransactionalDeliveryStore.js";
+export * from "./newsletterIntegrationContracts.js";
+export * from "./newsletterWebhookPort.js";
+export * from "./originPolicy.js";
+export * from "./postgresTransactionalDeliveryStore.js";
+export * from "./preferencesToken.js";
+export * from "./publicPreferenceToken.js";
+export * from "./shipmentNotifications.js";
+export * from "./sql.js";
+export * from "./standardWebhooks.js";
+export * from "./status.js";
+export * from "./transactionalDelivery.js";
+export * from "./transactionalDeliveryIdentifier.js";
+export * from "./unsubscribeToken.js";
+export * from "./consentPurposeRegistry.js";
+export * from "./newsletterWebhookProcessing.js";
+export * from "./nativeOperations.js";
+export * from "./postgresDeliveryReconciliation.js";
+export * from "./postgresCommunicationSync.js";
+export * from "./postgresNotificationRecipients.js";
+export * from "./postgresConsentEvaluator.js";

package/dist/communications/integrationEventSignature.d.ts

@@ -0,0 +1,15 @@
+export declare const COMMUNICATION_INTEGRATION_SIGNATURE_TOLERANCE_SECONDS = 300;
+export declare const COMMUNICATION_INTEGRATION_SIGNATURE_HEADER = "x-openlup-communications-signature";
+export declare const COMMUNICATION_INTEGRATION_TIMESTAMP_HEADER = "x-openlup-communications-timestamp";
+export declare function verifyCommunicationIntegrationEventSignature(input: {
+    rawBody: string;
+    signatureHeader: string | undefined;
+    timestampHeader: string | undefined;
+    secret: string;
+    now?: () => number;
+}): boolean;
+export declare function signCommunicationIntegrationEvent(input: {
+    rawBody: string;
+    timestamp: number;
+    secret: string;
+}): string;

package/dist/communications/integrationEventSignature.js

@@ -0,0 +1,37 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+export const COMMUNICATION_INTEGRATION_SIGNATURE_TOLERANCE_SECONDS = 300;
+export const COMMUNICATION_INTEGRATION_SIGNATURE_HEADER = "x-openlup-communications-signature";
+export const COMMUNICATION_INTEGRATION_TIMESTAMP_HEADER = "x-openlup-communications-timestamp";
+export function verifyCommunicationIntegrationEventSignature(input) {
+    if (!input.secret || !input.signatureHeader || !input.timestampHeader)
+        return false;
+    const timestamp = Number(input.timestampHeader);
+    if (!Number.isFinite(timestamp))
+        return false;
+    const now = input.now ?? (() => Math.floor(Date.now() / 1000));
+    const age = now() - timestamp;
+    if (age > COMMUNICATION_INTEGRATION_SIGNATURE_TOLERANCE_SECONDS)
+        return false;
+    if (age < -COMMUNICATION_INTEGRATION_SIGNATURE_TOLERANCE_SECONDS)
+        return false;
+    const signature = normalizeSignature(input.signatureHeader);
+    const expected = signCommunicationIntegrationEvent({
+        rawBody: input.rawBody,
+        timestamp,
+        secret: input.secret,
+    });
+    return safeEqual(signature, expected);
+}
+export function signCommunicationIntegrationEvent(input) {
+    return createHmac("sha256", input.secret)
+        .update(`${input.timestamp}.${input.rawBody}`)
+        .digest("hex");
+}
+function normalizeSignature(value) {
+    return value.trim().replace(/^sha256=/i, "");
+}
+function safeEqual(left, right) {
+    const leftBuffer = Buffer.from(left);
+    const rightBuffer = Buffer.from(right);
+    return leftBuffer.length === rightBuffer.length && timingSafeEqual(leftBuffer, rightBuffer);
+}

package/dist/communications/klaviyo/consentPush.d.ts

@@ -0,0 +1,51 @@
+import type { ConsentPushRequest } from "../contracts/marketingSync.js";
+/** Private singleton translation. Local evidence is deliberately absent from wire attributes. */
+export declare function consentCommand(request: ConsentPushRequest, target: {
+    id: string;
+    email: string;
+}, listId: string | undefined): {
+    method: string;
+    path: string;
+    expected: number[];
+    body: {
+        data: {
+            type: string;
+            id: string;
+        }[];
+    };
+} | {
+    method: string;
+    path: string;
+    expected: number[];
+    body: {
+        data: {
+            relationships?: {
+                list: {
+                    data: {
+                        type: string;
+                        id: string | undefined;
+                    };
+                };
+            } | undefined;
+            type: string;
+            attributes: {
+                profiles: {
+                    data: {
+                        attributes: {
+                            email: string;
+                            subscriptions: {
+                                email: {
+                                    marketing: {
+                                        consent: string;
+                                    };
+                                };
+                            };
+                        };
+                        id?: string | undefined;
+                        type: string;
+                    }[];
+                };
+            };
+        };
+    };
+};

package/dist/communications/klaviyo/consentPush.js

@@ -0,0 +1,19 @@
+/** Private singleton translation. Local evidence is deliberately absent from wire attributes. */
+export function consentCommand(request, target, listId) {
+    if (request.payload.action === "withdraw" && request.audience.kind === "audience") {
+        if (!listId)
+            throw new Error("scope");
+        return { method: "DELETE", path: `/api/lists/${listId}/relationships/profiles`, expected: [204],
+            body: { data: [{ type: "profile", id: target.id }] } };
+    }
+    const grant = request.payload.action === "grant";
+    const type = grant ? "profile-subscription-bulk-create-job" : "profile-subscription-bulk-delete-job";
+    if (grant && !listId)
+        throw new Error("scope");
+    return { method: "POST", path: `/api/${type}s`, expected: [202], body: { data: { type,
+                attributes: { profiles: { data: [{ type: "profile", ...(grant ? { id: target.id } : {}), attributes: {
+                                    email: target.email, subscriptions: { email: { marketing: { consent: grant ? "SUBSCRIBED" : "UNSUBSCRIBED" } } },
+                                } }] } },
+                ...(grant ? { relationships: { list: { data: { type: "list", id: listId } } } } : {}),
+            } } };
+}

package/dist/communications/klaviyo/index.d.ts

@@ -0,0 +1,110 @@
+import type { ConsentPushPort, ConsentPushRequest, MarketingSyncProvider, ProfileProjection, SyncAudience, SyncBinding, SyncRequest } from "../contracts/marketingSync.js";
+import type { MarketingAutomationClaim, MarketingAutomationProviderPort, MarketingAutomationScope } from "../contracts/marketingAutomation.js";
+import type { NewsletterSyncProviderPort } from "../contracts/newsletter.js";
+type Request = SyncRequest | ConsentPushRequest;
+type Operation = Request["operation"];
+type Subject = {
+    binding: SyncBinding;
+    subjectReference: string;
+    generation: number;
+    erased: boolean;
+    id?: string;
+    email: string;
+    externalReference: string;
+    ownedFields: readonly (keyof ProfileProjection["fields"])[];
+    ownedProperties: readonly string[];
+};
+type LocalEvidence = {
+    binding: SyncBinding;
+    subjectReference: string;
+    audience: SyncAudience;
+    purpose: string;
+    action: "profile" | "grant" | "withdraw" | "erase";
+    current: boolean;
+    projection?: ProfileProjection;
+    caseReference?: string;
+    authorityReference?: string;
+    allPurposes?: boolean;
+};
+type Authorization = {
+    binding: SyncBinding;
+    subjectReference: string;
+    audience: SyncAudience;
+    operation: Operation;
+    expiresAtMs: number;
+};
+type Verification = {
+    binding: SyncBinding;
+    audience: SyncAudience;
+    evidenceReference: string;
+    revision: string;
+    operations: readonly Exclude<Operation, "erasure.read">[];
+    scopes: readonly string[];
+    noTrigger: {
+        profile: boolean;
+        accountWideGrant: boolean;
+        doi: boolean;
+    };
+    safeCreate: boolean;
+    safeListRemoval: boolean;
+    suppressionSafeAtEffect: boolean;
+    negativeSourcesComplete: boolean;
+    listMappings: Readonly<Record<string, SyncAudience>>;
+};
+type Storage = {
+    /** Shared plain mutable record for this account/environment, independent of CAS failure.
+     * Start quarantined after host restart; only explicit host reconciliation clears it.
+     * Every adapter namespace/instance uses the same record. Never reset it at construction. */
+    availability: {
+        account: string;
+        environment: string;
+        busy: boolean;
+        quarantined: boolean;
+    };
+    /** Shared across every adapter for the account. false proves no commit; throws may have committed. */
+    get(key: string): Promise<string | null>;
+    compareAndSwap(key: string, expected: string | null, value: string): Promise<boolean>;
+};
+type Configuration = {
+    binding: SyncBinding;
+    audience: SyncAudience;
+    /** Synchronous current host registry lookup; never parses an opaque subject reference. */
+    subjectMapper(subjectReference: string): Subject | undefined;
+    resolveCredential(): {
+        binding: SyncBinding;
+        key: string;
+    } | undefined;
+    authorizations: ReadonlyMap<string, Authorization>;
+    localEvidence: ReadonlyMap<string, LocalEvidence>;
+    storage: Storage;
+    verification?: Verification;
+    /** Private authenticated settlement facts from the host's existing reconciliation journal. */
+    grantSettlements?: ReadonlyMap<string, {
+        binding: SyncBinding;
+        subjectReference: string;
+        requestId: string;
+        source: "provider-read";
+        evidenceReference: string;
+        settledAtMs: number;
+    }>;
+    fetch?: typeof fetch;
+    now?: () => number;
+    maxRequestBytes?: number;
+    maxResponseBytes?: number;
+    maxFeedbackItems?: number;
+    timeoutMs?: number;
+    rateIntervalMs?: number;
+    legacy?: {
+        scope: MarketingAutomationScope;
+        claims: ReadonlyMap<string, {
+            claim: MarketingAutomationClaim;
+            request: Request;
+        }>;
+    };
+};
+/** Opt-in Node adapter; owner TEST evidence is required before any bound operation is enabled. */
+export declare function createKlaviyoMarketingAdapter(input: Configuration): MarketingSyncProvider & MarketingAutomationProviderPort & {
+    readonly consentPush: ConsentPushPort;
+    readonly newsletter: NewsletterSyncProviderPort;
+};
+export {};