@openlup/platform 0.20.0 → 0.21.0

package/dist/payments/tpay/webhookNormalizer.js

@@ -0,0 +1,200 @@
+const PROVIDER_KIND = "tpay";
+/**
+ * Alias-rail event names, mapped to the neutral lifecycle vocabulary.
+ *
+ * ⛔ `ALIAS_UPDATE` is a ROTATION, not a death: the payer's standing consent is
+ * unchanged and only the alias behind it moves. Classifying it with the two
+ * terminal names would strip a healthy subscription of the mandate it renews
+ * on. That is why the `active` flag below already treats register and update
+ * alike, and why this table must keep them apart from unregister and expiry.
+ */
+const ALIAS_LIFECYCLE_KINDS = {
+    ALIAS_REGISTER: "method_registered",
+    ALIAS_UPDATE: "method_updated",
+    ALIAS_UNREGISTER: "method_revoked",
+    ALIAS_EXPIRED: "method_expired",
+};
+export function normalizeTpayWebhook(rawBody) {
+    const payload = parsePayload(rawBody);
+    const aliasEvent = payload.event;
+    if (aliasEvent) {
+        return normalizeAliasWebhook(payload);
+    }
+    return normalizeTransactionWebhook(payload);
+}
+export function toNormalizedProviderTpayWebhook(webhook, occurredAt) {
+    return {
+        provider: PROVIDER_KIND,
+        providerEventId: webhook.event.provider_event_id,
+        eventType: webhook.event.event_type,
+        providerPaymentId: webhook.event.payment_provider_id,
+        paymentIntentId: webhook.event.payment_intent_id ?? null,
+        amountMinor: webhook.event.amount_minor ?? null,
+        currency: readCurrency(webhook.event.raw_payload),
+        occurredAt,
+        rawPayload: webhook.event.raw_payload,
+        reusableMethod: toReusableMethod(webhook.methodRef),
+        // The alias value IS the stored method reference on this rail. The rail
+        // publishes no scheme label or digits with an alias transition, and its
+        // expiry field is deliberately not read here (see the wave plan): a
+        // transition on this rail is a state change, not a facts refresh.
+        methodLifecycle: webhook.methodLifecycleKind
+            ? {
+                kind: webhook.methodLifecycleKind,
+                providerKind: PROVIDER_KIND,
+                providerMethodRef: webhook.event.payment_provider_id,
+                providerEventId: webhook.event.provider_event_id,
+                occurredAt,
+                replacement: null,
+            }
+            : null,
+    };
+}
+function normalizeTransactionWebhook(payload) {
+    const transactionTitle = required(payload, "tr_id");
+    const rawStatus = required(payload, "tr_status");
+    // Tpay production sends `tr_status` UPPERCASE ("TRUE"/"CHARGEBACK"); a
+    // case-sensitive compare mislabels every real success as payment.failed
+    // (caught live 2026-07-13 via a production payment-link). Classify
+    // case-insensitively; keep the raw value in raw_payload for observability.
+    const status = rawStatus.toLowerCase();
+    const amountMinor = amountToMinor(payload.tr_paid || payload.tr_amount);
+    const paymentIntentId = parseUuid(payload.tr_crc);
+    return {
+        event: {
+            // Only chargebacks split identity; every other status keeps its legacy keys.
+            provider_event_id: status === "chargeback" ? `${transactionTitle}:chargeback` : transactionTitle,
+            event_type: status === "chargeback" ? "payment.refunded" : status === "true" ? "payment.succeeded" : "payment.failed",
+            payment_provider_id: transactionTitle,
+            payment_intent_id: paymentIntentId,
+            amount_minor: amountMinor,
+            raw_payload: {
+                provider: PROVIDER_KIND,
+                eventKind: "transaction",
+                transactionTitle,
+                hiddenDescription: payload.tr_crc ?? null,
+                transactionAmount: payload.tr_amount ?? null,
+                paidAmount: payload.tr_paid ?? null,
+                // Null, not the settlement default: this records what the provider SAID,
+                // and a currency it did not send is unknown. The whole path was already
+                // built for that - `NormalizedTpayProviderWebhook.currency` is typed
+                // `string | null` and `readCurrency` below returns null for an absent or
+                // blank field - so the old `?? "PLN"` was manufacturing an operand rather
+                // than filling a gap.
+                //
+                // It does not weaken the SQL cross-check either. `commerce_payment_control_
+                // apply_result` guards `v_event.currency IS NOT NULL AND v_event.currency <>
+                // v_intent.currency`; a fabricated code cannot detect a real mismatch, it can
+                // only compare equal by luck in a PLN deployment or raise a *false*
+                // `payment_control_result_currency_mismatch` in one that settles elsewhere and
+                // refuse a legitimate payment. Skipping a comparison nobody can make beats
+                // making one against an invented value.
+                currency: payload.tr_currency ?? null,
+                status: rawStatus,
+                testMode: payload.test_mode ?? null,
+            },
+        },
+        methodRef: null,
+        methodLifecycleKind: null,
+        responseBody: "TRUE",
+    };
+}
+function normalizeAliasWebhook(payload) {
+    const aliasValue = required(payload, "msg_value[value]");
+    // Tpay sends alias event names UPPERCASE; normalize defensively so the
+    // classification can never be defeated by casing (see tr_status above).
+    const event = required(payload, "event").toUpperCase();
+    const active = event === "ALIAS_REGISTER" || event === "ALIAS_UPDATE";
+    const paymentIntentId = paymentIntentIdFromAlias(aliasValue);
+    return {
+        event: {
+            provider_event_id: `${event}:${aliasValue}`,
+            event_type: active ? "setup.succeeded" : "setup.failed",
+            payment_provider_id: aliasValue,
+            payment_intent_id: paymentIntentId,
+            raw_payload: {
+                provider: PROVIDER_KIND,
+                eventKind: "blik_alias",
+                event,
+                paymentIntentId,
+                aliasValuePresent: true,
+                aliasType: payload["msg_value[type]"] ?? null,
+                aliasExpirationDatePresent: Boolean(payload["msg_value[expirationDate]"]),
+            },
+        },
+        methodRef: {
+            clientId: payload.client_id ?? null,
+            subscriptionId: payload.subscription_id ?? null,
+            providerMethodRef: aliasValue,
+            methodKind: "blik_payid",
+            status: active ? "active" : "inactive",
+            consentSnapshot: { source: "tpay.alias.webhook", event },
+        },
+        methodLifecycleKind: ALIAS_LIFECYCLE_KINDS[event] ?? null,
+        responseBody: "TRUE",
+    };
+}
+function toReusableMethod(methodRef) {
+    if (!methodRef?.clientId)
+        return null;
+    return {
+        clientId: methodRef.clientId,
+        subscriptionId: methodRef.subscriptionId ?? null,
+        providerCustomerRef: null,
+        providerMethodRef: methodRef.providerMethodRef,
+        providerMandateRef: null,
+        methodKind: methodRef.methodKind,
+        status: methodRef.status,
+        consentSnapshot: methodRef.consentSnapshot,
+    };
+}
+function readCurrency(payload) {
+    const currency = payload.currency;
+    return typeof currency === "string" && currency.trim() ? currency : null;
+}
+function parsePayload(rawBody) {
+    const trimmed = rawBody.trim();
+    if (trimmed.startsWith("{")) {
+        const parsed = JSON.parse(trimmed);
+        return flattenJson(parsed);
+    }
+    const params = new URLSearchParams(rawBody);
+    return Object.fromEntries(Array.from(params.entries()));
+}
+function flattenJson(value, prefix = "") {
+    const out = {};
+    for (const [key, raw] of Object.entries(value)) {
+        const name = prefix ? `${prefix}[${key}]` : key;
+        if (raw && typeof raw === "object" && !Array.isArray(raw)) {
+            Object.assign(out, flattenJson(raw, name));
+        }
+        else if (raw !== undefined && raw !== null) {
+            out[name] = String(raw);
+        }
+    }
+    return out;
+}
+function required(payload, key) {
+    const value = payload[key];
+    if (!value)
+        throw new Error(`tpay_webhook_missing_${key}`);
+    return value;
+}
+function amountToMinor(value) {
+    if (!value)
+        return undefined;
+    const numeric = Number(value.replace(",", "."));
+    return Number.isFinite(numeric) ? Math.round(numeric * 100) : undefined;
+}
+function paymentIntentIdFromAlias(value) {
+    const match = /^openlup_([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12})$/i.exec(value);
+    return match ? match[1].toLowerCase() : null;
+}
+function parseUuid(value) {
+    if (!value)
+        return null;
+    const trimmed = value.trim();
+    return /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(trimmed)
+        ? trimmed.toLowerCase()
+        : null;
+}

package/dist/payments/verifiedEvidenceProjection.d.ts

@@ -0,0 +1,12 @@
+import type { PaymentVerifyNormalizePort, RefundEvidencePolicy, VerifiedMethodEvidence, VerifiedPaymentEvidence } from "./contracts/evidence.js";
+import type { ProviderWebhookWithMethodLifecycle } from "./paymentMethodLifecycle.js";
+/** New boundary module: verified adapter envelopes into the unchanged donor carrier.
+ * Original bytes go only to verification. Store adapter-redacted audit facts plus
+ * nested normalized evidence; typed facts override overlapping reader keys.
+ * Neither audit shape nor receipt time changes adapter identity/fingerprint.
+ * Incomplete refunds are ingested and acknowledged, but require-evidence prevents apply.
+ */
+export declare function projectVerifiedEvidence(evidence: VerifiedPaymentEvidence | VerifiedMethodEvidence, input: Parameters<PaymentVerifyNormalizePort["verifyAndNormalize"]>[0], policy: RefundEvidencePolicy, methodOwner?: {
+    clientId: string;
+    subscriptionId?: string | null;
+}): ProviderWebhookWithMethodLifecycle;

package/dist/payments/verifiedEvidenceProjection.js

@@ -0,0 +1,166 @@
+/** New boundary module: verified adapter envelopes into the unchanged donor carrier.
+ * Original bytes go only to verification. Store adapter-redacted audit facts plus
+ * nested normalized evidence; typed facts override overlapping reader keys.
+ * Neither audit shape nor receipt time changes adapter identity/fingerprint.
+ * Incomplete refunds are ingested and acknowledged, but require-evidence prevents apply.
+ */
+export function projectVerifiedEvidence(evidence, input, policy, methodOwner) {
+    const payload = auditPayload(evidence);
+    const base = {
+        provider: evidence.provider, providerEventId: evidence.providerEventId,
+        occurredAt: input.receivedAt, rawPayload: payload,
+        paymentIntentId: evidence.intentRef,
+    };
+    switch (evidence.kind) {
+        case "money": {
+            // The donor treats absent money as unasserted and skips parity checks.
+            // Settling adapter evidence must instead use its existing mismatch refusal.
+            if ((evidence.outcome === "succeeded" || evidence.outcome === "refunded" || evidence.outcome === "disputed")
+                && (evidence.money === null || !Number.isSafeInteger(evidence.money.amountMinor)
+                    || evidence.money.amountMinor <= 0 || !evidence.money.currency.trim())) {
+                throw new Error("payment_control_result_amount_mismatch");
+            }
+            const reversal = evidence.refund;
+            const refundKind = evidence.outcome === "refunded"
+                ? (reversal ? projectRefund(reversal, evidence) : null) ?? (policy === "legacy-assume-full" ? "full" : null)
+                : undefined;
+            return {
+                ...base, eventType: moneyEvent(evidence.outcome, refundKind ? reversal : undefined),
+                providerPaymentId: evidence.providerPaymentRef, paymentAttemptId: evidence.attemptRef,
+                amountMinor: evidence.money?.amountMinor ?? null, currency: evidence.money?.currency ?? null,
+                refundKind,
+            };
+        }
+        case "method":
+            return {
+                ...base, eventType: methodEvent(evidence.outcome),
+                // Pinned donor normalizer :59 calls resolveLinkagePaymentId :146–154:
+                // setup/method objects use their own object id as the carrier reference.
+                providerPaymentId: evidence.setupRef ?? evidence.methodRef,
+                methodLifecycle: lifecycle(evidence.methodLifecycle),
+                ...(evidence.reusableMethod && methodOwner ? { reusableMethod: {
+                        clientId: methodOwner.clientId, subscriptionId: methodOwner.subscriptionId,
+                        providerCustomerRef: evidence.reusableMethod.providerCustomerRef,
+                        providerMethodRef: evidence.reusableMethod.providerMethodRef,
+                        providerMandateRef: evidence.reusableMethod.providerMandateRef,
+                        methodKind: evidence.reusableMethod.methodKind, status: evidence.reusableMethod.status,
+                    } } : {}),
+            };
+    }
+    return assertNever(evidence);
+}
+function moneyEvent(outcome, refund) {
+    switch (outcome) {
+        case "succeeded": return "payment.succeeded";
+        case "failed": return "payment.failed";
+        case "pending": return "payment.requires_action";
+        case "refunded": return refund?.kind === "full-reversal" && refund.reason === "chargeback" ? "payment.disputed" : "payment.refunded";
+        case "disputed": return "payment.disputed";
+    }
+    return assertNever(outcome);
+}
+function methodEvent(outcome) {
+    switch (outcome) {
+        case "registered":
+        case "updated": return "setup.succeeded";
+        case "revoked":
+        case "expired":
+        case "suspended":
+        case "failed": return "setup.failed";
+        case "requires-action": return "setup.requires_action";
+    }
+    return assertNever(outcome);
+}
+function projectRefund(refund, evidence) {
+    const original = refund.originalPaymentMoney;
+    if (!refund.operationId?.trim() || !evidence.providerPaymentRef.trim()
+        || !Number.isSafeInteger(original?.amountMinor) || original.amountMinor <= 0
+        || !original.currency?.trim() || !evidence.money
+        || evidence.money.amountMinor !== original.amountMinor || evidence.money.currency !== original.currency) {
+        return null;
+    }
+    switch (refund.kind) {
+        case "full-reversal": return "full";
+        case "cumulative-snapshot":
+        case "event-delta": {
+            const money = refund.refundedMoney;
+            if (!Number.isSafeInteger(money?.amountMinor) || money.amountMinor <= 0
+                || money.amountMinor > original.amountMinor || money.currency !== original.currency) {
+                return null;
+            }
+            return money.amountMinor < original.amountMinor ? "partial" : "full";
+        }
+    }
+    return assertNever(refund);
+}
+function assertNever(value) {
+    throw new Error(`payment_evidence_unmapped:${String(value)}`);
+}
+function auditPayload(evidence) {
+    // Explicit typed fields only: unknown envelope properties never enter storage.
+    const normalized = {
+        provider: evidence.provider, providerEventId: evidence.providerEventId,
+        fingerprint: evidence.fingerprint,
+        providerOccurredAt: evidence.providerOccurredAt, kind: evidence.kind,
+        intentRef: evidence.intentRef, outcome: evidence.outcome,
+        ...(evidence.kind === "money" ? {
+            providerPaymentRef: evidence.providerPaymentRef, attemptRef: evidence.attemptRef,
+            money: evidence.money && money(evidence.money),
+            refusal: evidence.refusal && { code: evidence.refusal.code,
+                hints: [...evidence.refusal.hints], adviceCode: evidence.refusal.adviceCode },
+            refund: evidence.refund && refund(evidence.refund),
+        } : {
+            methodRef: evidence.methodRef, setupRef: evidence.setupRef,
+            methodLifecycle: lifecycle(evidence.methodLifecycle),
+            reusableMethod: evidence.reusableMethod && {
+                providerCustomerRef: evidence.reusableMethod.providerCustomerRef,
+                providerMethodRef: evidence.reusableMethod.providerMethodRef,
+                providerMandateRef: evidence.reusableMethod.providerMandateRef,
+                methodKind: evidence.reusableMethod.methodKind, status: evidence.reusableMethod.status,
+            },
+        }),
+    };
+    const payload = { ...evidence.providerAuditPayload };
+    if (evidence.kind === "money") {
+        // Host readers use the provider object reference and original payment money.
+        payload.providerPaymentId = evidence.providerPaymentRef;
+        payload.amountMinor = evidence.money?.amountMinor ?? null;
+        payload.currency = evidence.money?.currency ?? null;
+        // Snapshot reader namespaces are adapter-owned. Their charge identity has no
+        // typed home; their cumulative amount must come from the typed observation.
+        for (const [key, value] of Object.entries(payload)) {
+            if (value && typeof value === "object" && !Array.isArray(value) && "chargeId" in value) {
+                payload[key] = { ...value, amountRefundedMinor: evidence.refund?.kind === "cumulative-snapshot"
+                        ? evidence.refund.refundedMoney?.amountMinor ?? null : null };
+            }
+        }
+        const failure = payload.failureEvidence;
+        if (failure && typeof failure === "object" && !Array.isArray(failure)) {
+            payload.failureEvidence = { ...failure, providerPaymentId: evidence.providerPaymentRef,
+                code: evidence.refusal?.code ?? null, adviceCode: evidence.refusal?.adviceCode ?? null };
+        }
+    }
+    payload.openlupEvidence = normalized;
+    return payload;
+}
+function money(value) {
+    return { amountMinor: value.amountMinor, currency: value.currency };
+}
+function refund(value) {
+    const base = { operationId: value.operationId, originalPaymentMoney: value.originalPaymentMoney && money(value.originalPaymentMoney) };
+    switch (value.kind) {
+        case "full-reversal": return { ...base, kind: value.kind, reason: value.reason };
+        case "cumulative-snapshot":
+        case "event-delta":
+            return { ...base, kind: value.kind, refundedMoney: value.refundedMoney && money(value.refundedMoney) };
+    }
+    return assertNever(value);
+}
+function lifecycle(value) {
+    return value && { kind: value.kind, providerKind: value.providerKind,
+        providerMethodRef: value.providerMethodRef, providerEventId: value.providerEventId,
+        occurredAt: value.occurredAt, replacement: value.replacement && {
+            schemeLabel: value.replacement.schemeLabel, lastDigits: value.replacement.lastDigits,
+            expiresAt: value.replacement.expiresAt,
+        } };
+}

package/dist/payments/verifiedIngress.d.ts

@@ -0,0 +1,119 @@
+import type { PaymentIngressPort, PaymentVerifyNormalizePort, RefundEvidencePolicy, VerifiedMethodEvidence } from "./contracts/evidence.js";
+declare const PAYMENT_WEBHOOK_EVENT_TYPES: readonly ["payment.succeeded", "payment.failed", "payment.refunded", "payment.requires_action", "payment.disputed", "setup.succeeded", "setup.failed", "setup.requires_action"];
+type PaymentWebhookEventType = (typeof PAYMENT_WEBHOOK_EVENT_TYPES)[number];
+export type ProviderPaymentWebhookKind = PaymentWebhookEventType;
+export interface NormalizedProviderPaymentWebhook {
+    provider: string;
+    providerEventId: string;
+    eventType: ProviderPaymentWebhookKind;
+    providerPaymentId: string;
+    paymentIntentId?: string | null;
+    paymentAttemptId?: string | null;
+    amountMinor?: number | null;
+    currency?: string | null;
+    occurredAt: string;
+    refundKind?: "full" | "partial" | null;
+    rawPayload: Record<string, unknown>;
+    reusableMethod?: {
+        clientId: string;
+        subscriptionId?: string | null;
+        providerCustomerRef?: string | null;
+        providerMethodRef: string;
+        providerMandateRef?: string | null;
+        methodKind: string;
+        status: "pending_verification" | "active" | "inactive" | "expired" | "revoked";
+        consentSnapshot?: Record<string, unknown>;
+    } | null;
+}
+export interface PaymentWebhookControlPort {
+    ingestPaymentEvent(input: NormalizedProviderPaymentWebhook): Promise<{
+        paymentEventId: string;
+        paymentIntentId: string | null;
+        paymentAttemptId: string | null;
+        replayed: boolean;
+        occurredAt?: string;
+    }>;
+    applyPaymentResult?(input: {
+        idempotencyKey: string;
+        paymentIntentId: string;
+        paymentEventId: string;
+        resultStatus: "succeeded" | "failed" | "refunded" | "partially_refunded" | "disputed";
+        occurredAt: string;
+        failureReason: string | null;
+    }): Promise<{
+        replayed: boolean;
+    }>;
+    confirmSubscriptionActivation?(input: {
+        idempotencyKey: string;
+        paymentIntentId: string;
+        occurredAt: string;
+        methodRef: string | null;
+        methodKind: string | null;
+    }): Promise<{
+        confirmed: boolean;
+        status: string | null;
+    }>;
+    recoverPaidSubscriptionActivationWithCard?(input: {
+        idempotencyKey: string;
+        subscriptionId: string;
+        paymentMethodRef: string;
+        occurredAt: string;
+    }): Promise<{
+        recovered: boolean;
+        replayed: boolean;
+        reason: string | null;
+    }>;
+    /**
+     * Closes the ledger row of a `setup.*` event once the full setup pipeline
+     * resolved. Setup events carry no money result, so applyPaymentResult (the
+     * only other processed_at writer) never runs for them.
+     */
+    markSetupEventProcessed?(input: {
+        paymentEventId: string;
+    }): Promise<{
+        updated: boolean;
+    }>;
+}
+export interface PaymentWebhookMethodRefPort {
+    upsertFromWebhook(input: NormalizedProviderPaymentWebhook): Promise<{
+        replayed: boolean;
+    }>;
+}
+export type PaymentWebhookAfterProcessed = (input: {
+    event: NormalizedProviderPaymentWebhook;
+    ingested: {
+        paymentEventId: string;
+        paymentIntentId: string | null;
+        paymentAttemptId: string | null;
+        replayed: boolean;
+    };
+    resultStatus: "succeeded" | "failed" | "refunded" | "partially_refunded" | "disputed" | null;
+}) => Promise<void>;
+export interface PaymentWebhookProcessingPorts {
+    paymentControlPort: PaymentWebhookControlPort;
+    methodRefPort?: PaymentWebhookMethodRefPort;
+    afterProcessed?: PaymentWebhookAfterProcessed;
+}
+type OperationalEventRecorder = (event: {
+    name: string;
+    domain: string;
+    surface: string;
+    details: Record<string, unknown>;
+}) => void;
+/** Verified ingress boundary; persistence and transport response writing belong to the host. */
+export declare function createVerifiedPaymentIngress({ provider, verifyPort, paymentControlPort, methodRefPort, afterProcessed, createPorts, resolveMethodOwner, refundEvidencePolicy, operationalEvents, }: {
+    provider: string;
+    verifyPort: PaymentVerifyNormalizePort;
+    paymentControlPort: PaymentWebhookControlPort;
+    methodRefPort?: PaymentWebhookMethodRefPort;
+    afterProcessed?: PaymentWebhookAfterProcessed;
+    createPorts?: (event: NormalizedProviderPaymentWebhook) => PaymentWebhookProcessingPorts | Promise<PaymentWebhookProcessingPorts>;
+    /** Host-owned identity; adapter metadata cannot supply client/subscription authority. */
+    resolveMethodOwner?: (evidence: VerifiedMethodEvidence) => Promise<{
+        clientId: string;
+        subscriptionId?: string | null;
+    } | null>;
+    refundEvidencePolicy?: RefundEvidencePolicy;
+    operationalEvents?: OperationalEventRecorder;
+}): PaymentIngressPort;
+export {};