@fire-spark/payments 0.0.0-stage → 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,397 @@
+import { OrderTotals, PaymentMethod, PaymentProvider } from "@fire-spark/types";
+//#region src/errors.d.ts
+type PaymentErrorReason = "timeout" | "network" | "declined" | "provider" | "ambiguous" | "user";
+type ErrorDefaults = {
+  reason: PaymentErrorReason;
+  retryable: boolean;
+  message: string;
+};
+/** Closed list of Spark payment error codes with their defaults. */
+declare const PAYMENT_ERROR_DEFAULTS: {
+  readonly CARD_DECLINED: ErrorDefaults;
+  readonly INSUFFICIENT_FUNDS: ErrorDefaults;
+  readonly EXPIRED_CARD: ErrorDefaults;
+  readonly INVALID_CARD: ErrorDefaults;
+  readonly INVALID_PIN: ErrorDefaults;
+  readonly LIMIT_EXCEEDED: ErrorDefaults;
+  readonly FRAUD_SUSPECTED: ErrorDefaults;
+  readonly WALLET_REJECTED: ErrorDefaults;
+  readonly WALLET_EXPIRED: ErrorDefaults;
+  readonly INSUFFICIENT_BALANCE: ErrorDefaults;
+  readonly TRANSFER_NOT_FOUND: ErrorDefaults;
+  readonly TRANSFER_ALREADY_USED: ErrorDefaults;
+  readonly TRANSFER_AMOUNT_MISMATCH: ErrorDefaults;
+  readonly FINANCING_REJECTED: ErrorDefaults;
+  readonly FINANCING_EXPIRED: ErrorDefaults;
+  readonly CANCELLED_BY_USER: {
+    readonly reason: "user";
+    readonly retryable: false;
+    readonly message: "Payment cancelled";
+  };
+  readonly USER_TIMEOUT: {
+    readonly reason: "user";
+    readonly retryable: false;
+    readonly message: "No response from the customer";
+  };
+  readonly TERMINAL_UNAVAILABLE: ErrorDefaults;
+  readonly TERMINAL_BUSY: ErrorDefaults;
+  readonly TERMINAL_NOT_CONFIGURED: ErrorDefaults;
+  readonly TERMINAL_NEEDS_INIT: ErrorDefaults;
+  readonly BATCH_CLOSE_REQUIRED: ErrorDefaults;
+  readonly INVALID_CREDENTIALS: ErrorDefaults;
+  readonly INVALID_REQUEST: ErrorDefaults;
+  readonly PROVIDER_UNAVAILABLE: ErrorDefaults;
+  readonly NETWORK_ERROR: {
+    readonly reason: "network";
+    readonly retryable: true;
+    readonly message: "Network error";
+  };
+  readonly TIMEOUT: {
+    readonly reason: "timeout";
+    readonly retryable: true;
+    readonly message: "Payment timed out";
+  };
+  readonly REVERSAL_NOT_ALLOWED: ErrorDefaults;
+  readonly MANUAL_REVERSAL_REQUIRED: ErrorDefaults;
+  readonly AMBIGUOUS: {
+    readonly reason: "ambiguous";
+    readonly retryable: false;
+    readonly message: "Payment result unknown";
+  };
+  readonly UNKNOWN: ErrorDefaults;
+};
+type PaymentErrorCode = keyof typeof PAYMENT_ERROR_DEFAULTS;
+declare const PAYMENT_ERROR_CODES: PaymentErrorCode[];
+type StandardPaymentError = {
+  code: PaymentErrorCode;
+  reason: PaymentErrorReason;
+  retryable: boolean;
+  message: string;
+  provider_code: string | null;
+  provider_message: string | null;
+  attempt: number;
+  elapsed_ms: number;
+};
+type PaymentErrorEntry = {
+  code: PaymentErrorCode;
+  message?: string;
+  retryable?: boolean;
+  reason?: PaymentErrorReason;
+  /** Ficha anchor, e.g. `docs/payments/transbank/pinpad.md#errores`. */
+  source: string;
+  /** Provider version since the code applies. */
+  since?: string;
+};
+/** Keyed by the provider code exactly as returned, as a string. */
+type PaymentErrorDictionary = Readonly<Record<string, PaymentErrorEntry>>;
+declare const definePaymentErrors: <T extends Record<string, PaymentErrorEntry>>(dictionary: T) => PaymentErrorDictionary & T;
+type RawPaymentError = {
+  code?: string | number | null;
+  message?: string | null;
+  /** Spark code to use when the provider code is not in the dictionary. */
+  fallback?: PaymentErrorCode;
+  attempt?: number;
+  elapsed_ms?: number;
+};
+declare const createPaymentError: (code: PaymentErrorCode, extra?: Partial<Omit<StandardPaymentError, "code">>) => StandardPaymentError;
+/** Translates a provider error with its dictionary; unknown codes are `UNKNOWN`. */
+declare const toPaymentError: (dictionary: PaymentErrorDictionary, raw: RawPaymentError) => StandardPaymentError;
+/** Thrown by adapters and by `PaymentUI` (e.g. `CANCELLED_BY_USER`). */
+declare class PaymentError extends Error {
+  readonly error: StandardPaymentError;
+  constructor(error: StandardPaymentError);
+}
+declare const isPaymentError: (value: unknown) => value is PaymentError;
+/** "Tarjeta rechazada (Transbank -1)" style label. */
+declare const formatPaymentError: (error: StandardPaymentError, providerName?: string) => string;
+//#endregion
+//#region src/types.d.ts
+type PaymentCollectAt = "DEVICE" | "KIOSK" | "COUNTER" | "DOOR" | "OTHER";
+type PaymentIntentStatus = "IDLE" | "PENDING" | "PAID" | "FAILED" | "CANCELLED" | "REFUNDED";
+type PaymentEnvironment = "sandbox" | "production";
+/** Amount of one intent, already in the charge currency. */
+type PaymentAmount = {
+  value: number;
+  minor: number;
+  currency: string;
+  decimals: number;
+};
+type TaxBreakdown = {
+  rate: number;
+  base: number;
+  tax: number;
+};
+/** One field the device must fill in `settings_overrides.payment_settings`. */
+type DeviceField = {
+  key: string;
+  label: string;
+  type: "text" | "number" | "password" | "select" | "boolean";
+  required?: boolean;
+  secret?: boolean;
+  options?: string[];
+  visible_if?: Record<string, unknown>;
+};
+type PaymentAction = {
+  type: "qr";
+  payload: string;
+  format: "text" | "image";
+  expiresAt: string | null;
+} | {
+  type: "redirect";
+  url: string;
+  expiresAt: string;
+} | {
+  type: "deeplink";
+  url: string;
+  expiresAt: string;
+} | {
+  type: "instructions";
+  title: string;
+  fields: {
+    label: string;
+    value: string;
+  }[];
+  amount: PaymentAmount;
+} | {
+  type: "terminal";
+  text: string;
+};
+/** Implemented once per template (modal, sheet or dialog). */
+type PaymentUI = {
+  message(input: {
+    text: string;
+    kind: "info" | "waiting" | "error";
+  }): void;
+  select<T>(input: {
+    title: string;
+    options: {
+      label: string;
+      value: T;
+    }[];
+  }): Promise<T>;
+  input(input: {
+    label: string;
+    type: "text" | "number" | "password";
+    mask?: string;
+    maxLength?: number;
+  }): Promise<string>;
+  confirm(input: {
+    text: string;
+  }): Promise<boolean>;
+  action(input: PaymentAction): void;
+};
+/** Persistent key-value store per device. */
+type PaymentStorage = {
+  get(key: string): Promise<string | null>;
+  set(key: string, value: string): Promise<void>;
+  remove(key: string): Promise<void>;
+};
+/** Calls `POST /storefront/payments/:payment_id/operations/:operation`. */
+type PaymentServer = {
+  call<T>(operation: string, input: Record<string, unknown>): Promise<T>;
+};
+type PaymentPolicy = {
+  timeout_ms: number;
+  interaction_timeout_ms: number;
+  max_attempts: number;
+  poll_interval_ms: number;
+  qr_ttl_ms: number;
+  batch_close_at: string | null;
+};
+type PaymentCustomer = {
+  document: string | null;
+  documentType: string | null;
+  phone: string | null;
+};
+type PaymentContext = {
+  paymentId: string;
+  order: {
+    id: string;
+    currency: string;
+    totals: OrderTotals;
+  };
+  customer: PaymentCustomer;
+  amount: PaymentAmount;
+  taxes: TaxBreakdown[];
+  collectAt: PaymentCollectAt;
+  attemptReference: string;
+  attempt: number;
+  environment: PaymentEnvironment;
+  config: Record<string, unknown>;
+  deviceSettings: Record<string, unknown>;
+  policy: PaymentPolicy;
+  ui: PaymentUI;
+  storage: PaymentStorage;
+  server: PaymentServer;
+  signal: AbortSignal;
+};
+type TerminalContext = Omit<PaymentContext, "order" | "amount" | "taxes" | "customer" | "collectAt">;
+type TerminalResult = {
+  ok: boolean;
+  message: string | null;
+  error?: StandardPaymentError;
+  data?: Record<string, unknown>;
+};
+type TerminalOperation = (ctx: TerminalContext) => Promise<TerminalResult>;
+type TerminalOperations = {
+  init?: TerminalOperation;
+  test?: TerminalOperation;
+  closeBatch?: TerminalOperation;
+  status?: TerminalOperation;
+  extra?: {
+    key: string;
+    label: string;
+    run: TerminalOperation;
+  }[];
+};
+type PaymentCardType = "DEBIT" | "CREDIT" | "PREPAID";
+type PaymentEntryMode = "CHIP" | "CONTACTLESS" | "SWIPE" | "MANUAL" | "QR";
+type PaymentMetadataPayment = {
+  provider_transaction_id: string | null;
+  authorization_code: string | null;
+  reference: string | null;
+  card_type: PaymentCardType | null;
+  brand: string | null;
+  last4: string | null;
+  entry_mode: PaymentEntryMode | null;
+  installments: {
+    count: number;
+    type: string | null;
+  } | null;
+  acquirer: string | null;
+  acquirer_tax_id: string | null;
+  terminal_id: string | null;
+  merchant_id: string | null;
+  batch: string | null;
+  ticket_number: string | null;
+  transaction_date: string | null;
+  account_type: string | null;
+  charged_amount: number | null;
+  charged_currency: string | null;
+  exchange_rate: number | null;
+  financed_amount: number | null;
+};
+/** Standard sections of `payment_intent.metadata`. */
+type PaymentMetadata = {
+  attempt_reference: string;
+  payment?: Partial<PaymentMetadataPayment>;
+  receipt?: {
+    customer: string | null;
+    merchant: string | null;
+    format: "text" | "escpos";
+  };
+  action?: PaymentAction;
+  confirm_after_inject?: boolean;
+  needs_review?: boolean;
+  error?: StandardPaymentError;
+  provider?: Record<string, unknown>;
+};
+/** What an adapter returns from every operation. */
+type PaymentResult = {
+  status: PaymentIntentStatus;
+  /** Amount this result covers, in the order currency. */
+  amount: number;
+  metadata: PaymentMetadata;
+  error?: StandardPaymentError;
+};
+type PaymentReversal = "cancel" | "refund" | "manual";
+type PaymentOperation = (ctx: PaymentContext, result: PaymentResult) => Promise<PaymentResult>;
+type PaymentAdapter = {
+  provider: PaymentProvider;
+  method: PaymentMethod;
+  deviceFields?: DeviceField[];
+  start(ctx: PaymentContext): Promise<PaymentResult>;
+  query?: PaymentOperation;
+  confirm?: PaymentOperation;
+  cancel?: PaymentOperation;
+  refund?: PaymentOperation;
+  reversalFor?(result: PaymentResult, now: Date): PaymentReversal;
+  terminal?: TerminalOperations;
+  errors: PaymentErrorDictionary;
+};
+//#endregion
+//#region src/amount.d.ts
+/** ISO 4217 minor units; anything not listed uses 2. */
+declare const CURRENCY_DECIMALS: Readonly<Record<string, number>>;
+declare const currencyDecimals: (currency: string) => number;
+declare const roundTo: (value: number, decimals: number) => number;
+declare const toPaymentAmount: (value: number, currency: string) => PaymentAmount;
+type ChargeConversion = {
+  amount: PaymentAmount;
+  charged_amount: number;
+  charged_currency: string;
+  exchange_rate: number;
+};
+/** Converts an order-currency value to the charge currency at a fixed rate. */
+declare const toChargeAmount: (input: {
+  value: number;
+  orderCurrency: string;
+  chargeCurrency?: string | null;
+  rate?: number | null;
+}) => ChargeConversion;
+/** Tolerance used when comparing amounts in a currency. */
+declare const amountTolerance: (currency: string) => number;
+//#endregion
+//#region src/device.d.ts
+/** Required, visible device fields that are still empty on this device. */
+declare const missingDeviceFields: (fields: DeviceField[] | null | undefined, settings: Record<string, unknown> | null | undefined) => DeviceField[];
+/** Default when the adapter has no `reversalFor`. */
+declare const defaultReversalFor: (result: PaymentResult) => PaymentReversal;
+//#endregion
+//#region src/policy.d.ts
+declare const DEFAULT_PAYMENT_POLICY: PaymentPolicy;
+/**
+ * Library default, then `payment_methods.config` (its `runtime` or root
+ * `qr_ttl_ms`), then `payments.config.runtime`.
+ */
+declare const resolvePaymentPolicy: (input: {
+  methodConfig?: Record<string, unknown> | null;
+  paymentConfig?: Record<string, unknown> | null;
+}) => PaymentPolicy;
+/** Production rows use the provider's production unless the config overrides it. */
+declare const resolveProviderEnvironment: (input: {
+  isProduction: boolean;
+  paymentConfig?: Record<string, unknown> | null;
+}) => PaymentEnvironment;
+/** True the first time the device is free after `batch_close_at` each local day. */
+declare const isBatchCloseDue: (input: {
+  batchCloseAt: string | null;
+  lastClosedDay: string | null;
+  now: Date;
+}) => boolean;
+declare const batchCloseDay: (now: Date) => string;
+//#endregion
+//#region src/reference.d.ts
+/** ULID per attempt; sent to the provider as merchant/idempotency reference. */
+declare const createAttemptReference: (now?: number) => string;
+//#endregion
+//#region src/taxes.d.ts
+type TaxLine = {
+  type?: string;
+  tax_rate: number | null;
+  subtotal: number;
+  discount_total: number;
+  tax_total: number;
+};
+/**
+ * Tax breakdown by rate from the order lines (each line counted once, without
+ * its children). `share` prorates it when the intent covers part of the order.
+ */
+declare const taxBreakdown: (lines: TaxLine[], options?: {
+  share?: number;
+  decimals?: number;
+}) => TaxBreakdown[];
+//#endregion
+//#region src/terminal.d.ts
+/**
+ * Serializes everything that touches one terminal (charge, query, batch close)
+ * by `payment_id`.
+ */
+declare const withTerminalLock: <T>(paymentId: string, task: () => Promise<T>) => Promise<T>;
+declare const isTerminalLocked: (paymentId: string) => boolean;
+/** Keys are prefixed with the `payment_id`. */
+declare const scopedPaymentStorage: (storage: PaymentStorage, paymentId: string) => PaymentStorage;
+/** For tests and web previews; apps provide AsyncStorage or localStorage. */
+declare const memoryPaymentStorage: () => PaymentStorage;
+//#endregion
+export { CURRENCY_DECIMALS, ChargeConversion, DEFAULT_PAYMENT_POLICY, type DeviceField, PAYMENT_ERROR_CODES, PAYMENT_ERROR_DEFAULTS, type PaymentAction, type PaymentAdapter, type PaymentAmount, type PaymentCardType, type PaymentCollectAt, type PaymentContext, type PaymentCustomer, type PaymentEntryMode, type PaymentEnvironment, PaymentError, PaymentErrorCode, PaymentErrorDictionary, PaymentErrorEntry, PaymentErrorReason, type PaymentIntentStatus, type PaymentMetadata, type PaymentMetadataPayment, type PaymentOperation, type PaymentPolicy, type PaymentResult, type PaymentReversal, type PaymentServer, type PaymentStorage, type PaymentUI, RawPaymentError, StandardPaymentError, type TaxBreakdown, TaxLine, type TerminalContext, type TerminalOperation, type TerminalOperations, type TerminalResult, amountTolerance, batchCloseDay, createAttemptReference, createPaymentError, currencyDecimals, defaultReversalFor, definePaymentErrors, formatPaymentError, isBatchCloseDue, isPaymentError, isTerminalLocked, memoryPaymentStorage, missingDeviceFields, resolvePaymentPolicy, resolveProviderEnvironment, roundTo, scopedPaymentStorage, taxBreakdown, toChargeAmount, toPaymentAmount, toPaymentError, withTerminalLock };

package/dist/index.js

@@ -0,0 +1,386 @@
+//#region src/amount.ts
+/** ISO 4217 minor units; anything not listed uses 2. */
+const CURRENCY_DECIMALS = {
+	CLP: 0,
+	PYG: 0,
+	JPY: 0,
+	COP: 2,
+	USD: 2,
+	BRL: 2,
+	PEN: 2,
+	ARS: 2,
+	VES: 2,
+	MXN: 2,
+	EUR: 2
+};
+const currencyDecimals = (currency) => {
+	return CURRENCY_DECIMALS[currency.toUpperCase()] ?? 2;
+};
+const roundTo = (value, decimals) => {
+	const factor = 10 ** decimals;
+	return Math.round((value + Number.EPSILON) * factor) / factor;
+};
+const toPaymentAmount = (value, currency) => {
+	const code = currency.toUpperCase();
+	const decimals = currencyDecimals(code);
+	const rounded = roundTo(value, decimals);
+	return {
+		value: rounded,
+		minor: Math.round(rounded * 10 ** decimals),
+		currency: code,
+		decimals
+	};
+};
+/** Converts an order-currency value to the charge currency at a fixed rate. */
+const toChargeAmount = (input) => {
+	const orderCurrency = input.orderCurrency.toUpperCase();
+	const chargeCurrency = (input.chargeCurrency ?? orderCurrency).toUpperCase();
+	const same = chargeCurrency === orderCurrency;
+	if (!same && !(input.rate && input.rate > 0)) {
+		const message = `Missing exchange rate ${orderCurrency}->${chargeCurrency}`;
+		throw new Error(message);
+	}
+	const rate = same ? 1 : input.rate;
+	const amount = toPaymentAmount(input.value * rate, chargeCurrency);
+	return {
+		amount,
+		charged_amount: amount.value,
+		charged_currency: chargeCurrency,
+		exchange_rate: rate
+	};
+};
+/** Tolerance used when comparing amounts in a currency. */
+const amountTolerance = (currency) => {
+	return 10 ** -currencyDecimals(currency) / 2;
+};
+//#endregion
+//#region src/device.ts
+const isEmpty = (value) => {
+	return value == null || typeof value === "string" && value.trim() === "";
+};
+const isVisible = (field, settings) => {
+	if (!field.visible_if) return true;
+	return Object.entries(field.visible_if).every(([key, expected]) => {
+		return settings[key] === expected;
+	});
+};
+/** Required, visible device fields that are still empty on this device. */
+const missingDeviceFields = (fields, settings) => {
+	const values = settings ?? {};
+	return (fields ?? []).filter((field) => {
+		if (!field.required) return false;
+		if (!isVisible(field, values)) return false;
+		return isEmpty(values[field.key]);
+	});
+};
+/** Default when the adapter has no `reversalFor`. */
+const defaultReversalFor = (result) => {
+	return result.status === "PAID" ? "refund" : "cancel";
+};
+//#endregion
+//#region src/errors.ts
+const declined = (message) => {
+	return {
+		reason: "declined",
+		retryable: false,
+		message
+	};
+};
+const provider = (message, retryable = false) => {
+	return {
+		reason: "provider",
+		retryable,
+		message
+	};
+};
+/** Closed list of Spark payment error codes with their defaults. */
+const PAYMENT_ERROR_DEFAULTS = {
+	CARD_DECLINED: declined("Card declined"),
+	INSUFFICIENT_FUNDS: declined("Insufficient funds"),
+	EXPIRED_CARD: declined("Expired card"),
+	INVALID_CARD: declined("Invalid card"),
+	INVALID_PIN: declined("Invalid PIN"),
+	LIMIT_EXCEEDED: declined("Limit exceeded"),
+	FRAUD_SUSPECTED: declined("Payment rejected for security reasons"),
+	WALLET_REJECTED: declined("Wallet payment rejected"),
+	WALLET_EXPIRED: declined("Payment request expired"),
+	INSUFFICIENT_BALANCE: declined("Insufficient balance"),
+	TRANSFER_NOT_FOUND: declined("Transfer not found"),
+	TRANSFER_ALREADY_USED: declined("Transfer already used"),
+	TRANSFER_AMOUNT_MISMATCH: declined("Transfer amount does not match"),
+	FINANCING_REJECTED: declined("Financing rejected"),
+	FINANCING_EXPIRED: declined("Financing request expired"),
+	CANCELLED_BY_USER: {
+		reason: "user",
+		retryable: false,
+		message: "Payment cancelled"
+	},
+	USER_TIMEOUT: {
+		reason: "user",
+		retryable: false,
+		message: "No response from the customer"
+	},
+	TERMINAL_UNAVAILABLE: provider("Terminal unavailable", true),
+	TERMINAL_BUSY: provider("Terminal busy", true),
+	TERMINAL_NOT_CONFIGURED: provider("Terminal not configured"),
+	TERMINAL_NEEDS_INIT: provider("Terminal needs initialization"),
+	BATCH_CLOSE_REQUIRED: provider("Batch close required"),
+	INVALID_CREDENTIALS: provider("Invalid payment credentials"),
+	INVALID_REQUEST: provider("Invalid payment request"),
+	PROVIDER_UNAVAILABLE: provider("Payment provider unavailable", true),
+	NETWORK_ERROR: {
+		reason: "network",
+		retryable: true,
+		message: "Network error"
+	},
+	TIMEOUT: {
+		reason: "timeout",
+		retryable: true,
+		message: "Payment timed out"
+	},
+	REVERSAL_NOT_ALLOWED: provider("Reversal not allowed"),
+	MANUAL_REVERSAL_REQUIRED: provider("Manual reversal required"),
+	AMBIGUOUS: {
+		reason: "ambiguous",
+		retryable: false,
+		message: "Payment result unknown"
+	},
+	UNKNOWN: provider("Payment failed")
+};
+const PAYMENT_ERROR_CODES = Object.keys(PAYMENT_ERROR_DEFAULTS);
+const definePaymentErrors = (dictionary) => {
+	return Object.freeze({ ...dictionary });
+};
+const createPaymentError = (code, extra = {}) => {
+	const defaults = PAYMENT_ERROR_DEFAULTS[code];
+	const b1 = {
+		code,
+		reason: defaults.reason,
+		retryable: defaults.retryable
+	};
+	const b2 = {
+		message: defaults.message,
+		provider_code: null
+	};
+	const b3 = {
+		provider_message: null,
+		attempt: 1,
+		elapsed_ms: 0
+	};
+	return {
+		...b1,
+		...b2,
+		...b3,
+		...extra
+	};
+};
+/** Translates a provider error with its dictionary; unknown codes are `UNKNOWN`. */
+const toPaymentError = (dictionary, raw) => {
+	const providerCode = raw.code == null ? null : String(raw.code);
+	const entry = providerCode == null ? void 0 : dictionary[providerCode];
+	const code = entry?.code ?? raw.fallback ?? "UNKNOWN";
+	const defaults = PAYMENT_ERROR_DEFAULTS[code];
+	const e1 = { provider_code: providerCode };
+	const e2 = { provider_message: raw.message ?? null };
+	const e3 = {
+		attempt: raw.attempt ?? 1,
+		elapsed_ms: raw.elapsed_ms ?? 0
+	};
+	const e4 = { message: entry?.message ?? defaults.message };
+	const e5 = { retryable: entry?.retryable ?? defaults.retryable };
+	const e6 = { reason: entry?.reason ?? defaults.reason };
+	return createPaymentError(code, {
+		...e1,
+		...e2,
+		...e3,
+		...e4,
+		...e5,
+		...e6
+	});
+};
+/** Thrown by adapters and by `PaymentUI` (e.g. `CANCELLED_BY_USER`). */
+var PaymentError = class extends Error {
+	error;
+	constructor(error) {
+		super(error.message);
+		this.name = "PaymentError";
+		this.error = error;
+	}
+};
+const isPaymentError = (value) => {
+	return value instanceof PaymentError;
+};
+/** "Tarjeta rechazada (Transbank -1)" style label. */
+const formatPaymentError = (error, providerName) => {
+	if (!error.provider_code) return error.message;
+	const prefix = providerName ? `${providerName} ` : "";
+	return `${error.message} (${prefix}${error.provider_code})`;
+};
+//#endregion
+//#region src/policy.ts
+const DEFAULT_PAYMENT_POLICY = {
+	timeout_ms: 3e4,
+	interaction_timeout_ms: 6e4,
+	max_attempts: 2,
+	poll_interval_ms: 3e3,
+	qr_ttl_ms: 3e5,
+	batch_close_at: null
+};
+const pickPolicy = (value) => {
+	if (!value || typeof value !== "object") return {};
+	const source = value;
+	const out = {};
+	for (const key of [
+		"timeout_ms",
+		"interaction_timeout_ms",
+		"max_attempts",
+		"poll_interval_ms",
+		"qr_ttl_ms"
+	]) {
+		const item = source[key];
+		if (typeof item === "number" && Number.isFinite(item) && item > 0) out[key] = item;
+	}
+	const batch = source.batch_close_at;
+	if (typeof batch === "string") out.batch_close_at = batch;
+	return out;
+};
+/**
+* Library default, then `payment_methods.config` (its `runtime` or root
+* `qr_ttl_ms`), then `payments.config.runtime`.
+*/
+const resolvePaymentPolicy = (input) => {
+	const method = input.methodConfig ?? {};
+	const fromMethod = {
+		...pickPolicy(method),
+		...pickPolicy(method.runtime)
+	};
+	const fromPayment = pickPolicy(input.paymentConfig?.runtime);
+	return {
+		...DEFAULT_PAYMENT_POLICY,
+		...fromMethod,
+		...fromPayment
+	};
+};
+/** Production rows use the provider's production unless the config overrides it. */
+const resolveProviderEnvironment = (input) => {
+	const override = input.paymentConfig?.provider_environment;
+	if (override === "sandbox" || override === "production") return override;
+	return input.isProduction ? "production" : "sandbox";
+};
+const minutesOf = (value) => {
+	const match = /^([01]\d|2[0-3]):([0-5]\d)$/.exec(value);
+	if (!match) return null;
+	return Number(match[1]) * 60 + Number(match[2]);
+};
+const localDay = (date) => {
+	return `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, "0")}-${String(date.getDate()).padStart(2, "0")}`;
+};
+/** True the first time the device is free after `batch_close_at` each local day. */
+const isBatchCloseDue = (input) => {
+	if (!input.batchCloseAt) return false;
+	const target = minutesOf(input.batchCloseAt);
+	if (target == null) return false;
+	const now = input.now;
+	if (now.getHours() * 60 + now.getMinutes() < target) return false;
+	return input.lastClosedDay !== localDay(now);
+};
+const batchCloseDay = (now) => localDay(now);
+//#endregion
+//#region src/reference.ts
+const ENCODING = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+const randomBytes = (size) => {
+	const bytes = new Uint8Array(size);
+	const crypto = globalThis.crypto;
+	if (crypto?.getRandomValues) return crypto.getRandomValues(bytes);
+	for (let i = 0; i < size; i += 1) bytes[i] = Math.floor(Math.random() * 256);
+	return bytes;
+};
+const encodeTime = (time) => {
+	let out = "";
+	let rest = time;
+	for (let i = 0; i < 10; i += 1) {
+		out = ENCODING[rest % 32] + out;
+		rest = Math.floor(rest / 32);
+	}
+	return out;
+};
+const encodeRandom = () => {
+	const bytes = randomBytes(16);
+	let out = "";
+	for (const byte of bytes) out += ENCODING[byte % 32];
+	return out;
+};
+/** ULID per attempt; sent to the provider as merchant/idempotency reference. */
+const createAttemptReference = (now = Date.now()) => {
+	return encodeTime(now) + encodeRandom();
+};
+//#endregion
+//#region src/taxes.ts
+/**
+* Tax breakdown by rate from the order lines (each line counted once, without
+* its children). `share` prorates it when the intent covers part of the order.
+*/
+const taxBreakdown = (lines, options = {}) => {
+	const share = options.share ?? 1;
+	const decimals = options.decimals ?? 2;
+	const byRate = /* @__PURE__ */ new Map();
+	for (const line of lines) {
+		const rate = line.tax_rate ?? 0;
+		const current = byRate.get(rate) ?? {
+			base: 0,
+			tax: 0
+		};
+		current.base += line.subtotal - line.discount_total;
+		current.tax += line.tax_total;
+		byRate.set(rate, current);
+	}
+	return [...byRate.entries()].toSorted(([a], [b]) => a - b).map(([rate, sums]) => {
+		return {
+			rate,
+			base: roundTo(sums.base * share, decimals),
+			tax: roundTo(sums.tax * share, decimals)
+		};
+	});
+};
+//#endregion
+//#region src/terminal.ts
+const tails = /* @__PURE__ */ new Map();
+/**
+* Serializes everything that touches one terminal (charge, query, batch close)
+* by `payment_id`.
+*/
+const withTerminalLock = async (paymentId, task) => {
+	const run = (tails.get(paymentId) ?? Promise.resolve()).catch(() => void 0).then(task);
+	const tail = run.catch(() => void 0);
+	tails.set(paymentId, tail);
+	try {
+		return await run;
+	} finally {
+		if (tails.get(paymentId) === tail) tails.delete(paymentId);
+	}
+};
+const isTerminalLocked = (paymentId) => tails.has(paymentId);
+/** Keys are prefixed with the `payment_id`. */
+const scopedPaymentStorage = (storage, paymentId) => {
+	const key = (name) => `${paymentId}:${name}`;
+	return {
+		get: (name) => storage.get(key(name)),
+		set: (name, value) => storage.set(key(name), value),
+		remove: (name) => storage.remove(key(name))
+	};
+};
+/** For tests and web previews; apps provide AsyncStorage or localStorage. */
+const memoryPaymentStorage = () => {
+	const values = /* @__PURE__ */ new Map();
+	return {
+		get: async (key) => values.get(key) ?? null,
+		set: async (key, value) => {
+			values.set(key, value);
+		},
+		remove: async (key) => {
+			values.delete(key);
+		}
+	};
+};
+//#endregion
+export { CURRENCY_DECIMALS, DEFAULT_PAYMENT_POLICY, PAYMENT_ERROR_CODES, PAYMENT_ERROR_DEFAULTS, PaymentError, amountTolerance, batchCloseDay, createAttemptReference, createPaymentError, currencyDecimals, defaultReversalFor, definePaymentErrors, formatPaymentError, isBatchCloseDue, isPaymentError, isTerminalLocked, memoryPaymentStorage, missingDeviceFields, resolvePaymentPolicy, resolveProviderEnvironment, roundTo, scopedPaymentStorage, taxBreakdown, toChargeAmount, toPaymentAmount, toPaymentError, withTerminalLock };

package/package.json

@@ -1,6 +1,57 @@
 {
   "name": "@fire-spark/payments",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Fire Spark payments contract: adapters, errors, amounts and policy",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@fire-spark/types": "0.0.4"
+  },
+  "devDependencies": {
+    "tsdown": "^0.22.14",
+    "typescript": "^7.0.2",
+    "vitest": "^2.1.8"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "tsdown": {
+    "entry": [
+      "src/index.ts"
+    ],
+    "format": [
+      "esm"
+    ],
+    "platform": "neutral",
+    "dts": {
+      "tsconfig": "tsconfig.build.json"
+    },
+    "clean": true,
+    "deps": {
+      "neverBundle": [
+        "@fire-spark/types"
+      ]
+    }
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "check-types": "tsc --noEmit",
+    "test:utils": "vitest run",
+    "lint": "oxlint ./src --max-warnings=0",
+    "format": "oxfmt ./src",
+    "check-format": "oxfmt --check ./src"
+  }
 }

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.