@openlup/platform 0.19.0 → 0.21.0

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;

package/dist/payments/tpay/index.js

@@ -0,0 +1,264 @@
+import { createHash, X509Certificate } from "node:crypto";
+import { classifyPaymentFailure, isPaymentRetryAdviceCode } from "@openlup/core/payment";
+import { tpayPaymentCapabilities } from "./capabilities.js";
+export { tpayPaymentCapabilities } from "./capabilities.js";
+import { createTpayHttpClient } from "./tpayHttpClient.js";
+import { createTpayPaymentExecutionAdapter } from "./tpayPaymentExecutionAdapter.js";
+import { ProviderAttemptPreDispatchError } from "./preparedProviderAttempt.js";
+import { createTpayPaymentReconciliationProvider } from "./tpayPaymentReconciliationProvider.js";
+import { verifyTpayJwsSignature } from "./webhookJwsVerifier.js";
+import { normalizeTpayWebhook, toNormalizedProviderTpayWebhook } from "./webhookNormalizer.js";
+const refusal = (reason) => ({ kind: "refusal", reason });
+/** Construction explicitly selects this adapter; the host owns account activation and I/O policy. */
+export function createTpayPaymentAdapter(config) {
+    const capabilities = tpayPaymentCapabilities;
+    const notification = config.notification;
+    if (!notification?.rootCertificatePem || typeof notification.resolveCertificate !== "function")
+        throw new Error("Required certificate configuration missing");
+    const prefix = new URL(notification.allowedCertificateUrlPrefix);
+    if (prefix.protocol !== "https:" || prefix.username || prefix.password || prefix.search || prefix.hash
+        || !notification.allowedCertificateUrlPrefix.endsWith("/"))
+        throw new Error("Invalid certificate URL prefix");
+    const root = new X509Certificate(notification.rootCertificatePem);
+    const maxAge = notification.maxNotificationAgeSeconds ?? 7 * 24 * 60 * 60;
+    const maxClockSkew = notification.maxClockSkewSeconds ?? 300;
+    if (!Number.isFinite(maxAge) || maxAge < 0 || !Number.isFinite(maxClockSkew) || maxClockSkew < 0 || !["test", "live"].includes(config.mode)
+        || typeof config.http.fetchImpl !== "function" || !config.http.clientId || !config.http.clientSecret
+        || typeof config.modelOActivationEnabled !== "boolean")
+        throw new Error("Invalid payment configuration");
+    for (const url of [config.http.baseUrl, ...Object.values(config.urls)]) {
+        const parsed = new URL(url);
+        if (parsed.protocol !== "https:" || parsed.username || parsed.password)
+            throw new Error("Invalid payment URL");
+    }
+    const now = config.clock ?? (() => Date.now() / 1000);
+    const client = createTpayHttpClient({ ...config.http, now: () => now() * 1000 });
+    const execution = createTpayPaymentExecutionAdapter({ client, ...config.urls,
+        modelOActivationEnabled: config.modelOActivationEnabled });
+    const reconciliation = createTpayPaymentReconciliationProvider(client);
+    const validateHostInput = (input) => {
+        if (input.mode !== config.mode || !["initial", "recovery", "renewal-unattended"].includes(input.purpose)
+            || !capabilities.supportedCurrencies.includes(input.money.currency))
+            throw new Error("Unsupported payment input");
+    };
+    const donorInput = (input) => {
+        if (!input.attemptRef || !input.intentRef || !input.fingerprint || !input.providerIdempotencyKey
+            || !Number.isSafeInteger(input.money.amountMinor) || input.money.amountMinor <= 0
+            || !input.payer?.email || (input.payer.name !== undefined && typeof input.payer.name !== "string")) {
+            throw new Error("Invalid payment input");
+        }
+        const renewal = input.purpose === "renewal-unattended";
+        const family = input.methodSelection?.family;
+        if (renewal ? !input.storedMethod?.reference || input.storedMethod.mandate.recurringModel !== "O"
+            || input.customerAuthorization !== undefined
+            : family !== "bank-redirect" && family !== "one-time-code")
+            throw new Error("Unsupported payment flow");
+        if (!renewal && (family === "bank-redirect" ? !input.methodSelection?.channelRef || input.customerAuthorization !== undefined
+            : !input.customerAuthorization))
+            throw new Error("Required payment context missing");
+        return {
+            idempotencyKey: input.attemptRef, providerIdempotencyKey: input.providerIdempotencyKey,
+            providerRequestFingerprint: input.fingerprint, paymentIntentId: input.intentRef, orderRef: input.intentRef,
+            amountMinor: input.money.amountMinor, currency: input.money.currency,
+            mode: renewal ? "subscription_cycle" : "one_time",
+            payer: { email: input.payer.email, name: input.payer.name?.trim() ? input.payer.name : "Customer" },
+            ...(renewal ? { providerFlow: "recurring_charge", paymentMethodRef: input.storedMethod.reference,
+                paymentMethodAliasType: "PAYID", paymentMethodRecurringModel: "O" } : {
+                transientProviderInput: family === "bank-redirect"
+                    ? { provider: "tpay", flow: "pbl_one_time", channelId: input.methodSelection.channelRef }
+                    : { provider: "tpay", flow: "blik_one_time", blikToken: input.customerAuthorization },
+            }),
+        };
+    };
+    const validateInput = (input) => {
+        validateHostInput(input);
+        execution.validateInput?.(donorInput(input));
+    };
+    return {
+        capabilities,
+        attemptPort: {
+            validateInput,
+            async execute(input) {
+                validateHostInput(input);
+                let prepared;
+                try {
+                    prepared = donorInput(input);
+                    execution.validateInput?.(prepared);
+                }
+                catch {
+                    const reason = { code: "fix_and_retry_customer_action", hints: ["dataInvalid"] };
+                    return { outcome: { kind: "decline", refusal: reason },
+                        dispatch: { kind: "notDispatched", evidence: { exact: true, phase: "before-dispatch", reason } }, diagnostics: {} };
+                }
+                let result;
+                try {
+                    result = await execution.execute(prepared);
+                }
+                catch (error) {
+                    if (!(error instanceof ProviderAttemptPreDispatchError))
+                        throw error;
+                    // A proven document refusal needs corrected data; other trusted no-charge failures can retry.
+                    const hints = error.phase === "response_decode"
+                        && error.code === "tpay_request_refused" && error.dispatchState === "refused" ? ["dataInvalid"] : ["transient"];
+                    const reason = { code: classifyPaymentFailure({ neutralReasonHints: hints }).failureClass, hints };
+                    return { outcome: { kind: "decline", refusal: reason },
+                        dispatch: { kind: "notDispatched", evidence: { exact: true, phase: "before-dispatch", reason } }, diagnostics: {} };
+                }
+                // Only these neutral facts cross the boundary; donor payloads and transient payer/authorization stay local.
+                return {
+                    outcome: result.providerDecline ? { kind: "decline", refusal: neutralDecline(result.providerDecline) }
+                        : { kind: "attempt", status: result.attemptStatus },
+                    // API transaction ID is required for readback; notification titles remain distinct.
+                    dispatch: result.providerSessionId ? { kind: "dispatched", providerPaymentRef: result.providerSessionId } : { kind: "unknown" },
+                    ...(result.nextActionKind === "redirect" && result.redirectUrl
+                        ? { handoff: { kind: "redirect", url: result.redirectUrl } } : {}),
+                    diagnostics: { webhookExpected: result.webhookExpected === true, recoveryRequired: result.recoveryRequired === true },
+                };
+            },
+        },
+        verifyPort: {
+            async verifyAndNormalize(input) {
+                const header = Object.entries(input.headers).find(([key]) => key.toLowerCase() === "x-jws-signature")?.[1];
+                if (typeof header !== "string")
+                    return refusal("signature");
+                const rawBody = Buffer.from(input.rawBody).toString("utf8");
+                if (!Buffer.from(rawBody).equals(Buffer.from(input.rawBody)))
+                    return refusal("malformed");
+                try {
+                    const current = now() * 1000;
+                    if (!validAt(root, current))
+                        return refusal("signature");
+                    const verified = await verifyTpayJwsSignature({ rawBody, signatureHeader: header,
+                        rootCertificatePem: notification.rootCertificatePem, allowedX5uPrefix: notification.allowedCertificateUrlPrefix,
+                        resolveCertificate: async (url) => {
+                            const pem = await notification.resolveCertificate(url);
+                            if (!validAt(new X509Certificate(pem), current))
+                                throw new Error("Certificate outside validity window");
+                            return pem;
+                        } });
+                    if (!verified)
+                        return refusal("signature");
+                }
+                catch {
+                    return refusal("signature");
+                }
+                try {
+                    // Only a signed protected-header issued-at assertion supplies notification time.
+                    const protectedHeader = JSON.parse(Buffer.from(header.split(".")[0], "base64url").toString("utf8"));
+                    const asserted = protectedHeader.iat;
+                    if (asserted !== undefined && (typeof asserted !== "number" || !Number.isFinite(asserted)
+                        || !Number.isFinite(new Date(asserted * 1000).getTime())))
+                        return refusal("malformed");
+                    const occurred = typeof asserted === "number" ? new Date(asserted * 1000).toISOString() : null;
+                    if (occurred !== null) {
+                        const received = Date.parse(input.receivedAt) / 1000;
+                        if (!Number.isFinite(received))
+                            return refusal("malformed");
+                        if (received - asserted > maxAge || asserted - received > maxClockSkew)
+                            return refusal("stale");
+                    }
+                    return mapVerifiedTpayEvent(rawBody, occurred, config.mode, capabilities.supportedCurrencies);
+                }
+                catch {
+                    return refusal("malformed");
+                }
+            },
+        },
+        readbackPort: {
+            async readPayment(input) {
+                const base = { identity: input.identity, expectedMoney: input.expectedMoney, purpose: input.purpose };
+                if (input.identity.provider !== "tpay" || !input.identity.providerPaymentRef)
+                    return { ...base, kind: "unsupported" };
+                try {
+                    const reading = await reconciliation.readRecoveryPayment({
+                        providerPaymentId: input.identity.providerPaymentRef, purpose: input.purpose, attempt: input.expectedMoney,
+                    });
+                    const observed = reading.status;
+                    if (!reading.identityMatches || !reading.configuredMoneyMatches || reading.manualReviewRequired
+                        || !Number.isSafeInteger(input.expectedMoney.amountMinor) || input.expectedMoney.amountMinor <= 0
+                        || observed.status === "unknown")
+                        return unknown(base);
+                    // Success and nonzero refused money must match; unpaid refusals retain the configured obligation.
+                    if ((observed.status === "succeeded" || (observed.status === "failed" && observed.amountMinor !== null && observed.amountMinor !== 0))
+                        && (observed.amountMinor !== input.expectedMoney.amountMinor
+                            || observed.currency !== input.expectedMoney.currency.toUpperCase()))
+                        return unknown(base);
+                    return { ...base, kind: observed.status, observedMoney: { amountMinor: input.expectedMoney.amountMinor,
+                            currency: input.expectedMoney.currency.toUpperCase() },
+                        providerOccurredAt: observed.occurredAt };
+                }
+                catch {
+                    return unknown(base);
+                }
+            },
+        },
+    };
+}
+function neutralDecline(decline) {
+    const hints = decline.neutralReasonHints ?? [];
+    return { code: classifyPaymentFailure({ adviceCode: decline.adviceCode, neutralReasonHints: hints }).failureClass, hints,
+        ...(decline.adviceCode && isPaymentRetryAdviceCode(decline.adviceCode) ? { adviceCode: decline.adviceCode } : {}) };
+}
+function validAt(certificate, instant) {
+    return Number.isFinite(instant) && Date.parse(certificate.validFrom) <= instant && instant <= Date.parse(certificate.validTo);
+}
+function unknown(base) {
+    return { ...base, kind: "unknown", reason: "indeterminate" };
+}
+/** All donor outcomes outside the current neutral union are refused here. */
+function mapTpayOutcome(event) {
+    switch (event) {
+        case "payment.succeeded": return "succeeded";
+        case "payment.failed": return "failed";
+        case "payment.requires_action": return "pending";
+        case "payment.refunded": return "refunded";
+        default: return null;
+    }
+}
+function mapVerifiedTpayEvent(rawBody, occurred, mode, supportedCurrencies) {
+    const webhook = normalizeTpayWebhook(rawBody);
+    const event = webhook.event;
+    const payload = event.raw_payload;
+    if (payload.testMode !== null && payload.testMode !== undefined
+        && payload.testMode !== (mode === "test" ? "1" : "0"))
+        return refusal("unsupported-event");
+    const identity = { provider: "tpay", providerOccurredAt: occurred };
+    let evidence;
+    if (payload.eventKind === "blik_alias") {
+        const kinds = {
+            method_registered: "registered", method_updated: "updated", method_revoked: "revoked", method_expired: "expired",
+        };
+        const outcome = kinds[webhook.methodLifecycleKind ?? ""];
+        if (!outcome)
+            return refusal("unsupported-event");
+        const lifecycle = occurred !== null ? toNormalizedProviderTpayWebhook(webhook, occurred).methodLifecycle : null;
+        evidence = { ...identity, kind: "method", outcome, providerEventId: `${event.provider_event_id}:${outcome}`,
+            methodRef: event.payment_provider_id, setupRef: null, intentRef: event.payment_intent_id ?? null,
+            ...(lifecycle ? { methodLifecycle: lifecycle } : {}) };
+    }
+    else {
+        const outcome = mapTpayOutcome(event.event_type);
+        if (!outcome)
+            return refusal("unsupported-event");
+        const amount = event.amount_minor;
+        const reportedCurrency = payload.currency;
+        if (reportedCurrency == null && supportedCurrencies.length !== 1)
+            return refusal("malformed");
+        // Currency binds to the adapter's declared single supported currency because
+        // attempts in any other currency are refused before dispatch; this is not a silent default.
+        const currency = reportedCurrency ?? supportedCurrencies[0];
+        const money = Number.isSafeInteger(amount) && amount > 0 && typeof currency === "string" && /^[A-Za-z]{3}$/u.test(currency)
+            ? { amountMinor: amount, currency: currency.toUpperCase() } : null;
+        const originalAmount = typeof payload.transactionAmount === "string"
+            ? Math.round(Number(payload.transactionAmount.replace(",", ".")) * 100) : NaN;
+        if (outcome === "refunded" && (!money || !Number.isSafeInteger(originalAmount) || originalAmount <= 0))
+            return refusal("malformed");
+        evidence = { ...identity, kind: "money", providerEventId: `${event.payment_provider_id}:${outcome}`,
+            providerPaymentRef: event.payment_provider_id, intentRef: event.payment_intent_id ?? null, attemptRef: null, outcome, money,
+            ...(outcome === "refunded" && money ? { refund: { kind: "full-reversal", reason: "chargeback",
+                    operationId: `${event.payment_provider_id}:chargeback`, originalPaymentMoney: { amountMinor: originalAmount, currency: money.currency } } } : {}),
+        };
+    }
+    return { ...evidence, fingerprint: createHash("sha256").update(JSON.stringify(evidence)).digest("hex"),
+        providerAuditPayload: payload };
+}

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

@@ -0,0 +1,26 @@
+import type { PaymentRecoveryMethod, PaymentRecoveryOperation } from "@openlup/core/payment";
+export type FailureObservationSource = "execution" | "webhook" | "readback";
+export type FailureObservationDisposition = "present" | "absent" | "unreadable" | "read_failed" | "read_timeout";
+/** Protected provider facts, not a customer message or a retry-policy input. */
+export interface PaymentFailureEvidence {
+    version: 1;
+    source: FailureObservationSource;
+    disposition: FailureObservationDisposition;
+    refusalVerified: boolean;
+    providerPaymentId: string | null;
+    providerChargeId: string | null;
+    code: string | null;
+    declineCode: string | null;
+    adviceCode: string | null;
+    adviceOrigin: "provider" | "inferred" | "unknown";
+    operation: PaymentRecoveryOperation | null;
+    method: PaymentRecoveryMethod | null;
+    methodSource: "provider" | "execution_contract" | "unknown";
+}
+/** Bounded machine tokens only. Free-form response fields never cross this seam. */
+export declare function evidenceToken(value: unknown): string | null;
+export declare function evidenceRecord(value: unknown): Record<string, unknown>;
+/** Explicit construction prevents accidental payload expansion by object spreading. */
+export declare function serializeFailureEvidence(input: PaymentFailureEvidence): PaymentFailureEvidence;
+/** Persist beside legacy fields; never merge the diagnostic codes into them. */
+export declare function failureEvidencePayload(evidence: PaymentFailureEvidence | null | undefined): Record<string, unknown>;

package/dist/payments/tpay/paymentFailureEvidence.js

@@ -0,0 +1,33 @@
+/** Bounded machine tokens only. Free-form response fields never cross this seam. */
+export function evidenceToken(value) {
+    return typeof value === "string" && /^[a-zA-Z0-9_:.-]{1,96}$/.test(value) ? value : null;
+}
+export function evidenceRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value : {};
+}
+/** Explicit construction prevents accidental payload expansion by object spreading. */
+export function serializeFailureEvidence(input) {
+    const method = input.method;
+    const kind = evidenceToken(method?.kind);
+    const recoveryMethodKey = evidenceToken(method?.recoveryMethodKey);
+    return {
+        version: 1,
+        source: input.source,
+        disposition: input.disposition,
+        refusalVerified: input.refusalVerified,
+        providerPaymentId: evidenceToken(input.providerPaymentId),
+        providerChargeId: evidenceToken(input.providerChargeId),
+        code: evidenceToken(input.code),
+        declineCode: evidenceToken(input.declineCode),
+        adviceCode: evidenceToken(input.adviceCode),
+        adviceOrigin: input.adviceOrigin,
+        operation: input.operation,
+        method: kind && recoveryMethodKey && method ? { kind, recoveryMethodKey, interaction: method.interaction } : null,
+        methodSource: kind && recoveryMethodKey ? input.methodSource : "unknown",
+    };
+}
+/** Persist beside legacy fields; never merge the diagnostic codes into them. */
+export function failureEvidencePayload(evidence) {
+    return evidence ? { failureEvidence: serializeFailureEvidence(evidence) } : {};
+}

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

@@ -0,0 +1,22 @@
+export interface TrustedProviderAttemptPreDispatchFailure {
+    phase: "oauth" | "transaction_dispatch";
+    code: "tpay_oauth_failed" | "tpay_oauth_timeout" | "tpay_oauth_invalid_response" | "tpay_request_encode_failed" | "tpay_request_deadline_exhausted";
+    dispatchState: "not_dispatched";
+}
+/** Either proof the provider holds no transaction: the POST was never invoked, or it was and the
+ * provider refused the request document. Two closed shapes, so neither absorbs the other. */
+export type TrustedProviderAttemptNoChargeFailure = TrustedProviderAttemptPreDispatchFailure | {
+    phase: "response_decode";
+    code: "tpay_request_refused";
+    dispatchState: "refused";
+};
+export declare class ProviderAttemptPreDispatchError extends Error {
+    readonly phase: TrustedProviderAttemptNoChargeFailure["phase"];
+    readonly code: TrustedProviderAttemptNoChargeFailure["code"];
+    readonly dispatchState: TrustedProviderAttemptNoChargeFailure["dispatchState"];
+    paymentAttemptId: string | null;
+    retryCount: number;
+    constructor(failure: TrustedProviderAttemptNoChargeFailure, paymentAttemptId?: string | null);
+    withPaymentAttempt(paymentAttemptId: string): this;
+    withRetryCount(retryCount: number): this;
+}

package/dist/payments/tpay/preparedProviderAttempt.js

@@ -0,0 +1,24 @@
+export class ProviderAttemptPreDispatchError extends Error {
+    phase;
+    code;
+    dispatchState;
+    paymentAttemptId;
+    retryCount = 0;
+    constructor(failure, paymentAttemptId = null) {
+        const kind = failure.dispatchState === "refused" ? "provider_refused_pre_transaction" : "provider_pre_dispatch_failed";
+        super(`${kind}:${failure.phase}:${failure.code}`);
+        this.name = "ProviderAttemptPreDispatchError";
+        this.phase = failure.phase;
+        this.code = failure.code;
+        this.dispatchState = failure.dispatchState;
+        this.paymentAttemptId = paymentAttemptId;
+    }
+    withPaymentAttempt(paymentAttemptId) {
+        this.paymentAttemptId = paymentAttemptId;
+        return this;
+    }
+    withRetryCount(retryCount) {
+        this.retryCount = retryCount;
+        return this;
+    }
+}

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

@@ -0,0 +1,3 @@
+export declare function loggableProviderRequestId(value: unknown): value is string;
+export declare function loggableProviderErrorCode(value: unknown): value is string;
+export declare function loggableProviderFieldName(value: unknown): value is string;

package/dist/payments/tpay/providerAttemptFailureDiagnostic.js

@@ -0,0 +1,95 @@
+const TPAY_REQUEST_ID = /^[a-f0-9]{20}$/;
+const LOGGABLE_PROVIDER_ERROR_CODES = new Set([
+    "bank_group_does_not_exist",
+    "blik_token_not_present",
+    "cannot_create_transaction",
+    "channel_passed_with_group",
+    "channel_unavailable",
+    "channel_unavailable_for_source",
+    "configuration_error",
+    "country_not_valid",
+    "crc_not_unique",
+    "field_required",
+    "general",
+    "incorrect_content_type",
+    "internal_server_error",
+    "invalid_request_body",
+    "is_required",
+    "no_payment_data",
+    "not_array",
+    "not_natural_int",
+    "not_string",
+    "not_valid",
+    "partner_cannot_create_transaction",
+    "payment_failed",
+    "too_low",
+    "transaction_blocked",
+    "transaction_lock",
+    "ts:channel:amount_outside_range",
+    "ts:channel:both_channel_and_group_specified",
+    "ts:channel:channel_blocked",
+    "ts:channel:channel_disabled",
+    "ts:channel:channel_disabled_for_pos",
+    "ts:channel:collect_prohibited",
+    "ts:channel:group_disabled_for_pos",
+    "ts:channel:not_available",
+    "ts:channel:not_found",
+    "ts:channel:source_prohibited",
+    "ts:channel:surcharge_prohibited",
+    "ts:country:not_valid",
+    "ts:merchant:disabled",
+    "ts:merchant:is_partner",
+    "ts:merchant:not_found",
+    "ts:payer:phone:not_valid",
+    "ts:pos:not_found",
+    "ts:pos:result_url_not_overridable",
+    "ts:request:no_ip",
+    "ts:transaction:not_inserted",
+    "ts:transaction:payer_data_not_inserted",
+    "ts:transaction:payer_info_not_inserted",
+    "unexpected_field",
+    "unsupported_blik_token",
+    "url_override_is_disabled",
+    "wrong_alias",
+    "wrong_autopayment_alias",
+    "wrong_model_data_combination",
+]);
+const LOGGABLE_PROVIDER_FIELD_NAMES = new Set([
+    "amount",
+    "currency",
+    "description",
+    "hiddenDescription",
+    "payer.email",
+    "payer.name",
+    "payer.phone",
+    "payer.address",
+    "payer.city",
+    "payer.country",
+    "payer.postalCode",
+    // This list carries FIELD NAMES ONLY - `ProviderAttemptFailureDiagnostic` has
+    // no field that holds a provider value - so these two entries log the literal
+    // strings, never a user agent or an IP address. Their absence is why the
+    // 2026-08-28 BLIK outage logged `fieldNames: []` and stayed unattributed for
+    // days: `readTpayHttpFailure` filters Tpay's returned `fieldName` through this
+    // set, so an unlisted name is silently dropped.
+    "payer.ip",
+    "payer.userAgent",
+    "pay.groupId",
+    "pay.channelId",
+    "pay.blikPaymentData.blikToken",
+    "pay.blikPaymentData.type",
+    "pay.blikPaymentData.aliases.value",
+    "pay.blikPaymentData.aliases.type",
+    "callbacks.notification.url",
+    "callbacks.payerUrls.success",
+    "callbacks.payerUrls.error",
+]);
+export function loggableProviderRequestId(value) {
+    return typeof value === "string" && TPAY_REQUEST_ID.test(value);
+}
+export function loggableProviderErrorCode(value) {
+    return typeof value === "string" && LOGGABLE_PROVIDER_ERROR_CODES.has(value);
+}
+export function loggableProviderFieldName(value) {
+    return typeof value === "string" && LOGGABLE_PROVIDER_FIELD_NAMES.has(value);
+}