@openlup/platform 0.20.0 → 0.22.0

package/src/payments/tpay/tpayHttpClient.ts

@@ -0,0 +1,290 @@
+import {
+  buildTpayTransactionPayload,
+  type TpayPaymentError,
+  type TpayTransactionCreateInput,
+  type TpayTransactionCreated,
+} from "./tpayTransactionPayload.js";
+import { tpayTransactionDispatchBoundary } from "./tpayDispatchFailure.js";
+import { readTpayHttpFailure, TpayHttpError } from "./tpayHttpFailure.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>;
+}
+
+interface OAuthToken {
+  accessToken: string;
+  expiresAtMs: number;
+}
+
+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 as unknown as TpayFetchLike,
+  now = () => Date.now(),
+}: TpayHttpClientOptions): TpayHttpClient {
+  let token: OAuthToken | null = null;
+  const normalizedBaseUrl = baseUrl.replace(/\/+$/, "");
+
+  function requestDeadline(): { expiresAtMs: number } {
+    return { expiresAtMs: Date.now() + timeoutMs };
+  }
+
+  async function bearer(deadline: { expiresAtMs: number }): Promise<string> {
+    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: string,
+    init: { method?: string; body?: unknown } = {},
+    deadline = requestDeadline(),
+  ) {
+    const headers: Record<string, string> = { Authorization: `Bearer ${await bearer(deadline)}` };
+    let body: string | undefined;
+    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: unknown[] = Array.isArray((json as Record<string, unknown>).channels)
+        ? (json as Record<string, unknown>).channels as unknown[]
+        : [];
+      return channels.map(mapChannel);
+    },
+  };
+}
+
+function remainingTimeoutMs(deadline: { expiresAtMs: number }, timeoutCode: string): number {
+  const remaining = deadline.expiresAtMs - Date.now();
+  if (remaining <= 0) throw new TpayHttpError(timeoutCode, 504);
+  return remaining;
+}
+
+async function fetchWithTimeout(
+  fetchImpl: TpayFetchLike,
+  url: string,
+  init: Parameters<TpayFetchLike>[1],
+  timeoutMs: number,
+  timeoutCode: string,
+): ReturnType<TpayFetchLike> {
+  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: unknown): Record<string, unknown> {
+  return value && typeof value === "object" ? value as Record<string, unknown> : {};
+}
+
+function readPaymentErrors(value: unknown): TpayPaymentError[] {
+  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: Awaited<ReturnType<TpayFetchLike>>, code: string): Promise<Record<string, unknown>> {
+  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 as Record<string, unknown>;
+}
+
+function mapChannel(value: unknown): TpayPaymentChannel {
+  const record = value && typeof value === "object" ? value as Record<string, unknown> : {};
+  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: unknown): { id: number; name: string } {
+  const record = value && typeof value === "object" ? value as Record<string, unknown> : {};
+  return { id: Number(record.id ?? 0), name: String(record.name ?? "") };
+}
+
+function readString(value: Record<string, unknown>, key: string): string {
+  const raw = value[key];
+  if (typeof raw !== "string" || raw.length === 0) throw new TpayHttpError("tpay_invalid_response", 200);
+  return raw;
+}
+
+function readNullableString(value: Record<string, unknown>, key: string): string | null {
+  const raw = value[key];
+  return typeof raw === "string" && raw.length > 0 ? raw : null;
+}
+
+function readNumber(value: Record<string, unknown>, key: string): number {
+  const raw = value[key];
+  if (typeof raw !== "number" || !Number.isFinite(raw)) throw new TpayHttpError("tpay_invalid_response", 200);
+  return raw;
+}
+
+function readNullableTransactionAmount(value: Record<string, unknown>, key: string): number | null {
+  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/src/payments/tpay/tpayHttpFailure.ts

@@ -0,0 +1,186 @@
+import {
+  loggableProviderErrorCode,
+  loggableProviderFieldName,
+  loggableProviderRequestId,
+} from "./providerAttemptFailureDiagnostic.js";
+
+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 const TPAY_PRE_TRANSACTION_REFUSAL_CODES: ReadonlySet<string> = 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: {
+  status: number;
+  text(): Promise<string>;
+}): Promise<TpayHttpFailure> {
+  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) as unknown;
+    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: number, rawErrorCodes: unknown[]): boolean {
+  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: TpayHttpFailureDiagnostic): TpayHttpFailure {
+  return { diagnostic, refusedBeforeTransaction: false };
+}
+
+export function tpayHttpFailureDiagnostic(error: unknown): TpayHttpFailureDiagnostic | null {
+  if (!error || typeof error !== "object") return null;
+  const value = asRecord((error as { failureDiagnostic?: unknown }).failureDiagnostic);
+  const httpStatus = value.httpStatus;
+  const requestId = value.requestId;
+  const providerErrorCodes = value.providerErrorCodes;
+  const fieldNames = value.fieldNames;
+  if (!Number.isInteger(httpStatus) || (httpStatus as number) < 100 || (httpStatus as number) > 599) return null;
+  if (requestId !== null && !loggableProviderRequestId(requestId)) return null;
+  if (!validAllowedValues(providerErrorCodes, loggableProviderErrorCode)
+    || !validAllowedValues(fieldNames, loggableProviderFieldName)) return null;
+  return {
+    httpStatus: httpStatus as number,
+    requestId: requestId as string | null,
+    providerErrorCodes: [...providerErrorCodes],
+    fieldNames: [...fieldNames],
+  };
+}
+
+export 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 = null,
+    refusedBeforeTransaction = false,
+  ) {
+    super(code);
+    this.name = "TpayHttpError";
+    this.code = code;
+    this.status = status;
+    this.failureDiagnostic = failureDiagnostic;
+    this.refusedBeforeTransaction = refusedBeforeTransaction;
+  }
+}
+
+function emptyDiagnostic(httpStatus: number): TpayHttpFailureDiagnostic {
+  return { httpStatus, requestId: null, providerErrorCodes: [], fieldNames: [] };
+}
+
+function asRecord(value: unknown): Record<string, unknown> {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : {};
+}
+
+function readArray(value: unknown): unknown[] {
+  return Array.isArray(value) ? value : [];
+}
+
+function allowedValues(values: unknown[], allowed: (value: unknown) => value is string): string[] {
+  return [...new Set(values.filter(allowed))].slice(0, MAX_DIAGNOSTIC_ITEMS);
+}
+
+function validAllowedValues(value: unknown, allowed: (item: unknown) => item is string): value is string[] {
+  return Array.isArray(value) && value.length <= MAX_DIAGNOSTIC_ITEMS
+    && value.every(allowed);
+}