@openlup/platform 0.20.0 → 0.22.0

package/src/payments/contracts/preparedAttempt.ts

@@ -0,0 +1,86 @@
+import type {
+  PaymentAttemptStatus,
+  PaymentExecutionBaseInput,
+  PaymentExecutionBaseResult,
+} from "@openlup/core/payment";
+
+/** Durable preparation facts; provider admission belongs to the caller. */
+export interface PreparedAttemptPrepareInput<P extends string = string> {
+  idempotencyKey: string;
+  paymentIntentId: string;
+  provider: P;
+  providerIdempotencyKey: string;
+  providerRequestFingerprint: string;
+  providerFlow: string;
+  paymentMethodRef?: string | null;
+  requestPayload: Record<string, unknown>;
+}
+
+export interface PreparedAttemptPersistenceResult<N extends string = string> {
+  paymentAttemptId: string;
+  status: PaymentAttemptStatus;
+  replayed: boolean;
+  providerAttemptId: string | null;
+  providerSessionId: string | null;
+  nextActionKind: N | null;
+}
+
+export interface PreparedAttemptFinalizeInput<N extends string = string> extends Pick<
+  PaymentExecutionBaseResult,
+  "providerAttemptId" | "providerSessionId" | "attemptStatus" | "requestPayload" | "responsePayload"
+> {
+  idempotencyKey: string;
+  paymentIntentId: string;
+  paymentAttemptId: string;
+  providerIdempotencyKey: string;
+  providerRequestFingerprint: string;
+  nextActionKind: N | null;
+}
+
+/** Only persistence capabilities needed by interactive attempt ordering. */
+export interface PreparedAttemptPersistencePort<P extends string = string, N extends string = string> {
+  prepareProviderAttempt(input: PreparedAttemptPrepareInput<P>): Promise<PreparedAttemptPersistenceResult<N>>;
+  finalizeProviderAttempt(input: PreparedAttemptFinalizeInput<N>): Promise<PreparedAttemptPersistenceResult<N>>;
+}
+
+export interface PreparedAttemptExecutionPort<I extends PaymentExecutionBaseInput, R extends PaymentExecutionBaseResult> {
+  validateInput?(input: I): void;
+  execute(input: I): Promise<R>;
+}
+
+/** Exact execution extensions and original input/port references cross this seam. */
+export interface PreparedAttemptExecutionInput<
+  I extends PaymentExecutionBaseInput,
+  R extends PaymentExecutionBaseResult,
+  P extends string,
+  N extends string,
+> {
+  paymentPort: PreparedAttemptPersistencePort<P, N>;
+  executionPort: PreparedAttemptExecutionPort<I, R>;
+  provider: P;
+  paymentIntentId: string;
+  executionInput: I;
+  prepareIdempotencyKey: string;
+  finalizeIdempotencyKey: string;
+  providerIdempotencyKey: string;
+  providerRequestFingerprint: string;
+  providerFlow: string;
+  paymentMethodRef?: string | null;
+  prepareRequestPayload: Record<string, unknown>;
+  validateExecution?: (execution: R) => void;
+}
+
+/** Synchronous, call-scoped native trust, diagnostics and error construction. */
+export interface PreparedAttemptFailurePolicy<E extends Error, N extends string> {
+  replayError(prepared: PreparedAttemptPersistenceResult<N>): Error;
+  isTrustedNoCharge(error: unknown): error is E;
+  logRetry(error: E, prepared: PreparedAttemptPersistenceResult<N>): void;
+  exhaustedError(error: E, first: E, prepared: PreparedAttemptPersistenceResult<N>): E;
+  executionError(error: unknown, prepared: PreparedAttemptPersistenceResult<N>): Error;
+  finalizationError(error: unknown, prepared: PreparedAttemptPersistenceResult<N>): Error;
+}
+
+export interface PreparedAttemptExecutionResult<R extends PaymentExecutionBaseResult> {
+  execution: R;
+  attempt: { paymentAttemptId: string; status: PaymentAttemptStatus };
+}

package/src/payments/contracts/reconciliation.ts

@@ -0,0 +1,296 @@
+import type { ProviderReadPurpose } from "./evidence.js";
+export type ReconciliationProviderKind = string;
+export type ProviderReconciliationStatusKind = "succeeded" | "failed" | "pending" | "unknown";
+
+export interface ProviderReconciliationStatus {
+  status: ProviderReconciliationStatusKind;
+  providerStatus: string;
+  occurredAt: string | null;
+  failureReason: string | null;
+  amountMinor: number | null;
+  currency: string | null;
+  rawPayload: Record<string, unknown>;
+}
+
+/**
+ * Who is asking, and therefore what an unresolved provider state MEANS.
+ *
+ * The same read answers two different questions. Reconciliation — the caller
+ * that names no purpose — asks "is this attempt over", long after the buyer
+ * left, and an intent still waiting for its first payment method is over. A
+ * buyer standing in a live checkout asks "is this attempt settled yet", and the
+ * same state means the opposite: nobody has been asked anything.
+ *
+ * ⛔ Omitting the purpose keeps the reconciliation reading. Terminalizing real
+ * abandonment is the more expensive of the two errors to lose, so it is the
+ * behaviour a caller gets by default rather than one it must opt into.
+ */
+
+
+export interface PaymentProviderReconciliationProvider {
+  readPayment(input: {
+    providerPaymentId: string;
+    attempt?: ClaimedPaymentAttempt;
+    purpose?: ProviderReadPurpose;
+  }): Promise<ProviderReconciliationStatus>;
+  /** Atomically close an incomplete provider object before minting a replacement. */
+  closePayment?(input: { providerPaymentId: string }): Promise<ProviderReconciliationStatus>;
+
+  /** Exact provider-side absence only; missing local acknowledgement is not
+   * absence proof and must never authorize another charge. */
+  findPaymentByLocalIntent?(input: {
+    attempt: ClaimedPaymentAttempt;
+  }): Promise<"found" | "absent">;
+}
+
+export interface ClaimedPaymentAttempt {
+  paymentAttemptId: string;
+  paymentIntentId: string;
+  paymentId: string;
+  orderId: string;
+  subscriptionId: string | null;
+  subscriptionCycleId: string | null;
+  provider: ReconciliationProviderKind;
+  providerPaymentId: string | null;
+  providerAttemptId: string | null;
+  providerSessionId: string | null;
+  attemptStatus: string;
+  intentStatus: string;
+  amountMinor: number;
+  currency: string;
+  orderMode: "one_time" | "subscription_cycle";
+  cycleRetryAttempt: number;
+  cycleNextRetryAt: string | null;
+  localUpdatedAt: string;
+}
+
+
+export type ManualInteractivePreparedAttemptAbsenceEvidence = {
+  providerAbsenceConfirmed: true;
+  watchdogEvidence: true;
+  evidenceCode: "operator_verified_absence" | "operator_documented_absence";
+};
+
+export interface InteractivePreparedAttemptReopenResult {
+  paymentAttemptId: string;
+  paymentIntentId: string;
+  paymentAttemptStatus: "failed";
+  paymentIntentStatus: "failed";
+  replayed: boolean;
+}
+
+export interface PaymentProviderReconciliationPort {
+  claimPreparedAttempts(input: {
+    now: string;
+    staleAfterSeconds: number;
+    limit: number;
+    claimKey: string;
+  }): Promise<ClaimedPaymentAttempt[]>;
+  claimStaleAttempts(input: {
+    now: string;
+    staleAfterSeconds: number;
+    limit: number;
+    claimKey: string;
+  }): Promise<ClaimedPaymentAttempt[]>;
+  recordEvidence(input: {
+    idempotencyKey: string;
+    provider: ReconciliationProviderKind;
+    providerPaymentId: string | null;
+    paymentIntentId: string;
+    paymentAttemptId: string;
+    localStatus: string;
+    providerStatus: string;
+    correctionStatus: "observed" | "corrected" | "ignored" | "failed";
+    checkedAt: string;
+    payload: Record<string, unknown>;
+  }): Promise<{ replayed: boolean }>;
+  applyTerminalResult(input: {
+    idempotencyKey: string;
+    expectedOrderId: string;
+    expectedPaymentIntentId: string;
+    expectedPaymentAttemptId: string;
+    expectedPaymentId: string;
+    provider: ReconciliationProviderKind;
+    providerPaymentId: string;
+    localStatus: string;
+    providerStatus: string;
+    resultStatus: "succeeded" | "failed";
+    occurredAt: string;
+    failureReason: string | null;
+    /**
+     * The class the reading adapter already decided for this refusal, persisted
+     * beside the refusal itself on both the attempt and the dunning case the
+     * terminal write opens.
+     *
+     * OPTIONAL, and absence is a real state rather than a default: a caller that
+     * omits it writes exactly what it wrote before this field existed, because
+     * the RPC coalesces it to NULL and the SQL treats a NULL class as "stamp
+     * nothing" rather than "stamp NULL". Two of this port's three consumers
+     * (`paymentVerifyNowService`, `checkoutRecoveryPaymentResolver`) resolve a
+     * payment without classifying it and are pinned to stay classification-absent.
+     *
+     * Shape mirrors `applyPaymentResultRpc` deliberately, so the synchronous
+     * decline rail and this polling rail hand the control plane the same object.
+     */
+    failureClassification?: { failureClass: string; decidedBy: string } | null;
+    checkedAt: string;
+    payload: Record<string, unknown>;
+  }): Promise<{
+    replayed: boolean;
+    paymentResult: {
+      paymentIntentId: string;
+      paymentAttemptId: string;
+      paymentId: string;
+      orderId: string;
+      status: string;
+      kind: string;
+      replayed: boolean;
+    };
+    correctionStatus: "corrected" | "ignored";
+    subscriptionWebhookDunning: {
+      opened: boolean;
+      replayed: boolean;
+      caseId: string | null;
+    } | null;
+  }>;
+  reopenPreparedAttemptAfterAbsence(input: {
+    idempotencyKey: string;
+    paymentAttemptId: string;
+    expectedPaymentIntentId: string;
+    expectedSubscriptionCycleId: string;
+    operatorRef: string;
+    absenceCheckedAt: string;
+    nextRetryAt: string;
+    absenceEvidence: Record<string, unknown>;
+  }): Promise<{ replayed: boolean }>;
+  /**
+   * Optional because the automatic reconciliation worker and its provider
+   * neutral fixtures must not acquire an operator-only interactive capability.
+   * A caller that selects this rail must require the narrow interface below.
+   */
+  reopenInteractivePreparedAttemptAfterAbsence?(input: {
+    idempotencyKey: string;
+    paymentAttemptId: string;
+    expectedPaymentIntentId: string;
+    expectedOrderId: string;
+    expectedSubscriptionId: string | null;
+    expectedSubscriptionCycleId: string | null;
+    operatorRef: string;
+    absenceCheckedAt: string;
+    absenceEvidence: ManualInteractivePreparedAttemptAbsenceEvidence;
+  }): Promise<InteractivePreparedAttemptReopenResult>;
+}
+
+/**
+ * Service-role operator boundary for an interactive checkout, distinct from
+ * the renewal retry RPC. It terminalizes the local prepared attempt after a
+ * human/provider absence confirmation; it never schedules dunning or cron.
+ */
+export interface InteractivePreparedAttemptManualReconciliationPort extends PaymentProviderReconciliationPort {
+  reopenInteractivePreparedAttemptAfterAbsence(input: {
+    idempotencyKey: string;
+    paymentAttemptId: string;
+    expectedPaymentIntentId: string;
+    expectedOrderId: string;
+    expectedSubscriptionId: string | null;
+    expectedSubscriptionCycleId: string | null;
+    operatorRef: string;
+    absenceCheckedAt: string;
+    absenceEvidence: ManualInteractivePreparedAttemptAbsenceEvidence;
+  }): Promise<InteractivePreparedAttemptReopenResult>;
+}
+
+export interface PaymentProviderReconciliationWorkerResult {
+  ok: boolean;
+  checked: number;
+  corrected: number;
+  succeeded: number;
+  failed: number;
+  pending: number;
+  unknown: number;
+  ignored: number;
+  dunningOpened: number;
+  replayed: number;
+  providerCalls: number;
+  preparedWithoutProviderAck: number;
+  preparedAttemptsReopened: number;
+  manualReview: number;
+  /**
+   * Attempts whose rail has answered non-terminally for longer than that rail
+   * declares normal. Counted, never acted on: elapsed time is not evidence
+   * about money, so this surfaces a case for a human rather than resolving it.
+   */
+  silenceOverdue: number;
+  amountCurrencyMismatches: number;
+  failures: number;
+  skipped: boolean;
+  reason?: string;
+}
+
+export interface PaymentProviderReconciliationWorkerInput {
+  port: PaymentProviderReconciliationPort;
+  providers: Partial<Record<ReconciliationProviderKind, PaymentProviderReconciliationProvider>>;
+  now?: string;
+  staleAfterSeconds?: number;
+  batchSize?: number;
+  claimKey?: string;
+  /**
+   * When true, prepared attempts whose provider proves absence (see
+   * PaymentProviderReconciliationProvider.findPaymentByLocalIntent) and that
+   * are at least MIN_PREPARED_ABSENCE_REOPEN_AGE_SECONDS old are automatically
+   * reopened for cron retry via the operator RPC. Default false — the
+   * stranded-attempt loop stays operator-manual unless the flag is on.
+   */
+  autoReopenPreparedAbsence?: boolean;
+  /**
+   * Published rail capabilities, read to learn how long a non-terminal answer
+   * from each rail is still normal. Optional: without it no attempt is ever
+   * counted overdue, so omitting it preserves today's behaviour exactly.
+   */
+  capabilities?: SilenceWindowLookup;
+}
+
+/**
+ * The narrow slice of the capability registry this worker reads.
+ *
+ * Declared here rather than importing the whole registry type so the worker
+ * depends on the one question it asks - "when does this rail's silence stop
+ * being normal" - and not on the shape of every unattended-charge capability.
+ */
+export interface SilenceWindowLookup {
+  get(providerKind: string): { terminalOutcomeReporting?: { silenceBecomesSuspectAfterMinutes: number } } | null;
+}
+
+
+
+export interface VerifiableAttemptSnapshot {
+  orderId: string;
+  orderClientId: string;
+  orderMode: string;
+  paymentIntentId: string;
+  intentStatus: string;
+  intentProviderPaymentId: string | null;
+  paymentAttemptId: string;
+  paymentId: string;
+  attemptStatus: string;
+  provider: string;
+  providerAttemptId: string | null;
+  providerSessionId: string | null;
+  amountMinor: number;
+  currency: string;
+  localUpdatedAt: string;
+}
+
+
+export interface PaymentVerifyReadPort {
+  readVerifiableAttempt(input: {
+    orderId: string;
+    paymentIntentId: string;
+  }): Promise<VerifiableAttemptSnapshot | null>;
+}
+
+
+export type PaymentVerifyNowResult =
+  | { status: string; verified: false; applied: false; providerPaymentId: string | null; attempt: ClaimedPaymentAttempt | null }
+  | { status: "unavailable" | "pending" | "manual_review"; verified: boolean; applied: false; providerPaymentId: string | null; attempt: ClaimedPaymentAttempt | null }
+  | { status: "succeeded" | "failed"; verified: true; applied: boolean; providerPaymentId: string; attempt: ClaimedPaymentAttempt };

package/src/payments/contracts/repair.ts

@@ -0,0 +1,95 @@
+import type { PaymentMethodHandoff } from "./adapter.js";
+import type { ClaimedPaymentAttempt, PaymentProviderReconciliationProvider, ProviderReconciliationStatus, PaymentVerifyReadPort } from "./reconciliation.js";
+import type { ProviderReadPurpose } from "./evidence.js";
+
+export type CheckoutRecoveryPaymentResolution =
+  | { kind: "paid" }
+  | { kind: "retry_new" }
+  | { kind: "resume_existing"; clientAction: PaymentRecoveryAction }
+  | { kind: "awaiting_provider" }
+  | { kind: "manual_review" };
+
+export interface ProviderPaymentReferenceInput {
+  providerAttemptId: string | null;
+  providerSessionId: string | null;
+  intentProviderPaymentId: string | null;
+}
+
+export type PaymentRecoveryAction = { provider: string } & PaymentMethodHandoff;
+
+export interface ProviderRecoveryRead {
+  status: ProviderReconciliationStatus;
+  identityMatches: boolean;
+  configuredMoneyMatches: boolean;
+  manualReviewRequired: boolean;
+  clientAction: PaymentRecoveryAction | null;
+}
+
+/**
+ * Recovery is an explicit capability, not an optional method on generic
+ * reconciliation providers. One read returns both PSP truth and any transient
+ * buyer action, so a redeem never calls the provider twice.
+ */
+export interface PaymentProviderRecoveryProvider extends PaymentProviderReconciliationProvider {
+  resolvePaymentReference(input: ProviderPaymentReferenceInput): string | null;
+  readRecoveryPayment(input: {
+    providerPaymentId: string;
+    attempt: ClaimedPaymentAttempt;
+    purpose?: ProviderReadPurpose;
+  }): Promise<ProviderRecoveryRead>;
+}
+
+export interface CheckoutRecoveryPaymentResolver {
+  resolve(input: {
+    orderId: string;
+    paymentIntentId: string | null;
+    intentStatus?: string | null;
+  }): Promise<CheckoutRecoveryPaymentResolution>;
+}
+
+
+export interface ActivePaymentActionAuthority {
+  orderId: string;
+  clientId: string;
+  paymentIntentId: string;
+  paymentAttemptId: string;
+  executionRail: string;
+}
+
+export interface CheckoutActivePaymentActionResolver {
+  readActiveAction(authority: ActivePaymentActionAuthority): Promise<PaymentRecoveryAction | null>;
+}
+
+export type CheckoutActionReadProvider = Pick<
+  PaymentProviderRecoveryProvider,
+  "resolvePaymentReference" | "readRecoveryPayment"
+>;
+
+
+/** Method collection only. Hosts authorize ownership before calling this port.
+ * The result never confirms payment, redeems a token or writes a subscription.
+ * Handoffs remain transient; unsupported must be shown as an explicit refusal.
+ */
+export interface PaymentRepairMethodPort {
+  setupMethod(input: {
+    customer: string;
+    metadata: Record<string, string>;
+    idempotencyKey: string;
+  }): Promise<
+    | { kind: "ready"; setupRef: string; handoff: PaymentMethodHandoff; replayed: boolean }
+    | { kind: "unsupported" }
+  >;
+}
+
+/** Host-selected durable truth scope. Unsupported schema never opens a store. */
+export interface PaymentServicesOptions {
+  schema?: { truth: "supported" | "unsupported" };
+  openTruth?: () => Promise<{
+    port: import("./truth.js").PaymentTruthPort;
+    close(): Promise<void>;
+  }>;
+}
+
+export interface PaymentServices {
+  run<T>(work: (port: import("./truth.js").PaymentTruthPort) => Promise<T>): Promise<T>;
+}

package/src/payments/contracts/truth.ts

@@ -0,0 +1,108 @@
+
+
+export type PaymentTruthOutcome = "captured" | "refused" | "indeterminate";
+
+
+/**
+ * How a refusal looked to the settlement source that reported it.
+ *
+ * NOT the retry taxonomy. `PaymentFailureClass` in `@openlup/core/payment` is a
+ * different vocabulary with no value in common: that one answers "may this be
+ * retried, and how", and is what `commerce_payment_attempts.failure_class`
+ * persists. This one answers "what did the source say happened" and never leaves
+ * this module's reconciliation ledger. They shared a name until this wave, which
+ * meant an import could quietly resolve to the wrong five strings.
+ */
+export type PaymentTruthRefusalClass =
+  | "authorization_refused"
+  | "insufficient_funds"
+  | "method_unavailable"
+  | "risk_refused"
+  | "unknown_refusal";
+
+
+export type PaymentSourceEvidence = {
+  sourceKind: "accepted_event" | "reconciliation_read";
+  sourceReference: string;
+  observedStatus: string;
+  observedAt: string;
+  payloadFingerprint: string;
+};
+
+
+export type PaymentTruthEvent = {
+  sourceEventId: string;
+  idempotencyKey: string;
+  settlementIntentId: string;
+  outcome: PaymentTruthOutcome;
+  amountMinor: number;
+  currency: string;
+  occurredAt: string;
+  failure: { classification: PaymentTruthRefusalClass; reason: string | null } | null;
+  evidence: PaymentSourceEvidence;
+};
+
+
+export type PaymentReconciliationResult = {
+  eventId: string;
+  idempotencyKey: string;
+  evidenceStatus: "observed" | "failed";
+  outcome: PaymentTruthOutcome;
+  occurredAt: string;
+  failure: PaymentTruthEvent["failure"];
+  evidence: PaymentSourceEvidence;
+};
+
+
+export type PaymentTruthReadback = {
+  event: {
+    id: string;
+    sourceEventId: string;
+    fingerprint: string;
+    state: "open" | "settled";
+    outcome: PaymentTruthOutcome;
+    replayed: boolean;
+  };
+  effects: {
+    paymentResultRecorded: boolean;
+    dunningOpened: boolean;
+    accountingRequested: boolean;
+  };
+  financial: {
+    settlementStatus: string | null;
+    orderStatus: string | null;
+    subscriptionStatus: string | null;
+    accountingStatus: string | null;
+    amountMinor: number;
+    currency: string;
+  };
+};
+
+
+export interface PaymentTruthPort {
+  ingestEvent(input: PaymentTruthEvent): Promise<PaymentTruthReadback>;
+  recordReconciliation(input: PaymentReconciliationResult): Promise<PaymentTruthReadback>;
+  sweepOpenEvents(input: { now: string; limit: number }): Promise<{
+    claimed: number;
+    settledIgnored: number;
+    eventIds: string[];
+  }>;
+  readEvent(eventId: string): Promise<PaymentTruthReadback | null>;
+}
+
+
+export type CanonicalPaymentSource = {
+  sourceEventId: string;
+  eventKind: string;
+  settlementIntentId: string | null;
+  amountMinor: number | null;
+  currency: string | null;
+  occurredAt: string | null;
+  payloadFingerprint: string;
+};
+
+export type PostgresPaymentTruthOptions = {
+  dunningTemplateSlug: string;
+  recoveryUrlPath: string;
+  recoveryTemplateSlug: string;
+};