@openlup/platform 0.19.0 → 0.21.0

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;

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