@openlup/platform 0.20.0 → 0.22.0

package/dist/payments/tpay/tpayPaymentReconciliationProvider.js

@@ -0,0 +1,244 @@
+import { refusalCapture, tpayFailureEvidence } from "./tpayFailureEvidence.js";
+import { failureEvidencePayload } from "./paymentFailureEvidence.js";
+import { parseInstant, wallClockToUtc } from "./wallClockTime.js";
+import { declineCodeReading } from "./declineFailureHints.js";
+import { attemptDeclineObservation, lastRefusalRow } from "./tpayDeclineEvidence.js";
+export function createTpayPaymentReconciliationProvider(client) {
+    return {
+        resolvePaymentReference(input) {
+            // Tpay's API address is its transactionId. `title`/TR-* is merchant
+            // display data, not a readback identifier.
+            return input.providerSessionId;
+        },
+        async readRecoveryPayment(input) {
+            const transaction = await client.getTransaction(input.providerPaymentId);
+            const status = normalizeTpayTransaction(transaction);
+            const identityMatches = tpayIdentityMatches(transaction, input.providerPaymentId);
+            const configuredMoneyMatches = tpayConfiguredMoneyMatches(transaction, input.attempt);
+            const manualReviewRequired = tpayMoneyMoved(transaction);
+            let clientAction = null;
+            if (identityMatches && !manualReviewRequired && status.status === "pending") {
+                const url = validatedTpayPaymentUrl(transaction);
+                clientAction = url ? { kind: "redirect", url } : null;
+            }
+            return { status, identityMatches, configuredMoneyMatches, manualReviewRequired, clientAction };
+        },
+        async readPayment(input) {
+            const transaction = await client.getTransaction(input.providerPaymentId);
+            return normalizeTpayTransaction(transaction);
+        },
+    };
+}
+function tpayMoneyMoved(transaction) {
+    const status = readStatus(transaction).trim().toLowerCase();
+    return status === "chargeback" || status === "refunded";
+}
+function tpayIdentityMatches(transaction, providerPaymentId) {
+    const actual = readOptionalString(transaction, "transactionId") ?? readOptionalString(transaction, "id");
+    return actual === providerPaymentId;
+}
+function tpayConfiguredMoneyMatches(transaction, attempt) {
+    return readConfiguredAmountMinor(transaction) === attempt.amountMinor
+        && readCurrency(transaction)?.toUpperCase() === attempt.currency.toUpperCase();
+}
+const TPAY_PAYMENT_HOSTS = new Set(["secure.tpay.com", "secure.sandbox.tpay.com"]);
+function validatedTpayPaymentUrl(transaction) {
+    const raw = transaction.transactionPaymentUrl;
+    if (typeof raw !== "string" || raw.length === 0)
+        return null;
+    try {
+        const parsed = new URL(raw);
+        return parsed.protocol === "https:"
+            && parsed.port === ""
+            && parsed.username === ""
+            && parsed.password === ""
+            && TPAY_PAYMENT_HOSTS.has(parsed.hostname.toLowerCase())
+            ? parsed.toString()
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function normalizeTpayTransaction(transaction) {
+    const providerStatus = readStatus(transaction);
+    const statusFromField = normalizeTpayStatus(providerStatus);
+    // This rail leaves its status field non-terminal when the bank refuses, reporting
+    // the reason beside it in TWO carriers instead — per attempt, and in an errors
+    // array — so reading only the status field left a refused charge polling forever
+    // (what stranded a renewal on 2026-08-12). Attempts win when both carry a code:
+    // being the dated carrier, they are the only one that can say which is current.
+    const payments = record(transaction.payments);
+    const refusal = statusFromField !== "succeeded"
+        ? lastRefusal(payments.attempts, "paymentErrorCode") ?? lastRefusal(payments.errors, "errorCode")
+        : null;
+    const status = refusal ? "failed" : statusFromField;
+    return {
+        status,
+        providerStatus,
+        occurredAt: refusal?.occurredAt ?? readDate(transaction),
+        failureReason: refusal
+            ? `tpay_decline_${refusal.code}`
+            : status === "failed" ? `tpay_${providerStatus}` : null,
+        amountMinor: readAmountMinor(transaction),
+        currency: readCurrency(transaction),
+        rawPayload: sanitizedTpayTransaction(transaction, providerStatus, refusal),
+    };
+}
+/**
+ * The last row carrying a refusal code, dated and read. The scan is shared with
+ * the execution path, which needs the same "which code does this stand on"
+ * answer the instant the provider refuses; only the date and the reading are
+ * added. Undated rows yield no instant, so the caller uses the charge's own date.
+ */
+function lastRefusal(rows, codeKey) {
+    const refusal = lastRefusalRow(rows, codeKey);
+    if (!refusal)
+        return null;
+    return {
+        code: refusal.code,
+        occurredAt: parseAttemptDate(refusal.row.date),
+        reading: declineCodeReading(refusal.code),
+    };
+}
+/**
+ * This rail labels no timestamp with a zone, on either carrier, and both are its
+ * own local wall clock. Reading them as UTC moved every instant this adapter
+ * produced one or two hours into the future: on 2026-08-15 a decline that landed
+ * 14:46Z was recorded as 16:46Z, later than the cron run that wrote it. The zone
+ * belongs to the rail, not to the merchant, so it is named here — beside the
+ * carriers it explains — and passed to the generic conversion.
+ */
+const REPORTING_TIME_ZONE = "Europe/Warsaw";
+/** Attempt timestamps arrive as `DD.MM.YYYY HH:mm`, which `Date.parse` misreads. */
+function parseAttemptDate(value) {
+    if (typeof value !== "string")
+        return null;
+    const match = /^(\d{2})\.(\d{2})\.(\d{4})[ T](\d{2}):(\d{2})/.exec(value.trim());
+    if (!match)
+        return parseDate(value);
+    const [, day, month, year, hour, minute] = match;
+    return wallClockToUtc(`${year}-${month}-${day}T${hour}:${minute}:00`, REPORTING_TIME_ZONE);
+}
+function normalizeTpayStatus(status) {
+    const normalized = status.trim().toLowerCase();
+    if (["correct", "paid", "true", "success", "settled"].includes(normalized))
+        return "succeeded";
+    if ([
+        "failed",
+        "failure",
+        "error",
+        "false",
+        "declined",
+        "rejected",
+        "cancelled",
+        "canceled",
+        "expired",
+    ].includes(normalized)) {
+        return "failed";
+    }
+    if ([
+        "new",
+        "pending",
+        "created",
+        "processing",
+        "in_progress",
+        "authorized",
+        "requires_action",
+        "pending_confirmation",
+    ].includes(normalized)) {
+        return "pending";
+    }
+    return "unknown";
+}
+function readStatus(transaction) {
+    for (const key of ["status", "tr_status", "transactionStatus", "state"]) {
+        const raw = transaction[key];
+        if (typeof raw === "string" && raw.trim())
+            return raw.trim();
+        if (typeof raw === "boolean")
+            return raw ? "true" : "false";
+    }
+    return "unknown";
+}
+function readDate(transaction) {
+    const nestedDate = record(transaction.date);
+    for (const key of ["realization", "creation"]) {
+        const parsed = parseDate(nestedDate[key]);
+        if (parsed)
+            return parsed;
+    }
+    for (const key of ["date", "updatedAt", "updated_at", "createdAt", "created_at"]) {
+        const parsed = parseDate(transaction[key]);
+        if (parsed)
+            return parsed;
+    }
+    return null;
+}
+/** The transaction carrier sends `YYYY-MM-DD HH:mm:ss` — zone-less, so read in the rail's zone. */
+function parseDate(value) {
+    return parseInstant(value, REPORTING_TIME_ZONE);
+}
+function readAmountMinor(transaction) {
+    return readAmountMinorFrom(transaction, ["amountMinor", "paidAmountMinor", "tr_amount_minor", "tr_paid_minor"], ["paidAmount", "amount", "tr_paid", "tr_amount"]);
+}
+function readConfiguredAmountMinor(transaction) {
+    return readAmountMinorFrom(transaction, ["amountMinor", "tr_amount_minor"], ["amount", "tr_amount"]);
+}
+function readAmountMinorFrom(transaction, minorKeys, majorKeys) {
+    for (const key of minorKeys) {
+        const raw = transaction[key];
+        if (typeof raw === "number" && Number.isFinite(raw))
+            return Math.round(raw);
+        if (typeof raw === "string" && /^\d+$/.test(raw.trim()))
+            return Number(raw);
+    }
+    for (const key of majorKeys) {
+        const raw = transaction[key];
+        const value = typeof raw === "number" ? raw : typeof raw === "string" ? Number(raw.replace(",", ".")) : NaN;
+        if (Number.isFinite(value))
+            return Math.round(value * 100);
+    }
+    return null;
+}
+function readCurrency(transaction) {
+    for (const key of ["currency", "tr_currency"]) {
+        const raw = transaction[key];
+        if (typeof raw === "string" && raw.trim().length === 3)
+            return raw.trim().toUpperCase();
+    }
+    return null;
+}
+/**
+ * Classification goes through the shared `classifyDecline` seam, the same one
+ * the synchronous path and the card rail use, so there is exactly one place a
+ * refusal becomes a class. Only neutral evidence crosses: this provider's code
+ * vocabulary is translated here and travels no further. Since PR 2724 the class
+ * reaches the case and becomes the payer's cause sentence; it is no cadence input.
+ */
+function sanitizedTpayTransaction(transaction, providerStatus, refusal = null) {
+    return {
+        // Before this, the only record of why a charge failed was discarded on
+        // every poll.
+        ...(refusal ? refusalCapture(refusal, `tpay_decline_${refusal.code}`) : {}),
+        ...failureEvidencePayload(refusal || ["failed", "failure", "error", "false", "declined", "rejected"].includes(providerStatus.trim().toLowerCase()) ? tpayFailureEvidence({
+            source: "readback", providerPaymentId: readOptionalString(transaction, "transactionId"),
+            refusalVerified: true, flow: null,
+            observation: refusal ? { code: refusal.code, disposition: "present" } : attemptDeclineObservation(transaction), reading: refusal?.reading,
+        }) : null),
+        provider: "tpay",
+        transactionId: readOptionalString(transaction, "transactionId") ?? readOptionalString(transaction, "id"),
+        title: readOptionalString(transaction, "title") ?? readOptionalString(transaction, "tr_id"),
+        status: providerStatus,
+        requestIdPresent: Boolean(readOptionalString(transaction, "requestId")),
+        amountMinorPresent: readAmountMinor(transaction) !== null,
+        currency: readCurrency(transaction),
+    };
+}
+function readOptionalString(value, key) {
+    const raw = value[key];
+    return typeof raw === "string" && raw.trim() ? raw.trim() : null;
+}
+function record(value) {
+    return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}

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

@@ -0,0 +1,120 @@
+export interface TpayPayerInput {
+    email: string;
+    name: string;
+    ip?: string | null;
+    userAgent?: string | null;
+}
+/**
+ * BLIK alias sent on transaction create.
+ *
+ * `UID` is merchant-scoped one-click; `PAYID` is the recurring mandate.
+ * `recommendedAuthLevel` is a SIBLING of `autopayment`, not a field inside it
+ * (Tpay SDK `Model/Objects/Transactions/Alias.php`), and Tpay documents it as
+ * available and required only for autopayment model `O`, where it omits the
+ * per-charge authorization screen.
+ */
+export interface TpayAliasInput {
+    value: string;
+    type: "UID" | "PAYID";
+    label?: string;
+    recommendedAuthLevel?: "NOCONFREQ";
+    /**
+     * Collect immediately instead of giving the payer 72 hours to approve. Required
+     * on every model `O` charge; available for models `A` and `O` only.
+     */
+    noDelay?: boolean;
+    /**
+     * `frequency` is deliberately absent: Tpay requires it for model `A`, treats it
+     * as optional for `M`, and does not accept it for `O`. We only ever register
+     * variable-amount mandates, so no caller needs it.
+     */
+    autopayment?: {
+        model: "A" | "M" | "O";
+    };
+}
+export interface TpayTransactionCreateInput {
+    amount: number;
+    currency: "PLN";
+    description: string;
+    hiddenDescription: string;
+    payer: TpayPayerInput;
+    notificationUrl: string;
+    successUrl: string;
+    errorUrl: string;
+    groupId?: number;
+    channelId?: string;
+    blikPaymentType?: 2;
+    blikToken?: string;
+    /**
+     * Ask BLIK to reject the transaction outright when the payer's bank does not
+     * support recurring payments, instead of taking the money and silently never
+     * showing the mandate invitation. Only meaningful when registering a `PAYID`
+     * alias; never set it for a plain one-off BLIK payment.
+     */
+    refuseNoPayId?: boolean;
+    alias?: TpayAliasInput | null;
+    simulatorContext?: {
+        orderId?: string;
+        paymentIntentId: string;
+        clientId?: string;
+        /** Stable per provider attempt; simulator-only and never sent to Tpay. */
+        providerAttemptKey?: string;
+        /**
+         * In-account terminal path the simulator panel returns to after the buyer
+         * settles (account `returnContext` only). Absent for the public flow, which
+         * keeps the simulator page's own `/checkout/payment` return so the
+         * public path stays byte-identical (and client-side localized).
+         */
+        returnPath?: string;
+    };
+}
+/** One entry of Tpay's `payments.errors[]`. `errorCode` is low-cardinality. */
+export interface TpayPaymentError {
+    errorCode: string;
+    errorMessage: string;
+    fieldName: string | null;
+}
+/**
+ * Create-transaction result.
+ *
+ * ⚠️ Tpay signals a synchronous BLIK rejection ONLY through `payments.errors[]`
+ * and the absence of `payments.payIdEligible`. Verified against production
+ * 2026-07-20: a rejected recurring BLIK still returns HTTP 200 with
+ * `result: "success"`, top-level `status: "pending"` AND `payments.status:
+ * "pending"`. Those three fields therefore prove nothing — never branch on them
+ * to decide success. `payments.method` is equally useless: it reads
+ * `"pay_by_link"` even for a settled BLIK PayID charge.
+ *
+ * This matters because Tpay has no async channel for failures — the transaction
+ * webhook's `tr_status` only ever carries `true` or `chargeback`, so a decline
+ * that is not read out of this response is never reported at all.
+ */
+export interface TpayTransactionCreated {
+    transactionId: string;
+    title: string;
+    status: string;
+    transactionPaymentUrl: string | null;
+    requestId: string | null;
+    /**
+     * Whether BLIK considers the payer's bank capable of registering a PayID
+     * mandate. Present and `true` when eligible; absent entirely when Tpay
+     * rejected the transaction.
+     *
+     * ⚠️ UNDOCUMENTED — observed empirically, absent from Tpay's OpenAPI spec and
+     * from their official SDK. Treat as a hint that may vanish without notice and
+     * always keep `errors` as the fallback signal.
+     */
+    payIdEligible: boolean | null;
+    /** Synchronous provider errors. Empty when the request was accepted. */
+    errors: TpayPaymentError[];
+}
+/**
+ * Builds the `POST /transactions` wire payload.
+ *
+ * Every BLIK-specific field lives under `pay.blikPaymentData`; `aliases` carries
+ * the mandate. `refuseNoPayId` sits beside `aliases` (not inside it), while
+ * `recommendedAuthLevel` and `noDelay` sit inside the alias object as siblings of
+ * `autopayment` — matching Tpay's SDK object model and verified against
+ * production on 2026-07-20.
+ */
+export declare function buildTpayTransactionPayload(input: TpayTransactionCreateInput): Record<string, unknown>;

package/dist/payments/tpay/tpayTransactionPayload.js

@@ -0,0 +1,96 @@
+/**
+ * Per-field maxima Tpay enforces on `payer.*`, read from the provider's own SDK
+ * rather than inferred. In `tpay-com/tpay-openapi-php`,
+ * `src/Model/Objects/Transactions/Payer.php` binds every accepted wire key to a
+ * field model, and each model declares the `$maxLength` the API applies:
+ *
+ *   email      `src/Model/Fields/Person/Email.php`      255
+ *   name       `src/Model/Fields/Payer/Name.php`        255
+ *   ip         `src/Model/Fields/Payer/IP.php`          255
+ *   userAgent  `src/Model/Fields/Payer/UserAgent.php`   255
+ *
+ * ⚠️ The unit is BYTES, not characters: `src/Model/Fields/FieldValidator.php`
+ * measures with PHP `strlen()`, which counts bytes. A 255-CHARACTER name in an
+ * accented or non-Latin script can be far more than 255 bytes in UTF-8 and would
+ * still be refused, so the clamp below counts bytes.
+ *
+ * An over-long field is refused synchronously with HTTP 400 `not_valid`. On BLIK
+ * the code then never reaches the bank and the buyer sees no prompt at all: the
+ * Facebook iOS in-app WebView user agent is 271 characters, which cost four
+ * orders and two cancelled subscriptions from 2026-08-28.
+ */
+const TPAY_PAYER_MAX_BYTES = {
+    email: 255,
+    name: 255,
+    ip: 255,
+    userAgent: 255,
+};
+/**
+ * Fits one payer field inside the provider's documented maximum.
+ *
+ * ⛔ Truncate, never omit, and for every one of the four keys. `Field.php` runs
+ * a `pattern` check only for models that declare one and none of these four
+ * does, so a truncated value stays structurally valid; `getRequiredFields()`
+ * makes `email` and `name` mandatory, so dropping either only buys a different
+ * 400; and `ts:request:no_ip` is a real provider error, so dropping `ip` trades
+ * one refusal for another. Truncation also keeps the prefix that a fraud review
+ * or a support ticket can still read.
+ *
+ * Lives here, in the single function that serialises the wire body, so no payer
+ * producer can bypass it.
+ */
+function payerFieldWithinLimit(key, value) {
+    const maxBytes = TPAY_PAYER_MAX_BYTES[key];
+    const bytes = new TextEncoder().encode(value);
+    if (bytes.length <= maxBytes)
+        return value;
+    let end = maxBytes;
+    // Never cut inside a code point: UTF-8 continuation bytes are 0b10xxxxxx, so
+    // walk back off them rather than emitting a replacement character.
+    while (end > 0 && (bytes[end] & 0xc0) === 0x80)
+        end -= 1;
+    return new TextDecoder().decode(bytes.subarray(0, end));
+}
+/**
+ * Builds the `POST /transactions` wire payload.
+ *
+ * Every BLIK-specific field lives under `pay.blikPaymentData`; `aliases` carries
+ * the mandate. `refuseNoPayId` sits beside `aliases` (not inside it), while
+ * `recommendedAuthLevel` and `noDelay` sit inside the alias object as siblings of
+ * `autopayment` — matching Tpay's SDK object model and verified against
+ * production on 2026-07-20.
+ */
+export function buildTpayTransactionPayload(input) {
+    const pay = {};
+    if (input.groupId)
+        pay.groupId = input.groupId;
+    if (input.channelId)
+        pay.channelId = input.channelId;
+    if (input.blikToken || input.alias) {
+        pay.blikPaymentData = {
+            ...(input.blikPaymentType ? { type: input.blikPaymentType } : {}),
+            ...(input.blikToken ? { blikToken: input.blikToken } : {}),
+            ...(input.refuseNoPayId ? { refuseNoPayId: true } : {}),
+            ...(input.alias ? { aliases: input.alias } : {}),
+        };
+    }
+    return {
+        amount: input.amount,
+        currency: input.currency,
+        description: input.description,
+        hiddenDescription: input.hiddenDescription,
+        payer: {
+            email: payerFieldWithinLimit("email", input.payer.email),
+            name: payerFieldWithinLimit("name", input.payer.name),
+            ...(input.payer.ip ? { ip: payerFieldWithinLimit("ip", input.payer.ip) } : {}),
+            ...(input.payer.userAgent
+                ? { userAgent: payerFieldWithinLimit("userAgent", input.payer.userAgent) }
+                : {}),
+        },
+        ...(Object.keys(pay).length > 0 ? { pay } : {}),
+        callbacks: {
+            notification: { url: input.notificationUrl },
+            payerUrls: { success: input.successUrl, error: input.errorUrl },
+        },
+    };
+}

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

@@ -0,0 +1,31 @@
+/**
+ * Reading a timestamp from a rail that does not say what clock it is on.
+ *
+ * A value carrying `Z` or `±HH:mm` is already an instant and is honoured as
+ * written. A value without one is a WALL CLOCK — a label on someone's local
+ * time — and turning it into an instant needs the zone that clock runs on.
+ * `Date.parse` resolves such a value against the HOST zone, which is a silent
+ * trap: it reads correct on a laptop set to the rail's own zone and skews by
+ * the offset on the UTC runtime that serves production. Callers therefore pass
+ * the zone explicitly; there is no default, because a wrong default is exactly
+ * the bug this module exists to remove.
+ */
+/**
+ * The UTC instant of a zone-less `YYYY-MM-DDTHH:mm[:ss]` read in `timeZone`.
+ *
+ * Two passes, because the offset is a function of the answer being computed:
+ * the first prices the naive reading, the second re-prices it at the instant
+ * that produced. That is what makes the conversion hold on both sides of a DST
+ * transition rather than only in the half-year it was written in — a single
+ * pass reads the hour after a spring-forward an hour early. A local time the
+ * transition skips or repeats resolves through the offset in force at the first
+ * pass; no wall clock can separate those two readings.
+ */
+export declare function wallClockToUtc(wallClock: string, timeZone: string): string | null;
+/**
+ * An ISO UTC instant for `value`, or `null` when it does not carry one. A
+ * zone-less value is read as a wall clock in `timeZone`; a value stating its
+ * own offset keeps it. Never invents an instant — the absence of a readable
+ * timestamp must stay distinguishable from a timestamp.
+ */
+export declare function parseInstant(value: unknown, timeZone: string): string | null;

package/dist/payments/tpay/wallClockTime.js

@@ -0,0 +1,57 @@
+/**
+ * Reading a timestamp from a rail that does not say what clock it is on.
+ *
+ * A value carrying `Z` or `±HH:mm` is already an instant and is honoured as
+ * written. A value without one is a WALL CLOCK — a label on someone's local
+ * time — and turning it into an instant needs the zone that clock runs on.
+ * `Date.parse` resolves such a value against the HOST zone, which is a silent
+ * trap: it reads correct on a laptop set to the rail's own zone and skews by
+ * the offset on the UTC runtime that serves production. Callers therefore pass
+ * the zone explicitly; there is no default, because a wrong default is exactly
+ * the bug this module exists to remove.
+ */
+/** A date-time with no `Z` and no `±HH:mm`, i.e. a bare wall-clock label. */
+const ZONELESS_DATE_TIME = /^(\d{4}-\d{2}-\d{2})[ T](\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?)$/;
+/** Milliseconds `timeZone` is ahead of UTC at `at` (negative when west of it). */
+function zoneOffsetMs(at, timeZone) {
+    const zone = new Intl.DateTimeFormat("en", { timeZone, timeZoneName: "longOffset" })
+        .formatToParts(at).find((part) => part.type === "timeZoneName")?.value;
+    const match = /^GMT([+-])(\d{1,2}):(\d{2})$/.exec(zone ?? "");
+    if (!match)
+        return 0;
+    const [, sign, hours, minutes] = match;
+    return (sign === "-" ? -1 : 1) * (Number(hours) * 60 + Number(minutes)) * 60_000;
+}
+/**
+ * The UTC instant of a zone-less `YYYY-MM-DDTHH:mm[:ss]` read in `timeZone`.
+ *
+ * Two passes, because the offset is a function of the answer being computed:
+ * the first prices the naive reading, the second re-prices it at the instant
+ * that produced. That is what makes the conversion hold on both sides of a DST
+ * transition rather than only in the half-year it was written in — a single
+ * pass reads the hour after a spring-forward an hour early. A local time the
+ * transition skips or repeats resolves through the offset in force at the first
+ * pass; no wall clock can separate those two readings.
+ */
+export function wallClockToUtc(wallClock, timeZone) {
+    const asIfUtc = Date.parse(`${wallClock}Z`);
+    if (!Number.isFinite(asIfUtc))
+        return null;
+    const firstPass = asIfUtc - zoneOffsetMs(new Date(asIfUtc), timeZone);
+    return new Date(asIfUtc - zoneOffsetMs(new Date(firstPass), timeZone)).toISOString();
+}
+/**
+ * An ISO UTC instant for `value`, or `null` when it does not carry one. A
+ * zone-less value is read as a wall clock in `timeZone`; a value stating its
+ * own offset keeps it. Never invents an instant — the absence of a readable
+ * timestamp must stay distinguishable from a timestamp.
+ */
+export function parseInstant(value, timeZone) {
+    if (typeof value !== "string" || !value.trim())
+        return null;
+    const trimmed = value.trim();
+    const zoneless = ZONELESS_DATE_TIME.exec(trimmed);
+    if (zoneless)
+        return wallClockToUtc(`${zoneless[1]}T${zoneless[2]}`, timeZone);
+    return Number.isFinite(Date.parse(trimmed)) ? new Date(trimmed).toISOString() : null;
+}

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

@@ -0,0 +1,17 @@
+export interface TpayJwsCertificateResolver {
+    (url: string): Promise<string>;
+}
+export interface TpayJwsVerificationInput {
+    rawBody: string;
+    signatureHeader: string | undefined;
+    resolveCertificate: TpayJwsCertificateResolver;
+    rootCertificatePem: string;
+    allowedX5uPrefix?: string;
+    verifyCertificateChain?: (signingCertificatePem: string, rootCertificatePem: string) => boolean;
+    verifyDetachedSignature?: (input: {
+        signingInput: string;
+        signature: Buffer;
+        signingCertificatePem: string;
+    }) => boolean;
+}
+export declare function verifyTpayJwsSignature({ rawBody, signatureHeader, resolveCertificate, rootCertificatePem, allowedX5uPrefix, verifyCertificateChain: verifyChain, verifyDetachedSignature: verifyDetached, }: TpayJwsVerificationInput): Promise<boolean>;

package/dist/payments/tpay/webhookJwsVerifier.js

@@ -0,0 +1,51 @@
+import { verify as verifySignature, X509Certificate } from "node:crypto";
+export async function verifyTpayJwsSignature({ rawBody, signatureHeader, resolveCertificate, rootCertificatePem, allowedX5uPrefix = "https://secure.sandbox.tpay.com/", verifyCertificateChain: verifyChain = verifyCertificateChain, verifyDetachedSignature: verifyDetached = defaultVerifyDetachedSignature, }) {
+    if (!signatureHeader || !rootCertificatePem)
+        return false;
+    const parts = signatureHeader.split(".");
+    if (parts.length < 3 || !parts[0] || !parts[2])
+        return false;
+    const header = parseJwsHeader(parts[0]);
+    if (!header?.x5u || !header.x5u.startsWith(allowedX5uPrefix))
+        return false;
+    const signingCertificatePem = await resolveCertificate(header.x5u);
+    if (!verifyChain(signingCertificatePem, rootCertificatePem))
+        return false;
+    const signedPayload = `${parts[0]}.${base64Url(Buffer.from(rawBody, "utf8"))}`;
+    const signature = base64UrlDecode(parts[2]);
+    return verifyDetached({ signingInput: signedPayload, signature, signingCertificatePem });
+}
+function parseJwsHeader(encoded) {
+    try {
+        const parsed = JSON.parse(base64UrlDecode(encoded).toString("utf8"));
+        if (!parsed || typeof parsed !== "object")
+            return null;
+        const x5u = parsed.x5u;
+        return typeof x5u === "string" ? { x5u } : null;
+    }
+    catch {
+        return null;
+    }
+}
+function verifyCertificateChain(signingCertificatePem, rootCertificatePem) {
+    try {
+        const signing = new X509Certificate(signingCertificatePem);
+        const root = new X509Certificate(rootCertificatePem);
+        return signing.verify(root.publicKey);
+    }
+    catch {
+        return false;
+    }
+}
+function defaultVerifyDetachedSignature(input) {
+    const publicKey = new X509Certificate(input.signingCertificatePem).publicKey;
+    return verifySignature("RSA-SHA256", Buffer.from(input.signingInput), publicKey, input.signature);
+}
+function base64Url(value) {
+    return value.toString("base64").replace(/=/g, "").replace(/\+/g, "-").replace(/\//g, "_");
+}
+function base64UrlDecode(value) {
+    const normalized = value.replace(/-/g, "+").replace(/_/g, "/");
+    const padded = normalized.padEnd(normalized.length + ((4 - normalized.length % 4) % 4), "=");
+    return Buffer.from(padded, "base64");
+}

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

@@ -0,0 +1,54 @@
+import type { PaymentMethodLifecycleEvent, PaymentMethodLifecycleEventKind } from "@openlup/core/payment";
+declare const PROVIDER_KIND = "tpay";
+type TpayCanonicalPaymentEvent = {
+    provider_event_id: string;
+    event_type: "payment.succeeded" | "payment.failed" | "payment.refunded" | "payment.requires_action" | "payment.disputed" | "setup.succeeded" | "setup.failed" | "setup.requires_action";
+    payment_provider_id: string;
+    payment_intent_id?: string | null;
+    amount_minor?: number;
+    raw_payload: Record<string, unknown>;
+};
+export interface NormalizedTpayMethodRef {
+    clientId: string | null;
+    subscriptionId?: string | null;
+    providerMethodRef: string;
+    methodKind: "blik_payid";
+    status: "active" | "inactive";
+    consentSnapshot: Record<string, unknown>;
+}
+export interface NormalizedTpayWebhook {
+    event: TpayCanonicalPaymentEvent;
+    methodRef: NormalizedTpayMethodRef | null;
+    /**
+     * The neutral transition this delivery reports about the stored mandate. The
+     * instant it happened is not known at this layer, so the full neutral event
+     * is assembled by the provider-webhook mapper below.
+     */
+    methodLifecycleKind: PaymentMethodLifecycleEventKind | null;
+    responseBody: "TRUE";
+}
+type NormalizedTpayProviderWebhook = {
+    provider: typeof PROVIDER_KIND;
+    providerEventId: string;
+    eventType: TpayCanonicalPaymentEvent["event_type"];
+    providerPaymentId: string;
+    paymentIntentId?: string | null;
+    amountMinor: number | null;
+    currency: string | null;
+    occurredAt: string;
+    rawPayload: Record<string, unknown>;
+    reusableMethod: {
+        clientId: string;
+        subscriptionId: string | null;
+        providerCustomerRef: null;
+        providerMethodRef: string;
+        providerMandateRef: null;
+        methodKind: "blik_payid";
+        status: "active" | "inactive";
+        consentSnapshot: Record<string, unknown>;
+    } | null;
+    methodLifecycle: PaymentMethodLifecycleEvent | null;
+};
+export declare function normalizeTpayWebhook(rawBody: string): NormalizedTpayWebhook;
+export declare function toNormalizedProviderTpayWebhook(webhook: NormalizedTpayWebhook, occurredAt: string): NormalizedTpayProviderWebhook;
+export {};