@openlup/platform 0.19.0 → 0.21.0

package/dist/payments/stripe/stripeWebhookNormalizer.js

@@ -0,0 +1,243 @@
+import { stripeWebhookPayload } from "./stripeFailureEvidence.js";
+import { stripeRefundEvidence } from "./stripeRefundEvidence.js";
+import { expiryInstantFromMonthYear } from "@openlup/core/payment";
+import { methodFactSnapshotKeys } from "./methodFacts.js";
+const PROVIDER_KIND = "stripe";
+const METHOD_LIFECYCLE_EVENTS = {
+    "payment_method.attached": { kind: "method_registered", canonical: "setup.succeeded" },
+    "payment_method.automatically_updated": { kind: "method_updated", canonical: "setup.succeeded" },
+    "payment_method.detached": { kind: "method_revoked", canonical: "setup.failed" },
+};
+const SUPPORTED_EVENT_TYPES = new Set([
+    "payment.requires_action",
+    "payment.succeeded",
+    "payment.failed",
+    "payment.refunded",
+    "payment.disputed",
+    "setup.succeeded",
+    "setup.failed",
+    "setup.requires_action",
+]);
+/**
+ * Convert a verified raw Stripe webhook payload into the plural handler's
+ * `NormalizedProviderPaymentWebhook` shape.
+ *
+ * Reusable method extraction (Wave C): populated for `setup_intent.succeeded`
+ * always, and for `payment_intent.succeeded` when `setup_future_usage` was
+ * requested at PaymentIntent creation. Requires `metadata.clientId` to be set
+ * (the adapter does this when the runtime caller passes `clientId` through
+ * `PaymentExecutionInput`). When metadata is missing, `reusableMethod` stays
+ * null and the plural handler skips the method-ref upsert — safe degradation
+ * rather than crashing the webhook.
+ */
+export function normalizeStripeWebhookEvent(rawPayload) {
+    const providerEventId = readString(rawPayload, "id");
+    const eventType = readString(rawPayload, "type");
+    const data = readObject(rawPayload, "data");
+    const object = readObject(data, "object");
+    const canonicalEventType = mapStripeEventType(eventType, object);
+    const providerPaymentId = resolveLinkagePaymentId(eventType, object);
+    // Payment-control compares this against the intent's `amount_cents` (the order
+    // total) as a tamper guard, so we want the PaymentIntent's authorized `amount`,
+    // not `amount_received`. On a declined/canceled PI Stripe reports
+    // `amount_received: 0` while `amount` still holds the full total — and `??`
+    // does NOT treat `0` as nullish, so reading `amount_received` first yielded a
+    // `0` that tripped the amount-mismatch guard and left every failed event
+    // unreconciled (intent stuck `processing`, inventory holds leaked). Prefer
+    // `amount`; fall back to `amount_received` only when `amount` is absent.
+    const amountMinor = readOptionalNumber(object, "amount") ??
+        readOptionalNumber(object, "amount_received") ??
+        null;
+    const currency = readOptionalString(object, "currency")?.toUpperCase() ?? null;
+    const occurredAt = readOccurredAt(rawPayload);
+    const reusableMethod = extractReusableMethod(canonicalEventType, object);
+    const refund = stripeRefundEvidence(eventType, object);
+    return {
+        provider: PROVIDER_KIND,
+        providerEventId,
+        eventType: canonicalEventType,
+        providerPaymentId,
+        paymentIntentId: null,
+        paymentAttemptId: null,
+        amountMinor,
+        currency,
+        occurredAt,
+        refundKind: refund.refundKind,
+        rawPayload: {
+            ...stripeWebhookPayload({ eventId: providerEventId, eventType, providerPaymentId, amountMinor, currency }, object),
+            ...(refund.snapshot ? { stripeRefundSnapshot: refund.snapshot } : {}),
+        },
+        reusableMethod,
+        methodLifecycle: extractMethodLifecycle(eventType, object, providerEventId, occurredAt),
+    };
+}
+/** The neutral transition this delivery reports, or null when it reports none. */
+function extractMethodLifecycle(rawEventType, object, providerEventId, occurredAt) {
+    const mapping = METHOD_LIFECYCLE_EVENTS[rawEventType];
+    // On a method-family event the webhook object IS the method, so its own id is
+    // the reference the stored row is keyed by.
+    const providerMethodRef = readOptionalString(object, "id");
+    if (!mapping || !providerMethodRef)
+        return null;
+    const replacement = readMethodFacts(object);
+    return { kind: mapping.kind, providerKind: PROVIDER_KIND, providerMethodRef, providerEventId, occurredAt, replacement };
+}
+/**
+ * Scheme label, trailing digits and expiry, from whichever of the three shapes
+ * the payload carries them in: the method object itself at the top level, an
+ * expanded method one level down, or a charge-shaped object's method details.
+ * A payload carrying none of them yields null, not a row of empty facts.
+ */
+function readMethodFacts(object) {
+    const card = readOptionalObject(object, "card")
+        ?? readOptionalObject(readOptionalObject(object, "payment_method") ?? {}, "card")
+        ?? readOptionalObject(readOptionalObject(object, "payment_method_details") ?? {}, "card");
+    if (!card)
+        return null;
+    const schemeLabel = readOptionalString(card, "brand") ?? null;
+    const lastDigits = readOptionalString(card, "last4") ?? null;
+    const expiresAt = expiryInstantFromMonthYear(readOptionalNumber(card, "exp_month") ?? null, readOptionalNumber(card, "exp_year") ?? null);
+    if (!schemeLabel && !lastDigits && !expiresAt)
+        return null;
+    return { schemeLabel, lastDigits, expiresAt };
+}
+/**
+ * Resolve the provider payment id used to LINK this event to the local payment
+ * attempt. Payment-control matches inbound events to an attempt by
+ * `commerce_payment_attempts.provider_attempt_id`, which holds the Stripe
+ * PaymentIntent id (`pi_…`).
+ *
+ * For `payment_intent.*` events the webhook object IS the PaymentIntent, so its
+ * `id` is already the linkage key. For `charge.*` (incl. `charge.dispute.*`)
+ * the object is a Charge (`ch_…`) or Dispute (`dp_…`) whose own id never
+ * matches an attempt — but it carries `payment_intent` pointing back at the PI.
+ * Using that field is what lets `charge.refunded` / `charge.dispute.created`
+ * resolve to the order and drive `applyPaymentResult`; without it refunds and
+ * disputes were ingested but silently never applied. Falls back to the object
+ * id when `payment_intent` is absent (defensive — keeps the event recordable).
+ */
+function resolveLinkagePaymentId(stripeEventType, object) {
+    if (stripeEventType.startsWith("charge.")) {
+        const paymentIntentId = readOptionalString(object, "payment_intent");
+        if (paymentIntentId)
+            return paymentIntentId;
+    }
+    return readString(object, "id");
+}
+function mapStripeEventType(stripeEventType, object) {
+    if (stripeEventType === "payment_intent.succeeded")
+        return "payment.succeeded";
+    if (stripeEventType === "payment_intent.payment_failed")
+        return "payment.failed";
+    if (stripeEventType === "payment_intent.canceled")
+        return "payment.failed";
+    if (stripeEventType === "payment_intent.requires_action")
+        return "payment.requires_action";
+    if (stripeEventType === "setup_intent.succeeded")
+        return "setup.succeeded";
+    if (stripeEventType === "setup_intent.setup_failed")
+        return "setup.failed";
+    if (stripeEventType === "setup_intent.requires_action")
+        return "setup.requires_action";
+    if (stripeEventType === "charge.refunded")
+        return "payment.refunded";
+    if (stripeEventType.startsWith("charge.dispute."))
+        return "payment.disputed";
+    const methodLifecycle = METHOD_LIFECYCLE_EVENTS[stripeEventType];
+    if (methodLifecycle)
+        return methodLifecycle.canonical;
+    const status = readOptionalString(object, "status");
+    if (status === "requires_action")
+        return "payment.requires_action";
+    const guess = `payment.${stripeEventType}`;
+    if (SUPPORTED_EVENT_TYPES.has(guess))
+        return guess;
+    throw new Error(`Unsupported Stripe webhook event: ${stripeEventType}`);
+}
+function extractReusableMethod(canonicalEventType, object) {
+    const isSetupSucceeded = canonicalEventType === "setup.succeeded";
+    const isPaymentSucceededWithSaveCard = canonicalEventType === "payment.succeeded" &&
+        readOptionalString(object, "setup_future_usage") === "off_session";
+    if (!isSetupSucceeded && !isPaymentSucceededWithSaveCard)
+        return null;
+    const customer = readOptionalString(object, "customer");
+    // The method arrives as a bare id, or as an expanded object when the payload
+    // also carries its facts; both address the same stored method.
+    const paymentMethod = readOptionalString(object, "payment_method")
+        ?? readOptionalString(readOptionalObject(object, "payment_method") ?? {}, "id");
+    const metadata = readOptionalObject(object, "metadata");
+    const clientId = metadata ? readOptionalString(metadata, "clientId") : undefined;
+    const subscriptionId = metadata ? readOptionalString(metadata, "subscriptionId") : undefined;
+    const mode = metadata ? readOptionalString(metadata, "mode") : undefined;
+    const recoveryCaseId = metadata ? readOptionalString(metadata, "recoveryCaseId") : undefined;
+    const metadataSource = metadata ? readOptionalString(metadata, "source") : undefined;
+    if (!customer || !paymentMethod || !clientId)
+        return null;
+    return {
+        clientId,
+        // W11.7 Wave D-4a — recovery setup-method flow tags `subscriptionId` in
+        // SetupIntent metadata so this upsert binds the new method to the
+        // subscription the dunning case targets. One-time + initial save-card
+        // (Wave C) flows leave the field null because no subscription exists yet.
+        subscriptionId: subscriptionId ?? null,
+        providerCustomerRef: customer,
+        providerMethodRef: paymentMethod,
+        providerMandateRef: null,
+        methodKind: "card",
+        status: "active",
+        consentSnapshot: {
+            source: "stripe_webhook",
+            eventType: canonicalEventType,
+            checkoutMode: mode ?? null,
+            recoveryCaseId: recoveryCaseId ?? null,
+            metadataSource: metadataSource ?? null,
+            // Additive facts only, and only when the payload actually carried them.
+            // The setup event carries the method's id and nothing else, so this is
+            // usually empty there and filled later by the method-family delivery.
+            ...methodFactSnapshotKeys(readMethodFacts(object)),
+        },
+    };
+}
+function readOccurredAt(rawPayload) {
+    const created = rawPayload.created;
+    if (typeof created === "number" && Number.isFinite(created)) {
+        return new Date(created * 1000).toISOString();
+    }
+    if (typeof created === "string") {
+        const parsed = new Date(created);
+        if (!Number.isNaN(parsed.getTime()))
+            return parsed.toISOString();
+    }
+    // Stripe always sends `created` on event payloads; fall back defensively if
+    // missing rather than refusing the event — downstream RPC still records the
+    // signature-verified facts.
+    return new Date(0).toISOString();
+}
+function readObject(value, key) {
+    const raw = value[key];
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+        throw new Error(`Stripe payload missing object ${key}`);
+    }
+    return raw;
+}
+function readOptionalObject(value, key) {
+    const raw = value[key];
+    return raw && typeof raw === "object" && !Array.isArray(raw)
+        ? raw
+        : null;
+}
+function readString(value, key) {
+    const raw = value[key];
+    if (typeof raw !== "string" || raw.length === 0) {
+        throw new Error(`Stripe payload missing string ${key}`);
+    }
+    return raw;
+}
+function readOptionalString(value, key) {
+    const raw = value[key];
+    return typeof raw === "string" && raw.length > 0 ? raw : undefined;
+}
+function readOptionalNumber(value, key) {
+    const raw = value[key];
+    return typeof raw === "number" ? raw : undefined;
+}

package/dist/payments/stripe/webhookSignature.d.ts

@@ -0,0 +1,14 @@
+export declare const STRIPE_TIMESTAMP_TOLERANCE_SECONDS = 300;
+export declare function verifyStripeSignature(input: {
+    rawBody: string;
+    signatureHeader: string | undefined;
+    /**
+     * One or many endpoint secrets to accept. Multi-secret support lets a single
+     * route accept signatures from both the dashboard webhook endpoint and a
+     * local `stripe listen` CLI tunnel; the signature is accepted if ANY secret
+     * verifies. An empty array (or missing single secret) fails closed.
+     */
+    endpointSecret: string | readonly string[];
+    /** Injectable clock (UTC seconds) for deterministic tests; defaults to now. */
+    now?: () => number;
+}): boolean;

package/dist/payments/stripe/webhookSignature.js

@@ -0,0 +1,43 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+export const STRIPE_TIMESTAMP_TOLERANCE_SECONDS = 300;
+export function verifyStripeSignature(input) {
+    const parts = Object.fromEntries((input.signatureHeader ?? "")
+        .split(",")
+        .map((part) => part.split("="))
+        .filter(([key, value]) => key && value));
+    const timestamp = parts.t;
+    const signature = parts.v1;
+    if (!timestamp || !signature)
+        return false;
+    // Reject replays outside the tolerance window before doing the HMAC work. A
+    // valid signature on a stale timestamp (captured-and-replayed event) must not
+    // pass; the future-skew bound tolerates small clock drift between Stripe and us.
+    const timestampSec = Number(timestamp);
+    if (!Number.isFinite(timestampSec))
+        return false;
+    const now = input.now ?? (() => Math.floor(Date.now() / 1000));
+    const ageSec = now() - timestampSec;
+    if (ageSec > STRIPE_TIMESTAMP_TOLERANCE_SECONDS)
+        return false;
+    if (ageSec < -STRIPE_TIMESTAMP_TOLERANCE_SECONDS)
+        return false;
+    const secrets = Array.isArray(input.endpointSecret)
+        ? input.endpointSecret
+        : input.endpointSecret
+            ? [input.endpointSecret]
+            : [];
+    return secrets.some((secret) => {
+        if (!secret)
+            return false;
+        const expected = hmac(`${timestamp}.${input.rawBody}`, secret);
+        return timingSafeStringEqual(signature, expected);
+    });
+}
+function hmac(value, secret) {
+    return createHmac("sha256", secret).update(value).digest("hex");
+}
+function timingSafeStringEqual(left, right) {
+    const leftBuffer = Buffer.from(left);
+    const rightBuffer = Buffer.from(right);
+    return leftBuffer.length === rightBuffer.length && timingSafeEqual(leftBuffer, rightBuffer);
+}

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

@@ -0,0 +1,37 @@
+export interface TpayBlikAliasRegistrationInput {
+    orderRef: string;
+    amountMinor: number;
+    currency: string;
+    customerEmail: string;
+    staticWebhookUrl: string;
+    consentRef: string;
+}
+export interface TpayBlikAliasChargeInput {
+    orderRef: string;
+    payId: string;
+    amountMinor: number;
+    currency: string;
+    staticWebhookUrl: string;
+}
+export declare function buildTpayBlikAliasRegistrationDraft(input: TpayBlikAliasRegistrationInput): {
+    provider: string;
+    requestKind: string;
+    orderRef: string;
+    amount: number;
+    currency: string;
+    customer: {
+        email: string;
+    };
+    webhookUrl: string;
+    consentRef: string;
+    fallbackRequiredWhenAliasUnavailable: boolean;
+};
+export declare function buildTpayBlikAliasChargeDraft(input: TpayBlikAliasChargeInput): {
+    provider: string;
+    requestKind: string;
+    orderRef: string;
+    payId: string;
+    amount: number;
+    currency: string;
+    webhookUrl: string;
+};

package/dist/payments/tpay/blikRecurringMapper.js

@@ -0,0 +1,24 @@
+export function buildTpayBlikAliasRegistrationDraft(input) {
+    return {
+        provider: "tpay",
+        requestKind: "blik_alias_registration",
+        orderRef: input.orderRef,
+        amount: input.amountMinor,
+        currency: input.currency,
+        customer: { email: input.customerEmail },
+        webhookUrl: input.staticWebhookUrl,
+        consentRef: input.consentRef,
+        fallbackRequiredWhenAliasUnavailable: true,
+    };
+}
+export function buildTpayBlikAliasChargeDraft(input) {
+    return {
+        provider: "tpay",
+        requestKind: "blik_alias_charge",
+        orderRef: input.orderRef,
+        payId: input.payId,
+        amount: input.amountMinor,
+        currency: input.currency,
+        webhookUrl: input.staticWebhookUrl,
+    };
+}

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

@@ -0,0 +1,3 @@
+import type { PaymentAdapterCapabilities } from "../contracts/index.js";
+/** Bank-redirect, one-time-code and unattended Model O attempts are supported with host payer/method input; account availability remains verification_pending. */
+export declare const tpayPaymentCapabilities: Readonly<PaymentAdapterCapabilities>;

package/dist/payments/tpay/capabilities.js

@@ -0,0 +1,18 @@
+/** Bank-redirect, one-time-code and unattended Model O attempts are supported with host payer/method input; account availability remains verification_pending. */
+export const tpayPaymentCapabilities = Object.freeze({
+    providerKind: "tpay",
+    captureFlows: Object.freeze([
+        Object.freeze({ kind: "bank_redirect", handoff: "redirect", methodFamilies: Object.freeze(["bank-redirect"]) }),
+        Object.freeze({ kind: "one_time_code", handoff: "customer-authorization", methodFamilies: Object.freeze(["one-time-code"]) }),
+    ]),
+    requiresStoredMandateEvidence: true,
+    assessMandate: snapshot => snapshot.recurringModel === "O" ? { chargeable: true }
+        : { chargeable: false, blockReason: "mandate_model_unsupported_for_unattended_charge" },
+    unattendedChargeFlow: "recurring_charge",
+    payerContext: Object.freeze({ requiresPayerBlock: true, customerRefFallsBackToContactEmail: false }),
+    methodHealth: Object.freeze({ requiresCustomerRef: false, requiredMethodKind: "blik_payid", requiresPayerContact: true }),
+    terminalOutcomeReporting: Object.freeze({ kind: "attempt_records", silenceBecomesSuspectAfterMinutes: 360 }),
+    mandateUpsertIsSubscriptionScoped: true,
+    supportedCurrencies: Object.freeze(["PLN"]), unattended: "supported", readback: "supported", close: "unsupported",
+    exactAbsence: "unsupported", refundObservation: "supported", refundCreate: "unsupported", authorizationCaptureSplit: "unsupported",
+});

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;
+}