@openlup/platform 0.20.0 → 0.22.0

package/dist/payments/tpay/index.js

@@ -0,0 +1,294 @@
+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 };
+}
+/**
+ * @experimental Reference-application support surface; may change.
+ * Reference consumer: `server/adapters/tpay/tpayAdapterFactory.ts`.
+ */
+export { createTpayPaymentExecutionAdapter } from "./tpayPaymentExecutionAdapter.js";
+/**
+ * @experimental Reference-application support surface; may change.
+ * Reference consumer: `server/runtime/paymentProviderReadbackRegistry.ts`.
+ */
+export { createTpayPaymentReconciliationProvider } from "./tpayPaymentReconciliationProvider.js";
+/**
+ * @experimental Reference-application support surface; may change.
+ * Reference consumer: `server/bff/commerce/tpay-channels.ts`.
+ */
+export { createTpayHttpClient } from "./tpayHttpClient.js";
+/**
+ * @experimental Reference-application support surface; may change.
+ * Reference consumer: `server/adapters/paymentRecoveryGuidance.ts`.
+ */
+export { normalizeTpayFailureEvidence } from "./tpayFailureEvidence.js";
+/**
+ * @experimental Reference-application support surface; may change.
+ * Reference consumer: `server/adapters/supabase/payment/tpaySubscriptionActivation.ts`.
+ */
+export { aliasValue } from "./tpayCreateTransactionInput.js";
+/**
+ * @experimental Reference-application support surface; may change.
+ * Reference consumer: `server/shared/preparedProviderAttempt.ts`.
+ */
+export { ProviderAttemptPreDispatchError } from "./preparedProviderAttempt.js";

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

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

@@ -0,0 +1,25 @@
+import type { PaymentExecutionInput, TpayTransientProviderInput } from "./donorContracts.js";
+import type { TpayPayerInput, TpayTransactionCreateInput } from "./tpayHttpClient.js";
+export declare function buildCreateTransactionInput(input: {
+    input: PaymentExecutionInput;
+    transient: TpayTransientProviderInput;
+    payer: TpayPayerInput;
+    notificationUrl: string;
+    successUrl: string;
+    errorUrl: string;
+    aliasRegistrationOnCodeEnabled: boolean;
+    modelOActivationEnabled: boolean;
+}): TpayTransactionCreateInput;
+/**
+ * The autopayment model actually sent to Tpay.
+ *
+ * Once the Model O activation switch is on, every recurring activation registers
+ * as model O: it is the only model that permits a variable amount without the
+ * payer confirming each charge, which is what a configurable subscription needs.
+ * Model M would silently degrade every renewal into an approval prompt.
+ *
+ * Single source of truth on purpose — the new-activation switch and the alias
+ * payload must never disagree about which model this activation attempt is.
+ */
+export declare function resolveRecurringModel(requested: "O" | "M" | undefined, modelOActivationEnabled: boolean): "O" | "M";
+export declare function aliasValue(paymentIntentId: string): string;

package/dist/payments/tpay/tpayCreateTransactionInput.js

@@ -0,0 +1,128 @@
+const TPAY_BLIK_GROUP_ID = 150;
+/**
+ * In-shell account return path (account terminal, localized client-side). When the
+ * checkout declares `returnContext: "account"`, the Tpay redirect/return targets
+ * this in-account terminal instead of the public `/checkout/payment`
+ * page — the origin is preserved, only the path is swapped. Mirrors how the
+ * public path is selected server-side and re-localized on the client.
+ */
+const ACCOUNT_RETURN_PATH = "/account/order/status";
+/**
+ * Swap the path of an origin-derived return URL to the in-account terminal while
+ * preserving the env/origin-driven host. `returnContext` defaults to public, so a
+ * caller that omits it gets the byte-identical public URL.
+ */
+function returnUrlForContext(baseUrl, returnContext) {
+    if (returnContext !== "account")
+        return baseUrl;
+    const url = new URL(baseUrl);
+    url.pathname = ACCOUNT_RETURN_PATH;
+    return url.toString();
+}
+export function buildCreateTransactionInput(input) {
+    const { transient } = input;
+    const effectiveModel = resolveRecurringModel(transient.recurringModel, input.modelOActivationEnabled);
+    const shouldRegisterOneTimeAlias = transient.flow === "blik_one_time" && input.aliasRegistrationOnCodeEnabled;
+    const returnContext = input.input.returnContext;
+    const successUrl = returnUrlForContext(input.successUrl, returnContext);
+    const errorUrl = returnUrlForContext(input.errorUrl, returnContext);
+    return {
+        amount: input.input.amountMinor / 100,
+        currency: "PLN",
+        description: input.input.orderRef,
+        hiddenDescription: input.input.paymentIntentId,
+        payer: input.payer,
+        notificationUrl: input.notificationUrl,
+        successUrl: payerReturnUrl(successUrl, input.input),
+        errorUrl: payerReturnUrl(errorUrl, input.input),
+        groupId: transient.flow === "pbl_one_time" ? undefined : TPAY_BLIK_GROUP_ID,
+        channelId: transient.flow === "pbl_one_time" ? transient.channelId : undefined,
+        blikPaymentType: transient.flow === "recurring_charge" ||
+            (transient.flow === "blik_one_click" && (input.input.paymentMethodAliasType ?? "PAYID") === "PAYID")
+            ? 2
+            : undefined,
+        blikToken: transient.flow === "blik_one_time" || transient.flow === "blik_recurring_activation"
+            ? transient.blikToken
+            : undefined,
+        // Only meaningful while registering a PAYID mandate: it makes BLIK refuse an
+        // incapable bank outright instead of taking the money and silently never
+        // showing the mandate invitation. Never set for a plain one-off BLIK.
+        refuseNoPayId: transient.flow === "blik_recurring_activation" && effectiveModel === "O"
+            ? true
+            : undefined,
+        alias: transient.flow === "blik_recurring_activation"
+            ? {
+                value: aliasValue(input.input.paymentIntentId),
+                type: "PAYID",
+                label: "openlup",
+                ...(effectiveModel === "O" ? { recommendedAuthLevel: "NOCONFREQ" } : {}),
+                autopayment: { model: effectiveModel },
+            }
+            : shouldRegisterOneTimeAlias
+                ? { value: aliasValue(input.input.paymentIntentId), type: "UID", label: "openlup" }
+                : (transient.flow === "recurring_charge" || transient.flow === "blik_one_click") && input.input.paymentMethodRef
+                    ? chargeAlias(input.input.paymentMethodRef, input.input.paymentMethodAliasType ?? "PAYID", input.input.paymentMethodRecurringModel)
+                    : null,
+        simulatorContext: {
+            orderId: input.input.orderId,
+            paymentIntentId: input.input.paymentIntentId,
+            clientId: input.input.clientId,
+            providerAttemptKey: input.input.providerIdempotencyKey,
+            ...(returnContext === "account" ? { returnPath: ACCOUNT_RETURN_PATH } : {}),
+        },
+    };
+}
+/**
+ * Alias sent when charging an already-registered mandate.
+ *
+ * `noDelay` and `recommendedAuthLevel` are autopayment fields: they belong to a
+ * `PAYID` mandate under model O and are meaningless on a `UID` one-click alias,
+ * which carries no autopayment agreement at all.
+ *
+ * Keyed on the model the MANDATE was registered under, never on the switch that
+ * admits new Model O activations. Production may already hold model M mandates;
+ * charging those as model O would both contradict the payer's consent and risk
+ * rejection. Unknown or absent means not-model-O — fail closed, never guess.
+ */
+function chargeAlias(value, type, registeredModel) {
+    const autopaymentCharge = registeredModel === "O" && type === "PAYID";
+    return {
+        value,
+        type,
+        // Needed on every model O charge, not only at registration: without them
+        // Tpay emails the payer an approval link instead of collecting, which is
+        // model M behaviour. Verified against production 2026-07-20.
+        ...(autopaymentCharge ? { noDelay: true, recommendedAuthLevel: "NOCONFREQ" } : {}),
+    };
+}
+/**
+ * The autopayment model actually sent to Tpay.
+ *
+ * Once the Model O activation switch is on, every recurring activation registers
+ * as model O: it is the only model that permits a variable amount without the
+ * payer confirming each charge, which is what a configurable subscription needs.
+ * Model M would silently degrade every renewal into an approval prompt.
+ *
+ * Single source of truth on purpose — the new-activation switch and the alias
+ * payload must never disagree about which model this activation attempt is.
+ */
+export function resolveRecurringModel(requested, modelOActivationEnabled) {
+    if (modelOActivationEnabled)
+        return "O";
+    return requested ?? "M";
+}
+function payerReturnUrl(baseUrl, input) {
+    const url = new URL(baseUrl);
+    if (input.orderId)
+        url.searchParams.set("orderId", input.orderId);
+    url.searchParams.set("paymentIntentId", input.paymentIntentId);
+    if (input.clientId)
+        url.searchParams.set("clientId", input.clientId);
+    if (input.returnContext === "account" && input.subjectId)
+        url.searchParams.set("subject", input.subjectId);
+    url.searchParams.set("order", input.orderRef);
+    return url.toString();
+}
+export function aliasValue(paymentIntentId) {
+    return `openlup_${paymentIntentId}`;
+}