@openlup/platform 0.17.0 → 0.19.0

package/src/catalog/sellableSchemas.ts

@@ -0,0 +1,33 @@
+import { z } from "./validation.js";
+import { SELLABLE_CATALOG_CONTRACT_VERSION } from "./contracts/sellable.js";
+export { SELLABLE_CATALOG_CONTRACT_VERSION } from "./contracts/sellable.js";
+export type { SellableCatalogItem, SellableCatalogProfile, SellableCatalogListResponse } 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/src/catalog/sql.ts

@@ -0,0 +1,14 @@
+/** 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) },
+] as const;
+
+/** 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) },
+] as const;

package/src/catalog/validation.ts

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

package/src/communications/contracts/index.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/src/communications/contracts/marketingSync.ts

@@ -0,0 +1,109 @@
+// Private helpers/symbols, never exported. Brands are not serialization authority.
+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 describes this current-state observation only; never historical completeness.
+  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 }));
+// Receipt identifies the original admitted mutation; status lives only in the result union.
+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; // private, same receipt style
+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>;
+}

package/src/communications/index.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/src/communications/klaviyo/consentPush.ts

@@ -0,0 +1,19 @@
+import type { ConsentPushRequest } from "../contracts/marketingSync.js";
+
+/** Private singleton translation. Local evidence is deliberately absent from wire attributes. */
+export function consentCommand(request: ConsentPushRequest, target: { id: string; email: string }, listId: string | undefined) {
+  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 } } } } : {}),
+  } } };
+}