@openlup/platform 0.20.0 → 0.21.0

package/dist/payments/tpay/tpayHttpClient.js

@@ -0,0 +1,185 @@
+import { buildTpayTransactionPayload, } from "./tpayTransactionPayload.js";
+import { tpayTransactionDispatchBoundary } from "./tpayDispatchFailure.js";
+import { readTpayHttpFailure, TpayHttpError } from "./tpayHttpFailure.js";
+export { TpayHttpError } from "./tpayHttpFailure.js";
+const TOKEN_REFRESH_SKEW_MS = 60_000;
+const DEFAULT_TPAY_TIMEOUT_MS = 10_000;
+export function createTpayHttpClient({ baseUrl, clientId, clientSecret, timeoutMs = DEFAULT_TPAY_TIMEOUT_MS, fetchImpl = globalThis.fetch, now = () => Date.now(), }) {
+    let token = null;
+    const normalizedBaseUrl = baseUrl.replace(/\/+$/, "");
+    function requestDeadline() {
+        return { expiresAtMs: Date.now() + timeoutMs };
+    }
+    async function bearer(deadline) {
+        if (token && token.expiresAtMs - TOKEN_REFRESH_SKEW_MS > now()) {
+            return token.accessToken;
+        }
+        const body = new URLSearchParams({ client_id: clientId, client_secret: clientSecret });
+        const response = await fetchWithTimeout(fetchImpl, `${normalizedBaseUrl}/oauth/auth`, {
+            method: "POST",
+            headers: { "Content-Type": "application/x-www-form-urlencoded" },
+            body: body.toString(),
+        }, remainingTimeoutMs(deadline, "tpay_oauth_timeout"), "tpay_oauth_timeout");
+        const json = await readJson(response, "tpay_oauth_failed");
+        const accessToken = readString(json, "access_token");
+        const expiresIn = readNumber(json, "expires_in");
+        token = { accessToken, expiresAtMs: now() + expiresIn * 1000 };
+        return accessToken;
+    }
+    async function request(path, init = {}, deadline = requestDeadline()) {
+        const headers = { Authorization: `Bearer ${await bearer(deadline)}` };
+        let body;
+        if (init.body !== undefined) {
+            headers["Content-Type"] = "application/json";
+            body = JSON.stringify(init.body);
+        }
+        const response = await fetchWithTimeout(fetchImpl, `${normalizedBaseUrl}${path}`, {
+            method: init.method ?? "GET",
+            headers,
+            body,
+        }, remainingTimeoutMs(deadline, "tpay_request_timeout"), "tpay_request_timeout");
+        return readJson(response, "tpay_request_failed");
+    }
+    return {
+        async createTransaction(input) {
+            const deadline = requestDeadline();
+            return tpayTransactionDispatchBoundary({
+                authenticate: () => bearer(deadline),
+                prepare: (accessToken) => ({
+                    headers: { Authorization: `Bearer ${accessToken}`, "Content-Type": "application/json" },
+                    body: JSON.stringify(buildTpayTransactionPayload(input)),
+                    timeoutMs: remainingTimeoutMs(deadline, "tpay_request_deadline_exhausted"),
+                }),
+                dispatch: ({ headers, body, timeoutMs }) => fetchWithTimeout(fetchImpl, `${normalizedBaseUrl}/transactions`, { method: "POST", headers, body }, timeoutMs, "tpay_request_timeout"),
+                decode: async (response) => {
+                    const json = await readJson(response, "tpay_request_failed");
+                    const payments = asRecord(json.payments);
+                    return {
+                        transactionId: readString(json, "transactionId"),
+                        title: readString(json, "title"),
+                        status: readString(json, "status"),
+                        transactionPaymentUrl: readNullableString(json, "transactionPaymentUrl"),
+                        requestId: readNullableString(json, "requestId"),
+                        payIdEligible: typeof payments.payIdEligible === "boolean" ? payments.payIdEligible : null,
+                        errors: readPaymentErrors(payments.errors),
+                    };
+                },
+            });
+        },
+        async getTransaction(transactionId) {
+            const json = await request(`/transactions/${encodeURIComponent(transactionId)}`, {}, requestDeadline());
+            return {
+                // Keep provider fields that recovery normalizes later (notably nested
+                // dates and paidAmount). Explicit canonical fields below remain the
+                // typed client contract.
+                ...json,
+                transactionId: readString(json, "transactionId"),
+                title: readNullableString(json, "title"),
+                status: readString(json, "status"),
+                transactionPaymentUrl: readNullableString(json, "transactionPaymentUrl"),
+                amount: readNullableTransactionAmount(json, "amount"),
+                currency: readNullableString(json, "currency"),
+                requestId: readNullableString(json, "requestId"),
+                payments: asRecord(json.payments),
+            };
+        },
+        async listPaymentChannels() {
+            const json = await request("/transactions/channels", {}, requestDeadline());
+            const channels = Array.isArray(json.channels)
+                ? json.channels
+                : [];
+            return channels.map(mapChannel);
+        },
+    };
+}
+function remainingTimeoutMs(deadline, timeoutCode) {
+    const remaining = deadline.expiresAtMs - Date.now();
+    if (remaining <= 0)
+        throw new TpayHttpError(timeoutCode, 504);
+    return remaining;
+}
+async function fetchWithTimeout(fetchImpl, url, init, timeoutMs, timeoutCode) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        return await fetchImpl(url, { ...init, signal: controller.signal });
+    }
+    catch (error) {
+        if (controller.signal.aborted) {
+            throw new TpayHttpError(timeoutCode, 504);
+        }
+        throw error;
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+function asRecord(value) {
+    return value && typeof value === "object" ? value : {};
+}
+function readPaymentErrors(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.map((entry) => {
+        const record = asRecord(entry);
+        return {
+            errorCode: String(record.errorCode ?? ""),
+            errorMessage: String(record.errorMessage ?? ""),
+            fieldName: typeof record.fieldName === "string" ? record.fieldName : null,
+        };
+    });
+}
+async function readJson(response, code) {
+    if (!response.ok) {
+        const failure = await readTpayHttpFailure(response);
+        throw new TpayHttpError(code, response.status, failure.diagnostic, failure.refusedBeforeTransaction);
+    }
+    const json = await response.json();
+    if (!json || typeof json !== "object")
+        throw new TpayHttpError("tpay_invalid_response", response.status);
+    return json;
+}
+function mapChannel(value) {
+    const record = value && typeof value === "object" ? value : {};
+    return {
+        id: String(record.id ?? ""),
+        name: String(record.name ?? ""),
+        fullName: String(record.fullName ?? record.name ?? ""),
+        available: record.available === true,
+        onlinePayment: record.onlinePayment === true,
+        instantRedirection: record.instantRedirection === true,
+        groups: Array.isArray(record.groups) ? record.groups.map(mapGroup) : [],
+    };
+}
+function mapGroup(value) {
+    const record = value && typeof value === "object" ? value : {};
+    return { id: Number(record.id ?? 0), name: String(record.name ?? "") };
+}
+function readString(value, key) {
+    const raw = value[key];
+    if (typeof raw !== "string" || raw.length === 0)
+        throw new TpayHttpError("tpay_invalid_response", 200);
+    return raw;
+}
+function readNullableString(value, key) {
+    const raw = value[key];
+    return typeof raw === "string" && raw.length > 0 ? raw : null;
+}
+function readNumber(value, key) {
+    const raw = value[key];
+    if (typeof raw !== "number" || !Number.isFinite(raw))
+        throw new TpayHttpError("tpay_invalid_response", 200);
+    return raw;
+}
+function readNullableTransactionAmount(value, key) {
+    const raw = value[key];
+    if (typeof raw === "number")
+        return Number.isFinite(raw) ? raw : null;
+    if (typeof raw !== "string")
+        return null;
+    const trimmed = raw.trim();
+    if (!/^\d+(?:\.\d+)?$/.test(trimmed))
+        return null;
+    const parsed = Number(trimmed);
+    return Number.isFinite(parsed) ? parsed : null;
+}

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

@@ -0,0 +1,57 @@
+export interface TpayHttpFailureDiagnostic {
+    httpStatus: number;
+    requestId: string | null;
+    providerErrorCodes: string[];
+    fieldNames: string[];
+}
+/**
+ * The provider answered, and its answer is read for two independent things: the
+ * sanitized diagnostic that may be logged, and whether the refusal PROVES no
+ * transaction was created.
+ */
+export interface TpayHttpFailure {
+    diagnostic: TpayHttpFailureDiagnostic;
+    /**
+     * Tpay rejected the request document itself, so no transaction row can exist.
+     * `false` is the fail-closed answer and the only one any ambiguity produces.
+     */
+    refusedBeforeTransaction: boolean;
+}
+/**
+ * Tpay error codes that describe the REQUEST DOCUMENT — a missing field, a wrong
+ * type, an out-of-range or malformed value, an unknown field, an unparseable
+ * body, a wrong content type. Every one of them is decided by request validation
+ * and therefore cannot be produced once a transaction row exists.
+ *
+ * Deliberately excluded, and each for a reason: `crc_not_unique` names an
+ * ALREADY EXISTING transaction; `transaction_lock`, `transaction_blocked`,
+ * `payment_failed` and `ts:transaction:*` describe a transaction's outcome or a
+ * partially completed insert; `cannot_create_transaction`,
+ * `partner_cannot_create_transaction` and every channel/merchant availability
+ * code refuse for reasons whose ordering against creation we cannot prove from
+ * here; `general` and `internal_server_error` are opaque. A refusal carrying any
+ * of them keeps today's behavior and defers to reconciliation.
+ *
+ * ⚠️ This list is matched against the RAW body, never against
+ * `TpayHttpFailureDiagnostic.providerErrorCodes` — that projection drops any code
+ * outside the loggable set, which would turn a mixed body into a uniformly safe
+ * one.
+ */
+export declare const TPAY_PRE_TRANSACTION_REFUSAL_CODES: ReadonlySet<string>;
+export declare function readTpayHttpFailure(response: {
+    status: number;
+    text(): Promise<string>;
+}): Promise<TpayHttpFailure>;
+export declare function tpayHttpFailureDiagnostic(error: unknown): TpayHttpFailureDiagnostic | null;
+export declare class TpayHttpError extends Error {
+    readonly code: string;
+    readonly status: number;
+    readonly failureDiagnostic: TpayHttpFailureDiagnostic | null;
+    /**
+     * Set only from a body this client actually parsed. It never crosses a
+     * boundary as a claim on its own — the dispatch boundary turns it into typed
+     * evidence, and the control-plane RPC re-proves the attempt independently.
+     */
+    readonly refusedBeforeTransaction: boolean;
+    constructor(code: string, status: number, failureDiagnostic?: TpayHttpFailureDiagnostic | null, refusedBeforeTransaction?: boolean);
+}

package/dist/payments/tpay/tpayHttpFailure.js

@@ -0,0 +1,143 @@
+import { loggableProviderErrorCode, loggableProviderFieldName, loggableProviderRequestId, } from "./providerAttemptFailureDiagnostic.js";
+/**
+ * Tpay error codes that describe the REQUEST DOCUMENT — a missing field, a wrong
+ * type, an out-of-range or malformed value, an unknown field, an unparseable
+ * body, a wrong content type. Every one of them is decided by request validation
+ * and therefore cannot be produced once a transaction row exists.
+ *
+ * Deliberately excluded, and each for a reason: `crc_not_unique` names an
+ * ALREADY EXISTING transaction; `transaction_lock`, `transaction_blocked`,
+ * `payment_failed` and `ts:transaction:*` describe a transaction's outcome or a
+ * partially completed insert; `cannot_create_transaction`,
+ * `partner_cannot_create_transaction` and every channel/merchant availability
+ * code refuse for reasons whose ordering against creation we cannot prove from
+ * here; `general` and `internal_server_error` are opaque. A refusal carrying any
+ * of them keeps today's behavior and defers to reconciliation.
+ *
+ * ⚠️ This list is matched against the RAW body, never against
+ * `TpayHttpFailureDiagnostic.providerErrorCodes` — that projection drops any code
+ * outside the loggable set, which would turn a mixed body into a uniformly safe
+ * one.
+ */
+export const TPAY_PRE_TRANSACTION_REFUSAL_CODES = new Set([
+    "country_not_valid",
+    "field_required",
+    "incorrect_content_type",
+    "invalid_request_body",
+    "is_required",
+    "not_array",
+    "not_natural_int",
+    "not_string",
+    "not_valid",
+    "too_low",
+    "ts:country:not_valid",
+    "ts:payer:phone:not_valid",
+    "unexpected_field",
+]);
+/** The one HTTP status on which Tpay reports request validation. */
+const TPAY_REQUEST_VALIDATION_STATUS = 400;
+const MAX_FAILURE_BODY_BYTES = 16_384;
+const MAX_DIAGNOSTIC_ITEMS = 5;
+export async function readTpayHttpFailure(response) {
+    const base = emptyDiagnostic(response.status);
+    try {
+        const body = await response.text();
+        if (body.length > MAX_FAILURE_BODY_BYTES)
+            return unreadableFailure(base);
+        const parsed = JSON.parse(body);
+        const root = asRecord(parsed);
+        const payment = asRecord(root.payments);
+        const errors = [...readArray(root.errors), ...readArray(payment.errors)];
+        const rawErrorCodes = errors.map((entry) => asRecord(entry).errorCode);
+        return {
+            diagnostic: {
+                ...base,
+                requestId: loggableProviderRequestId(root.requestId) ? root.requestId : null,
+                providerErrorCodes: allowedValues(errors.map((entry) => asRecord(entry).errorCode), loggableProviderErrorCode),
+                fieldNames: allowedValues(errors.map((entry) => asRecord(entry).fieldName), loggableProviderFieldName),
+            },
+            refusedBeforeTransaction: refusedBeforeTransaction(response.status, rawErrorCodes),
+        };
+    }
+    catch {
+        return unreadableFailure(base);
+    }
+}
+/**
+ * Whether this answer proves Tpay created nothing.
+ *
+ * Three conditions, all required. The status must be exactly the validation
+ * status: a 409 may name an existing transaction, a 429 or any 5xx may follow
+ * one that was created before the response was lost. The body must have yielded
+ * at least one error code, so an opaque refusal from an edge proxy — which we
+ * cannot attribute to Tpay's validator — releases nothing. And EVERY raw code
+ * must be allow-listed, including codes this repository does not otherwise
+ * recognize, so one unknown code in a mixed body is enough to refuse.
+ */
+function refusedBeforeTransaction(status, rawErrorCodes) {
+    return status === TPAY_REQUEST_VALIDATION_STATUS
+        && rawErrorCodes.length > 0
+        && rawErrorCodes.every((code) => typeof code === "string" && TPAY_PRE_TRANSACTION_REFUSAL_CODES.has(code));
+}
+function unreadableFailure(diagnostic) {
+    return { diagnostic, refusedBeforeTransaction: false };
+}
+export function tpayHttpFailureDiagnostic(error) {
+    if (!error || typeof error !== "object")
+        return null;
+    const value = asRecord(error.failureDiagnostic);
+    const httpStatus = value.httpStatus;
+    const requestId = value.requestId;
+    const providerErrorCodes = value.providerErrorCodes;
+    const fieldNames = value.fieldNames;
+    if (!Number.isInteger(httpStatus) || httpStatus < 100 || httpStatus > 599)
+        return null;
+    if (requestId !== null && !loggableProviderRequestId(requestId))
+        return null;
+    if (!validAllowedValues(providerErrorCodes, loggableProviderErrorCode)
+        || !validAllowedValues(fieldNames, loggableProviderFieldName))
+        return null;
+    return {
+        httpStatus: httpStatus,
+        requestId: requestId,
+        providerErrorCodes: [...providerErrorCodes],
+        fieldNames: [...fieldNames],
+    };
+}
+export class TpayHttpError extends Error {
+    code;
+    status;
+    failureDiagnostic;
+    /**
+     * Set only from a body this client actually parsed. It never crosses a
+     * boundary as a claim on its own — the dispatch boundary turns it into typed
+     * evidence, and the control-plane RPC re-proves the attempt independently.
+     */
+    refusedBeforeTransaction;
+    constructor(code, status, failureDiagnostic = null, refusedBeforeTransaction = false) {
+        super(code);
+        this.name = "TpayHttpError";
+        this.code = code;
+        this.status = status;
+        this.failureDiagnostic = failureDiagnostic;
+        this.refusedBeforeTransaction = refusedBeforeTransaction;
+    }
+}
+function emptyDiagnostic(httpStatus) {
+    return { httpStatus, requestId: null, providerErrorCodes: [], fieldNames: [] };
+}
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : {};
+}
+function readArray(value) {
+    return Array.isArray(value) ? value : [];
+}
+function allowedValues(values, allowed) {
+    return [...new Set(values.filter(allowed))].slice(0, MAX_DIAGNOSTIC_ITEMS);
+}
+function validAllowedValues(value, allowed) {
+    return Array.isArray(value) && value.length <= MAX_DIAGNOSTIC_ITEMS
+        && value.every(allowed);
+}

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

@@ -0,0 +1,20 @@
+import type { PaymentExecutionPort } from "./donorContracts.js";
+import type { PaymentExecutionInput } from "./donorContracts.js";
+import type { TpayHttpClient, TpayPayerInput } from "./tpayHttpClient.js";
+/** The one place this adapter spells its own provider identity. */
+export declare const PROVIDER_KIND: "tpay";
+export interface TpayPaymentExecutionAdapterOptions {
+    client: TpayHttpClient;
+    notificationUrl: string;
+    successUrl: string;
+    errorUrl: string;
+    oneClickEnabled?: boolean;
+    aliasRegistrationOnCodeEnabled?: boolean;
+    /** One public switch for admitting new subscription BLIK Model O mandates. */
+    modelOActivationEnabled?: boolean;
+    resolvePayer?: (input: PaymentExecutionInput) => TpayPayerInput | null;
+}
+export declare function createTpayPaymentExecutionAdapter({ client, notificationUrl, successUrl, errorUrl, oneClickEnabled, aliasRegistrationOnCodeEnabled, modelOActivationEnabled, resolvePayer, }: TpayPaymentExecutionAdapterOptions): PaymentExecutionPort;
+export declare class TpayExecutionInputError extends Error {
+    constructor(message: string);
+}

package/dist/payments/tpay/tpayPaymentExecutionAdapter.js

@@ -0,0 +1,249 @@
+import { failureEvidencePayload } from "./paymentFailureEvidence.js";
+import { tpayFailureEvidence } from "./tpayFailureEvidence.js";
+import { aliasValue, buildCreateTransactionInput, resolveRecurringModel, } from "./tpayCreateTransactionInput.js";
+import { declineCodeReading } from "./declineFailureHints.js";
+import { assertableHints, isMandateRefusal, mandateCapabilityReadable, readAttemptDeclineObservation, declineEvidenceSource, states, } from "./tpayDeclineEvidence.js";
+import { tpayTrustedPreDispatchFailure, tpayTrustedRefusalFailure, } from "./tpayDispatchFailure.js";
+import { ProviderAttemptPreDispatchError } from "./preparedProviderAttempt.js";
+/** The one place this adapter spells its own provider identity. */
+export const PROVIDER_KIND = "tpay";
+export function createTpayPaymentExecutionAdapter({ client, notificationUrl, successUrl, errorUrl, oneClickEnabled = false, aliasRegistrationOnCodeEnabled = false, modelOActivationEnabled = false, resolvePayer = defaultPayer, }) {
+    const validateInput = (input) => {
+        const transient = requireTpayTransientInput(input, {
+            oneClickEnabled,
+            modelOActivationEnabled,
+        });
+        if (input.currency !== "PLN")
+            throw new TpayExecutionInputError("tpay_currency_not_supported");
+        const payer = resolvePayer(input);
+        if (!payer)
+            throw new TpayExecutionInputError("tpay_payer_missing");
+        return { transient, payer };
+    };
+    return {
+        validateInput(input) {
+            validateInput(input);
+        },
+        async execute(input) {
+            const { transient, payer } = validateInput(input);
+            const request = buildCreateTransactionInput({
+                input,
+                transient,
+                payer,
+                notificationUrl,
+                successUrl,
+                errorUrl,
+                aliasRegistrationOnCodeEnabled,
+                modelOActivationEnabled,
+            });
+            let response;
+            try {
+                response = await client.createTransaction(request);
+            }
+            catch (error) {
+                // Two independent proofs Tpay holds no transaction: never asked, or it refused the request
+                // document. Both release the attempt; everything else stays ambiguous and rethrows.
+                const noCharge = tpayTrustedPreDispatchFailure(error) ?? tpayTrustedRefusalFailure(error);
+                if (noCharge)
+                    throw new ProviderAttemptPreDispatchError(noCharge);
+                throw error;
+            }
+            const providerAttemptId = response.title || response.transactionId;
+            // This provider reports a synchronous decline ONLY here. `result`, `status`
+            // and `payments.status` all still read "success"/"pending" on a rejected
+            // transaction, so they cannot be used to detect one.
+            const rejections = response.errors ?? [];
+            const rejection = rejections[0] ?? null;
+            // The provider has carried a hard refusal code since the first minute, but
+            // only in the transaction's attempt log — never in the create response,
+            // whose codes are generic. So ask for it the moment the provider says no,
+            // instead of learning it hours later from the reconciliation poll.
+            // Fail-open: `null` means "read nothing", and every branch below then
+            // behaves exactly as it did before this read existed.
+            const observation = rejection
+                ? await readAttemptDeclineObservation(client, response.transactionId)
+                : null;
+            const attemptCode = observation?.code ?? null;
+            // A code the table cannot read decides nothing. Promoting a known-unknown
+            // such as `"100"` to a verdict would silence the message fallback for the
+            // one code we openly admit we cannot read — a regression, not a fix.
+            const attemptReading = attemptCode === null ? null : declineCodeReading(attemptCode);
+            const decidingAttemptReading = attemptReading !== null && states(attemptReading)
+                ? attemptReading
+                : null;
+            const mandateUnsupported = decidingAttemptReading
+                ? mandateCapabilityReadable(transient.flow)
+                    && response.payIdEligible !== true
+                    && (decidingAttemptReading.hints?.includes("mandateUnsupported") ?? false)
+                : rejection !== null && rejections.some((error) => isMandateRefusal(transient.flow, response.payIdEligible, error.errorMessage));
+            // Read here, where the code vocabulary is owned, so the control plane
+            // classifies the refusal without ever seeing a provider-native code. The
+            // attempt log wins when it says something, because it is the carrier the
+            // provider itself writes the refusal into; the create response's own code
+            // is the fallback reading.
+            // The advice half is suppressed when this adapter is already asserting a
+            // mandate refusal: advice outranks hints by design in the taxonomy, and
+            // the identity code is only the FIRST error, so a generic terminal code
+            // arriving ahead of the mandate explanation would otherwise mask the one
+            // reading that says the stored reference — not the instrument — is dead.
+            const reading = decidingAttemptReading ?? declineCodeReading(rejection?.errorCode);
+            const declineEvidence = rejection ? declineEvidenceSource({
+                attemptCode, decidingAttemptReading, mandateUnsupported, reading, errorCode: rejection.errorCode,
+            }) : null;
+            // A capability code is read as mandate evidence only while registering a
+            // mandate. The same opaque code on one-time or stored-mandate charges must
+            // not claim that a mandate is dead. The rule itself lives beside the
+            // refusal evidence it qualifies, because the reconciliation rail funnels
+            // its hints through the same one — a refusal must not classify by which
+            // rail saw it.
+            const neutralReasonHints = assertableHints(reading.hints, transient.flow);
+            const providerDecline = rejection
+                ? {
+                    code: rejection.errorCode,
+                    // Preserve the first provider code as the stable decline identity, but
+                    // inspect every error for the capability signal. The provider may put a
+                    // generic payment failure first and the mandate explanation later.
+                    mandateUnsupported,
+                    ...(reading.adviceCode && !mandateUnsupported ? { adviceCode: reading.adviceCode } : {}),
+                    ...(neutralReasonHints?.length ? { neutralReasonHints } : {}),
+                }
+                : null;
+            return {
+                provider: PROVIDER_KIND,
+                providerAttemptId,
+                providerSessionId: response.transactionId,
+                // Stays non-terminal even on a decline: the control plane owns terminal
+                // transitions and reads `providerDecline` below to make one.
+                attemptStatus: "processing",
+                providerDecline,
+                nextActionKind: !providerDecline && transient.flow === "pbl_one_time" && response.transactionPaymentUrl
+                    ? "redirect"
+                    : null,
+                redirectUrl: providerDecline ? null : response.transactionPaymentUrl,
+                // A rejected activation must not publish a payment method reference.
+                paymentMethodRef: transient.flow === "blik_recurring_activation" && !providerDecline
+                    ? aliasValue(input.paymentIntentId)
+                    : null,
+                // A declined transaction produces no webhook at all: Tpay's `tr_status`
+                // only ever carries `true` or `chargeback`. Claiming otherwise would
+                // strand the attempt waiting for a callback that never arrives.
+                webhookExpected: !providerDecline,
+                recoveryRequired: false,
+                requestPayload: {
+                    providerIdempotencyKey: input.providerIdempotencyKey,
+                    providerRequestFingerprint: input.providerRequestFingerprint,
+                    providerFlow: transient.flow,
+                    amountMinor: input.amountMinor,
+                    currency: input.currency,
+                    orderRef: input.orderRef,
+                    channelId: transient.flow === "pbl_one_time" ? transient.channelId : undefined,
+                    // The model actually sent, not the one the client asked for — the single
+                    // activation switch can make those diverge, and this field is where a
+                    // diagnosis looks for the truth.
+                    recurringModel: transient.flow === "blik_recurring_activation"
+                        ? resolveRecurringModel(transient.recurringModel, modelOActivationEnabled)
+                        : undefined,
+                    methodRefPresent: transient.flow === "recurring_charge" || transient.flow === "blik_one_click"
+                        ? Boolean(input.paymentMethodRef)
+                        : undefined,
+                    methodRefAliasType: transient.flow === "recurring_charge" || transient.flow === "blik_one_click"
+                        ? input.paymentMethodAliasType ?? "PAYID"
+                        : undefined,
+                    aliasRegistrationRequested: transient.flow === "blik_one_time"
+                        ? aliasRegistrationOnCodeEnabled
+                        : undefined,
+                },
+                responsePayload: {
+                    providerStatus: response.status,
+                    providerAttemptId,
+                    providerSessionId: response.transactionId,
+                    requestId: response.requestId,
+                    redirectUrlPresent: Boolean(response.transactionPaymentUrl),
+                    payIdEligible: response.payIdEligible,
+                    // Codes only. `errorMessage` is free-form prose that can carry
+                    // payer-identifying text, so it never reaches our stored payload.
+                    providerErrorCodes: (response.errors ?? []).map((error) => error.errorCode),
+                    ...(declineEvidence ? { declineEvidence } : {}),
+                    ...failureEvidencePayload(observation ? tpayFailureEvidence({
+                        source: "execution", providerPaymentId: response.transactionId, refusalVerified: true,
+                        flow: transient.flow, observation, errorCode: rejection?.errorCode, reading,
+                    }) : null),
+                },
+            };
+        },
+    };
+}
+function requireTpayTransientInput(input, options) {
+    if (input.providerFlow === "blik_one_click") {
+        if (!options.oneClickEnabled)
+            throw new TpayExecutionInputError("tpay_blik_one_click_not_enabled");
+        if (input.mode !== "one_time")
+            throw new TpayExecutionInputError("tpay_blik_one_click_requires_one_time");
+        if (!input.paymentMethodRef)
+            throw new TpayExecutionInputError("tpay_blik_one_click_payid_missing");
+        if (input.transientProviderInput && input.transientProviderInput.flow !== "blik_one_click") {
+            throw new TpayExecutionInputError("tpay_provider_flow_mismatch");
+        }
+        return { provider: PROVIDER_KIND, flow: "blik_one_click" };
+    }
+    if (input.providerFlow === "recurring_charge") {
+        if (input.mode !== "subscription_cycle")
+            throw new TpayExecutionInputError("tpay_recurring_charge_requires_cycle");
+        if (!input.paymentMethodRef)
+            throw new TpayExecutionInputError("tpay_recurring_charge_payid_missing");
+        if (input.paymentMethodAliasType && input.paymentMethodAliasType !== "PAYID") {
+            throw new TpayExecutionInputError("tpay_recurring_charge_requires_payid");
+        }
+        if (input.paymentMethodRecurringModel !== "O") {
+            throw new TpayExecutionInputError("tpay_recurring_charge_requires_model_o");
+        }
+        if (input.transientProviderInput && input.transientProviderInput.flow !== "recurring_charge") {
+            throw new TpayExecutionInputError("tpay_provider_flow_mismatch");
+        }
+        return { provider: PROVIDER_KIND, flow: "recurring_charge" };
+    }
+    const transient = input.transientProviderInput;
+    if (!transient || transient.provider !== PROVIDER_KIND)
+        throw new TpayExecutionInputError("tpay_transient_input_missing");
+    if (input.providerFlow && input.providerFlow !== transient.flow) {
+        throw new TpayExecutionInputError("tpay_provider_flow_mismatch");
+    }
+    if (transient.flow === "blik_one_time" || transient.flow === "blik_recurring_activation") {
+        if (!transient.blikToken)
+            throw new TpayExecutionInputError("tpay_blik_token_missing");
+    }
+    if (transient.flow === "pbl_one_time" && !transient.channelId) {
+        throw new TpayExecutionInputError("tpay_channel_id_missing");
+    }
+    if (transient.flow === "pbl_one_time" && input.mode !== "one_time") {
+        throw new TpayExecutionInputError("tpay_pbl_recurring_not_supported");
+    }
+    if (transient.flow === "blik_recurring_activation") {
+        if (!options.modelOActivationEnabled) {
+            throw new TpayExecutionInputError("tpay_blik_recurring_activation_not_enabled");
+        }
+        if (transient.recurringModel !== "O") {
+            throw new TpayExecutionInputError("tpay_blik_model_o_required");
+        }
+        if (input.mode !== "subscription_cycle") {
+            throw new TpayExecutionInputError("tpay_blik_recurring_activation_requires_subscription_cycle");
+        }
+        if (input.saveForFutureUse !== true) {
+            throw new TpayExecutionInputError("tpay_blik_recurring_activation_requires_save_for_future_use");
+        }
+    }
+    return transient;
+}
+function defaultPayer(input) {
+    if (input.payer)
+        return input.payer;
+    if (!input.customerRef)
+        return null;
+    return { email: input.customerRef, name: "Customer" };
+}
+export class TpayExecutionInputError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "TpayExecutionInputError";
+    }
+}

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

@@ -0,0 +1,5 @@
+import type { ProviderReconciliationStatus } from "./donorContracts.js";
+import type { PaymentProviderRecoveryProvider } from "./donorContracts.js";
+import type { TpayHttpClient } from "./tpayHttpClient.js";
+export declare function createTpayPaymentReconciliationProvider(client: Pick<TpayHttpClient, "getTransaction">): PaymentProviderRecoveryProvider;
+export declare function normalizeTpayTransaction(transaction: Record<string, unknown>): ProviderReconciliationStatus;