@openlup/platform 0.20.0 → 0.21.0

package/src/payments/tpay/tpayDeclineEvidence.ts

@@ -0,0 +1,233 @@
+import type { PaymentFailureHint } from "@openlup/core/payment";
+
+import type { DeclineCodeReading } from "./declineFailureHints.js";
+import type { TpayHttpClient } from "./tpayHttpClient.js";
+
+/**
+ * What this rail is allowed to conclude from a refusal, and from which evidence.
+ *
+ * Two rails ask the same question — "which refusal code does this transaction
+ * stand on" — the reconciliation poll and the execution path the moment the
+ * provider says no, so the scan lives here once rather than twice against the
+ * same payload shape. The message-shape heuristic lives here too, as the weakest
+ * grade of evidence and the last one consulted.
+ */
+
+/**
+ * Short on purpose. This read only EXPLAINS a refusal the provider has already
+ * decided; the attempt is finalized either way, so every millisecond spent here
+ * is pure added latency inside the money path. Well below the transport client's
+ * own request timeout, so the deadline that fires is this one.
+ */
+export const DECLINE_CODE_READBACK_TIMEOUT_MS = 3_000;
+
+export interface RefusalRow {
+  row: Record<string, unknown>;
+  code: string;
+}
+
+/**
+ * The last row carrying a refusal code. Last rather than first: a payer may retry
+ * inside their banking app, so the most recent row describes the charge's current
+ * standing. Asserted only from an explicit code — never from silence or elapsed
+ * time — so a charge genuinely still running is never turned terminal. The row
+ * travels back with the code because a caller may need its date; a caller that
+ * does not can ignore it.
+ */
+export function lastRefusalRow(rows: unknown, codeKey: string): RefusalRow | null {
+  const entries = Array.isArray(rows) ? rows : [];
+  for (let index = entries.length - 1; index >= 0; index -= 1) {
+    const row = asRecord(entries[index]);
+    const raw = row[codeKey];
+    if (typeof raw === "string" && raw.trim()) return { row, code: raw.trim() };
+  }
+  return null;
+}
+
+/**
+ * The refusal code the provider's own attempt log stands on, or `null`.
+ *
+ * FAIL-OPEN BY CONSTRUCTION. A rejected request, a malformed body, a client that
+ * never settles, an attempt log without codes — every one of them resolves to
+ * `null`, which is the caller's "read nothing" branch. This function cannot
+ * throw and cannot block past its deadline, because the only thing it can add is
+ * a better explanation of a refusal that is already final. Anything stronger
+ * would put a provider read on the critical path of terminalizing an attempt,
+ * and a stalled terminalization is a stalled subscription cycle.
+ */
+export interface AttemptDeclineObservation {
+  /** Diagnostic-only quarantine; code remains the unchanged legacy classifier input. */
+  identityMismatch?: true;
+  code: string | null;
+  disposition: "present" | "absent" | "unreadable" | "read_failed" | "read_timeout";
+}
+
+/** Compatibility accessor: the existing classifier still sees exactly code or null. */
+export async function readAttemptDeclineCode(
+  client: Pick<TpayHttpClient, "getTransaction">,
+  transactionId: string,
+  timeoutMs: number = DECLINE_CODE_READBACK_TIMEOUT_MS,
+): Promise<string | null> {
+  return (await readAttemptDeclineObservation(client, transactionId, timeoutMs)).code;
+}
+
+export function attemptDeclineObservation(transaction: unknown): AttemptDeclineObservation {
+  const record = asRecord(transaction);
+  const payments = asRecord(record.payments);
+  const attempts = payments.attempts;
+  const code = lastRefusalRow(attempts, "paymentErrorCode")?.code ?? null;
+  const malformed = transaction === null || typeof transaction !== "object" || Array.isArray(transaction)
+    || (record.payments !== undefined && (record.payments === null || typeof record.payments !== "object" || Array.isArray(record.payments)))
+    || (attempts !== undefined && !Array.isArray(attempts))
+    || (Array.isArray(attempts) && attempts.some((row) => {
+      const item = asRecord(row);
+      return row === null || typeof row !== "object" || Array.isArray(row)
+        || (item.paymentErrorCode !== undefined && item.paymentErrorCode !== null && typeof item.paymentErrorCode !== "string");
+    }));
+  return { code, disposition: malformed ? "unreadable" : code ? "present" : "absent" };
+}
+
+/** One bounded read; diagnostic failure never changes terminalization or legacy code. */
+export async function readAttemptDeclineObservation(
+  client: Pick<TpayHttpClient, "getTransaction">,
+  transactionId: string,
+  timeoutMs: number = DECLINE_CODE_READBACK_TIMEOUT_MS,
+): Promise<AttemptDeclineObservation> {
+  if (!transactionId) return { code: null, disposition: "absent" };
+  let deadline: ReturnType<typeof setTimeout> | undefined;
+  try {
+    return await Promise.race([
+      Promise.resolve().then(() => client.getTransaction(transactionId)).then(
+        (transaction): AttemptDeclineObservation => {
+          const observation = attemptDeclineObservation(transaction);
+          const actualId = asRecord(transaction).transactionId ?? asRecord(transaction).id;
+          return typeof actualId === "string" && actualId.trim() !== transactionId
+            ? { ...observation, disposition: "unreadable", identityMismatch: true } : observation;
+        },
+        (): AttemptDeclineObservation => ({ code: null, disposition: "read_failed" }),
+      ),
+      new Promise<AttemptDeclineObservation>((resolve) => {
+        deadline = setTimeout(() => resolve({ code: null, disposition: "read_timeout" }), timeoutMs);
+      }),
+    ]);
+  } catch {
+    return { code: null, disposition: "read_failed" };
+  } finally {
+    if (deadline !== undefined) clearTimeout(deadline);
+  }
+}
+
+/** Legacy attribution remains a separate field with unchanged precedence. */
+export function declineEvidenceSource(input: {
+  attemptCode: string | null; decidingAttemptReading: DeclineCodeReading | null;
+  mandateUnsupported: boolean; reading: DeclineCodeReading; errorCode: string;
+}): string {
+  return input.decidingAttemptReading !== null ? `attempt_code:${input.attemptCode}`
+    : input.mandateUnsupported ? "prose_regex"
+    : states(input.reading) ? `error_code:${input.errorCode}`
+    : input.attemptCode !== null ? `attempt_code:${input.attemptCode}` : "none";
+}
+
+/** Whether a reading says anything at all, as opposed to `indeterminate`. */
+export function states(reading: DeclineCodeReading): boolean {
+  return reading.hints !== undefined || reading.adviceCode !== undefined;
+}
+
+/** The one flow in which this provider is asked to REGISTER a reusable mandate. */
+const MANDATE_REGISTRATION_FLOW = "blik_recurring_activation";
+
+/**
+ * Whether an observation of this flow may conclude anything about the payer's
+ * BANK being able to hold a mandate.
+ *
+ * Only a mandate REGISTRATION can answer that question. A refused charge on an
+ * already-registered mandate proves the bank held one, so a capability code
+ * arriving there says something else — which one, nobody here knows.
+ *
+ * `observedFlow` is `null` for an observer that cannot establish the flow at
+ * all, and that is a real answer rather than a missing argument: the
+ * reconciliation poll sees a transaction readback, and the flow is not a column
+ * of the claim it works from. Unknown is fail-closed for a capability claim, so
+ * such an observer abstains. Parameterized rather than hardcoded per rail, so a
+ * rail that later LEARNS its flow starts stating the claim by passing it, with
+ * no second copy of this rule to keep in step.
+ */
+export function mandateCapabilityReadable(observedFlow: string | null): boolean {
+  return observedFlow === MANDATE_REGISTRATION_FLOW;
+}
+
+/**
+ * The hints one observation is allowed to assert from a reading.
+ *
+ * The reading table is a reading of a CODE and knows nothing about the charge
+ * the code arrived on; this is where the observation's own context is applied
+ * to it. Both rails funnel through here, because a refusal that classifies one
+ * way when the execution path sees it and another way when the poll sees it is
+ * a race rather than a verdict — and the retry ladder cannot be allowed to
+ * terminate on a race.
+ *
+ * Narrow on purpose: only the mandate-capability hint depends on context. Every
+ * other hint states something about the charge itself and crosses untouched.
+ *
+ * The reconciliation rail passes `null` here and therefore always abstains from
+ * that one hint: it reads a transaction back, and a readback cannot tell a
+ * refused mandate REGISTRATION from a refused charge on a mandate the bank
+ * already holds. Abstaining is what it costs to have one verdict per refusal;
+ * the claim stays reachable from evidence that is not a guess, which on a
+ * renewal is the preflight reason this deployment writes itself.
+ */
+export function assertableHints(
+  hints: readonly PaymentFailureHint[] | undefined,
+  observedFlow: string | null,
+): readonly PaymentFailureHint[] | undefined {
+  if (mandateCapabilityReadable(observedFlow)) return hints;
+  return hints?.filter((hint) => hint !== "mandateUnsupported");
+}
+
+/**
+ * FALLBACK ONLY, since the 2026-08-26 incident. Whether a decline means "this
+ * bank cannot hold a mandate" — the one cause a retry can never fix, and the
+ * only one worth telling a buyer to use a card.
+ *
+ * The deciding signal is now the refusal code in the transaction's attempt log,
+ * read back by `readAttemptDeclineCode`. This heuristic runs only when that read
+ * yields no code, or a code the reading table cannot read. It exists because the
+ * create response's own `errorCode` is generic (`payment_failed` covers a
+ * mistyped code, an expired code and an incapable bank alike), and
+ * `payIdEligible` is absent on EVERY rejection, not just this one — so absence
+ * alone would brand a fat-fingered code as "your bank does not support
+ * recurring". Reading the message is the last resort it always should have been:
+ * only its shape is consulted, and the text itself is never returned or stored,
+ * because it is free-form and can carry payer-identifying detail.
+ *
+ * Restricted to mandate REGISTRATION: a failed charge on an already-registered
+ * mandate proves the bank can hold one, so bank capability is never the answer
+ * there.
+ *
+ * Anything uncertain falls through to a generic decline, whose copy is never
+ * wrong — only less specific.
+ */
+export function isMandateRefusal(
+  flow: string,
+  payIdEligible: boolean | null,
+  errorMessage: string,
+): boolean {
+  if (!mandateCapabilityReadable(flow)) return false;
+  if (payIdEligible === true) return false;
+  const normalized = errorMessage
+    .normalize("NFKD")
+    .replace(/\p{Diacritic}/gu, "")
+    .toLowerCase();
+  const namesMandate = /alias|payid|powtarzaln|recurring/.test(normalized);
+  const deniesCapability =
+    /nie\s+(?:umozliwia|obsluguje|wspiera|pozwala)|brak\s+(?:mozliwosci|obslugi|wsparcia)|unsupported|not\s+supported|does\s+not\s+support|cannot|can't|unable/.test(
+      normalized,
+    );
+  return namesMandate && deniesCapability;
+}
+
+function asRecord(value: unknown): Record<string, unknown> {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : {};
+}

package/src/payments/tpay/tpayDispatchFailure.ts

@@ -0,0 +1,186 @@
+export type TpayTransactionFailurePhase = "oauth" | "transaction_dispatch" | "response_decode";
+/**
+ * What is known about the PROVIDER's side after a failed create-transaction.
+ *
+ * `not_dispatched` - the transaction POST was never invoked.
+ * `refused` - it was invoked, and the provider's own answer proves it created
+ *   nothing. Strictly weaker evidence than `not_dispatched`, and deliberately a
+ *   separate value: the two are proved by different facts and are accepted by
+ *   different control-plane reopen modes.
+ * `unknown` - anything else. A transaction may exist.
+ */
+export type TpayTransactionDispatchState = "not_dispatched" | "refused" | "unknown";
+
+export type TpayTransactionFailureCode =
+  | "tpay_oauth_failed"
+  | "tpay_oauth_timeout"
+  | "tpay_oauth_invalid_response"
+  | "tpay_request_encode_failed"
+  | "tpay_request_deadline_exhausted"
+  | "tpay_request_refused"
+  | "tpay_request_timeout"
+  | "tpay_request_failed"
+  | "tpay_invalid_response"
+  | "tpay_transport_failed";
+
+export interface TpayTransactionDispatchFailure {
+  phase: TpayTransactionFailurePhase;
+  code: TpayTransactionFailureCode;
+  dispatchState: TpayTransactionDispatchState;
+  failureDiagnostic?: TpayHttpFailureDiagnostic | null;
+}
+
+export interface TpayTrustedPreDispatchFailure {
+  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";
+}
+
+/**
+ * The provider answered the create-transaction by refusing the request document
+ * itself. One shape only, because only one thing is provable here: no
+ * transaction was created.
+ */
+export interface TpayTrustedRefusalFailure {
+  phase: "response_decode";
+  code: "tpay_request_refused";
+  dispatchState: "refused";
+}
+
+/**
+ * Deliberately excludes the transport exception and provider response. This
+ * crosses the money boundary, so consumers may log only the typed facts.
+ */
+export class TpayTransactionDispatchError extends Error {
+  readonly phase: TpayTransactionFailurePhase;
+  readonly code: TpayTransactionFailureCode;
+  readonly dispatchState: TpayTransactionDispatchState;
+  readonly failureDiagnostic: TpayHttpFailureDiagnostic | null;
+
+  constructor(failure: TpayTransactionDispatchFailure) {
+    super(`tpay_transaction_${failure.dispatchState}:${failure.phase}:${failure.code}`);
+    this.name = "TpayTransactionDispatchError";
+    this.phase = failure.phase;
+    this.code = failure.code;
+    this.dispatchState = failure.dispatchState;
+    this.failureDiagnostic = tpayHttpFailureDiagnostic({ failureDiagnostic: failure.failureDiagnostic });
+  }
+}
+
+export function tpayTransactionFailureCode(
+  error: unknown,
+  fallback: TpayTransactionFailureCode,
+): TpayTransactionFailureCode {
+  const candidate = error && typeof error === "object" && "code" in error
+    ? (error as { code?: unknown }).code
+    : null;
+  return isTpayTransactionFailureCode(candidate) ? candidate : fallback;
+}
+
+/**
+ * Reads back the refusal the dispatch boundary already decided rather than
+ * re-deriving it: by this point the raw body is gone and only the typed verdict
+ * survives, which is exactly what may cross the money boundary.
+ */
+export function tpayTrustedRefusalFailure(error: unknown): TpayTrustedRefusalFailure | null {
+  if (!(error instanceof TpayTransactionDispatchError)) return null;
+  return error.dispatchState === "refused"
+      && error.phase === "response_decode"
+      && error.code === "tpay_request_refused"
+    ? { phase: "response_decode", code: "tpay_request_refused", dispatchState: "refused" }
+    : null;
+}
+
+export function tpayTrustedPreDispatchFailure(error: unknown): TpayTrustedPreDispatchFailure | null {
+  if (!(error instanceof TpayTransactionDispatchError) || error.dispatchState !== "not_dispatched") return null;
+  const validPhase = error.phase === "oauth" || error.phase === "transaction_dispatch";
+  const validCode = error.code === "tpay_oauth_failed" || error.code === "tpay_oauth_timeout" || error.code === "tpay_oauth_invalid_response" ||
+    error.code === "tpay_request_encode_failed" || error.code === "tpay_request_deadline_exhausted";
+  return validPhase && validCode ? { phase: error.phase, code: error.code, dispatchState: error.dispatchState } : null;
+}
+
+export async function tpayTransactionDispatchBoundary<Token, Request, Response, Result>(input: {
+  authenticate: () => Promise<Token>;
+  prepare: (token: Token) => Request;
+  dispatch: (request: Request) => Promise<Response>;
+  decode: (response: Response) => Promise<Result>;
+}): Promise<Result> {
+  let token: Token;
+  try {
+    token = await input.authenticate();
+  } catch (error) {
+    throw new TpayTransactionDispatchError({
+      phase: "oauth",
+      code: tpayOAuthFailureCode(error),
+      dispatchState: "not_dispatched",
+    });
+  }
+
+  let request: Request;
+  try {
+    request = input.prepare(token);
+  } catch (error) {
+    throw new TpayTransactionDispatchError({
+      phase: "transaction_dispatch",
+      code: tpayTransactionFailureCode(error, "tpay_request_encode_failed"),
+      dispatchState: "not_dispatched",
+    });
+  }
+
+  let response: Response;
+  try {
+    response = await input.dispatch(request);
+  } catch (error) {
+    throw new TpayTransactionDispatchError({
+      phase: "transaction_dispatch",
+      code: tpayTransactionFailureCode(error, "tpay_transport_failed"),
+      dispatchState: "unknown",
+    });
+  }
+
+  try {
+    return await input.decode(response);
+  } catch (error) {
+    // A refusal of the request document is the one answer that proves the
+    // provider created nothing. Everything else reaching here - an unparseable
+    // 200, a 5xx, a 409, an opaque 400 - may sit on a real transaction and
+    // stays `unknown`, which keeps the attempt fenced until reconciliation.
+    if (error instanceof TpayHttpError && error.refusedBeforeTransaction) {
+      throw new TpayTransactionDispatchError({
+        phase: "response_decode",
+        code: "tpay_request_refused",
+        dispatchState: "refused",
+        failureDiagnostic: tpayHttpFailureDiagnostic(error),
+      });
+    }
+    throw new TpayTransactionDispatchError({
+      phase: "response_decode",
+      code: tpayTransactionFailureCode(error, "tpay_invalid_response"),
+      dispatchState: "unknown",
+      failureDiagnostic: tpayHttpFailureDiagnostic(error),
+    });
+  }
+}
+
+function isTpayTransactionFailureCode(value: unknown): value is TpayTransactionFailureCode {
+  return value === "tpay_oauth_failed" ||
+    value === "tpay_oauth_timeout" ||
+    value === "tpay_oauth_invalid_response" ||
+    value === "tpay_request_encode_failed" ||
+    value === "tpay_request_deadline_exhausted" ||
+    value === "tpay_request_refused" ||
+    value === "tpay_request_timeout" ||
+    value === "tpay_request_failed" ||
+    value === "tpay_invalid_response" ||
+    value === "tpay_transport_failed";
+}
+
+function tpayOAuthFailureCode(error: unknown): TpayTransactionFailureCode {
+  const code = tpayTransactionFailureCode(error, "tpay_oauth_failed");
+  return code === "tpay_invalid_response" ? "tpay_oauth_invalid_response" : code;
+}
+import {
+  tpayHttpFailureDiagnostic,
+  TpayHttpError,
+  type TpayHttpFailureDiagnostic,
+} from "./tpayHttpFailure.js";

package/src/payments/tpay/tpayFailureEvidence.ts

@@ -0,0 +1,75 @@
+import type { PaymentRecoveryEvidence, PaymentRecoveryMethod, PaymentRecoveryOperation } from "@openlup/core/payment";
+import { serializeFailureEvidence, type FailureObservationSource, type PaymentFailureEvidence } from "./paymentFailureEvidence.js";
+import { assertableHints, type AttemptDeclineObservation } from "./tpayDeclineEvidence.js";
+import type { DeclineCodeReading } from "./declineFailureHints.js";
+import { classifyDecline } from "./classifyDecline.js";
+
+/** Known execution construction, never a conclusion drawn from the PSP name. */
+function methodFor(flow: string | null): PaymentRecoveryMethod | null {
+  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: {
+  source: FailureObservationSource;
+  providerPaymentId: string | null;
+  refusalVerified: boolean;
+  flow: string | null;
+  observation: AttemptDeclineObservation;
+  errorCode?: string | null;
+  reading?: DeclineCodeReading;
+}): PaymentFailureEvidence {
+  const method = methodFor(input.flow);
+  const advice = input.observation.identityMismatch ? null : input.reading?.adviceCode ?? null;
+  const operation: PaymentRecoveryOperation | null = 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: PaymentFailureEvidence): PaymentRecoveryEvidence {
+  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: { code: string; reading: DeclineCodeReading }, failureReasonKey: string): Record<string, unknown> {
+  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,
+  };
+}