@openlup/platform 0.20.0 → 0.21.0

package/dist/payments/tpay/classifyDecline.d.ts

@@ -0,0 +1,46 @@
+import { type PaymentExecutionProviderDecline, type PaymentFailureClassification } from "@openlup/core/payment";
+export declare const DECLINE_FAILURE_REASONS: {
+    /** The payer's bank cannot register a reusable mandate — offer a card instead. */
+    readonly mandateUnsupported: "blik_recurring_unsupported_bank";
+    /** Declined for a reason the provider did not distinguish. */
+    readonly generic: "provider_declined";
+};
+/** Maps a provider refusal to the stable code persisted as `failure_reason`. */
+export declare function declineFailureReason(decline: PaymentExecutionProviderDecline): string;
+/**
+ * The one place a refused payment gets a class, for every rail that consumes a
+ * synchronous decline: interactive checkout, checkout recovery, and the
+ * off-session renewal cron.
+ *
+ * Provider-agnostic on purpose. Every code the adapter understood has already
+ * been translated into `adviceCode` and `neutralReasonHints` by the adapter that
+ * owns the vocabulary, so nothing here needs to know which provider refused.
+ *
+ * The one reading this seam adds is the mandate flag. `mandateUnsupported` is a
+ * neutral capability statement any adapter may set, and it is what produces the
+ * scheme-named failure reason below; asserting the matching hint is what turns
+ * that reason into `mandate_dead` instead of leaving it unclassified. Doing it
+ * here rather than per adapter means a second adapter setting the same flag gets
+ * the same class without repeating the mapping.
+ *
+ * DISPLAY-LOAD-BEARING, and NOT a cadence input. Three live readers turn the
+ * class this seam decides into what the payer is told: `dunningFailureClassPort`
+ * reads it off the case, `customerAccountActionRequiredReadModel` selects it into
+ * the account surface, and `paymentRecoverySetupHandler` renders it as the cause
+ * sentence on the recovery page. What still does NOT read it is the retry ladder:
+ * no cadence, retry decision or scheduling branch consults the class, and that
+ * wave stays gated on validating this taxonomy against the historical corpus.
+ *
+ * `failureReasonKey` overrides the reason this seam would derive itself, and is
+ * supplied by a rail that persists a DIFFERENT reason string with the attempt:
+ * the reconciliation rail writes its own adapter-prefixed key, not
+ * `provider_declined`. That key is the classifier's weakest evidence tier, so
+ * the override changes a class only where the rail's own key is mapped; what it
+ * always changes is `decidedBy`, and that is the point. The historical-corpus
+ * replay reproduces a verdict from the stored attempt row, so the key named in
+ * the telemetry has to be the key actually on that row rather than one this seam
+ * invented for itself.
+ */
+export declare function classifyDecline(decline: PaymentExecutionProviderDecline, options?: {
+    failureReasonKey?: string;
+}): PaymentFailureClassification;

package/dist/payments/tpay/classifyDecline.js

@@ -0,0 +1,58 @@
+import { classifyPaymentFailure } from "@openlup/core/payment";
+export const DECLINE_FAILURE_REASONS = {
+    /** The payer's bank cannot register a reusable mandate — offer a card instead. */
+    mandateUnsupported: "blik_recurring_unsupported_bank",
+    /** Declined for a reason the provider did not distinguish. */
+    generic: "provider_declined",
+};
+/** Maps a provider refusal to the stable code persisted as `failure_reason`. */
+export function declineFailureReason(decline) {
+    return decline.mandateUnsupported
+        ? DECLINE_FAILURE_REASONS.mandateUnsupported
+        : DECLINE_FAILURE_REASONS.generic;
+}
+/**
+ * The one place a refused payment gets a class, for every rail that consumes a
+ * synchronous decline: interactive checkout, checkout recovery, and the
+ * off-session renewal cron.
+ *
+ * Provider-agnostic on purpose. Every code the adapter understood has already
+ * been translated into `adviceCode` and `neutralReasonHints` by the adapter that
+ * owns the vocabulary, so nothing here needs to know which provider refused.
+ *
+ * The one reading this seam adds is the mandate flag. `mandateUnsupported` is a
+ * neutral capability statement any adapter may set, and it is what produces the
+ * scheme-named failure reason below; asserting the matching hint is what turns
+ * that reason into `mandate_dead` instead of leaving it unclassified. Doing it
+ * here rather than per adapter means a second adapter setting the same flag gets
+ * the same class without repeating the mapping.
+ *
+ * DISPLAY-LOAD-BEARING, and NOT a cadence input. Three live readers turn the
+ * class this seam decides into what the payer is told: `dunningFailureClassPort`
+ * reads it off the case, `customerAccountActionRequiredReadModel` selects it into
+ * the account surface, and `paymentRecoverySetupHandler` renders it as the cause
+ * sentence on the recovery page. What still does NOT read it is the retry ladder:
+ * no cadence, retry decision or scheduling branch consults the class, and that
+ * wave stays gated on validating this taxonomy against the historical corpus.
+ *
+ * `failureReasonKey` overrides the reason this seam would derive itself, and is
+ * supplied by a rail that persists a DIFFERENT reason string with the attempt:
+ * the reconciliation rail writes its own adapter-prefixed key, not
+ * `provider_declined`. That key is the classifier's weakest evidence tier, so
+ * the override changes a class only where the rail's own key is mapped; what it
+ * always changes is `decidedBy`, and that is the point. The historical-corpus
+ * replay reproduces a verdict from the stored attempt row, so the key named in
+ * the telemetry has to be the key actually on that row rather than one this seam
+ * invented for itself.
+ */
+export function classifyDecline(decline, options = {}) {
+    const asserted = [...(decline.neutralReasonHints ?? [])];
+    if (decline.mandateUnsupported)
+        asserted.push("mandateUnsupported");
+    return classifyPaymentFailure({
+        adviceCode: decline.adviceCode,
+        declineCode: decline.declineCode,
+        neutralReasonHints: asserted,
+        failureReasonKey: options.failureReasonKey ?? declineFailureReason(decline),
+    });
+}

package/dist/payments/tpay/declineFailureHints.d.ts

@@ -0,0 +1,72 @@
+import type { PaymentFailureHint, PaymentRetryAdviceCode } from "@openlup/core/payment";
+/**
+ * ⚠️ UNOFFICIAL INFERENCE — the whole table below.
+ *
+ * The provider publishes no retryable-versus-terminal classification for these
+ * numeric refusal codes. Every row is this adapter's reading of the code's
+ * documented MEANING, not a documented retry verdict, and one of them
+ * (`"100"`) appears in no published table at all. Treat the table as a
+ * hypothesis under test. The class it produces is already DISPLAY-load-bearing:
+ * it becomes the sentence the payer reads about their own refusal, so a wrong
+ * row here misinforms a customer today. It is still not a cadence input: the
+ * dunning programme validates this table against the historical refusal corpus
+ * before anything in the retry ladder is allowed to branch on it.
+ *
+ * The contract that would end the inference is OUTSTANDING, not absent: the
+ * dunning programme's letter to the provider asks for the official meaning of
+ * these codes, and is tracked there as an open item. Until it is answered, a row
+ * may be read more narrowly than it is written — see `assertableHints` in
+ * `tpayDeclineEvidence.ts`, where each observation decides how much of its own
+ * reading it is entitled to state — but no row may be read more widely.
+ *
+ * Two rails read this table, and both reach it through the attempt log's
+ * `paymentErrorCode`: the reconciliation poll, and — since the 2026-08-26
+ * incident — the synchronous execution path, which until then decided a
+ * mandate refusal by pattern-matching the refusal MESSAGE.
+ *
+ * Codes arrive as strings because that is how they leave the transport layer.
+ *
+ * Two rows carry a decision worth stating rather than a lookup:
+ *
+ *   - `"101"` (refused by the payer) and `"107"` (refused on security grounds)
+ *     are NOT credential death — the instrument may be in perfect health and
+ *     the payer may approve the very next charge on it. There is no hint for
+ *     "terminal for this attempt, instrument fine", so this adapter instead
+ *     states the retry verdict directly, as advice: an unattended repeat of a
+ *     refusal the payer or their bank made deliberately is the retry that
+ *     cannot succeed and still costs a scheme fee. Naming it as advice is also
+ *     the more honest shape — it records what this adapter concludes about
+ *     RETRYING, without asserting anything about the instrument.
+ *   - `"100"` and `"102"` get NO reading. Nothing published says what they mean
+ *     precisely enough to classify, and `indeterminate` is the correct answer to
+ *     a code we cannot read. They are named in
+ *     `KNOWN_UNREADABLE_DECLINE_CODES` below, so their absence stays a recorded
+ *     decision rather than an oversight.
+ */
+export interface DeclineCodeReading {
+    hints?: readonly PaymentFailureHint[];
+    adviceCode?: PaymentRetryAdviceCode;
+}
+export declare const DECLINE_CODE_READING_TABLE: Readonly<Record<string, DeclineCodeReading>>;
+/**
+ * Codes this adapter has SEEN and still cannot read. They are deliberately absent
+ * from the table above rather than mapped to a guess: a row there must state
+ * vocabulary the kernel declares, and `indeterminate` is the honest answer to a
+ * code whose meaning is unconfirmed. Listing them here separates "we have met
+ * this code and refuse to invent its semantics" from "we have never seen it",
+ * which read identically at the lookup.
+ *
+ *   - `"100"` — observed in production on 2026-08-26, as the first attempt of a
+ *     refused mandate registration whose second attempt was `"105"`. Nothing
+ *     published says what it means, so it maps to no hint and no advice.
+ *   - `"102"` — same standing, from the same unpublished range.
+ *
+ * A code moving out of this list into the table is a semantics decision backed by
+ * evidence, not a lookup edit.
+ */
+export declare const KNOWN_UNREADABLE_DECLINE_CODES: readonly string[];
+/**
+ * This adapter's reading of one refusal code. Own-property lookup, so an
+ * inherited key (`constructor`, `toString`) is not a mapping.
+ */
+export declare function declineCodeReading(code: string | undefined): DeclineCodeReading;

package/dist/payments/tpay/declineFailureHints.js

@@ -0,0 +1,37 @@
+export const DECLINE_CODE_READING_TABLE = Object.freeze({
+    "101": Object.freeze({ adviceCode: "do_not_try_again" }),
+    "103": Object.freeze({ hints: Object.freeze(["transient"]) }),
+    "104": Object.freeze({ hints: Object.freeze(["transient"]) }),
+    "105": Object.freeze({ hints: Object.freeze(["mandateUnsupported"]) }),
+    "106": Object.freeze({ hints: Object.freeze(["limitExceeded"]) }),
+    "107": Object.freeze({ adviceCode: "do_not_try_again" }),
+});
+/**
+ * Codes this adapter has SEEN and still cannot read. They are deliberately absent
+ * from the table above rather than mapped to a guess: a row there must state
+ * vocabulary the kernel declares, and `indeterminate` is the honest answer to a
+ * code whose meaning is unconfirmed. Listing them here separates "we have met
+ * this code and refuse to invent its semantics" from "we have never seen it",
+ * which read identically at the lookup.
+ *
+ *   - `"100"` — observed in production on 2026-08-26, as the first attempt of a
+ *     refused mandate registration whose second attempt was `"105"`. Nothing
+ *     published says what it means, so it maps to no hint and no advice.
+ *   - `"102"` — same standing, from the same unpublished range.
+ *
+ * A code moving out of this list into the table is a semantics decision backed by
+ * evidence, not a lookup edit.
+ */
+export const KNOWN_UNREADABLE_DECLINE_CODES = Object.freeze(["100", "102"]);
+const NO_READING = Object.freeze({});
+/**
+ * This adapter's reading of one refusal code. Own-property lookup, so an
+ * inherited key (`constructor`, `toString`) is not a mapping.
+ */
+export function declineCodeReading(code) {
+    if (code === undefined)
+        return NO_READING;
+    return Object.prototype.hasOwnProperty.call(DECLINE_CODE_READING_TABLE, code)
+        ? DECLINE_CODE_READING_TABLE[code]
+        : NO_READING;
+}

package/dist/payments/tpay/donorContracts.d.ts

@@ -0,0 +1,140 @@
+/** Private structural contracts for the unchanged execution and observation slices. */
+import type { PaymentExecutionBaseInput, PaymentExecutionBaseResult } from "@openlup/core/payment";
+import type { ProviderReadPurpose } from "../contracts/index.js";
+export type PaymentProviderFlow = "one_time_payment" | "setup_reusable_method" | "off_session_payment" | "blik_one_time" | "blik_one_click" | "pbl_one_time" | "blik_recurring_activation" | "recurring_charge";
+export declare const PAYMENT_NEXT_ACTION_KINDS: readonly ["redirect", "3ds_challenge", "sca_required"];
+export type PaymentNextActionKind = (typeof PAYMENT_NEXT_ACTION_KINDS)[number];
+export interface PaymentExecutionInput extends PaymentExecutionBaseInput {
+    orderRef: string;
+    orderId?: string;
+    subjectId?: string | null;
+    returnContext?: "public" | "account";
+    payer?: {
+        email: string;
+        name: string;
+        ip?: string | null;
+        userAgent?: string | null;
+    };
+    transientProviderInput?: TpayTransientProviderInput | null;
+    paymentMethodAliasType?: "UID" | "PAYID";
+    paymentMethodRecurringModel?: "O" | "M";
+    providerFlow?: PaymentProviderFlow;
+    customerRef?: string;
+    paymentMethodRef?: string;
+    saveForFutureUse?: boolean;
+    clientId?: string;
+}
+export interface PaymentExecutionResult extends PaymentExecutionBaseResult {
+    nextActionKind: PaymentNextActionKind | null;
+    redirectUrl?: string | null;
+    clientSecret?: string | null;
+    customerProviderRef?: string | null;
+    paymentMethodRef?: string | null;
+    webhookExpected?: boolean;
+    recoveryRequired?: boolean;
+}
+export interface PaymentExecutionPort {
+    validateInput?(input: PaymentExecutionInput): void;
+    execute(input: PaymentExecutionInput): Promise<PaymentExecutionResult>;
+}
+export type PaymentWebhookEventType = "payment.succeeded" | "payment.failed" | "payment.refunded" | "payment.requires_action" | "payment.disputed" | "setup.succeeded" | "setup.failed" | "setup.requires_action";
+export interface CanonicalPaymentEvent {
+    provider_event_id: string;
+    event_type: PaymentWebhookEventType;
+    payment_provider_id: string;
+    amount_minor?: number;
+    next_action_kind?: PaymentNextActionKind;
+    raw_payload: Record<string, unknown>;
+}
+export interface NormalizedProviderPaymentWebhook {
+    provider: string;
+    providerEventId: string;
+    eventType: PaymentWebhookEventType;
+    providerPaymentId: string;
+    paymentIntentId?: string | null;
+    paymentAttemptId?: string | null;
+    amountMinor?: number | null;
+    currency?: string | null;
+    occurredAt: string;
+    refundKind?: "full" | "partial" | null;
+    rawPayload: Record<string, unknown>;
+    reusableMethod?: {
+        clientId: string;
+        subscriptionId?: string | null;
+        providerCustomerRef?: string | null;
+        providerMethodRef: string;
+        providerMandateRef?: string | null;
+        methodKind: "card";
+        status: "active";
+        consentSnapshot?: Record<string, unknown>;
+    } | null;
+}
+export interface ProviderReconciliationStatus {
+    status: "succeeded" | "failed" | "pending" | "unknown";
+    providerStatus: string;
+    occurredAt: string | null;
+    failureReason: string | null;
+    amountMinor: number | null;
+    currency: string | null;
+    rawPayload: Record<string, unknown>;
+}
+export interface ClaimedPaymentAttempt {
+    paymentAttemptId: string;
+    paymentIntentId: string;
+    paymentId: string;
+    orderId: string;
+    subscriptionId: string | null;
+    subscriptionCycleId: string | null;
+    provider: string;
+    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 ProviderRecoveryAction = {
+    kind: "redirect";
+    url: string;
+};
+export interface PaymentProviderRecoveryProvider {
+    resolvePaymentReference(input: {
+        providerAttemptId: string | null;
+        intentProviderPaymentId: string | null;
+        providerSessionId: string | null;
+    }): string | null;
+    readPayment(input: {
+        providerPaymentId: string;
+        attempt?: ClaimedPaymentAttempt;
+        purpose?: ProviderReadPurpose;
+    }): Promise<ProviderReconciliationStatus>;
+    readRecoveryPayment(input: {
+        providerPaymentId: string;
+        attempt: Pick<ClaimedPaymentAttempt, "amountMinor" | "currency">;
+        purpose?: ProviderReadPurpose;
+    }): Promise<{
+        status: ProviderReconciliationStatus;
+        identityMatches: boolean;
+        configuredMoneyMatches: boolean;
+        manualReviewRequired: boolean;
+        clientAction: ProviderRecoveryAction | null;
+    }>;
+    closePayment?(input: {
+        providerPaymentId: string;
+    }): Promise<ProviderReconciliationStatus>;
+    findPaymentByLocalIntent?(input: {
+        attempt: ClaimedPaymentAttempt;
+    }): Promise<"found" | "absent">;
+}
+export interface TpayTransientProviderInput {
+    provider: "tpay";
+    flow: "blik_one_time" | "blik_one_click" | "pbl_one_time" | "blik_recurring_activation" | "recurring_charge";
+    blikToken?: string;
+    channelId?: string;
+    recurringModel?: "O" | "M";
+}

package/dist/payments/tpay/donorContracts.js

@@ -0,0 +1 @@
+export const PAYMENT_NEXT_ACTION_KINDS = ["redirect", "3ds_challenge", "sca_required"];

package/dist/payments/tpay/index.d.ts

@@ -0,0 +1,43 @@
+import type { PaymentAdapter } from "../contracts/index.js";
+export { tpayPaymentCapabilities } from "./capabilities.js";
+import { type TpayJwsCertificateResolver } from "./webhookJwsVerifier.js";
+/** Explicit host configuration. clock returns UTC seconds; imports perform no I/O. */
+export interface TpayPaymentAdapterConfig {
+    http: {
+        baseUrl: string;
+        clientId: string;
+        clientSecret: string;
+        fetchImpl: (url: string, init?: {
+            method?: string;
+            headers?: Record<string, string>;
+            body?: string;
+            signal?: AbortSignal;
+        }) => Promise<{
+            ok: boolean;
+            status: number;
+            json(): Promise<unknown>;
+            text(): Promise<string>;
+        }>;
+        timeoutMs?: number;
+    };
+    notification: {
+        rootCertificatePem: string;
+        /** HTTPS certificate directory ending in a slash; resolver must enforce redirect/egress policy. */
+        allowedCertificateUrlPrefix: string;
+        resolveCertificate: TpayJwsCertificateResolver;
+        /** Seven days by default: generous retry allowance assumed until provider schedule is established. */
+        maxNotificationAgeSeconds?: number;
+        /** Maximum future signed issue time relative to receipt; defaults to 300 seconds. */
+        maxClockSkewSeconds?: number;
+    };
+    urls: {
+        notificationUrl: string;
+        successUrl: string;
+        errorUrl: string;
+    };
+    modelOActivationEnabled: boolean;
+    mode: "live" | "test";
+    clock?: () => number;
+}
+/** Construction explicitly selects this adapter; the host owns account activation and I/O policy. */
+export declare function createTpayPaymentAdapter(config: TpayPaymentAdapterConfig): PaymentAdapter;