@gbitx/pay-react-native 0.1.0

package/src/config.ts

@@ -0,0 +1,219 @@
+import { GbitXPayError } from './errors';
+import { assertPublishableKey, assertHttpsOrigin } from './validation';
+import { debugLog, setDebug, redactSecrets } from './redact';
+import type { ConfigureOptions, Environment, MerchantInfo } from './types';
+
+// Bootstrap API base — where /v1/sdk/config lives (distinct from the checkout
+// host returned by that endpoint). Overridable via configure({ apiBaseUrl })
+// for staging, but must be https.
+const DEFAULT_API_BASE = 'https://gateway.gbitx.com';
+const DEFAULT_TIMEOUT_MS = 10_000;
+const MIN_TIMEOUT_MS = 1_000;
+const MAX_TIMEOUT_MS = 60_000;
+
+export interface ResolvedConfig {
+  publishableKey: string;
+  environment: Environment;
+  // Frozen https origin of the checkout host (e.g. https://pay.gbitx.com).
+  // The single root of trust for the WebView source, originWhitelist, and
+  // every message-origin check. Server-authoritative, asserted https.
+  checkoutOrigin: string;
+  merchant: MerchantInfo;
+}
+
+type State = 'unconfigured' | 'configuring' | 'configured' | 'configure_failed';
+
+let _state: State = 'unconfigured';
+let _config: ResolvedConfig | null = null;
+let _inflight: Promise<ResolvedConfig> | null = null;
+let _inflightKey: string | null = null;
+
+export function isConfigured(): boolean {
+  return _state === 'configured' && _config !== null;
+}
+
+export function getResolvedConfig(): ResolvedConfig | null {
+  return _config;
+}
+
+// Test-only reset of module state. Not exported from the package index.
+export function __resetConfigForTest(): void {
+  _state = 'unconfigured';
+  _config = null;
+  _inflight = null;
+  _inflightKey = null;
+}
+
+function normalizeTimeout(ms: unknown): number {
+  if (typeof ms !== 'number' || !Number.isFinite(ms)) return DEFAULT_TIMEOUT_MS;
+  return Math.min(MAX_TIMEOUT_MS, Math.max(MIN_TIMEOUT_MS, Math.floor(ms)));
+}
+
+// Only echo a server-provided message after scrubbing it (defense in depth —
+// the publishableKeyAuth messages are static today, but never trust that).
+function safeMessage(msg: unknown, fallback: string): string {
+  return typeof msg === 'string' && msg.trim() ? redactSecrets(msg.trim()) : fallback;
+}
+
+// Map a non-2xx GET /v1/sdk/config response to a typed error, keyed off the
+// real backend shapes (publishableKeyAuth.js). Pure + unit-tested.
+export function mapConfigError(
+  status: number,
+  body: { code?: string; message?: string; onboardingStatus?: string } | null | undefined,
+  retryAfterHeader?: string | null,
+): GbitXPayError {
+  const b = body || {};
+  if (status === 403 && b.code === 'ONBOARDING_REQUIRED') {
+    return new GbitXPayError('onboarding_required', safeMessage(b.message, 'This publishable key is not active yet. Complete onboarding to activate.'), {
+      onboardingStatus: typeof b.onboardingStatus === 'string' ? b.onboardingStatus : undefined,
+    });
+  }
+  if (status === 403) {
+    return new GbitXPayError('merchant_suspended', safeMessage(b.message, 'This merchant account is not active.'));
+  }
+  if (status === 429) {
+    const ra = Number(retryAfterHeader);
+    return new GbitXPayError('rate_limited', safeMessage(b.message, 'Too many requests. Please try again shortly.'), {
+      retryAfterSec: Number.isFinite(ra) && ra > 0 ? ra : undefined,
+    });
+  }
+  if (status >= 500) {
+    return new GbitXPayError('server_error', safeMessage(b.message, 'GbitXPay is temporarily unavailable. Please try again.'));
+  }
+  // 401 and any other 4xx -> the key was rejected.
+  return new GbitXPayError('invalid_key', safeMessage(b.message, 'The publishable key was rejected.'));
+}
+
+// Validate a 2xx body's shape so 'configured' means the REAL backend answered
+// correctly (a captive portal / CDN error page / partial deploy that returns
+// 200 with junk is treated as server_error, not silently accepted). Pure.
+export function parseConfigSuccess(body: unknown): { environment: Environment; checkoutOrigin: string; merchant: MerchantInfo } {
+  const b = body as {
+    success?: unknown;
+    environment?: unknown;
+    checkoutBaseUrl?: unknown;
+    merchant?: { name?: unknown; website?: unknown } | null;
+  } | null;
+
+  if (!b || b.success !== true) {
+    throw new GbitXPayError('server_error', 'Unexpected response while validating the key.');
+  }
+  if (b.environment !== 'live' && b.environment !== 'test') {
+    throw new GbitXPayError('server_error', 'Unexpected config response (environment).');
+  }
+  let checkoutOrigin: string;
+  try {
+    checkoutOrigin = assertHttpsOrigin(b.checkoutBaseUrl, 'checkoutBaseUrl');
+  } catch {
+    throw new GbitXPayError('server_error', 'Insecure or invalid checkout origin from server.');
+  }
+  const m = b.merchant;
+  if (!m || typeof m !== 'object' || Array.isArray(m)) {
+    throw new GbitXPayError('server_error', 'Unexpected config response (merchant).');
+  }
+  const name = typeof m.name === 'string' && m.name.trim() ? m.name.trim() : 'Merchant';
+  const website = typeof m.website === 'string' && m.website.trim() ? m.website.trim() : null;
+  return { environment: b.environment, checkoutOrigin, merchant: { name, website } };
+}
+
+async function fetchConfig(key: string, apiBase: string, timeoutMs: number): Promise<ResolvedConfig> {
+  const url = `${apiBase}/v1/sdk/config`;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+
+  let res: Response;
+  try {
+    res = await fetch(url, {
+      method: 'GET',
+      signal: controller.signal,
+      headers: { Authorization: `Bearer ${key}`, Accept: 'application/json' },
+    });
+  } catch (cause) {
+    throw new GbitXPayError('network_error', 'Could not reach GbitXPay to validate the publishable key.', { cause });
+  } finally {
+    clearTimeout(timer);
+  }
+
+  // Body may be non-JSON (proxy/CDN error page) — parse defensively.
+  const body = await res.json().catch(() => null);
+
+  if (!res.ok) {
+    throw mapConfigError(res.status, body as never, res.headers?.get?.('retry-after'));
+  }
+
+  const parsed = parseConfigSuccess(body);
+  return {
+    publishableKey: key,
+    environment: parsed.environment,
+    checkoutOrigin: parsed.checkoutOrigin,
+    merchant: parsed.merchant,
+  };
+}
+
+// Validate the publishable key against the GbitX backend and prepare the SDK.
+// Must complete successfully before present() can run. Safe to call more than
+// once (an in-flight call for the SAME key is shared; the last successful
+// configure wins).
+export async function configure(options: ConfigureOptions): Promise<void> {
+  if (options && options.debug) setDebug(true);
+
+  const { key, environment: prefixEnv } = assertPublishableKey(options?.publishableKey);
+
+  if (options.environment && options.environment !== prefixEnv) {
+    throw new GbitXPayError('environment_mismatch', 'The environment option does not match the publishable key.');
+  }
+
+  const timeoutMs = normalizeTimeout(options.timeoutMs);
+  const apiBase = options.apiBaseUrl ? assertHttpsOrigin(options.apiBaseUrl, 'apiBaseUrl') : DEFAULT_API_BASE;
+
+  // Share an in-flight configure for the same key.
+  if (_inflight && _inflightKey === key) {
+    await _inflight;
+    return;
+  }
+
+  _state = 'configuring';
+  debugLog('configure: validating key against', `${apiBase}/v1/sdk/config`);
+
+  const run = (async (): Promise<ResolvedConfig> => {
+    const resolved = await fetchConfig(key, apiBase, timeoutMs);
+    // Cross-check the key prefix against the server's environment. A mismatch
+    // is a fatal misconfiguration (mis-issued/tampered key or wrong backend).
+    if (resolved.environment !== prefixEnv) {
+      throw new GbitXPayError('environment_mismatch', 'Key environment and server environment disagree.');
+    }
+    if (options.environment && options.environment !== resolved.environment) {
+      throw new GbitXPayError('environment_mismatch', 'The environment option does not match the server environment.');
+    }
+    return resolved;
+  })();
+
+  _inflight = run;
+  _inflightKey = key;
+
+  try {
+    const resolved = await run;
+    // Only commit if THIS run is still the current in-flight one. A later
+    // configure() (different key) may have superseded us while we awaited; a
+    // stale, superseded run must never overwrite the winning checkoutOrigin
+    // (the root of trust). If superseded, drop our result silently.
+    if (_inflight === run) {
+      _config = resolved;
+      _state = 'configured';
+      debugLog('configure: ok, environment =', resolved.environment);
+    }
+  } catch (err) {
+    // Only flip to failed if this run is still the current one (a newer
+    // configure() may have superseded us).
+    if (_inflight === run) {
+      _state = 'configure_failed';
+      _config = null;
+    }
+    throw err;
+  } finally {
+    if (_inflight === run) {
+      _inflight = null;
+      _inflightKey = null;
+    }
+  }
+}

package/src/controller.ts

@@ -0,0 +1,100 @@
+import { GbitXPayError } from './errors';
+import { assertPaymentArgs, buildCheckoutUrl } from './validation';
+import { getResolvedConfig, isConfigured, type ResolvedConfig } from './config';
+import type { PaymentResult, PresentOptions } from './types';
+
+// One active checkout session, handed to the mounted host (GbitXPayProvider)
+// to render. `settle` is the SINGLE exit: the controller dedupes it and
+// resolves the present() promise, then tells the host to unmount.
+export interface CheckoutSession {
+  paymentId: string;
+  clientToken: string;
+  url: string;
+  config: ResolvedConfig;
+  onLoaded?: () => void;
+  onEvent?: PresentOptions['onEvent'];
+  settle: (result: PaymentResult) => void;
+}
+
+type HostListener = (session: CheckoutSession | null) => void;
+
+let _host: HostListener | null = null;
+let _active: CheckoutSession | null = null;
+
+// The provider registers exactly one host. If a host is already registered
+// (two providers mounted — a merchant mistake), the last one wins and we warn
+// via the returned unregister being scoped to the specific listener.
+export function registerHost(listener: HostListener): () => void {
+  _host = listener;
+  if (_active) listener(_active); // replay a pending session to a late host
+  return () => {
+    if (_host === listener) _host = null;
+  };
+}
+
+export function hasHost(): boolean {
+  return _host !== null;
+}
+
+// Test-only.
+export function __resetControllerForTest(): void {
+  _host = null;
+  _active = null;
+}
+
+// Open the hosted checkout for one payment. Resolves with the terminal
+// PaymentResult (confirmed / cancelled / expired / failed). Rejects ONLY for
+// SDK/credential faults (GbitXPayError). A terminal outcome is never a reject.
+export function present(options: PresentOptions): Promise<PaymentResult> {
+  return new Promise<PaymentResult>((resolve, reject) => {
+    if (!isConfigured()) {
+      reject(new GbitXPayError('not_configured', 'Call and await GbitXPay.configure({ publishableKey }) before present().'));
+      return;
+    }
+    if (!_host) {
+      reject(new GbitXPayError('not_mounted', 'Mount <GbitXPayProvider> once near your app root before calling present().'));
+      return;
+    }
+    if (_active) {
+      reject(new GbitXPayError('invalid_arguments', 'A checkout is already open.'));
+      return;
+    }
+
+    let args: { paymentId: string; clientToken: string };
+    try {
+      args = assertPaymentArgs(options?.paymentId, options?.clientToken);
+    } catch (e) {
+      reject(e);
+      return;
+    }
+
+    const config = getResolvedConfig();
+    if (!config) {
+      // Guarded by isConfigured() above; defensive.
+      reject(new GbitXPayError('not_configured', 'Configuration was lost. Call configure() again.'));
+      return;
+    }
+
+    const url = buildCheckoutUrl(config.checkoutOrigin, args.paymentId, args.clientToken);
+
+    let done = false;
+    const session: CheckoutSession = {
+      paymentId: args.paymentId,
+      clientToken: args.clientToken,
+      url,
+      config,
+      onLoaded: options.onLoaded,
+      onEvent: options.onEvent,
+      settle: (result: PaymentResult) => {
+        if (done) return; // controller-level latch (the modal has its own too)
+        done = true;
+        _active = null;
+        _host?.(null); // ask the host to unmount the modal/WebView
+        resolve(result);
+      },
+    };
+
+    _active = session;
+    _host(session);
+  });
+}

package/src/errors.ts

@@ -0,0 +1,89 @@
+// The ONE public error type. Terminal payment outcomes (cancelled / expired
+// / failed) are NOT errors — they resolve as a PaymentResult. Throw/reject
+// only for SDK or credential faults. `code` is a stable, closed union;
+// changing it is a semver-major event.
+
+export type GbitXPayErrorCode =
+  // present() called before configure() completed successfully.
+  | 'not_configured'
+  // present() called with no <GbitXPayProvider> mounted in the tree.
+  | 'not_mounted'
+  // publishable key wrong/revoked/malformed, or a config 4xx.
+  | 'invalid_key'
+  // a SECRET key (gk_) was handed to the SDK — a serious integration bug.
+  | 'secret_key_used'
+  // key environment and server environment disagree.
+  | 'environment_mismatch'
+  // merchant not yet approved for this (live) key.
+  | 'onboarding_required'
+  // merchant account suspended.
+  | 'merchant_suspended'
+  // config endpoint rate-limited (429).
+  | 'rate_limited'
+  // could not reach GbitX (DNS/TLS/offline/timeout).
+  | 'network_error'
+  // GbitX reachable but returned 5xx or an unusable body.
+  | 'server_error'
+  // bad arguments to configure()/present() (e.g. malformed paymentId).
+  | 'invalid_arguments';
+
+// Publicly readable meta — ONLY safe, serializable fields. The transport
+// `cause` is accepted by the constructor but is never placed on an enumerable
+// property (see below), so it can't be captured by `{...error}`, JSON, or a
+// crash reporter that walks own-enumerable keys.
+export interface GbitXPayErrorMeta {
+  // Present on 'onboarding_required'.
+  onboardingStatus?: string;
+  // Present on 'rate_limited' when the server sent Retry-After.
+  retryAfterSec?: number;
+}
+
+// What the constructor accepts. `cause` may reference a Request/URL holding a
+// token, so it is stored non-enumerably on the standard Error `cause` slot and
+// kept out of `meta`, `message`, and `toJSON()`.
+export type GbitXPayErrorInit = GbitXPayErrorMeta & { cause?: unknown };
+
+export class GbitXPayError extends Error {
+  readonly code: GbitXPayErrorCode;
+  readonly meta?: GbitXPayErrorMeta;
+
+  constructor(code: GbitXPayErrorCode, message: string, init?: GbitXPayErrorInit) {
+    super(message);
+    this.name = 'GbitXPayError';
+    this.code = code;
+
+    // Only safe fields go on the enumerable, serializable `meta`.
+    const meta: GbitXPayErrorMeta = {};
+    if (init?.onboardingStatus) meta.onboardingStatus = init.onboardingStatus;
+    if (typeof init?.retryAfterSec === 'number') meta.retryAfterSec = init.retryAfterSec;
+    this.meta = Object.keys(meta).length ? meta : undefined;
+
+    // The cause (if any) is stored NON-enumerably so spreads / JSON / crash
+    // reporters that walk own-enumerable keys never see it.
+    if (init && 'cause' in init) {
+      Object.defineProperty(this, 'cause', { value: init.cause, enumerable: false, writable: false, configurable: true });
+    }
+
+    // Keep instanceof working across transpile targets / bundlers.
+    Object.setPrototypeOf(this, GbitXPayError.prototype);
+  }
+
+  // Custom serialization so a crash reporter or JSON.stringify() can never
+  // leak `cause` (which might hold the checkout URL with #t=<clientToken>).
+  // Only the safe, non-sensitive fields are emitted.
+  toJSON() {
+    const out: Record<string, unknown> = {
+      name: this.name,
+      code: this.code,
+      message: this.message,
+    };
+    if (this.meta?.onboardingStatus) out.onboardingStatus = this.meta.onboardingStatus;
+    if (typeof this.meta?.retryAfterSec === 'number') out.retryAfterSec = this.meta.retryAfterSec;
+    return out;
+  }
+}
+
+// Narrowing helper for consumers who don't want `instanceof`.
+export function isGbitXPayError(e: unknown): e is GbitXPayError {
+  return e instanceof GbitXPayError || (typeof e === 'object' && e !== null && (e as { name?: string }).name === 'GbitXPayError');
+}

package/src/index.ts

@@ -0,0 +1,33 @@
+// @gbitx/pay-react-native — public entrypoint.
+//
+// Accept crypto payments in your React Native app. Your SERVER creates the
+// payment with your SECRET key and hands the app { paymentId, clientToken };
+// the app opens the hardened hosted checkout in a WebView. Fulfilment is
+// driven by the signed server webhook — SDK callbacks are UX only.
+
+export { GbitXPay } from './GbitXPay';
+export type { GbitXPayApi } from './GbitXPay';
+export { GbitXPayProvider } from './GbitXPayProvider';
+export { useGbitXPay } from './useGbitXPay';
+export type { UseGbitXPay } from './useGbitXPay';
+
+export { GbitXPayError, isGbitXPayError } from './errors';
+export type { GbitXPayErrorCode, GbitXPayErrorMeta } from './errors';
+
+export { setDebug } from './redact';
+
+export { SDK_VERSION } from './version';
+
+export type {
+  Environment,
+  PaymentStatus,
+  SanitizedPayment,
+  PaymentResult,
+  CancelReason,
+  ExpiredReason,
+  ConfigureOptions,
+  PresentOptions,
+  MerchantInfo,
+  CheckoutEvent,
+  CheckoutEventType,
+} from './types';

package/src/messageHandler.ts

@@ -0,0 +1,124 @@
+import type { CheckoutEventType, PaymentResult, PaymentStatus, SanitizedPayment } from './types';
+
+// Exact set of bridge event types the checkout page emits. Anything else is
+// dropped. Keys are the wire `type` strings; values are the short event names.
+const KNOWN_TYPES: Record<string, CheckoutEventType> = {
+  'gbitx:payment:loaded': 'loaded',
+  'gbitx:payment:confirmed': 'confirmed',
+  'gbitx:payment:cancelled': 'cancelled',
+  'gbitx:payment:expired': 'expired',
+  'gbitx:payment:failed': 'failed',
+  'gbitx:payment:closed': 'closed',
+};
+
+// A bridge message is a single JSON string. Cap it well under any sane size so
+// a hostile page can't feed us a giant string before we even parse.
+const MAX_MESSAGE_BYTES = 8192;
+
+const PAYMENT_STATUSES: readonly PaymentStatus[] = [
+  'PENDING', 'AWAITING_PAYMENT', 'UNDERPAID', 'CONFIRMING', 'CONFIRMED', 'EXPIRED', 'FAILED', 'CANCELLED',
+];
+
+export interface ParsedMessage {
+  type: CheckoutEventType;
+  // null for :loaded (the page sends {}) or when a payment payload is absent
+  // / malformed. Terminal handling tolerates null (webhook is truth).
+  payment: SanitizedPayment | null;
+}
+
+function asString(v: unknown): string | null {
+  return typeof v === 'string' ? v : null;
+}
+
+// Accept string OR finite number for decimal amount fields (the page sends
+// strings — Prisma Decimal — but we stay tolerant) and normalize to a plain
+// decimal string. A number whose String() form uses exponential notation
+// (very large, or small like 1e-8) is dropped to null rather than surfaced as
+// "1e-8"/"1e+21"; the field is display-only, so null is safer than a
+// misleading exponent.
+function asDecimalString(v: unknown): string | null {
+  if (typeof v === 'string') return v;
+  if (typeof v === 'number' && Number.isFinite(v)) {
+    const s = String(v);
+    return s.includes('e') || s.includes('E') ? null : s;
+  }
+  return null;
+}
+
+// Re-pick ONLY the whitelisted fields into a fresh object. This discards any
+// extra keys (prototype-pollution vectors, functions, nested junk, and the
+// fields the page deliberately strips). Returns null if the payload is not a
+// usable payment (no id or unknown status).
+export function sanitizePayment(input: unknown): SanitizedPayment | null {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) return null;
+  const p = input as Record<string, unknown>;
+
+  const id = asString(p.id);
+  const status = asString(p.status);
+  if (!id || !status || !(PAYMENT_STATUSES as readonly string[]).includes(status)) return null;
+
+  const mode = p.mode === 'LIVE' || p.mode === 'SANDBOX' ? p.mode : 'SANDBOX';
+
+  return {
+    id,
+    status: status as PaymentStatus,
+    amount: asDecimalString(p.amount) ?? '',
+    currency: asString(p.currency) ?? '',
+    crypto: asString(p.crypto),
+    network: asString(p.network),
+    amountCrypto: asDecimalString(p.amountCrypto),
+    amountPaid: asDecimalString(p.amountPaid),
+    mode,
+    confirmedAt: asString(p.confirmedAt),
+    expiresAt: asString(p.expiresAt) ?? '',
+  };
+}
+
+// Defensively parse a raw onMessage string into a known event, or null. Never
+// throws. Callers MUST have already verified the message origin (the WebView's
+// committed top-frame URL) before invoking this.
+export function parseBridgeMessage(raw: unknown): ParsedMessage | null {
+  if (typeof raw !== 'string' || raw.length === 0 || raw.length > MAX_MESSAGE_BYTES) return null;
+
+  let obj: unknown;
+  try {
+    obj = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (!obj || typeof obj !== 'object' || Array.isArray(obj)) return null;
+
+  const type = (obj as { type?: unknown }).type;
+  if (typeof type !== 'string') return null;
+  const mapped = KNOWN_TYPES[type];
+  if (!mapped) return null;
+
+  return {
+    type: mapped,
+    payment: sanitizePayment((obj as { payment?: unknown }).payment),
+  };
+}
+
+// True for the events that end a checkout session.
+export function isTerminal(type: CheckoutEventType): boolean {
+  return type !== 'loaded';
+}
+
+// Map a terminal event to a PaymentResult. `loaded` is non-terminal -> null.
+// `closed` and `cancelled` collapse to a single cancelled representation.
+export function terminalResult(type: CheckoutEventType, payment: SanitizedPayment | null): PaymentResult | null {
+  switch (type) {
+    case 'confirmed':
+      return { status: 'confirmed', payment };
+    case 'cancelled':
+    case 'closed':
+      return { status: 'cancelled', reason: 'user_closed', payment };
+    case 'expired':
+      return { status: 'expired', reason: 'expired', payment };
+    case 'failed':
+      return { status: 'failed', payment };
+    case 'loaded':
+    default:
+      return null;
+  }
+}

package/src/redact.ts

@@ -0,0 +1,58 @@
+// Credential hygiene. The publishable key, the client token, and the full
+// checkout URL (which carries #t=<clientToken>) must NEVER hit a log, a
+// breadcrumb, or a serialized error. Everything here is defensive: even the
+// debug logger routes through redaction.
+
+// Reduce a URL to origin + pathname, dropping the query and fragment (where
+// the token lives). Use this anywhere a URL might be surfaced.
+export function redactUrl(url: string): string {
+  try {
+    const u = new URL(url);
+    return `${u.origin}${u.pathname}`;
+  } catch {
+    return '[unparseable-url]';
+  }
+}
+
+// Scrub key-shaped and token substrings from arbitrary text.
+export function redactSecrets(input: string): string {
+  return input
+    // gk_/pk_ live/test keys -> keep the class prefix, redact the body.
+    .replace(/([gp]k_(?:live|test)_)[0-9a-f]{6,}/gi, '$1redacted')
+    // t= token in a fragment OR query string (#t=…, ?t=…, &t=…).
+    .replace(/([#?&]t=)[^\s&"']+/g, '$1redacted')
+    // Authorization: Bearer <key/token>.
+    .replace(/(Bearer\s+)[^\s"']+/gi, '$1redacted');
+}
+
+function safeStringify(value: unknown): string {
+  const seen = new WeakSet<object>();
+  try {
+    return JSON.stringify(value, (_k, v) => {
+      if (typeof v === 'object' && v !== null) {
+        if (seen.has(v)) return '[circular]';
+        seen.add(v);
+      }
+      return v;
+    });
+  } catch {
+    return String(value);
+  }
+}
+
+let _debug = false;
+export function setDebug(on: boolean): void {
+  _debug = !!on;
+}
+
+// Debug logger. Off by default; even when on it redacts every line.
+export function debugLog(...parts: unknown[]): void {
+  if (!_debug) return;
+  try {
+    const line = parts.map((p) => (typeof p === 'string' ? p : safeStringify(p))).join(' ');
+    // eslint-disable-next-line no-console
+    console.log('[GbitXPay]', redactSecrets(line));
+  } catch {
+    /* logging must never throw */
+  }
+}