@openlup/platform 0.17.0 → 0.18.0

package/dist/catalog/sellableBundleHandler.d.ts

@@ -0,0 +1,46 @@
+import type { HttpRequest, HttpResponse } from "../http/index.js";
+import type { BffResponder } from "../bff/index.js";
+import type { BundleResponseSchema } from "./adminBindings.js";
+import type { SellableBundle } from "./contracts/bundleAvailability.js";
+import type { BundleAvailability } from "./bundleAvailability.js";
+import type { ActiveBundleComposition } from "./bundleCatalogReadPort.js";
+import type { BundleAvailabilityService } from "./bundleAvailabilityService.js";
+/**
+ * The public sellable-bundle feed handler, shaped after the reference catalog
+ * handler: GET-only, one
+ * port call, validate the body before sending, and never serve an unvalidated
+ * shape.
+ *
+ * It composes rather than computes twice: the availability service already folds
+ * one batched stock answer into the live compositions, and the pricing kernel
+ * turns the stored target price into per-component money. This module only decides
+ * what a storefront is allowed to see.
+ *
+ * A bundle whose money cannot be derived is DROPPED from the feed, not published
+ * with a guessed figure. Three cases reach that door — an unpriced component, an
+ * empty composition, and a target price the kernel refuses — and all three mean
+ * the same thing to a storefront: this is not sellable today. Publishing it with a
+ * partial price would put a number on a shelf that no order line could reproduce.
+ */
+export interface SellableBundleHandlerDeps {
+    availabilityService: BundleAvailabilityService;
+    /** Narrow the feed to one currency; omitted means every currency an operator priced. */
+    currency?: string;
+    enabled: boolean;
+}
+export declare function createSellableBundleHandlers({ responder, sellableBundleListResponseSchema, SELLABLE_BUNDLE_CONTRACT_VERSION }: {
+    responder: BffResponder;
+    sellableBundleListResponseSchema: BundleResponseSchema;
+    SELLABLE_BUNDLE_CONTRACT_VERSION: "catalog.sellable-bundle.v1";
+}): {
+    createSellableBundleHandler: (deps: SellableBundleHandlerDeps) => (req: HttpRequest, res: HttpResponse) => Promise<void>;
+};
+/**
+ * Derive the row a storefront sees, or `null` when the money cannot be stated.
+ *
+ * The allocator emits TWO lines for a quantity whose subtotal does not divide
+ * evenly, which is exactly why the feed carries lines rather than a unit price per
+ * component: `unitPrice x quantity === lineSubtotal` holds on every line, and the
+ * lines sum to the bundle's price with no remainder.
+ */
+export declare function toSellableBundle(composition: ActiveBundleComposition, availability: BundleAvailability): SellableBundle | null;

package/dist/catalog/sellableBundleHandler.js

@@ -0,0 +1,84 @@
+import { allocateBundleTargetPrice } from "@openlup/core/pricing";
+export function createSellableBundleHandlers({ responder, sellableBundleListResponseSchema, SELLABLE_BUNDLE_CONTRACT_VERSION }) {
+    const { sendBffError, sendBffSuccess, sendMethodNotAllowed } = responder;
+    function createSellableBundleHandler(deps) {
+        return async function handler(req, res) {
+            if (req.method !== "GET") {
+                sendMethodNotAllowed(res, ["GET"]);
+                return;
+            }
+            if (!deps.enabled) {
+                sendBffError(res, "UPSTREAM_UNAVAILABLE", "Bundle reads are disabled", {
+                    details: { reason: "feature_flag_disabled", featureFlag: "COMMERCE_BUNDLE_READ_ENABLED" },
+                });
+                return;
+            }
+            try {
+                const rows = await deps.availabilityService.describeActiveBundles(deps.currency ? { currency: deps.currency } : {});
+                const response = sellableBundleListResponseSchema.safeParse({
+                    contractVersion: SELLABLE_BUNDLE_CONTRACT_VERSION,
+                    bundles: rows
+                        .map((row) => toSellableBundle(row.composition, row.availability))
+                        .filter((bundle) => bundle !== null),
+                });
+                if (!response.success) {
+                    sendBffError(res, "INVALID_RESPONSE", "Sellable bundle feed returned an invalid shape");
+                    return;
+                }
+                sendBffSuccess(res, response.data, { contractVersion: SELLABLE_BUNDLE_CONTRACT_VERSION }, { cacheControl: "no-store" });
+            }
+            catch {
+                sendBffError(res, "UPSTREAM_UNAVAILABLE", "Sellable bundles are unavailable");
+            }
+        };
+    }
+    return { createSellableBundleHandler };
+}
+/**
+ * Derive the row a storefront sees, or `null` when the money cannot be stated.
+ *
+ * The allocator emits TWO lines for a quantity whose subtotal does not divide
+ * evenly, which is exactly why the feed carries lines rather than a unit price per
+ * component: `unitPrice x quantity === lineSubtotal` holds on every line, and the
+ * lines sum to the bundle's price with no remainder.
+ */
+export function toSellableBundle(composition, availability) {
+    if (composition.components.length === 0)
+        return null;
+    if (composition.components.some((component) => component.referenceUnitPriceMinor === null)) {
+        return null;
+    }
+    const allocation = allocateBundleTargetPrice({
+        components: composition.components.map((component) => ({
+            sku: component.sku,
+            quantity: component.quantity,
+            unitPriceMinor: component.referenceUnitPriceMinor,
+        })),
+        targetPriceMinor: composition.targetPriceMinor,
+    });
+    if (!allocation.ok)
+        return null;
+    // Basis points come from the per-component allocation, so a component split
+    // across two lines reports the same discount on both halves rather than two
+    // rounded figures that disagree.
+    const discountBpsBySku = new Map(allocation.components.map((component) => [component.sku, component.discountBps]));
+    return {
+        code: composition.code,
+        title: composition.title,
+        fulfillmentMode: composition.fulfillmentMode,
+        price: { amountMinor: composition.targetPriceMinor, currency: composition.currency },
+        components: allocation.lines.map((line) => ({
+            sku: line.sku,
+            quantity: line.quantity,
+            effectiveUnitPriceMinor: line.effectiveUnitPriceMinor,
+            lineSubtotalMinor: line.lineSubtotalMinor,
+            discountBps: discountBpsBySku.get(line.sku) ?? 0,
+        })),
+        availability: {
+            status: availability.status,
+            sellableNow: availability.sellableNow,
+            limitingSku: availability.limitingSku,
+            reasonCode: availability.reasonCode,
+        },
+    };
+}

package/dist/catalog/sellableSchemas.d.ts

@@ -0,0 +1,46 @@
+import { z } from "./validation.js";
+export { SELLABLE_CATALOG_CONTRACT_VERSION } from "./contracts/sellable.js";
+export type { SellableCatalogItem, SellableCatalogProfile, SellableCatalogListResponse } from "./contracts/sellable.js";
+export declare const sellableCatalogItemSchema: z.ZodObject<{
+    sku: z.ZodString;
+    title: z.ZodString;
+    unitPrice: z.ZodObject<{
+        amountMinor: z.ZodNumber;
+        currency: z.ZodString;
+    }, z.core.$strict>;
+    permittedPurchaseModes: z.ZodArray<z.ZodEnum<{
+        subscription: "subscription";
+        one_time: "one_time";
+    }>>;
+}, z.core.$strict>;
+export declare const sellableCatalogProfileSchema: z.ZodObject<{
+    id: z.ZodString;
+    brand: z.ZodString;
+    country: z.ZodString;
+    currency: z.ZodString;
+    locale: z.ZodString;
+    timezone: z.ZodString;
+}, z.core.$strict>;
+export declare const sellableCatalogListResponseSchema: z.ZodObject<{
+    contractVersion: z.ZodLiteral<"catalog.sellable.v1">;
+    profile: z.ZodObject<{
+        id: z.ZodString;
+        brand: z.ZodString;
+        country: z.ZodString;
+        currency: z.ZodString;
+        locale: z.ZodString;
+        timezone: z.ZodString;
+    }, z.core.$strict>;
+    items: z.ZodArray<z.ZodObject<{
+        sku: z.ZodString;
+        title: z.ZodString;
+        unitPrice: z.ZodObject<{
+            amountMinor: z.ZodNumber;
+            currency: z.ZodString;
+        }, z.core.$strict>;
+        permittedPurchaseModes: z.ZodArray<z.ZodEnum<{
+            subscription: "subscription";
+            one_time: "one_time";
+        }>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;

package/dist/catalog/sellableSchemas.js

@@ -0,0 +1,27 @@
+import { z } from "./validation.js";
+import { SELLABLE_CATALOG_CONTRACT_VERSION } from "./contracts/sellable.js";
+export { SELLABLE_CATALOG_CONTRACT_VERSION } from "./contracts/sellable.js";
+/** Minimal neutral storefront wire schema. */
+const sellableCatalogMoneySchema = z.object({
+    amountMinor: z.number().int().nonnegative(),
+    currency: z.string().regex(/^[A-Z]{3}$/),
+}).strict();
+export const sellableCatalogItemSchema = z.object({
+    sku: z.string().trim().min(1).max(128).regex(/^[a-zA-Z0-9._:-]+$/),
+    title: z.string().trim().min(1).max(160),
+    unitPrice: sellableCatalogMoneySchema,
+    permittedPurchaseModes: z.array(z.enum(["one_time", "subscription"])).min(1).max(2),
+}).strict();
+export const sellableCatalogProfileSchema = z.object({
+    id: z.string().trim().min(1).max(120),
+    brand: z.string().trim().min(1).max(160),
+    country: z.string().regex(/^[A-Z]{2}$/),
+    currency: z.string().regex(/^[A-Z]{3}$/),
+    locale: z.string().trim().min(2).max(35),
+    timezone: z.string().trim().min(1).max(80),
+}).strict();
+export const sellableCatalogListResponseSchema = z.object({
+    contractVersion: z.literal(SELLABLE_CATALOG_CONTRACT_VERSION),
+    profile: sellableCatalogProfileSchema,
+    items: z.array(sellableCatalogItemSchema).min(1),
+}).strict();

package/dist/catalog/sql.d.ts

@@ -0,0 +1,46 @@
+/** Sparse projections of canonical units, never an install chain. */
+export declare const BUNDLE_MIGRATIONS: readonly [{
+    readonly id: "20260812140000_sellable_bundle_catalog";
+    readonly catalogPath: "db/platform/migrations/20260812140000_sellable_bundle_catalog.sql";
+    readonly position: 16;
+    readonly sha256: "62fbf0910a3a7a2ee47e2d798933fe0a5a273fd1242cae7cc78ff237ba39e394";
+    readonly url: URL;
+}, {
+    readonly id: "20260812210000_bundle_operator_write_boundary";
+    readonly catalogPath: "db/platform/migrations/20260812210000_bundle_operator_write_boundary.sql";
+    readonly position: 19;
+    readonly sha256: "d0ec6674d7eedf4cd3ce0d8ccd7345ebe2f93da635316a68a6bd178ec55b2679";
+    readonly url: URL;
+}];
+/** Catalog foundation projections; install the complete canonical catalogue. */
+export declare const CATALOG_MIGRATIONS: readonly [{
+    readonly id: "20260807140000_read_parity_catalog";
+    readonly catalogPath: "db/platform/migrations/20260807140000_read_parity_catalog.sql";
+    readonly position: 1;
+    readonly sha256: "fcf3827028c1651ae42a7c7d7472153825a3121c936d58a3d105befc7dece9ea";
+    readonly url: URL;
+}, {
+    readonly id: "20260810120000_storefront_catalog_attributes";
+    readonly catalogPath: "db/platform/migrations/20260810120000_storefront_catalog_attributes.sql";
+    readonly position: 8;
+    readonly sha256: "2bf938f5d0076193557bea834f86dbd9bcb7f3e2de00f99fb91cc1229b93a14b";
+    readonly url: URL;
+}, {
+    readonly id: "20260827220000_catalog_document_revision_foundation";
+    readonly catalogPath: "db/platform/migrations/20260827220000_catalog_document_revision_foundation.sql";
+    readonly position: 58;
+    readonly sha256: "715e74d655b76d35b8a49e0d2a5625594a6c4856863f369cd1eadcd1fb1ae90e";
+    readonly url: URL;
+}, {
+    readonly id: "20260827220001_catalog_document_revision_foundation_validate";
+    readonly catalogPath: "db/platform/migrations/20260827220001_catalog_document_revision_foundation_validate.sql";
+    readonly position: 59;
+    readonly sha256: "f3cd7fb61dcebac1cf0468cf2d7c1f9dd036817ab0094c72864266e307b269de";
+    readonly url: URL;
+}, {
+    readonly id: "20260908100000_catalog_draft_foundation";
+    readonly catalogPath: "db/platform/migrations/20260908100000_catalog_draft_foundation.sql";
+    readonly position: 61;
+    readonly sha256: "ac0d614cdb2874df8fbdbbbda4f9455986ef95241fe1334b0b54a1fa6478ab2e";
+    readonly url: URL;
+}];

package/dist/catalog/sql.js

@@ -0,0 +1,13 @@
+/** Sparse projections of canonical units, never an install chain. */
+export const BUNDLE_MIGRATIONS = [
+    { id: "20260812140000_sellable_bundle_catalog", catalogPath: "db/platform/migrations/20260812140000_sellable_bundle_catalog.sql", position: 16, sha256: "62fbf0910a3a7a2ee47e2d798933fe0a5a273fd1242cae7cc78ff237ba39e394", url: new URL("../../sql/20260812140000_sellable_bundle_catalog.sql", import.meta.url) },
+    { id: "20260812210000_bundle_operator_write_boundary", catalogPath: "db/platform/migrations/20260812210000_bundle_operator_write_boundary.sql", position: 19, sha256: "d0ec6674d7eedf4cd3ce0d8ccd7345ebe2f93da635316a68a6bd178ec55b2679", url: new URL("../../sql/20260812210000_bundle_operator_write_boundary.sql", import.meta.url) },
+];
+/** Catalog foundation projections; install the complete canonical catalogue. */
+export const CATALOG_MIGRATIONS = [
+    { id: "20260807140000_read_parity_catalog", catalogPath: "db/platform/migrations/20260807140000_read_parity_catalog.sql", position: 1, sha256: "fcf3827028c1651ae42a7c7d7472153825a3121c936d58a3d105befc7dece9ea", url: new URL("../../sql/20260807140000_read_parity_catalog.sql", import.meta.url) },
+    { id: "20260810120000_storefront_catalog_attributes", catalogPath: "db/platform/migrations/20260810120000_storefront_catalog_attributes.sql", position: 8, sha256: "2bf938f5d0076193557bea834f86dbd9bcb7f3e2de00f99fb91cc1229b93a14b", url: new URL("../../sql/20260810120000_storefront_catalog_attributes.sql", import.meta.url) },
+    { id: "20260827220000_catalog_document_revision_foundation", catalogPath: "db/platform/migrations/20260827220000_catalog_document_revision_foundation.sql", position: 58, sha256: "715e74d655b76d35b8a49e0d2a5625594a6c4856863f369cd1eadcd1fb1ae90e", url: new URL("../../sql/20260827220000_catalog_document_revision_foundation.sql", import.meta.url) },
+    { id: "20260827220001_catalog_document_revision_foundation_validate", catalogPath: "db/platform/migrations/20260827220001_catalog_document_revision_foundation_validate.sql", position: 59, sha256: "f3cd7fb61dcebac1cf0468cf2d7c1f9dd036817ab0094c72864266e307b269de", url: new URL("../../sql/20260827220001_catalog_document_revision_foundation_validate.sql", import.meta.url) },
+    { id: "20260908100000_catalog_draft_foundation", catalogPath: "db/platform/migrations/20260908100000_catalog_draft_foundation.sql", position: 61, sha256: "ac0d614cdb2874df8fbdbbbda4f9455986ef95241fe1334b0b54a1fa6478ab2e", url: new URL("../../sql/20260908100000_catalog_draft_foundation.sql", import.meta.url) },
+];

package/dist/catalog/validation.d.ts

@@ -0,0 +1,2 @@
+import { z } from "zod";
+export { z };

package/dist/catalog/validation.js

@@ -0,0 +1,3 @@
+import { z } from "zod";
+z.config({ jitless: true });
+export { z };

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

@@ -49,3 +49,4 @@ export * from "./invoiceDocumentContent.js";
 export * from "./roleNotificationContent.js";
 export * from "./inquiryContent.js";
 export * from "./optOutContent.js";
+export type * from "./marketingSync.js";

package/dist/communications/contracts/marketingSync.d.ts

@@ -0,0 +1,194 @@
+declare const subjectBrand: unique symbol, feedbackBrand: unique symbol, receiptBrand: unique symbol, readBrand: unique symbol;
+type Operation = "profile.sync" | "consent.read" | "erasure.request" | "erasure.read";
+type Mutation = "profile.sync" | "erasure.request";
+type SubjectReference = string & {
+    readonly [subjectBrand]: "opaque-subject";
+};
+export type SyncBinding = Readonly<{
+    account: string;
+    environment: string;
+    namespace: string;
+    mappingVersion: string;
+}>;
+export type SyncAudience = Readonly<{
+    kind: "account-wide";
+} | {
+    kind: "audience";
+    reference: string;
+}>;
+export type ProfileProjection = Readonly<{
+    email: string;
+    externalReference: string;
+    fields: Readonly<Partial<Record<"givenName" | "familyName" | "locale", string>>>;
+    properties: Readonly<Record<string, string | number | boolean>>;
+}>;
+type Payload = {
+    "profile.sync": {
+        projection: ProfileProjection;
+        consentEvidenceReference: string;
+    };
+    "consent.read": Readonly<Record<string, never>>;
+    "erasure.request": {
+        caseReference: string;
+        authorityReference: string;
+    };
+    "erasure.read": {
+        receipt: SyncReceipt<"erasure.request">;
+    };
+};
+export type SyncRequest<O extends Operation = Operation> = {
+    [K in O]: Readonly<{
+        binding: SyncBinding;
+        audience: SyncAudience;
+        subjectReference: SubjectReference;
+        requestId: string;
+        generation: number;
+        deadlineMs: number;
+        authorizationReference: string;
+        operation: K;
+        payload: Readonly<Payload[K]>;
+    }>;
+}[O];
+export type NegativeFeedback = Readonly<{
+    [feedbackBrand]: "provider-negative";
+    sourceReference: string;
+    occurredAtMs: number | null;
+    audience: SyncAudience;
+}> & Readonly<{
+    kind: "unsubscribe" | "complaint" | "manual_block";
+    outcome: "deny_permission";
+} | {
+    kind: "hard_bounce" | "invalid_address";
+    outcome: "deny_delivery";
+}>;
+export type ConsentReadback = Readonly<{
+    audience: SyncAudience;
+    observedAtMs: number;
+    remoteConsent: "subscribed" | "unsubscribed" | "pending" | "never_subscribed" | "unknown";
+    feedback: readonly NegativeFeedback[];
+    coverage: "complete" | "partial" | "unsupported";
+}>;
+export type SyncFailure<O extends Operation = Operation> = {
+    kind: "refused";
+    reason: "invalid_request" | "binding" | "provenance" | "stale" | "deadline" | "unsupported" | "verification_pending" | "restricted" | "identity_conflict" | "provider_refusal";
+} | {
+    kind: "retryable";
+    reason: "cooling" | "host" | "provider";
+    afterSeconds: number;
+} | ({
+    kind: "unknown";
+    reason: "dispatch_unresolved" | "acceptance_ambiguous" | "record_failed";
+} & (O extends Mutation ? {
+    receipt?: SyncReceipt<O>;
+} : {
+    receipt?: never;
+}));
+export type SyncReceipt<O extends Mutation> = Readonly<{
+    [receiptBrand]: O;
+    operation: O;
+    request: SyncRequest<O>;
+}>;
+type MutationSuccess<O extends Mutation> = {
+    kind: "accepted" | "acknowledged";
+    receipt: SyncReceipt<O>;
+    journal: "confirmed" | "unknown";
+};
+type Success = {
+    "profile.sync": MutationSuccess<"profile.sync">;
+    "consent.read": {
+        kind: "completed";
+        value: ConsentReadback;
+        journal: "confirmed" | "unknown";
+    };
+    "erasure.request": MutationSuccess<"erasure.request">;
+    "erasure.read": MutationSuccess<"erasure.request"> | {
+        kind: "completed";
+        receipt: SyncReceipt<"erasure.request">;
+        journal: "confirmed" | "unknown";
+        evidence: Readonly<{
+            [readBrand]: "provider-read";
+            readRequestId: string;
+            observedAtMs: number;
+            evidenceReference: string;
+            assurance: "provider_record_deleted" | "provider_erasure_confirmed";
+        }>;
+    };
+};
+export type SyncResult<O extends Operation = Operation> = {
+    [K in O]: Readonly<Pick<SyncRequest<K>, "binding" | "operation" | "subjectReference" | "requestId" | "generation">> & Readonly<Success[K] | SyncFailure<K>>;
+}[O];
+export type SyncCapabilities = Readonly<{
+    binding: SyncBinding;
+    audience: SyncAudience;
+    operations: Readonly<Record<Operation, {
+        state: "supported";
+        evidenceReference: string;
+        maxRequestBytes: number;
+        maxFeedbackItems: number;
+    } | {
+        state: "unsupported" | "verification_pending";
+    }>>;
+}>;
+export interface ProfileSyncPort {
+    sync(request: SyncRequest<"profile.sync">): Promise<SyncResult<"profile.sync">>;
+}
+export interface ConsentReadPort {
+    read(request: SyncRequest<"consent.read">): Promise<SyncResult<"consent.read">>;
+}
+export interface ErasurePort {
+    request(request: SyncRequest<"erasure.request">): Promise<SyncResult<"erasure.request">>;
+    read(request: SyncRequest<"erasure.read">): Promise<SyncResult<"erasure.read">>;
+}
+export interface MarketingSyncProvider {
+    readonly capabilities: SyncCapabilities;
+    readonly profiles: ProfileSyncPort;
+    readonly consent: ConsentReadPort;
+    readonly erasure: ErasurePort;
+}
+export type ConsentPushRequest = Readonly<Omit<SyncRequest<"profile.sync">, "operation" | "audience" | "payload"> & {
+    operation: "consent.push";
+} & ({
+    audience: Extract<SyncAudience, {
+        kind: "audience";
+    }>;
+    payload: Readonly<{
+        action: "grant";
+        consentEvidenceReference: string;
+    }>;
+} | {
+    audience: SyncAudience;
+    payload: Readonly<{
+        action: "withdraw";
+        consentEvidenceReference: string;
+    }>;
+})>;
+declare const pushReceiptBrand: unique symbol;
+type PushReceipt = Readonly<{
+    [pushReceiptBrand]: "consent.push";
+    operation: "consent.push";
+    request: ConsentPushRequest;
+}>;
+type PushFailure = Exclude<SyncFailure, {
+    kind: "unknown";
+}> | (Omit<Extract<SyncFailure, {
+    kind: "unknown";
+}>, "receipt"> & {
+    receipt?: PushReceipt;
+});
+export type ConsentPushResult = Readonly<Pick<ConsentPushRequest, "binding" | "operation" | "subjectReference" | "requestId" | "generation">> & Readonly<{
+    kind: "accepted" | "acknowledged";
+    receipt: PushReceipt;
+    journal: "confirmed" | "unknown";
+    reconcileRequired: boolean;
+} | PushFailure>;
+export interface ConsentPushPort {
+    readonly capabilities: SyncCapabilities & Readonly<{
+        operations: SyncCapabilities["operations"] & Readonly<{
+            "consent.push": SyncCapabilities["operations"]["profile.sync"] & Readonly<{
+                grantEffect: "audience" | "account-wide";
+            }>;
+        }>;
+    }>;
+    push(request: ConsentPushRequest): Promise<ConsentPushResult>;
+}
+export {};

package/dist/communications/contracts/marketingSync.js

@@ -0,0 +1 @@
+export {};

package/dist/communications/index.d.ts

@@ -44,3 +44,4 @@ 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/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 {};