@openlup/platform 0.20.0 → 0.22.0

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

@@ -0,0 +1,126 @@
+import type { PaymentFailureHint } from "@openlup/core/payment";
+import type { DeclineCodeReading } from "./declineFailureHints.js";
+import type { TpayHttpClient } from "./tpayHttpClient.js";
+/**
+ * What this rail is allowed to conclude from a refusal, and from which evidence.
+ *
+ * Two rails ask the same question — "which refusal code does this transaction
+ * stand on" — the reconciliation poll and the execution path the moment the
+ * provider says no, so the scan lives here once rather than twice against the
+ * same payload shape. The message-shape heuristic lives here too, as the weakest
+ * grade of evidence and the last one consulted.
+ */
+/**
+ * Short on purpose. This read only EXPLAINS a refusal the provider has already
+ * decided; the attempt is finalized either way, so every millisecond spent here
+ * is pure added latency inside the money path. Well below the transport client's
+ * own request timeout, so the deadline that fires is this one.
+ */
+export declare const DECLINE_CODE_READBACK_TIMEOUT_MS = 3000;
+export interface RefusalRow {
+    row: Record<string, unknown>;
+    code: string;
+}
+/**
+ * The last row carrying a refusal code. Last rather than first: a payer may retry
+ * inside their banking app, so the most recent row describes the charge's current
+ * standing. Asserted only from an explicit code — never from silence or elapsed
+ * time — so a charge genuinely still running is never turned terminal. The row
+ * travels back with the code because a caller may need its date; a caller that
+ * does not can ignore it.
+ */
+export declare function lastRefusalRow(rows: unknown, codeKey: string): RefusalRow | null;
+/**
+ * The refusal code the provider's own attempt log stands on, or `null`.
+ *
+ * FAIL-OPEN BY CONSTRUCTION. A rejected request, a malformed body, a client that
+ * never settles, an attempt log without codes — every one of them resolves to
+ * `null`, which is the caller's "read nothing" branch. This function cannot
+ * throw and cannot block past its deadline, because the only thing it can add is
+ * a better explanation of a refusal that is already final. Anything stronger
+ * would put a provider read on the critical path of terminalizing an attempt,
+ * and a stalled terminalization is a stalled subscription cycle.
+ */
+export interface AttemptDeclineObservation {
+    /** Diagnostic-only quarantine; code remains the unchanged legacy classifier input. */
+    identityMismatch?: true;
+    code: string | null;
+    disposition: "present" | "absent" | "unreadable" | "read_failed" | "read_timeout";
+}
+/** Compatibility accessor: the existing classifier still sees exactly code or null. */
+export declare function readAttemptDeclineCode(client: Pick<TpayHttpClient, "getTransaction">, transactionId: string, timeoutMs?: number): Promise<string | null>;
+export declare function attemptDeclineObservation(transaction: unknown): AttemptDeclineObservation;
+/** One bounded read; diagnostic failure never changes terminalization or legacy code. */
+export declare function readAttemptDeclineObservation(client: Pick<TpayHttpClient, "getTransaction">, transactionId: string, timeoutMs?: number): Promise<AttemptDeclineObservation>;
+/** Legacy attribution remains a separate field with unchanged precedence. */
+export declare function declineEvidenceSource(input: {
+    attemptCode: string | null;
+    decidingAttemptReading: DeclineCodeReading | null;
+    mandateUnsupported: boolean;
+    reading: DeclineCodeReading;
+    errorCode: string;
+}): string;
+/** Whether a reading says anything at all, as opposed to `indeterminate`. */
+export declare function states(reading: DeclineCodeReading): boolean;
+/**
+ * Whether an observation of this flow may conclude anything about the payer's
+ * BANK being able to hold a mandate.
+ *
+ * Only a mandate REGISTRATION can answer that question. A refused charge on an
+ * already-registered mandate proves the bank held one, so a capability code
+ * arriving there says something else — which one, nobody here knows.
+ *
+ * `observedFlow` is `null` for an observer that cannot establish the flow at
+ * all, and that is a real answer rather than a missing argument: the
+ * reconciliation poll sees a transaction readback, and the flow is not a column
+ * of the claim it works from. Unknown is fail-closed for a capability claim, so
+ * such an observer abstains. Parameterized rather than hardcoded per rail, so a
+ * rail that later LEARNS its flow starts stating the claim by passing it, with
+ * no second copy of this rule to keep in step.
+ */
+export declare function mandateCapabilityReadable(observedFlow: string | null): boolean;
+/**
+ * The hints one observation is allowed to assert from a reading.
+ *
+ * The reading table is a reading of a CODE and knows nothing about the charge
+ * the code arrived on; this is where the observation's own context is applied
+ * to it. Both rails funnel through here, because a refusal that classifies one
+ * way when the execution path sees it and another way when the poll sees it is
+ * a race rather than a verdict — and the retry ladder cannot be allowed to
+ * terminate on a race.
+ *
+ * Narrow on purpose: only the mandate-capability hint depends on context. Every
+ * other hint states something about the charge itself and crosses untouched.
+ *
+ * The reconciliation rail passes `null` here and therefore always abstains from
+ * that one hint: it reads a transaction back, and a readback cannot tell a
+ * refused mandate REGISTRATION from a refused charge on a mandate the bank
+ * already holds. Abstaining is what it costs to have one verdict per refusal;
+ * the claim stays reachable from evidence that is not a guess, which on a
+ * renewal is the preflight reason this deployment writes itself.
+ */
+export declare function assertableHints(hints: readonly PaymentFailureHint[] | undefined, observedFlow: string | null): readonly PaymentFailureHint[] | undefined;
+/**
+ * FALLBACK ONLY, since the 2026-08-26 incident. Whether a decline means "this
+ * bank cannot hold a mandate" — the one cause a retry can never fix, and the
+ * only one worth telling a buyer to use a card.
+ *
+ * The deciding signal is now the refusal code in the transaction's attempt log,
+ * read back by `readAttemptDeclineCode`. This heuristic runs only when that read
+ * yields no code, or a code the reading table cannot read. It exists because the
+ * create response's own `errorCode` is generic (`payment_failed` covers a
+ * mistyped code, an expired code and an incapable bank alike), and
+ * `payIdEligible` is absent on EVERY rejection, not just this one — so absence
+ * alone would brand a fat-fingered code as "your bank does not support
+ * recurring". Reading the message is the last resort it always should have been:
+ * only its shape is consulted, and the text itself is never returned or stored,
+ * because it is free-form and can carry payer-identifying detail.
+ *
+ * Restricted to mandate REGISTRATION: a failed charge on an already-registered
+ * mandate proves the bank can hold one, so bank capability is never the answer
+ * there.
+ *
+ * Anything uncertain falls through to a generic decline, whose copy is never
+ * wrong — only less specific.
+ */
+export declare function isMandateRefusal(flow: string, payIdEligible: boolean | null, errorMessage: string): boolean;

package/dist/payments/tpay/tpayDeclineEvidence.js

@@ -0,0 +1,177 @@
+/**
+ * What this rail is allowed to conclude from a refusal, and from which evidence.
+ *
+ * Two rails ask the same question — "which refusal code does this transaction
+ * stand on" — the reconciliation poll and the execution path the moment the
+ * provider says no, so the scan lives here once rather than twice against the
+ * same payload shape. The message-shape heuristic lives here too, as the weakest
+ * grade of evidence and the last one consulted.
+ */
+/**
+ * Short on purpose. This read only EXPLAINS a refusal the provider has already
+ * decided; the attempt is finalized either way, so every millisecond spent here
+ * is pure added latency inside the money path. Well below the transport client's
+ * own request timeout, so the deadline that fires is this one.
+ */
+export const DECLINE_CODE_READBACK_TIMEOUT_MS = 3_000;
+/**
+ * The last row carrying a refusal code. Last rather than first: a payer may retry
+ * inside their banking app, so the most recent row describes the charge's current
+ * standing. Asserted only from an explicit code — never from silence or elapsed
+ * time — so a charge genuinely still running is never turned terminal. The row
+ * travels back with the code because a caller may need its date; a caller that
+ * does not can ignore it.
+ */
+export function lastRefusalRow(rows, codeKey) {
+    const entries = Array.isArray(rows) ? rows : [];
+    for (let index = entries.length - 1; index >= 0; index -= 1) {
+        const row = asRecord(entries[index]);
+        const raw = row[codeKey];
+        if (typeof raw === "string" && raw.trim())
+            return { row, code: raw.trim() };
+    }
+    return null;
+}
+/** Compatibility accessor: the existing classifier still sees exactly code or null. */
+export async function readAttemptDeclineCode(client, transactionId, timeoutMs = DECLINE_CODE_READBACK_TIMEOUT_MS) {
+    return (await readAttemptDeclineObservation(client, transactionId, timeoutMs)).code;
+}
+export function attemptDeclineObservation(transaction) {
+    const record = asRecord(transaction);
+    const payments = asRecord(record.payments);
+    const attempts = payments.attempts;
+    const code = lastRefusalRow(attempts, "paymentErrorCode")?.code ?? null;
+    const malformed = transaction === null || typeof transaction !== "object" || Array.isArray(transaction)
+        || (record.payments !== undefined && (record.payments === null || typeof record.payments !== "object" || Array.isArray(record.payments)))
+        || (attempts !== undefined && !Array.isArray(attempts))
+        || (Array.isArray(attempts) && attempts.some((row) => {
+            const item = asRecord(row);
+            return row === null || typeof row !== "object" || Array.isArray(row)
+                || (item.paymentErrorCode !== undefined && item.paymentErrorCode !== null && typeof item.paymentErrorCode !== "string");
+        }));
+    return { code, disposition: malformed ? "unreadable" : code ? "present" : "absent" };
+}
+/** One bounded read; diagnostic failure never changes terminalization or legacy code. */
+export async function readAttemptDeclineObservation(client, transactionId, timeoutMs = DECLINE_CODE_READBACK_TIMEOUT_MS) {
+    if (!transactionId)
+        return { code: null, disposition: "absent" };
+    let deadline;
+    try {
+        return await Promise.race([
+            Promise.resolve().then(() => client.getTransaction(transactionId)).then((transaction) => {
+                const observation = attemptDeclineObservation(transaction);
+                const actualId = asRecord(transaction).transactionId ?? asRecord(transaction).id;
+                return typeof actualId === "string" && actualId.trim() !== transactionId
+                    ? { ...observation, disposition: "unreadable", identityMismatch: true } : observation;
+            }, () => ({ code: null, disposition: "read_failed" })),
+            new Promise((resolve) => {
+                deadline = setTimeout(() => resolve({ code: null, disposition: "read_timeout" }), timeoutMs);
+            }),
+        ]);
+    }
+    catch {
+        return { code: null, disposition: "read_failed" };
+    }
+    finally {
+        if (deadline !== undefined)
+            clearTimeout(deadline);
+    }
+}
+/** Legacy attribution remains a separate field with unchanged precedence. */
+export function declineEvidenceSource(input) {
+    return input.decidingAttemptReading !== null ? `attempt_code:${input.attemptCode}`
+        : input.mandateUnsupported ? "prose_regex"
+            : states(input.reading) ? `error_code:${input.errorCode}`
+                : input.attemptCode !== null ? `attempt_code:${input.attemptCode}` : "none";
+}
+/** Whether a reading says anything at all, as opposed to `indeterminate`. */
+export function states(reading) {
+    return reading.hints !== undefined || reading.adviceCode !== undefined;
+}
+/** The one flow in which this provider is asked to REGISTER a reusable mandate. */
+const MANDATE_REGISTRATION_FLOW = "blik_recurring_activation";
+/**
+ * Whether an observation of this flow may conclude anything about the payer's
+ * BANK being able to hold a mandate.
+ *
+ * Only a mandate REGISTRATION can answer that question. A refused charge on an
+ * already-registered mandate proves the bank held one, so a capability code
+ * arriving there says something else — which one, nobody here knows.
+ *
+ * `observedFlow` is `null` for an observer that cannot establish the flow at
+ * all, and that is a real answer rather than a missing argument: the
+ * reconciliation poll sees a transaction readback, and the flow is not a column
+ * of the claim it works from. Unknown is fail-closed for a capability claim, so
+ * such an observer abstains. Parameterized rather than hardcoded per rail, so a
+ * rail that later LEARNS its flow starts stating the claim by passing it, with
+ * no second copy of this rule to keep in step.
+ */
+export function mandateCapabilityReadable(observedFlow) {
+    return observedFlow === MANDATE_REGISTRATION_FLOW;
+}
+/**
+ * The hints one observation is allowed to assert from a reading.
+ *
+ * The reading table is a reading of a CODE and knows nothing about the charge
+ * the code arrived on; this is where the observation's own context is applied
+ * to it. Both rails funnel through here, because a refusal that classifies one
+ * way when the execution path sees it and another way when the poll sees it is
+ * a race rather than a verdict — and the retry ladder cannot be allowed to
+ * terminate on a race.
+ *
+ * Narrow on purpose: only the mandate-capability hint depends on context. Every
+ * other hint states something about the charge itself and crosses untouched.
+ *
+ * The reconciliation rail passes `null` here and therefore always abstains from
+ * that one hint: it reads a transaction back, and a readback cannot tell a
+ * refused mandate REGISTRATION from a refused charge on a mandate the bank
+ * already holds. Abstaining is what it costs to have one verdict per refusal;
+ * the claim stays reachable from evidence that is not a guess, which on a
+ * renewal is the preflight reason this deployment writes itself.
+ */
+export function assertableHints(hints, observedFlow) {
+    if (mandateCapabilityReadable(observedFlow))
+        return hints;
+    return hints?.filter((hint) => hint !== "mandateUnsupported");
+}
+/**
+ * FALLBACK ONLY, since the 2026-08-26 incident. Whether a decline means "this
+ * bank cannot hold a mandate" — the one cause a retry can never fix, and the
+ * only one worth telling a buyer to use a card.
+ *
+ * The deciding signal is now the refusal code in the transaction's attempt log,
+ * read back by `readAttemptDeclineCode`. This heuristic runs only when that read
+ * yields no code, or a code the reading table cannot read. It exists because the
+ * create response's own `errorCode` is generic (`payment_failed` covers a
+ * mistyped code, an expired code and an incapable bank alike), and
+ * `payIdEligible` is absent on EVERY rejection, not just this one — so absence
+ * alone would brand a fat-fingered code as "your bank does not support
+ * recurring". Reading the message is the last resort it always should have been:
+ * only its shape is consulted, and the text itself is never returned or stored,
+ * because it is free-form and can carry payer-identifying detail.
+ *
+ * Restricted to mandate REGISTRATION: a failed charge on an already-registered
+ * mandate proves the bank can hold one, so bank capability is never the answer
+ * there.
+ *
+ * Anything uncertain falls through to a generic decline, whose copy is never
+ * wrong — only less specific.
+ */
+export function isMandateRefusal(flow, payIdEligible, errorMessage) {
+    if (!mandateCapabilityReadable(flow))
+        return false;
+    if (payIdEligible === true)
+        return false;
+    const normalized = errorMessage
+        .normalize("NFKD")
+        .replace(/\p{Diacritic}/gu, "")
+        .toLowerCase();
+    const namesMandate = /alias|payid|powtarzaln|recurring/.test(normalized);
+    const deniesCapability = /nie\s+(?:umozliwia|obsluguje|wspiera|pozwala)|brak\s+(?:mozliwosci|obslugi|wsparcia)|unsupported|not\s+supported|does\s+not\s+support|cannot|can't|unable/.test(normalized);
+    return namesMandate && deniesCapability;
+}
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : {};
+}

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

@@ -0,0 +1,60 @@
+export type TpayTransactionFailurePhase = "oauth" | "transaction_dispatch" | "response_decode";
+/**
+ * What is known about the PROVIDER's side after a failed create-transaction.
+ *
+ * `not_dispatched` - the transaction POST was never invoked.
+ * `refused` - it was invoked, and the provider's own answer proves it created
+ *   nothing. Strictly weaker evidence than `not_dispatched`, and deliberately a
+ *   separate value: the two are proved by different facts and are accepted by
+ *   different control-plane reopen modes.
+ * `unknown` - anything else. A transaction may exist.
+ */
+export type TpayTransactionDispatchState = "not_dispatched" | "refused" | "unknown";
+export type TpayTransactionFailureCode = "tpay_oauth_failed" | "tpay_oauth_timeout" | "tpay_oauth_invalid_response" | "tpay_request_encode_failed" | "tpay_request_deadline_exhausted" | "tpay_request_refused" | "tpay_request_timeout" | "tpay_request_failed" | "tpay_invalid_response" | "tpay_transport_failed";
+export interface TpayTransactionDispatchFailure {
+    phase: TpayTransactionFailurePhase;
+    code: TpayTransactionFailureCode;
+    dispatchState: TpayTransactionDispatchState;
+    failureDiagnostic?: TpayHttpFailureDiagnostic | null;
+}
+export interface TpayTrustedPreDispatchFailure {
+    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";
+}
+/**
+ * The provider answered the create-transaction by refusing the request document
+ * itself. One shape only, because only one thing is provable here: no
+ * transaction was created.
+ */
+export interface TpayTrustedRefusalFailure {
+    phase: "response_decode";
+    code: "tpay_request_refused";
+    dispatchState: "refused";
+}
+/**
+ * Deliberately excludes the transport exception and provider response. This
+ * crosses the money boundary, so consumers may log only the typed facts.
+ */
+export declare class TpayTransactionDispatchError extends Error {
+    readonly phase: TpayTransactionFailurePhase;
+    readonly code: TpayTransactionFailureCode;
+    readonly dispatchState: TpayTransactionDispatchState;
+    readonly failureDiagnostic: TpayHttpFailureDiagnostic | null;
+    constructor(failure: TpayTransactionDispatchFailure);
+}
+export declare function tpayTransactionFailureCode(error: unknown, fallback: TpayTransactionFailureCode): TpayTransactionFailureCode;
+/**
+ * Reads back the refusal the dispatch boundary already decided rather than
+ * re-deriving it: by this point the raw body is gone and only the typed verdict
+ * survives, which is exactly what may cross the money boundary.
+ */
+export declare function tpayTrustedRefusalFailure(error: unknown): TpayTrustedRefusalFailure | null;
+export declare function tpayTrustedPreDispatchFailure(error: unknown): TpayTrustedPreDispatchFailure | null;
+export declare function tpayTransactionDispatchBoundary<Token, Request, Response, Result>(input: {
+    authenticate: () => Promise<Token>;
+    prepare: (token: Token) => Request;
+    dispatch: (request: Request) => Promise<Response>;
+    decode: (response: Response) => Promise<Result>;
+}): Promise<Result>;
+import { type TpayHttpFailureDiagnostic } from "./tpayHttpFailure.js";

package/dist/payments/tpay/tpayDispatchFailure.js

@@ -0,0 +1,121 @@
+/**
+ * Deliberately excludes the transport exception and provider response. This
+ * crosses the money boundary, so consumers may log only the typed facts.
+ */
+export class TpayTransactionDispatchError extends Error {
+    phase;
+    code;
+    dispatchState;
+    failureDiagnostic;
+    constructor(failure) {
+        super(`tpay_transaction_${failure.dispatchState}:${failure.phase}:${failure.code}`);
+        this.name = "TpayTransactionDispatchError";
+        this.phase = failure.phase;
+        this.code = failure.code;
+        this.dispatchState = failure.dispatchState;
+        this.failureDiagnostic = tpayHttpFailureDiagnostic({ failureDiagnostic: failure.failureDiagnostic });
+    }
+}
+export function tpayTransactionFailureCode(error, fallback) {
+    const candidate = error && typeof error === "object" && "code" in error
+        ? error.code
+        : null;
+    return isTpayTransactionFailureCode(candidate) ? candidate : fallback;
+}
+/**
+ * Reads back the refusal the dispatch boundary already decided rather than
+ * re-deriving it: by this point the raw body is gone and only the typed verdict
+ * survives, which is exactly what may cross the money boundary.
+ */
+export function tpayTrustedRefusalFailure(error) {
+    if (!(error instanceof TpayTransactionDispatchError))
+        return null;
+    return error.dispatchState === "refused"
+        && error.phase === "response_decode"
+        && error.code === "tpay_request_refused"
+        ? { phase: "response_decode", code: "tpay_request_refused", dispatchState: "refused" }
+        : null;
+}
+export function tpayTrustedPreDispatchFailure(error) {
+    if (!(error instanceof TpayTransactionDispatchError) || error.dispatchState !== "not_dispatched")
+        return null;
+    const validPhase = error.phase === "oauth" || error.phase === "transaction_dispatch";
+    const validCode = error.code === "tpay_oauth_failed" || error.code === "tpay_oauth_timeout" || error.code === "tpay_oauth_invalid_response" ||
+        error.code === "tpay_request_encode_failed" || error.code === "tpay_request_deadline_exhausted";
+    return validPhase && validCode ? { phase: error.phase, code: error.code, dispatchState: error.dispatchState } : null;
+}
+export async function tpayTransactionDispatchBoundary(input) {
+    let token;
+    try {
+        token = await input.authenticate();
+    }
+    catch (error) {
+        throw new TpayTransactionDispatchError({
+            phase: "oauth",
+            code: tpayOAuthFailureCode(error),
+            dispatchState: "not_dispatched",
+        });
+    }
+    let request;
+    try {
+        request = input.prepare(token);
+    }
+    catch (error) {
+        throw new TpayTransactionDispatchError({
+            phase: "transaction_dispatch",
+            code: tpayTransactionFailureCode(error, "tpay_request_encode_failed"),
+            dispatchState: "not_dispatched",
+        });
+    }
+    let response;
+    try {
+        response = await input.dispatch(request);
+    }
+    catch (error) {
+        throw new TpayTransactionDispatchError({
+            phase: "transaction_dispatch",
+            code: tpayTransactionFailureCode(error, "tpay_transport_failed"),
+            dispatchState: "unknown",
+        });
+    }
+    try {
+        return await input.decode(response);
+    }
+    catch (error) {
+        // A refusal of the request document is the one answer that proves the
+        // provider created nothing. Everything else reaching here - an unparseable
+        // 200, a 5xx, a 409, an opaque 400 - may sit on a real transaction and
+        // stays `unknown`, which keeps the attempt fenced until reconciliation.
+        if (error instanceof TpayHttpError && error.refusedBeforeTransaction) {
+            throw new TpayTransactionDispatchError({
+                phase: "response_decode",
+                code: "tpay_request_refused",
+                dispatchState: "refused",
+                failureDiagnostic: tpayHttpFailureDiagnostic(error),
+            });
+        }
+        throw new TpayTransactionDispatchError({
+            phase: "response_decode",
+            code: tpayTransactionFailureCode(error, "tpay_invalid_response"),
+            dispatchState: "unknown",
+            failureDiagnostic: tpayHttpFailureDiagnostic(error),
+        });
+    }
+}
+function isTpayTransactionFailureCode(value) {
+    return value === "tpay_oauth_failed" ||
+        value === "tpay_oauth_timeout" ||
+        value === "tpay_oauth_invalid_response" ||
+        value === "tpay_request_encode_failed" ||
+        value === "tpay_request_deadline_exhausted" ||
+        value === "tpay_request_refused" ||
+        value === "tpay_request_timeout" ||
+        value === "tpay_request_failed" ||
+        value === "tpay_invalid_response" ||
+        value === "tpay_transport_failed";
+}
+function tpayOAuthFailureCode(error) {
+    const code = tpayTransactionFailureCode(error, "tpay_oauth_failed");
+    return code === "tpay_invalid_response" ? "tpay_oauth_invalid_response" : code;
+}
+import { tpayHttpFailureDiagnostic, TpayHttpError, } from "./tpayHttpFailure.js";

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

@@ -0,0 +1,20 @@
+import type { PaymentRecoveryEvidence } from "@openlup/core/payment";
+import { type FailureObservationSource, type PaymentFailureEvidence } from "./paymentFailureEvidence.js";
+import { type AttemptDeclineObservation } from "./tpayDeclineEvidence.js";
+import type { DeclineCodeReading } from "./declineFailureHints.js";
+export declare function tpayFailureEvidence(input: {
+    source: FailureObservationSource;
+    providerPaymentId: string | null;
+    refusalVerified: boolean;
+    flow: string | null;
+    observation: AttemptDeclineObservation;
+    errorCode?: string | null;
+    reading?: DeclineCodeReading;
+}): PaymentFailureEvidence;
+/** Numeric code hypotheses are not promoted into new customer-facing facts. */
+export declare function normalizeTpayFailureEvidence(input: PaymentFailureEvidence): PaymentRecoveryEvidence;
+/** Existing reconciliation classification; moved intact, never fed new evidence. */
+export declare function refusalCapture(refusal: {
+    code: string;
+    reading: DeclineCodeReading;
+}, failureReasonKey: string): Record<string, unknown>;

package/dist/payments/tpay/tpayFailureEvidence.js

@@ -0,0 +1,61 @@
+import { serializeFailureEvidence } from "./paymentFailureEvidence.js";
+import { assertableHints } from "./tpayDeclineEvidence.js";
+import { classifyDecline } from "./classifyDecline.js";
+/** Known execution construction, never a conclusion drawn from the PSP name. */
+function methodFor(flow) {
+    if (flow === "blik_one_time" || flow === "blik_recurring_activation") {
+        return { kind: "blik", recoveryMethodKey: "blik", interaction: "new_instrument" };
+    }
+    if (flow === "blik_one_click" || flow === "blik_recurring_saved") {
+        return { kind: "blik", recoveryMethodKey: "blik_one_click", interaction: "stored_instrument" };
+    }
+    return flow === "pbl_one_time"
+        ? { kind: "bank_transfer", recoveryMethodKey: "transfer", interaction: "new_instrument" } : null;
+}
+export function tpayFailureEvidence(input) {
+    const method = methodFor(input.flow);
+    const advice = input.observation.identityMismatch ? null : input.reading?.adviceCode ?? null;
+    const operation = input.flow === "blik_recurring_activation"
+        ? "recurring_setup" : method?.interaction === "stored_instrument"
+        ? "stored_method_payment" : method ? "one_time_payment" : null;
+    return serializeFailureEvidence({
+        version: 1, source: input.source, disposition: input.observation.disposition,
+        refusalVerified: input.refusalVerified, providerPaymentId: input.providerPaymentId, providerChargeId: null,
+        code: input.errorCode ?? null, declineCode: input.observation.identityMismatch ? null : input.observation.code,
+        adviceCode: advice,
+        // This table is explicitly inferred; it must never masquerade as issuer advice.
+        adviceOrigin: advice ? "inferred" : "unknown",
+        operation, method, methodSource: method ? "execution_contract" : "unknown",
+    });
+}
+/** Numeric code hypotheses are not promoted into new customer-facing facts. */
+export function normalizeTpayFailureEvidence(input) {
+    const evidence = serializeFailureEvidence(input);
+    // The operation is context, not a cause: a mistyped or expired BLIK code is
+    // refused inside a mandate registration too. Only the persisted mandate
+    // decision (`failure_reason`) may say the agreement itself was refused.
+    return {
+        refusalVerified: evidence.refusalVerified,
+        cause: "generic_decline",
+        certainty: "unknown", disclosure: "safe",
+        method: evidence.method, operation: evidence.operation, advice: null,
+    };
+}
+/** Existing reconciliation classification; moved intact, never fed new evidence. */
+export function refusalCapture(refusal, failureReasonKey) {
+    const hints = assertableHints(refusal.reading.hints, null) ?? [];
+    const classification = classifyDecline({
+        code: refusal.code,
+        mandateUnsupported: false,
+        declineCode: refusal.code,
+        ...(refusal.reading.adviceCode ? { adviceCode: refusal.reading.adviceCode } : {}),
+        ...(hints.length > 0 ? { neutralReasonHints: hints } : {}),
+    }, { failureReasonKey });
+    return {
+        declineCode: refusal.code,
+        adviceCode: refusal.reading.adviceCode ?? null,
+        neutralReasonHints: hints,
+        failureClass: classification.failureClass,
+        failureClassDecidedBy: classification.decidedBy,
+    };
+}

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

@@ -0,0 +1,52 @@
+import { type TpayTransactionCreateInput, type TpayTransactionCreated } from "./tpayTransactionPayload.js";
+export { TpayHttpError } from "./tpayHttpFailure.js";
+export interface TpayFetchLike {
+    (url: string, init?: {
+        method?: string;
+        headers?: Record<string, string>;
+        body?: string;
+        signal?: AbortSignal;
+    }): Promise<{
+        ok: boolean;
+        status: number;
+        json(): Promise<unknown>;
+        text(): Promise<string>;
+    }>;
+}
+export interface TpayHttpClientOptions {
+    baseUrl: string;
+    clientId: string;
+    clientSecret: string;
+    timeoutMs?: number;
+    fetchImpl?: TpayFetchLike;
+    now?: () => number;
+}
+export type { TpayAliasInput, TpayPayerInput, TpayPaymentError, TpayTransactionCreateInput, TpayTransactionCreated, } from "./tpayTransactionPayload.js";
+export interface TpayPaymentChannel {
+    id: string;
+    name: string;
+    fullName: string;
+    available: boolean;
+    onlinePayment: boolean;
+    instantRedirection: boolean;
+    groups: Array<{
+        id: number;
+        name: string;
+    }>;
+}
+export interface TpayHttpClient {
+    createTransaction(input: TpayTransactionCreateInput): Promise<TpayTransactionCreated>;
+    getTransaction(transactionId: string): Promise<TpayTransactionReadback>;
+    listPaymentChannels(): Promise<TpayPaymentChannel[]>;
+}
+export interface TpayTransactionReadback extends Record<string, unknown> {
+    transactionId: string;
+    title: string | null;
+    status: string;
+    transactionPaymentUrl: string | null;
+    amount: number | null;
+    currency: string | null;
+    requestId: string | null;
+    payments: Record<string, unknown>;
+}
+export declare function createTpayHttpClient({ baseUrl, clientId, clientSecret, timeoutMs, fetchImpl, now, }: TpayHttpClientOptions): TpayHttpClient;