@spare-technologies/spare-link 0.1.0-beta.0 → 1.0.0

package/src/core/client/link-api-client.ts

@@ -1,414 +0,0 @@
-import { createLogger } from '../../internal/logger';
-import { DEFAULT_REQUEST_TIMEOUT_MS } from '../../public/constants';
-import { type SpareApiTenant, tenantCountryCode } from '../../public/spare-link-config';
-import { SDK_VERSION } from '../../version';
-import { PaymentApiError, isPaymentApiError } from '../errors/payment-api-error';
-import type {
-  ConsentResponse,
-  CopResponse,
-  LinkSessionResponse,
-  LinkStatusResponse,
-  PatchTokenResponse,
-  ProviderSummary,
-  TelemetryResponse,
-} from '../models';
-import {
-  mapConsentResponse,
-  mapCopResponse,
-  mapLinkSessionResponse,
-  mapLinkStatusResponse,
-  mapPatchTokenResponse,
-  mapProvidersResponse,
-  mapTelemetryResponse,
-  unwrap,
-} from '../models/wire-mappers';
-
-export interface LinkApiClientOptions {
-  baseUrl: string;
-  /** Either 'UAE' (raw header value) or a tenant enum. */
-  tenant: SpareApiTenant | string;
-  fetch?: typeof fetch;
-  requestTimeoutMs?: number;
-  /** UUID generator for the Idempotency-Key header on POST /link/consent. */
-  uuid?: () => string;
-  /** User-Agent header (defaults to `@spare-technologies/spare-link/<SDK_VERSION>`). */
-  userAgent?: string;
-}
-
-const RETRYABLE_ERROR_CODES = new Set([
-  'network_timeout',
-  'consent_creation_failed',
-  'bank_unavailable',
-  'network_error',
-]);
-
-const DEFAULT_USER_AGENT = `@spare-technologies/spare-link/${SDK_VERSION}`;
-const log = createLogger('LinkApiClient');
-
-function isCryptoCapable(g: typeof globalThis): g is typeof globalThis & {
-  crypto: { randomUUID(): string };
-} {
-  return (
-    typeof g.crypto !== 'undefined' &&
-    typeof (g.crypto as { randomUUID?: () => string }).randomUUID === 'function'
-  );
-}
-
-function isCryptoRandom(g: typeof globalThis): g is typeof globalThis & {
-  crypto: { getRandomValues(arr: Uint8Array): Uint8Array };
-} {
-  return (
-    typeof g.crypto !== 'undefined' &&
-    typeof (g.crypto as { getRandomValues?: (a: Uint8Array) => Uint8Array }).getRandomValues ===
-      'function'
-  );
-}
-
-function defaultUuid(): string {
-  if (isCryptoCapable(globalThis)) {
-    return globalThis.crypto.randomUUID();
-  }
-  const bytes = new Uint8Array(16);
-  if (isCryptoRandom(globalThis)) {
-    globalThis.crypto.getRandomValues(bytes);
-  } else {
-    for (let i = 0; i < 16; i += 1) bytes[i] = Math.floor(Math.random() * 256);
-  }
-  bytes[6] = ((bytes[6] ?? 0) & 0x0f) | 0x40;
-  bytes[8] = ((bytes[8] ?? 0) & 0x3f) | 0x80;
-  const hex = Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
-  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`;
-}
-
-/** Full client for all Link-origin endpoints — headers, retry rules, and error mapping. */
-export class LinkApiClient {
-  readonly baseUrl: string;
-  readonly tenantHeader: string;
-  readonly requestTimeoutMs: number;
-  readonly userAgent: string;
-
-  private readonly fetchImpl: typeof fetch;
-  private readonly uuid: () => string;
-  private readonly aborters = new Set<AbortController>();
-  private disposed = false;
-
-  constructor(opts: LinkApiClientOptions) {
-    this.baseUrl = opts.baseUrl.endsWith('/') ? opts.baseUrl.slice(0, -1) : opts.baseUrl;
-    this.tenantHeader =
-      typeof opts.tenant === 'string' && /^[A-Z]+$/.test(opts.tenant)
-        ? opts.tenant
-        : tenantCountryCode(opts.tenant as SpareApiTenant);
-    this.requestTimeoutMs = opts.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
-    this.fetchImpl = opts.fetch ?? globalThis.fetch.bind(globalThis);
-    this.uuid = opts.uuid ?? defaultUuid;
-    this.userAgent = opts.userAgent ?? DEFAULT_USER_AGENT;
-  }
-
-  /** Aborts in-flight requests and rejects further work. */
-  dispose(): void {
-    this.disposed = true;
-    for (const c of this.aborters) c.abort();
-    this.aborters.clear();
-  }
-
-  private headers(linkToken: string, extra?: Record<string, string>): HeadersInit {
-    return {
-      'x-link-token': linkToken,
-      'Content-Type': 'application/json',
-      'X-Tenant': this.tenantHeader,
-      'User-Agent': this.userAgent,
-      ...(extra ?? {}),
-    };
-  }
-
-  private url(path: string): string {
-    return `${this.baseUrl}${path.startsWith('/') ? path : `/${path}`}`;
-  }
-
-  /**
-   * Wraps a single attempt with a per-request `AbortController`. Times out after
-   * `requestTimeoutMs`. Classifies any thrown non-{@link PaymentApiError} as
-   * `network_error` so callers always see a typed error.
-   */
-  private async withTimeout<T>(body: (signal: AbortSignal) => Promise<T>): Promise<T> {
-    if (this.disposed) {
-      throw new PaymentApiError('client_disposed', 'API client has been disposed.');
-    }
-    const controller = new AbortController();
-    this.aborters.add(controller);
-    const timer = setTimeout(() => controller.abort(), this.requestTimeoutMs);
-    try {
-      return await body(controller.signal);
-    } catch (err) {
-      if (isPaymentApiError(err)) throw err;
-      const name = (err as { name?: string }).name;
-      if (name === 'AbortError') {
-        log.severe(
-          `request timed out after ${this.requestTimeoutMs}ms${this.disposed ? ' (client disposed)' : ''}`,
-        );
-        throw new PaymentApiError(
-          this.disposed ? 'client_disposed' : 'network_timeout',
-          this.disposed
-            ? 'API client was disposed mid-request.'
-            : 'The request timed out. Please check your connection and try again.',
-        );
-      }
-      // Catch-all: DNS, refused, malformed response, JSON parse failure, etc.
-      // We surface the message for debugging but a stable code for branching.
-      const message = err instanceof Error ? err.message : String(err);
-      throw new PaymentApiError('network_error', `Network error: ${message}`);
-    } finally {
-      clearTimeout(timer);
-      this.aborters.delete(controller);
-    }
-  }
-
-  /** Idempotent retry helper (max 2 attempts, 500ms + 1000ms backoff). */
-  private async withRetry<T>(
-    body: (signal: AbortSignal) => Promise<T>,
-    maxAttempts = 2,
-  ): Promise<T> {
-    let lastError: PaymentApiError | undefined;
-    for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
-      try {
-        return await this.withTimeout(body);
-      } catch (err) {
-        if (
-          isPaymentApiError(err) &&
-          RETRYABLE_ERROR_CODES.has(err.code) &&
-          attempt < maxAttempts
-        ) {
-          lastError = err;
-          await delay(attempt === 1 ? 500 : 1000);
-          continue;
-        }
-        throw err;
-      }
-    }
-    throw (
-      lastError ??
-      new PaymentApiError('network_error', 'A network error occurred. Please try again.')
-    );
-  }
-
-  private async parseAndHandle<T>(
-    res: Response,
-    mapper: (raw: unknown) => T,
-    endpoint: string,
-  ): Promise<T> {
-    if (!res.ok) {
-      await this.throwForError(res);
-    }
-    let body: unknown;
-    try {
-      body = (await res.json()) as unknown;
-    } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
-      throw new PaymentApiError(
-        `${endpoint}_payload_invalid`,
-        `${endpoint} response body is not valid JSON: ${message}`,
-      );
-    }
-    try {
-      return mapper(unwrap(body));
-    } catch (err) {
-      if (isPaymentApiError(err)) throw err;
-      const message = err instanceof Error ? err.message : String(err);
-      throw new PaymentApiError(
-        `${endpoint}_payload_invalid`,
-        `${endpoint} response payload is invalid: ${message}`,
-      );
-    }
-  }
-
-  private async throwForError(res: Response): Promise<never> {
-    const text = await res.text().catch(() => '');
-    let parsed:
-      | { error_code?: string; code?: string; error?: string; message?: string }
-      | undefined;
-    try {
-      parsed = text ? (JSON.parse(text) as typeof parsed) : undefined;
-    } catch {
-      parsed = undefined;
-    }
-    const errorCode =
-      parsed?.error_code ??
-      parsed?.code ??
-      (typeof parsed?.error === 'string' ? parsed.error : undefined);
-
-    switch (res.status) {
-      case 401:
-        log.severe('HTTP 401: link token invalid or expired');
-        throw new PaymentApiError('invalid_token', 'The link token is invalid or has expired.');
-      case 410:
-        if (errorCode === 'SESSION_CANCELLED') {
-          log.severe('HTTP 410: session cancelled');
-          throw new PaymentApiError('session_cancelled', 'The payment session was cancelled.');
-        }
-        log.severe('HTTP 410: session expired');
-        throw PaymentApiError.sessionExpired();
-      case 409:
-        log.severe('HTTP 409: session already completed');
-        throw new PaymentApiError(
-          'session_already_completed',
-          'The payment session has already been completed.',
-        );
-      case 503:
-        log.severe('HTTP 503: bank unavailable');
-        throw new PaymentApiError(
-          'bank_unavailable',
-          'Bank is temporarily unavailable. Please try again.',
-        );
-      case 502:
-        log.severe('HTTP 502: consent creation failed');
-        throw new PaymentApiError(
-          'consent_creation_failed',
-          'Unable to create payment authorization. Please try again.',
-        );
-      case 408:
-        log.severe('HTTP 408: request timeout');
-        throw new PaymentApiError(
-          'network_timeout',
-          'The server timed out processing the request. Please try again.',
-        );
-      case 429:
-        log.severe('HTTP 429: rate limit exceeded');
-        throw new PaymentApiError(
-          'rate_limit_exceeded',
-          'Too many requests. Please wait and try again.',
-        );
-      default:
-        log.severe(`HTTP ${res.status}: unexpected error`);
-        throw new PaymentApiError(
-          'network_error',
-          `Unexpected status ${res.status} from Link API.`,
-        );
-    }
-  }
-
-  // ---- Endpoints ----------------------------------------------------------
-
-  /** `GET /link` — one-time session hydration. */
-  async getSession(linkToken: string): Promise<LinkSessionResponse> {
-    log.info('GET /link');
-    return this.withRetry(async (signal) => {
-      const res = await this.fetchImpl(this.url('/link'), {
-        method: 'GET',
-        headers: this.headers(linkToken),
-        signal,
-      });
-      return this.parseAndHandle(res, mapLinkSessionResponse, 'session');
-    });
-  }
-
-  /** `GET /link/status` — read-only session status. */
-  async getStatus(linkToken: string): Promise<LinkStatusResponse> {
-    log.info('GET /link/status');
-    return this.withRetry(async (signal) => {
-      const res = await this.fetchImpl(this.url('/link/status'), {
-        method: 'GET',
-        headers: this.headers(linkToken),
-        signal,
-      });
-      return this.parseAndHandle(res, mapLinkStatusResponse, 'status');
-    });
-  }
-
-  /** `GET /link/providers` — bank list for the session jurisdiction. */
-  async getProviders(linkToken: string): Promise<ProviderSummary[]> {
-    log.info('GET /link/providers');
-    return this.withRetry(async (signal) => {
-      const res = await this.fetchImpl(this.url('/link/providers'), {
-        method: 'GET',
-        headers: this.headers(linkToken),
-        signal,
-      });
-      return this.parseAndHandle(res, mapProvidersResponse, 'providers');
-    });
-  }
-
-  /** `POST /link/telemetry` — device/risk signals (best-effort). */
-  async postTelemetry(args: {
-    linkToken: string;
-    payload: Record<string, unknown>;
-  }): Promise<TelemetryResponse> {
-    log.info('POST /link/telemetry');
-    return this.withRetry(async (signal) => {
-      const res = await this.fetchImpl(this.url('/link/telemetry'), {
-        method: 'POST',
-        headers: this.headers(args.linkToken),
-        body: JSON.stringify(args.payload),
-        signal,
-      });
-      return this.parseAndHandle(res, mapTelemetryResponse, 'telemetry');
-    });
-  }
-
-  /** `GET /link/cop` — Confirmation of Payee. Accepts an optional providerId override. */
-  async getConfirmPayee(linkToken: string, providerId?: string): Promise<CopResponse> {
-    log.info(`GET /link/cop${providerId ? ` (providerId: ${providerId})` : ''}`);
-    return this.withRetry(async (signal) => {
-      const path = providerId
-        ? `/link/cop?providerId=${encodeURIComponent(providerId)}`
-        : '/link/cop';
-      const res = await this.fetchImpl(this.url(path), {
-        method: 'GET',
-        headers: this.headers(linkToken),
-        signal,
-      });
-      return this.parseAndHandle(res, mapCopResponse, 'cop');
-    });
-  }
-
-  /**
-   * `POST /link/consent` — creates a consent and returns the bank redirect URL.
-   *
-   * NEVER retried — the Idempotency-Key header guarantees safe retries at the
-   * caller level if they re-invoke with the SAME key.
-   */
-  async postConsent(args: {
-    linkToken: string;
-    bankId?: string;
-    idempotencyKey?: string;
-  }): Promise<ConsentResponse> {
-    const key = args.idempotencyKey ?? this.uuid();
-    log.info(`POST /link/consent (bankId: ${args.bankId ?? 'n/a'}, idempotencyKey: ${key})`);
-    return this.withTimeout(async (signal) => {
-      const body = args.bankId ? JSON.stringify({ provider_id: args.bankId }) : '{}';
-      const res = await this.fetchImpl(this.url('/link/consent'), {
-        method: 'POST',
-        headers: this.headers(args.linkToken, { 'Idempotency-Key': key }),
-        body,
-        signal,
-      });
-      return this.parseAndHandle(res, mapConsentResponse, 'consent');
-    });
-  }
-
-  /** `PATCH /link` — cancel or report an error on the session. */
-  async patchToken(args: {
-    linkToken: string;
-    action: 'cancel' | 'error';
-    errorCode?: string;
-  }): Promise<PatchTokenResponse> {
-    log.info(`PATCH /link (action: ${args.action}, errorCode: ${args.errorCode ?? 'n/a'})`);
-    return this.withRetry(async (signal) => {
-      const body: { action: string; code?: string; source?: string } = { action: args.action };
-      if (args.errorCode) body.code = args.errorCode;
-      // Tag SDK-originated error reports so the backend can distinguish them
-      // from hosted/provider-return reports in its dashboards.
-      if (args.action === 'error') body.source = 'sdk';
-      const res = await this.fetchImpl(this.url('/link'), {
-        method: 'PATCH',
-        headers: this.headers(args.linkToken),
-        body: JSON.stringify(body),
-        signal,
-      });
-      return this.parseAndHandle(res, mapPatchTokenResponse, 'patch_token');
-    });
-  }
-}
-
-function delay(ms: number): Promise<void> {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}

package/src/core/errors/payment-api-error.ts

@@ -1,35 +0,0 @@
-/**
- * Errors emitted by the SDK's API client.
- *
- * The `code` field is stable wire-of-record for merchant analytics/logging.
- * The `message` field is intentionally generic and safe to display to end users.
- */
-export class PaymentApiError extends Error {
-  readonly code: string;
-
-  constructor(code: string, message: string) {
-    super(message);
-    this.name = 'PaymentApiError';
-    this.code = code;
-    // Preserve the prototype chain across compile targets.
-    Object.setPrototypeOf(this, PaymentApiError.prototype);
-  }
-
-  override toString(): string {
-    return `PaymentApiError(${this.code}): ${this.message}`;
-  }
-
-  static sessionExpired(): PaymentApiError {
-    return new PaymentApiError('session_expired', 'The payment session has expired.');
-  }
-}
-
-/** Type guard so consumers can narrow without instanceof. */
-export function isPaymentApiError(err: unknown): err is PaymentApiError {
-  return (
-    err instanceof PaymentApiError ||
-    (typeof err === 'object' &&
-      err !== null &&
-      (err as { name?: string }).name === 'PaymentApiError')
-  );
-}

package/src/core/models/link-session-status.ts

@@ -1,7 +0,0 @@
-/**
- * `/link/status` values where the bank has returned but settlement may still be
- * pending. `redirected` only means consent was posted — not bank authorization.
- */
-export function isBankCallbackReceivedStatus(status: string): boolean {
-  return status === 'callback_received';
-}

package/src/core/models/payment-type.ts

@@ -1,54 +0,0 @@
-import type { CreatePaymentRequestInput } from './index';
-
-export enum PaymentType {
-  singleInstantPayment = 'SingleInstantPayment',
-  fixedDefinedSchedule = 'FixedDefinedSchedule',
-  variableDefinedSchedule = 'VariableDefinedSchedule',
-  fixedPeriodicSchedule = 'FixedPeriodicSchedule',
-  variablePeriodicSchedule = 'VariablePeriodicSchedule',
-  fixedOnDemand = 'FixedOnDemand',
-  variableOnDemand = 'VariableOnDemand',
-  internationalPayment = 'InternationalPayment',
-}
-
-export type ConsentUiVariant = 'singlePayment' | 'international' | 'multiPayment';
-
-const MANDATE_TYPES = new Set<string>([
-  PaymentType.fixedDefinedSchedule,
-  PaymentType.variableDefinedSchedule,
-  PaymentType.fixedPeriodicSchedule,
-  PaymentType.variablePeriodicSchedule,
-  PaymentType.fixedOnDemand,
-  PaymentType.variableOnDemand,
-]);
-
-export function resolvedPaymentType(request: CreatePaymentRequestInput): PaymentType {
-  const t = request.type;
-  if (Object.values(PaymentType).includes(t as PaymentType)) {
-    return t as PaymentType;
-  }
-  return PaymentType.singleInstantPayment;
-}
-
-export function isMultiPayment(request: CreatePaymentRequestInput): boolean {
-  return MANDATE_TYPES.has(request.type);
-}
-
-export function isInternational(request: CreatePaymentRequestInput): boolean {
-  return (
-    request.instructions.isInternationalPayment === true ||
-    resolvedPaymentType(request) === PaymentType.internationalPayment
-  );
-}
-
-export function supportsConfirmationOfPayee(request: CreatePaymentRequestInput): boolean {
-  return (
-    resolvedPaymentType(request) === PaymentType.singleInstantPayment && !isInternational(request)
-  );
-}
-
-export function consentUiVariant(request: CreatePaymentRequestInput): ConsentUiVariant {
-  if (isMultiPayment(request)) return 'multiPayment';
-  if (isInternational(request)) return 'international';
-  return 'singlePayment';
-}