@openlup/platform 0.27.0 → 0.28.0

package/src/account-support/customer360.ts

@@ -0,0 +1,268 @@
+import type {
+  Customer360Snapshot,
+  Customer360Subject,
+  Customer360ContactHealth,
+  Customer360ReadPort,
+  Customer360Lookup,
+  Customer360SummaryReadPort,
+  DiagnosticHistoryReadPort
+} from "./contracts/customer360.js";
+
+export const SUPPORT_CUSTOMER_360_CONTRACT_VERSION = "support.customer_360.v2" as const;
+type Row = Record<string, unknown>;
+export type CustomerJourneyAuditEvent = {
+  eventId: string;
+  occurredAt: string;
+  action: string;
+  outcome: string;
+  entity: { kind: "subject" | "order" | "subscription" | "dunning_case"; id: string }
+};
+
+export interface ContactHealthDelivery {
+  readonly status: string;
+  readonly occurredAt: string | null;
+  readonly permanentBounce: boolean | null
+}
+
+export interface Customer360ProjectionInput<Extension = unknown> {
+  subject: {
+    subjectId: string;
+    displayName: string | null;
+    email: string | null;
+    phone?: string | null;
+    lifecycleStage: Customer360Subject["lifecycleStage"];
+    createdAt: string | null;
+    lastActivityAt: string | null
+  };
+  legacy: {
+    lookup: { warnings: string[] };
+    customer: { authUserLinked: boolean };
+    orders: { orderId: string; orderNumber: string | null; status: string | null; omsProjection: Row }[];
+    subscriptions: {
+      subscriptionId: string;
+      status: string | null;
+      nextCycleAt: string | null;
+      templateVersion?: number | null;
+      paymentMethodStatus?: string | null;
+      renewalOrders: Row[]
+    }[];
+    payment: { status: string | null; intents: Row[] };
+    timeline: Row[];
+  } | null;
+  cases: Row[];
+  notices: Row[];
+  tokens: Row[];
+  recoveryAudit: Row[];
+  orderTruth: Row[];
+  now: number;
+  contactHealth?: Customer360ContactHealth | null;
+  signedIn?: boolean;
+  addresses?: Customer360Snapshot["addresses"] | null;
+  subscriptionPointers?: Map<string, { shippingAddressId: string | null; paymentMethodKind: string | null }> | null;
+  /** false means failed/unavailable; null means no enrichment selected. */
+  profile?: { extension: Extension; partial: boolean } | false | null;
+}
+
+export interface Customer360ProjectionPolicy {
+  lifecycle(subject: Customer360ProjectionInput["subject"]): Customer360Subject["lifecycle"];
+  /** Stable audit identity hashing remains in the server host. */
+  timelineAudit(event: Row, subjectId: string): CustomerJourneyAuditEvent[];
+}
+
+export function projectCustomer360Snapshot<Extension>(
+  input: Customer360ProjectionInput<Extension>,
+  policy: Customer360ProjectionPolicy
+): Customer360Snapshot<Extension> {
+  const { subject, legacy, cases, notices, tokens, recoveryAudit, orderTruth, now } = input;
+  const orders = legacy?.orders.map(order => ({
+    orderId: order.orderId,
+    orderNumber: order.orderNumber,
+    status: order.status ?? "unknown",
+    subscriptionId: string(order.omsProjection.subscriptionId),
+    totalMinor: integer(order.omsProjection.totalMinor),
+    currency: string(order.omsProjection.currency),
+    createdAt: date(order.omsProjection.createdAt)
+  })) ?? [];
+  const pending = (row: Row) => orderTruth.some(
+    order => order.id === row.order_id && order.client_id === row.client_id && order.status === "pending_payment"
+  );
+  const eligible = (row: Row) => subject.lifecycleStage === "customer" && row.status === "open" && pending(row);
+  const audit = boundedCustomerJourneyAudit([
+    ...(legacy?.timeline ?? []).flatMap(event => policy.timelineAudit(event, subject.subjectId)),
+    ...recoveryAudit.flatMap(recoveryEvent)
+  ]);
+  const profile = input.profile;
+  const warnings = [...new Set([
+    ...(legacy?.lookup.warnings ?? []),
+    ...(audit.windowed ? ["evidence_window_limited:customer_360_audit_trail"] : []),
+    ...(recoveryAudit.length === 80 ? ["evidence_window_limited:customer_recovery_audit"] : []),
+    ...(profile === false ? ["evidence_unavailable:customer_profile"] : profile?.partial ? ["evidence_partial:customer_profile"] : [])
+  ])];
+  return {
+    contractVersion: SUPPORT_CUSTOMER_360_CONTRACT_VERSION,
+    lookup: { query: subject.subjectId, matchedBy: "subject_id", confidence: "exact", warnings },
+    ...(input.contactHealth ? { contactHealth: input.contactHealth } : {}),
+    ...(input.addresses ? { addresses: input.addresses } : {}),
+    ...(profile ? { extension: profile.extension } : {}),
+    subject: {
+      subjectId: subject.subjectId,
+      displayName: subject.displayName,
+      email: subject.email,
+      phone: subject.phone ?? null,
+      lifecycleStage: subject.lifecycleStage,
+      lifecycle: policy.lifecycle(subject),
+      firstSeenAt: subject.createdAt,
+      lastActivityAt: latest([...(legacy?.timeline ?? []), ...cases, ...recoveryAudit]) ?? subject.lastActivityAt,
+      ...(legacy ? { authUserLinked: legacy.customer.authUserLinked } : {}),
+      ...(input.signedIn === undefined ? {} : { hasSignedIn: input.signedIn })
+    },
+    orders,
+    subscriptions: legacy?.subscriptions.map(value => ({
+      subscriptionId: value.subscriptionId,
+      status: value.status ?? "unknown",
+      nextCycleAt: value.nextCycleAt,
+      latestOrderId: string(value.renewalOrders[0]?.orderId),
+      ...(typeof value.templateVersion === "number" ? { templateVersion: value.templateVersion } : {}),
+      ...(input.subscriptionPointers
+        ? {
+          shippingAddressId: input.subscriptionPointers.get(value.subscriptionId)?.shippingAddressId ?? null,
+          paymentMethodKind: input.subscriptionPointers.get(value.subscriptionId)?.paymentMethodKind ?? null
+        }
+        : {}),
+      paymentMethodStatus: string(value.paymentMethodStatus)
+    })) ?? [],
+    payment: orders.map(order => {
+      const intent = legacy?.payment.intents.find(value => string(value.orderId) === order.orderId);
+      return {
+        orderId: order.orderId,
+        status: string(intent?.status) ?? legacy?.payment.status ?? "unknown",
+        recoverable: cases.some(row => row.order_id === order.orderId && eligible(row)),
+        amountMinor: order.totalMinor,
+        currency: order.currency,
+        lastAttemptAt: date(intent?.updatedAt)
+      };
+    }),
+    dunningCases: cases.map(row => ({
+      caseId: string(row.id)!,
+      subscriptionId: string(row.subscription_id)!,
+      orderId: string(row.order_id),
+      status: string(row.status) ?? "unknown",
+      retryAttempt: integer(row.retry_attempt) ?? 0,
+      nextRetryAt: date(row.next_retry_at),
+      notificationStatus: string(latestNotice(notices, string(row.id)!)?.status),
+      recoveryAvailable: eligible(row)
+    })),
+    recovery: cases.map(row => {
+      const id = string(row.id)!, related = tokens.filter(value => value.case_id === id);
+      return {
+        caseId: id,
+        status: pending(row) && related.some(value => {
+          const expiry = date(value.expires_at);
+          return Boolean(expiry && Date.parse(expiry) > now && !value.used_at && !value.revoked_at);
+        }) ? "available" : "unavailable",
+        actionAvailable: eligible(row),
+        lastIssuedAt: related.map(value => date(value.created_at)).filter(value => value !== null).sort().at(-1) ?? null,
+        lastDeliveryStatus: string(latestNotice(notices, id, "payment_recovery")?.status)
+      };
+    }),
+    auditTrail: audit.events
+  };
+}
+
+export function boundedCustomerJourneyAudit(events: CustomerJourneyAuditEvent[]) {
+  const instant = (value: string) => Number.isFinite(Date.parse(value)) ? Date.parse(value) : 0;
+  const newest = [...events].sort((a, b) => instant(b.occurredAt) - instant(a.occurredAt) || a.eventId.localeCompare(b.eventId));
+  return {
+    events: newest.slice(0, 80).sort((a, b) => instant(a.occurredAt) - instant(b.occurredAt) || a.eventId.localeCompare(b.eventId)),
+    windowed: newest.length > 80
+  };
+}
+
+export function deriveContactHealth(deliveries: readonly ContactHealthDelivery[]): Customer360ContactHealth {
+  const terminal = ["delivered", "bounced", "complained", "failed"] as const;
+  const newest = deliveries.filter(
+    (value): value is ContactHealthDelivery & { occurredAt: string } =>
+      (terminal as readonly string[]).includes(value.status) && typeof value.occurredAt === "string"
+  )
+    .reduce<(ContactHealthDelivery & { occurredAt: string }) | null>(
+      (best, value) => best === null || value.occurredAt > best.occurredAt ? value : best,
+      null
+    );
+  if (!newest) return { lastTerminalStatus: null, lastTerminalAt: null, reachable: true };
+  return {
+    lastTerminalStatus: newest.status as typeof terminal[number],
+    lastTerminalAt: newest.occurredAt,
+    reachable: newest.status === "delivered" || (newest.status === "bounced" && newest.permanentBounce === false)
+  };
+}
+
+/** Authorize before every source read; retain host defaults, ambiguity, null and failure semantics. */
+export function createCustomer360ReadFacade<Search, Snapshot, SummaryRequest, SummaryResult, DiagnosticRequest, DiagnosticResult>(ports: {
+  authorize(): Promise<boolean>;
+  journey: Customer360ReadPort<Search, Snapshot>;
+  summary: Customer360SummaryReadPort<SummaryRequest, SummaryResult>;
+  diagnostics: DiagnosticHistoryReadPort<DiagnosticRequest, DiagnosticResult>;
+}) {
+  async function read<Result>(query: () => Promise<Result>) {
+    if (!await ports.authorize()) return { kind: "denied" as const };
+    return query();
+  }
+  return {
+    searchCustomerJourney: (request: Customer360Lookup) => read(() => ports.journey.searchCustomerJourney(request)),
+    getCustomerJourney: (request: Customer360Lookup) => read(() => ports.journey.getCustomerJourney(request)),
+    getPortableSummary: (request: SummaryRequest) => read(() => ports.summary.getPortableSummary(request)),
+    history: (request: DiagnosticRequest) => read(() => ports.diagnostics.history(request))
+  };
+}
+
+function recoveryEvent(row: Row): CustomerJourneyAuditEvent[] {
+  const eventId = string(row.id),
+    occurredAt = date(row.occurred_at),
+    id = string(row.case_id),
+    outcome = string(row.outcome);
+  if (!eventId || !occurredAt || !id || !outcome) return [];
+  const refusal = string(row.refusal_code);
+  return [{
+    eventId,
+    occurredAt,
+    action: "recovery.issue",
+    outcome: refusal ? `${outcome}:${refusal}` : outcome,
+    entity: { kind: "dunning_case", id }
+  }];
+}
+
+function latestNotice(rows: Row[], id: string, kind?: string) {
+  return rows.filter(
+    row => row.case_id === id && row.recipient_kind === "customer" && (!kind || row.notification_kind === kind)
+  )
+    .sort(
+      (a, b) => `${string(b.created_at) ?? ""}:${string(b.id) ?? ""}`.localeCompare(
+        `${string(a.created_at) ?? ""}:${string(a.id) ?? ""}`
+      )
+    )[0];
+}
+
+function string(value: unknown): string | null {
+  return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+
+function integer(value: unknown): number | null {
+  return typeof value === "number" && Number.isInteger(value) && value >= 0 ? value : null;
+}
+
+function date(value: unknown): string | null {
+  const text = string(value);
+  return text && !Number.isNaN(Date.parse(text)) ? text : null;
+}
+
+function latest(rows: Row[]): string | null {
+  return rows.map(
+    row => date(
+      row.updated_at ?? row.updatedAt ?? row.created_at ?? row.createdAt ?? row.occurred_at ?? row.occurredAt
+    )
+  )
+    .filter(value => value !== null)
+    .sort((a, b) => Date.parse(a) - Date.parse(b))
+    .at(-1)
+    ?? null;
+}

package/src/account-support/customerAccountReadDiagnostics.ts

@@ -0,0 +1,83 @@
+export type CustomerAccountReadStage = "account_aggregate";
+
+type DiagnosticRecord = Record<string, unknown>;
+
+export class CustomerAccountReadModelError extends Error {
+  readonly stage: CustomerAccountReadStage;
+  readonly cause: unknown;
+
+  constructor(stage: CustomerAccountReadStage, cause: unknown) {
+    super(`Customer account read model failed at ${stage}`);
+    this.name = "CustomerAccountReadModelError";
+    this.stage = stage;
+    this.cause = cause;
+  }
+}
+
+export async function withCustomerAccountReadStage<T>(
+  stage: CustomerAccountReadStage,
+  operation: () => Promise<T>,
+): Promise<T> {
+  try {
+    return await operation();
+  } catch (error) {
+    if (error instanceof CustomerAccountReadModelError) throw error;
+    throw new CustomerAccountReadModelError(stage, error);
+  }
+}
+
+export function customerAccountReadFailureDetails(error: unknown): DiagnosticRecord {
+  if (!(error instanceof CustomerAccountReadModelError)) {
+    return { reason: "read_model_failed", stage: "unknown" };
+  }
+  return {
+    reason: "read_model_failed",
+    stage: error.stage,
+    providerCode: diagnosticText(readRecord(error.cause).code),
+  };
+}
+
+export function logCustomerAccountReadFailure(error: unknown): void {
+  if (error instanceof CustomerAccountReadModelError) {
+    console.error("[customer-account] read model failed:", JSON.stringify({
+      stage: error.stage,
+      cause: safeCause(error.cause),
+    }));
+    return;
+  }
+
+  console.error("[customer-account] read failed:", JSON.stringify({ cause: safeCause(error) }));
+}
+
+function safeCause(error: unknown): DiagnosticRecord {
+  if (error instanceof Error) {
+    const record = readRecord(error);
+    return compact({
+      name: error.name,
+      message: error.message,
+      code: diagnosticText(record.code),
+      hint: diagnosticText(record.hint),
+      details: diagnosticText(record.details),
+    });
+  }
+  return compact({
+    type: typeof error,
+    code: diagnosticText(readRecord(error).code),
+    message: diagnosticText(readRecord(error).message),
+  });
+}
+
+function readRecord(value: unknown): DiagnosticRecord {
+  return value && typeof value === "object" && !Array.isArray(value) ? value as DiagnosticRecord : {};
+}
+
+function diagnosticText(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const trimmed = value.trim();
+  if (!trimmed) return undefined;
+  return trimmed.slice(0, 300);
+}
+
+function compact(value: DiagnosticRecord): DiagnosticRecord {
+  return Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== undefined));
+}

package/src/account-support/index.ts

@@ -0,0 +1,72 @@
+export { createAccountReadFacade } from "./accountReadFacade.js";
+export { CustomerAccountReadModelError, withCustomerAccountReadStage, customerAccountReadFailureDetails, logCustomerAccountReadFailure } from "./customerAccountReadDiagnostics.js";
+export type { CustomerAccountReadStage } from "./customerAccountReadDiagnostics.js";
+export type * from "./contracts/index.js";
+export {
+  CUSTOMER_ACCOUNT_V2_CONTRACT_VERSION,
+  readAccountSnapshot,
+  isCustomerVisibleSubscription,
+  recurringPrice,
+  computeEditState,
+  editCutoff,
+  buildActionRequired
+} from "./accountReadModels.js";
+export type {
+  AccountReadSources,
+  AccountReadProjectionPolicy,
+  CustomerSubscriptionEligibilityInput,
+  CustomerSubscriptionEligibility,
+  SubscriptionActionState
+} from "./accountReadModels.js";
+export {
+  CUSTOMER_ORDERS_CONTRACT_VERSION,
+  readCustomerOrderSummaries,
+  readCustomerOrderDetail,
+  customerOrderMoney,
+  toOrderMoneyHeader,
+  toOrderMoneyItem,
+  mapCustomerOrderLines,
+  lineListTotalMinor
+} from "./orderHistory.js";
+export type {
+  CustomerOrderHistoryRow,
+  CustomerOrderHistoryReadStore,
+  CustomerOrderLinePresentationPort,
+  CustomerOrderHistoryProjectionPort
+} from "./orderHistory.js";
+export {
+  SUPPORT_CUSTOMER_360_CONTRACT_VERSION,
+  projectCustomer360Snapshot,
+  deriveContactHealth,
+  boundedCustomerJourneyAudit,
+  createCustomer360ReadFacade
+} from "./customer360.js";
+export type {
+  Customer360ProjectionInput,
+  Customer360ProjectionPolicy,
+  ContactHealthDelivery,
+  CustomerJourneyAuditEvent
+} from "./customer360.js";
+export { createInvoiceAccess, downloadOwnedInvoicePdf, deriveCustomerDocumentDeliveryStatus } from "./invoiceAccess.js";
+export type {
+  InvoiceOwnerAccessPort,
+  InvoiceArtifactDownloadPort,
+  InvoiceAccessOptions,
+  CustomerInvoiceDocumentStatusInput
+} from "./invoiceAccess.js";
+export { createSelfServiceCommandFacade } from "./selfService.js";
+export { encodeNativeSubscriptionCommand, decodeNativeSubscriptionPreview, createNativeSubscriptionDriver } from "./subscriptionCommandCodec.js";
+export { createPaymentMethodComposition } from "./paymentMethodComposition.js";
+export { createOperatorRecovery, moveIdentityForEmailCorrection, OperatorIdentityMoveRefusedError, executeOperatorAccountLink, linkThenApply } from "./operatorRecovery.js";
+export type { OperatorRecoverySelection } from "./operatorRecovery.js";
+export { createManagedOperatorAuthority, operatorAuthorityCapabilities, CustomerSupportCommandInvalidError,
+  CustomerSupportCommandIdempotencyConflictError, OperatorSubscriptionAuthorityUnavailableError,
+  CustomerSupportCommandRequiresHumanError, CustomerSupportOperatorInactiveError, CustomerSupportOperatorNotProvisionedError } from "./operatorAuthority.js";
+export type { OperatorRpcExecutor, OperatorAuthorityOptions } from "./operatorAuthority.js";
+export { createPostgresOperatorAuthority } from "./postgresOperatorAuthority.js";
+export type { OperatorQueryExecutor, OperatorTransactionExecutor } from "./postgresOperatorAuthority.js";
+export { ACCOUNT_SUPPORT_MIGRATIONS } from "./migrations.js";
+export { createAccountSupportBindings } from "./bindings.js";
+export type { AccountSupportCallable, AccountSupportOperations, AccountSupportHostBindingRequired } from "./bindings.js";
+export { createAccountSupportServices } from "./contribution.js";
+export type { AccountSupportBindingRefusal, AccountSupportReadiness, GuardedAccountSupportOperation, GuardedAccountSupportOperations } from "./contribution.js";

package/src/account-support/invoiceAccess.ts

@@ -0,0 +1,63 @@
+import { createInvoiceReadModel } from "../invoicing/index.js";
+import type { InvoiceHostPorts } from "../invoicing/contracts/index.js";
+import type { CustomerDocumentDeliveryStatus } from "./contracts/invoice.js";
+
+export type InvoiceOwnerAccessPort = InvoiceHostPorts["accountHistory"];
+export type InvoiceArtifactDownloadPort = Pick<InvoiceHostPorts["artifacts"], "download">;
+
+export interface InvoiceAccessOptions {
+  accountHistory?: InvoiceOwnerAccessPort;
+  artifacts?: InvoiceArtifactDownloadPort
+}
+
+export function createInvoiceAccess(options: InvoiceAccessOptions = {}) {
+  const accountHistory = options.accountHistory;
+  const owner = createInvoiceReadModel({
+    ...options,
+    accountHistory: accountHistory && {
+      read: input => accountHistory.read(input),
+      async resolveDownload(input) {
+        const history = await accountHistory.read({ accountRef: input.accountRef, orderId: input.orderId });
+        if (history.kind !== "found") return history;
+        if (history.accountRef !== input.accountRef || history.orderId !== input.orderId
+          || !history.documents.some(document => document.documentRef === input.documentRef)) return { kind: "denied" };
+        return accountHistory.resolveDownload(input);
+      }
+    }
+  });
+  return { history: owner.history, download: owner.download };
+}
+
+export function downloadOwnedInvoicePdf<Ticket, Pdf extends { content: Uint8Array; contentType: string }>(input: {
+  resolve(): Promise<Ticket | null>;
+  download(ticket: Ticket): Promise<Pdf>
+}) {
+  return createInvoiceReadModel().ownedPdf(input);
+}
+
+export interface CustomerInvoiceDocumentStatusInput {
+  blockedReason: string | null;
+  status: string | null;
+  documentKind: string | null;
+  ksefStatus: string | null;
+  emailStatus: string | null;
+  outboxStatus: string | null;
+  downloadAvailable: boolean
+}
+
+export function deriveCustomerDocumentDeliveryStatus(input: CustomerInvoiceDocumentStatusInput): CustomerDocumentDeliveryStatus {
+  const status = normalized(input.status),
+    clearance = normalized(input.ksefStatus),
+    email = normalized(input.emailStatus),
+    outbox = normalized(input.outboxStatus);
+  if (input.blockedReason || ["rejected", "voided", "cancelled"].includes(status) || clearance === "rejected") return "requires_correction";
+  if (email === "failed" || ["failed", "uncertain", "cancelled"].includes(outbox)) return "delivery_failed";
+  if (input.documentKind === "b2b_vat" && !["accepted", "not_required"].includes(clearance)) return "ksef_pending";
+  if (["sent", "provider_accepted"].includes(email) || outbox === "succeeded") return "email_provider_accepted";
+  if (email === "pending" || ["pending", "processing"].includes(outbox)) return "email_pending";
+  return input.downloadAvailable ? "pdf_ready" : "not_ready";
+}
+
+function normalized(value: string | null): string {
+  return value?.trim().toLowerCase() ?? "";
+}

package/src/account-support/migrations.ts

@@ -0,0 +1,7 @@
+/** Sparse projections only. Install the complete native/managed prefix, never this list alone. */
+export const ACCOUNT_SUPPORT_MIGRATIONS = {
+  native: { units: [{ position: 87, catalogPath: "db/platform/migrations/20261026120000_account_support_operator_authority.sql",
+    sha256: "ac1e31679179e712d7558e7b1d82e8113f264abf9aaa44c2562ab988acdc7508",
+    url: new URL("../../sql/20261026120000_account_support_operator_authority.sql", import.meta.url) }] },
+  managed: { units: ["supabase/migrations/20261026120100_account_support_current_authority.sql"] },
+} as const;