@momorail/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Momorail contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,307 @@
+/**
+ * Mobile money operators, each scoped by its ISO 3166-1 alpha-2 country code so
+ * that the same brand in two countries (e.g. Orange in Mali vs Senegal) stays
+ * distinct. Adapters advertise the subset they support via {@link ProviderCapabilities}.
+ */
+declare const OPERATORS: readonly ["orange_ml", "moov_ml", "wave_ml", "orange_ci", "mtn_ci", "moov_ci", "wave_ci", "orange_sn", "free_sn", "wave_sn", "expresso_sn", "orange_bf", "moov_bf", "mtn_bj", "moov_bj", "orange_ne", "moov_ne", "airtel_ne", "moov_tg", "togocom_tg", "orange_cd", "airtel_cd", "vodacom_cd"];
+type Operator = (typeof OPERATORS)[number];
+declare function isOperator(value: string): value is Operator;
+declare const CURRENCIES: readonly ["XOF", "XAF", "GHS", "NGN"];
+type Currency = (typeof CURRENCIES)[number];
+/**
+ * Currencies with no minor unit. Amounts are always integers in Momorail, but for
+ * these the integer is a whole franc rather than a hundredth. Adapters use this
+ * to format amounts for providers that still expect a decimal string.
+ */
+declare const ZERO_DECIMAL_CURRENCIES: ReadonlySet<Currency>;
+
+interface Money {
+    /**
+     * Amount as an integer. For zero-decimal currencies (XOF, XAF) this is a whole
+     * unit; for the others it is the minor unit (e.g. pesewa, kobo).
+     */
+    amount: number;
+    currency: Currency;
+}
+type TransactionType = 'collection' | 'disbursement';
+type TransactionStatus = 'pending' | 'processing' | 'succeeded' | 'failed' | 'cancelled' | 'expired' | 'unknown';
+/** Statuses that never change again once reached. */
+declare const TERMINAL_STATUSES: ReadonlySet<TransactionStatus>;
+declare function isTerminal(status: TransactionStatus): boolean;
+type FailureReason = 'insufficient_funds' | 'invalid_number' | 'user_declined' | 'timeout' | 'provider_error' | 'limit_exceeded' | 'duplicate_reference' | 'other';
+interface Party {
+    /** E.164 phone number, e.g. "+22370000000". */
+    phone: string;
+    operator?: Operator;
+    firstName?: string;
+    lastName?: string;
+    email?: string;
+}
+interface CollectionInput {
+    amount: Money;
+    customer: Party;
+    /** Caller-supplied unique reference. Doubles as the idempotency key. */
+    reference: string;
+    description?: string;
+    /** Server-to-server webhook URL the provider should call with status updates. */
+    callbackUrl?: string;
+    /** Browser redirect target after a hosted-checkout flow succeeds. */
+    returnUrl?: string;
+    /** Browser redirect target after a hosted-checkout flow is cancelled. */
+    cancelUrl?: string;
+    metadata?: Record<string, string>;
+}
+interface DisbursementInput {
+    amount: Money;
+    recipient: Party;
+    /** Caller-supplied unique reference. Doubles as the idempotency key. */
+    reference: string;
+    description?: string;
+    callbackUrl?: string;
+    metadata?: Record<string, string>;
+}
+interface TransactionRef {
+    /** Provider-side id, when known. */
+    id?: string;
+    /** Caller-supplied reference. */
+    reference?: string;
+}
+interface Transaction {
+    provider: string;
+    /** Provider-side id. */
+    id: string;
+    /** Caller-supplied reference echoed back. */
+    reference: string;
+    type: TransactionType;
+    status: TransactionStatus;
+    amount: Money;
+    fees?: Money;
+    operator?: Operator;
+    customer?: Party;
+    /** Set when the flow needs the customer redirected to a hosted page. */
+    checkoutUrl?: string;
+    /** Set only for a `failed` transaction. */
+    failureReason?: FailureReason;
+    /** Raw, unmodified provider payload. Always populated so callers never get stuck. */
+    providerRaw: unknown;
+    /** ISO 8601 timestamp. */
+    createdAt: string;
+    /** ISO 8601 timestamp. */
+    updatedAt: string;
+}
+interface ProviderCapabilities {
+    collection: boolean;
+    disbursement: boolean;
+    /** Status can be queried by caller reference, not only by provider id. */
+    lookupByReference: boolean;
+    /** Collection requires redirecting the customer to a hosted checkout page. */
+    hostedCheckout: boolean;
+    operators: readonly Operator[];
+    currencies: readonly Currency[];
+}
+interface RawWebhook {
+    headers: Record<string, string | string[] | undefined>;
+    /** Raw request body as received; keep it a string when a signature covers it. */
+    body: string | Uint8Array | Record<string, unknown>;
+    /** Full request URL or path+query, when the provider signs it. */
+    url?: string;
+}
+type WebhookEventType = 'transaction.succeeded' | 'transaction.failed' | 'transaction.pending' | 'transaction.cancelled' | 'transaction.expired' | 'unknown';
+interface WebhookEvent {
+    type: WebhookEventType;
+    transaction: Transaction;
+    providerRaw: unknown;
+}
+/** Map a normalised {@link TransactionStatus} onto the webhook event type adapters emit. */
+declare function webhookEventTypeForStatus(status: TransactionStatus): WebhookEventType;
+interface RetryPolicy {
+    /** Number of retries after the first attempt. */
+    retries: number;
+    /** Base delay in ms; grows exponentially with full jitter. */
+    baseDelayMs: number;
+    /** Upper bound on a single delay in ms. */
+    maxDelayMs: number;
+}
+interface RequestOptions {
+    /** Route this call to a specific configured provider by id (skips operator routing). */
+    provider?: string;
+    /** Abort signal forwarded to the underlying transport and retry waits. */
+    signal?: AbortSignal;
+    /** Per-call override of the client retry policy. */
+    retry?: Partial<RetryPolicy>;
+    /** Per-call override of the client `failover` setting (`collection` only). */
+    failover?: boolean;
+}
+
+interface MomorailErrorOptions {
+    /** Id of the adapter that produced the error, when known. */
+    provider?: string;
+    /** Whether a retry with the same input could plausibly succeed. */
+    retryable?: boolean;
+    /** Raw provider payload that triggered the error. */
+    providerRaw?: unknown;
+    cause?: unknown;
+}
+/** Base class for every error Momorail throws. Adapters map provider errors onto a subclass. */
+declare class MomorailError extends Error {
+    readonly provider: string | undefined;
+    readonly code: string;
+    readonly retryable: boolean;
+    readonly providerRaw: unknown;
+    constructor(message: string, code: string, options?: MomorailErrorOptions);
+}
+/** Credentials were rejected by the provider. */
+declare class AuthError extends MomorailError {
+    constructor(message?: string, options?: MomorailErrorOptions);
+}
+/** The request was malformed before it ever reached the provider. */
+declare class ValidationError extends MomorailError {
+    constructor(message: string, options?: MomorailErrorOptions);
+}
+/** The provider is reachable but temporarily refusing work; safe to retry. */
+declare class ProviderUnavailableError extends MomorailError {
+    constructor(message?: string, options?: MomorailErrorOptions);
+}
+/** The provider throttled the request. Carries a hint of how long to wait. */
+declare class RateLimitError extends MomorailError {
+    readonly retryAfterMs: number | undefined;
+    constructor(message?: string, options?: MomorailErrorOptions & {
+        retryAfterMs?: number;
+    });
+}
+/** No transaction matched the given id or reference. */
+declare class TransactionNotFoundError extends MomorailError {
+    constructor(message?: string, options?: MomorailErrorOptions);
+}
+/** A webhook payload failed signature verification and must not be trusted. */
+declare class WebhookVerificationError extends MomorailError {
+    constructor(message?: string, options?: MomorailErrorOptions);
+}
+
+/**
+ * The contract every aggregator adapter implements. An adapter translates
+ * between this shape and exactly one provider's API; it never talks to more
+ * than one provider, and it does not implement retry — the client owns that.
+ */
+interface PaymentProvider {
+    /** Stable lowercase identifier, e.g. `'cinetpay'`. Matches `/^[a-z0-9_-]+$/`. */
+    readonly id: string;
+    collection(input: CollectionInput, options?: ProviderCallOptions): Promise<Transaction>;
+    disbursement(input: DisbursementInput, options?: ProviderCallOptions): Promise<Transaction>;
+    getTransaction(ref: TransactionRef, options?: ProviderCallOptions): Promise<Transaction>;
+    /** Verify and normalise an inbound webhook. Throws {@link WebhookVerificationError} on a bad signature. */
+    parseWebhook(raw: RawWebhook): Promise<WebhookEvent>;
+    capabilities(): ProviderCapabilities;
+}
+/** The slice of {@link RequestOptions} an adapter receives (retry stays with the client). */
+type ProviderCallOptions = Pick<RequestOptions, 'signal'>;
+
+declare const DEFAULT_RETRY_POLICY: RetryPolicy;
+interface RetryContext {
+    policy: RetryPolicy;
+    signal?: AbortSignal;
+    onRetry?: (info: {
+        attempt: number;
+        delayMs: number;
+        error: unknown;
+    }) => void;
+}
+/**
+ * Run `fn`, retrying only while it throws a {@link MomorailError} whose `retryable`
+ * flag is set. `attempt` is zero-based. A provider-supplied `retryAfterMs`
+ * (e.g. on {@link RateLimitError}) lengthens the wait but never shortens it.
+ */
+declare function runWithRetry<T>(fn: (attempt: number) => Promise<T>, ctx: RetryContext): Promise<T>;
+
+/**
+ * Where an adapter remembers the transactions it has created, so a retried
+ * `collection` / `disbursement` with the same `reference` returns the same
+ * `Transaction` rather than starting a second one, and so a sparse
+ * `getTransaction` / webhook payload can be enriched with what the adapter
+ * already knows.
+ *
+ * The default is {@link MemoryIdempotencyStore} (per process). Pass a shared
+ * implementation (Redis, a database) for idempotency that survives restarts and
+ * spans instances. Keys are opaque strings; values are plain JSON-serialisable
+ * `Transaction` objects.
+ */
+interface IdempotencyStore {
+    get(key: string): Transaction | undefined | Promise<Transaction | undefined>;
+    set(key: string, value: Transaction): void | Promise<void>;
+}
+/** In-memory {@link IdempotencyStore} with a bounded, FIFO-evicting map. */
+declare class MemoryIdempotencyStore implements IdempotencyStore {
+    #private;
+    constructor(options?: {
+        maxEntries?: number;
+    });
+    get(key: string): Transaction | undefined;
+    set(key: string, value: Transaction): void;
+}
+/**
+ * A namespaced view over an {@link IdempotencyStore} that an adapter uses to
+ * store and recall a `Transaction` by either the caller `reference` or the
+ * provider-side `id`. The namespace (the adapter id) keeps entries from
+ * different adapters apart when they share one backing store.
+ */
+declare class IdempotencyCache {
+    #private;
+    constructor(store: IdempotencyStore, namespace: string);
+    byReference(reference: string): Promise<Transaction | undefined>;
+    byId(id: string): Promise<Transaction | undefined>;
+    remember(txn: Transaction): Promise<void>;
+}
+
+interface MomorailClientOptions {
+    /** One or more configured adapters. Must contain at least one, with unique ids. */
+    providers: PaymentProvider[];
+    /** Id used when a call doesn't name a provider and no adapter matches the operator. Defaults to the first entry. */
+    defaultProvider?: string;
+    /** Overrides merged onto {@link DEFAULT_RETRY_POLICY}. */
+    retry?: Partial<RetryPolicy>;
+    /**
+     * When true, `collection` retries the *next* adapter covering the same
+     * operator if the chosen one raises {@link ProviderUnavailableError} (nothing
+     * was created, so it is safe to move on). Off by default. Never applies to
+     * `disbursement`. Can be overridden per call with `options.failover`.
+     */
+    failover?: boolean;
+    onRetry?: (info: {
+        provider: string;
+        attempt: number;
+        delayMs: number;
+        error: unknown;
+    }) => void;
+    onFailover?: (info: {
+        from: string;
+        to: string;
+        error: unknown;
+    }) => void;
+}
+/**
+ * Fans a single unified surface out to one of several {@link PaymentProvider}
+ * adapters. Validates input, routes by provider id, and applies the retry policy
+ * so adapters stay small.
+ */
+declare class MomorailClient {
+    #private;
+    constructor(options: MomorailClientOptions);
+    get providerIds(): string[];
+    /** Resolve a configured adapter by id, or the default when `id` is omitted. */
+    provider(id?: string): PaymentProvider;
+    /** Id of the adapter a call for `operator` would be routed to, if any. */
+    route(operator: Operator): string | undefined;
+    /** `operator -> [adapter ids that advertise it]`, default-first. */
+    coverage(): Record<string, string[]>;
+    collection(input: CollectionInput, options?: RequestOptions): Promise<Transaction>;
+    disbursement(input: DisbursementInput, options?: RequestOptions): Promise<Transaction>;
+    getTransaction(ref: TransactionRef, options?: RequestOptions): Promise<Transaction>;
+    parseWebhook(providerId: string, raw: RawWebhook): Promise<WebhookEvent>;
+    /**
+     * Re-fetch every non-terminal transaction and return the refreshed list,
+     * preserving order. Terminal transactions are passed through untouched.
+     */
+    reconcile(transactions: readonly Transaction[], options?: RequestOptions): Promise<Transaction[]>;
+}
+
+export { AuthError, CURRENCIES, type CollectionInput, type Currency, DEFAULT_RETRY_POLICY, type DisbursementInput, type FailureReason, IdempotencyCache, type IdempotencyStore, MemoryIdempotencyStore, MomorailClient, type MomorailClientOptions, MomorailError, type MomorailErrorOptions, type Money, OPERATORS, type Operator, type Party, type PaymentProvider, type ProviderCallOptions, type ProviderCapabilities, ProviderUnavailableError, RateLimitError, type RawWebhook, type RequestOptions, type RetryContext, type RetryPolicy, TERMINAL_STATUSES, type Transaction, TransactionNotFoundError, type TransactionRef, type TransactionStatus, type TransactionType, ValidationError, type WebhookEvent, type WebhookEventType, WebhookVerificationError, ZERO_DECIMAL_CURRENCIES, isOperator, isTerminal, runWithRetry, webhookEventTypeForStatus };

package/dist/index.js

@@ -0,0 +1,370 @@
+// src/operators.ts
+var OPERATORS = [
+  "orange_ml",
+  "moov_ml",
+  "wave_ml",
+  "orange_ci",
+  "mtn_ci",
+  "moov_ci",
+  "wave_ci",
+  "orange_sn",
+  "free_sn",
+  "wave_sn",
+  "expresso_sn",
+  "orange_bf",
+  "moov_bf",
+  "mtn_bj",
+  "moov_bj",
+  "orange_ne",
+  "moov_ne",
+  "airtel_ne",
+  "moov_tg",
+  "togocom_tg",
+  "orange_cd",
+  "airtel_cd",
+  "vodacom_cd"
+];
+function isOperator(value) {
+  return OPERATORS.includes(value);
+}
+var CURRENCIES = ["XOF", "XAF", "GHS", "NGN"];
+var ZERO_DECIMAL_CURRENCIES = /* @__PURE__ */ new Set(["XOF", "XAF"]);
+
+// src/types.ts
+var TERMINAL_STATUSES = /* @__PURE__ */ new Set([
+  "succeeded",
+  "failed",
+  "cancelled",
+  "expired"
+]);
+function isTerminal(status) {
+  return TERMINAL_STATUSES.has(status);
+}
+function webhookEventTypeForStatus(status) {
+  switch (status) {
+    case "succeeded":
+      return "transaction.succeeded";
+    case "failed":
+      return "transaction.failed";
+    case "cancelled":
+      return "transaction.cancelled";
+    case "expired":
+      return "transaction.expired";
+    case "pending":
+    case "processing":
+      return "transaction.pending";
+    default:
+      return "unknown";
+  }
+}
+
+// src/errors.ts
+var MomorailError = class extends Error {
+  provider;
+  code;
+  retryable;
+  providerRaw;
+  constructor(message, code, options = {}) {
+    super(message, options.cause !== void 0 ? { cause: options.cause } : void 0);
+    this.name = new.target.name;
+    this.code = code;
+    this.provider = options.provider;
+    this.retryable = options.retryable ?? false;
+    this.providerRaw = options.providerRaw;
+  }
+};
+var AuthError = class extends MomorailError {
+  constructor(message = "Authentication with the provider failed", options = {}) {
+    super(message, "auth_error", { retryable: false, ...options });
+  }
+};
+var ValidationError = class extends MomorailError {
+  constructor(message, options = {}) {
+    super(message, "validation_error", { retryable: false, ...options });
+  }
+};
+var ProviderUnavailableError = class extends MomorailError {
+  constructor(message = "The provider is temporarily unavailable", options = {}) {
+    super(message, "provider_unavailable", { retryable: true, ...options });
+  }
+};
+var RateLimitError = class extends MomorailError {
+  retryAfterMs;
+  constructor(message = "Rate limit exceeded", options = {}) {
+    super(message, "rate_limit", { retryable: true, ...options });
+    this.retryAfterMs = options.retryAfterMs;
+  }
+};
+var TransactionNotFoundError = class extends MomorailError {
+  constructor(message = "Transaction not found", options = {}) {
+    super(message, "transaction_not_found", { retryable: false, ...options });
+  }
+};
+var WebhookVerificationError = class extends MomorailError {
+  constructor(message = "Webhook signature verification failed", options = {}) {
+    super(message, "webhook_verification", { retryable: false, ...options });
+  }
+};
+
+// src/retry.ts
+var DEFAULT_RETRY_POLICY = {
+  retries: 2,
+  baseDelayMs: 200,
+  maxDelayMs: 2e3
+};
+function isRetryable(error) {
+  return error instanceof MomorailError && error.retryable;
+}
+function jitteredDelay(attempt, policy) {
+  const cap = Math.min(policy.maxDelayMs, policy.baseDelayMs * 2 ** attempt);
+  return Math.random() * cap;
+}
+function sleep(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(signal.reason ?? new Error("Aborted"));
+      return;
+    }
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(signal?.reason ?? new Error("Aborted"));
+    };
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+async function runWithRetry(fn, ctx) {
+  const { policy, signal } = ctx;
+  let lastError;
+  for (let attempt = 0; attempt <= policy.retries; attempt++) {
+    try {
+      return await fn(attempt);
+    } catch (error) {
+      lastError = error;
+      if (attempt === policy.retries || !isRetryable(error)) throw error;
+      let delayMs = jitteredDelay(attempt, policy);
+      const retryAfter = error.retryAfterMs;
+      if (typeof retryAfter === "number" && retryAfter > delayMs) delayMs = retryAfter;
+      ctx.onRetry?.({ attempt, delayMs, error });
+      await sleep(delayMs, signal);
+    }
+  }
+  throw lastError;
+}
+
+// src/idempotency.ts
+var MemoryIdempotencyStore = class {
+  #max;
+  #map = /* @__PURE__ */ new Map();
+  constructor(options = {}) {
+    this.#max = options.maxEntries ?? 5e3;
+  }
+  get(key) {
+    return this.#map.get(key);
+  }
+  set(key, value) {
+    if (this.#map.size >= this.#max && !this.#map.has(key)) {
+      const oldest = this.#map.keys().next().value;
+      if (oldest !== void 0) this.#map.delete(oldest);
+    }
+    this.#map.set(key, value);
+  }
+};
+var IdempotencyCache = class {
+  #store;
+  #ns;
+  constructor(store, namespace) {
+    this.#store = store;
+    this.#ns = namespace;
+  }
+  byReference(reference) {
+    return Promise.resolve(this.#store.get(`${this.#ns}:ref:${reference}`));
+  }
+  byId(id) {
+    return Promise.resolve(this.#store.get(`${this.#ns}:pid:${id}`));
+  }
+  async remember(txn) {
+    await this.#store.set(`${this.#ns}:ref:${txn.reference}`, txn);
+    await this.#store.set(`${this.#ns}:pid:${txn.id}`, txn);
+  }
+};
+
+// src/client.ts
+var MomorailClient = class {
+  #providers;
+  #defaultProvider;
+  #retry;
+  #failover;
+  #onRetry;
+  #onFailover;
+  constructor(options) {
+    const [first] = options.providers;
+    if (!first) {
+      throw new ValidationError("MomorailClient requires at least one provider");
+    }
+    this.#providers = /* @__PURE__ */ new Map();
+    for (const provider of options.providers) {
+      if (this.#providers.has(provider.id)) {
+        throw new ValidationError(`Duplicate provider id: ${provider.id}`);
+      }
+      this.#providers.set(provider.id, provider);
+    }
+    this.#defaultProvider = options.defaultProvider ?? first.id;
+    if (!this.#providers.has(this.#defaultProvider)) {
+      throw new ValidationError(`Unknown defaultProvider: ${this.#defaultProvider}`);
+    }
+    this.#retry = { ...DEFAULT_RETRY_POLICY, ...options.retry };
+    this.#failover = options.failover ?? false;
+    this.#onRetry = options.onRetry;
+    this.#onFailover = options.onFailover;
+  }
+  get providerIds() {
+    return [...this.#providers.keys()];
+  }
+  /** Resolve a configured adapter by id, or the default when `id` is omitted. */
+  provider(id) {
+    const key = id ?? this.#defaultProvider;
+    const provider = this.#providers.get(key);
+    if (!provider) throw new ValidationError(`Unknown provider: ${key}`);
+    return provider;
+  }
+  /** Id of the adapter a call for `operator` would be routed to, if any. */
+  route(operator) {
+    return this.#candidatesFor(operator)[0]?.id;
+  }
+  /** `operator -> [adapter ids that advertise it]`, default-first. */
+  coverage() {
+    const out = {};
+    for (const provider of this.#providers.values()) {
+      for (const op of provider.capabilities().operators) {
+        const list = out[op] ?? [];
+        list.push(provider.id);
+        out[op] = list;
+      }
+    }
+    return out;
+  }
+  async collection(input, options = {}) {
+    assertReference(input.reference);
+    assertAmount(input.amount);
+    const candidates = this.#candidatesFor(input.customer.operator, options.provider);
+    const failover = options.failover ?? this.#failover;
+    return this.#runAcross(
+      candidates,
+      failover,
+      options,
+      (p, signal) => p.collection(input, { signal })
+    );
+  }
+  async disbursement(input, options = {}) {
+    assertReference(input.reference);
+    assertAmount(input.amount);
+    const provider = this.#candidatesFor(
+      input.recipient.operator,
+      options.provider
+    )[0];
+    return this.#callProvider(provider, options, (p, signal) => p.disbursement(input, { signal }));
+  }
+  async getTransaction(ref, options = {}) {
+    if (!ref.id && !ref.reference) {
+      throw new ValidationError("getTransaction requires an id or a reference");
+    }
+    return this.#callProvider(
+      this.provider(options.provider),
+      options,
+      (p, signal) => p.getTransaction(ref, { signal })
+    );
+  }
+  async parseWebhook(providerId, raw) {
+    return this.provider(providerId).parseWebhook(raw);
+  }
+  /**
+   * Re-fetch every non-terminal transaction and return the refreshed list,
+   * preserving order. Terminal transactions are passed through untouched.
+   */
+  reconcile(transactions, options = {}) {
+    return Promise.all(
+      transactions.map(
+        (txn) => isTerminal(txn.status) ? Promise.resolve(txn) : this.getTransaction(
+          { id: txn.id, reference: txn.reference },
+          { ...options, provider: txn.provider }
+        )
+      )
+    );
+  }
+  /** Ordered adapters for a call: explicit id wins; else operator match (default first); else default. */
+  #candidatesFor(operator, explicit) {
+    if (explicit) return [this.provider(explicit)];
+    const all = [...this.#providers.values()];
+    if (!operator) return [this.provider()];
+    const matching = all.filter((p) => p.capabilities().operators.includes(operator));
+    if (matching.length === 0) return [this.provider()];
+    const def = this.#providers.get(this.#defaultProvider);
+    return def && matching.includes(def) ? [def, ...matching.filter((p) => p !== def)] : matching;
+  }
+  #callProvider(provider, options, run) {
+    const policy = { ...this.#retry, ...options.retry };
+    return runWithRetry((_attempt) => run(provider, options.signal), {
+      policy,
+      signal: options.signal,
+      onRetry: (info) => this.#onRetry?.({ provider: provider.id, ...info })
+    });
+  }
+  async #runAcross(candidates, failover, options, run) {
+    const list = failover ? candidates : candidates.slice(0, 1);
+    let lastError;
+    for (let i = 0; i < list.length; i++) {
+      const provider = list[i];
+      try {
+        return await this.#callProvider(provider, options, run);
+      } catch (err) {
+        lastError = err;
+        const next = list[i + 1];
+        if (!(err instanceof ProviderUnavailableError) || !next) throw err;
+        this.#onFailover?.({ from: provider.id, to: next.id, error: err });
+      }
+    }
+    throw lastError;
+  }
+};
+function assertReference(reference) {
+  if (typeof reference !== "string" || reference.trim().length === 0) {
+    throw new ValidationError("reference must be a non-empty string");
+  }
+  if (reference.length > 128) {
+    throw new ValidationError("reference must be at most 128 characters");
+  }
+}
+function assertAmount(amount) {
+  if (!Number.isFinite(amount.amount) || amount.amount <= 0) {
+    throw new ValidationError("amount.amount must be a positive number");
+  }
+  if (!Number.isInteger(amount.amount)) {
+    throw new ValidationError("amount.amount must be an integer");
+  }
+}
+export {
+  AuthError,
+  CURRENCIES,
+  DEFAULT_RETRY_POLICY,
+  IdempotencyCache,
+  MemoryIdempotencyStore,
+  MomorailClient,
+  MomorailError,
+  OPERATORS,
+  ProviderUnavailableError,
+  RateLimitError,
+  TERMINAL_STATUSES,
+  TransactionNotFoundError,
+  ValidationError,
+  WebhookVerificationError,
+  ZERO_DECIMAL_CURRENCIES,
+  isOperator,
+  isTerminal,
+  runWithRetry,
+  webhookEventTypeForStatus
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/operators.ts","../src/types.ts","../src/errors.ts","../src/retry.ts","../src/idempotency.ts","../src/client.ts"],"sourcesContent":["/**\n * Mobile money operators, each scoped by its ISO 3166-1 alpha-2 country code so\n * that the same brand in two countries (e.g. Orange in Mali vs Senegal) stays\n * distinct. Adapters advertise the subset they support via {@link ProviderCapabilities}.\n */\nexport const OPERATORS = [\n  'orange_ml',\n  'moov_ml',\n  'wave_ml',\n  'orange_ci',\n  'mtn_ci',\n  'moov_ci',\n  'wave_ci',\n  'orange_sn',\n  'free_sn',\n  'wave_sn',\n  'expresso_sn',\n  'orange_bf',\n  'moov_bf',\n  'mtn_bj',\n  'moov_bj',\n  'orange_ne',\n  'moov_ne',\n  'airtel_ne',\n  'moov_tg',\n  'togocom_tg',\n  'orange_cd',\n  'airtel_cd',\n  'vodacom_cd',\n] as const;\n\nexport type Operator = (typeof OPERATORS)[number];\n\nexport function isOperator(value: string): value is Operator {\n  return (OPERATORS as readonly string[]).includes(value);\n}\n\nexport const CURRENCIES = ['XOF', 'XAF', 'GHS', 'NGN'] as const;\n\nexport type Currency = (typeof CURRENCIES)[number];\n\n/**\n * Currencies with no minor unit. Amounts are always integers in Momorail, but for\n * these the integer is a whole franc rather than a hundredth. Adapters use this\n * to format amounts for providers that still expect a decimal string.\n */\nexport const ZERO_DECIMAL_CURRENCIES: ReadonlySet<Currency> = new Set(['XOF', 'XAF']);\n","import type { Currency, Operator } from './operators.js';\n\nexport interface Money {\n  /**\n   * Amount as an integer. For zero-decimal currencies (XOF, XAF) this is a whole\n   * unit; for the others it is the minor unit (e.g. pesewa, kobo).\n   */\n  amount: number;\n  currency: Currency;\n}\n\nexport type TransactionType = 'collection' | 'disbursement';\n\nexport type TransactionStatus =\n  | 'pending'\n  | 'processing'\n  | 'succeeded'\n  | 'failed'\n  | 'cancelled'\n  | 'expired'\n  | 'unknown';\n\n/** Statuses that never change again once reached. */\nexport const TERMINAL_STATUSES: ReadonlySet<TransactionStatus> = new Set<TransactionStatus>([\n  'succeeded',\n  'failed',\n  'cancelled',\n  'expired',\n]);\n\nexport function isTerminal(status: TransactionStatus): boolean {\n  return TERMINAL_STATUSES.has(status);\n}\n\nexport type FailureReason =\n  | 'insufficient_funds'\n  | 'invalid_number'\n  | 'user_declined'\n  | 'timeout'\n  | 'provider_error'\n  | 'limit_exceeded'\n  | 'duplicate_reference'\n  | 'other';\n\nexport interface Party {\n  /** E.164 phone number, e.g. \"+22370000000\". */\n  phone: string;\n  operator?: Operator;\n  firstName?: string;\n  lastName?: string;\n  email?: string;\n}\n\nexport interface CollectionInput {\n  amount: Money;\n  customer: Party;\n  /** Caller-supplied unique reference. Doubles as the idempotency key. */\n  reference: string;\n  description?: string;\n  /** Server-to-server webhook URL the provider should call with status updates. */\n  callbackUrl?: string;\n  /** Browser redirect target after a hosted-checkout flow succeeds. */\n  returnUrl?: string;\n  /** Browser redirect target after a hosted-checkout flow is cancelled. */\n  cancelUrl?: string;\n  metadata?: Record<string, string>;\n}\n\nexport interface DisbursementInput {\n  amount: Money;\n  recipient: Party;\n  /** Caller-supplied unique reference. Doubles as the idempotency key. */\n  reference: string;\n  description?: string;\n  callbackUrl?: string;\n  metadata?: Record<string, string>;\n}\n\nexport interface TransactionRef {\n  /** Provider-side id, when known. */\n  id?: string;\n  /** Caller-supplied reference. */\n  reference?: string;\n}\n\nexport interface Transaction {\n  provider: string;\n  /** Provider-side id. */\n  id: string;\n  /** Caller-supplied reference echoed back. */\n  reference: string;\n  type: TransactionType;\n  status: TransactionStatus;\n  amount: Money;\n  fees?: Money;\n  operator?: Operator;\n  customer?: Party;\n  /** Set when the flow needs the customer redirected to a hosted page. */\n  checkoutUrl?: string;\n  /** Set only for a `failed` transaction. */\n  failureReason?: FailureReason;\n  /** Raw, unmodified provider payload. Always populated so callers never get stuck. */\n  providerRaw: unknown;\n  /** ISO 8601 timestamp. */\n  createdAt: string;\n  /** ISO 8601 timestamp. */\n  updatedAt: string;\n}\n\nexport interface ProviderCapabilities {\n  collection: boolean;\n  disbursement: boolean;\n  /** Status can be queried by caller reference, not only by provider id. */\n  lookupByReference: boolean;\n  /** Collection requires redirecting the customer to a hosted checkout page. */\n  hostedCheckout: boolean;\n  operators: readonly Operator[];\n  currencies: readonly Currency[];\n}\n\nexport interface RawWebhook {\n  headers: Record<string, string | string[] | undefined>;\n  /** Raw request body as received; keep it a string when a signature covers it. */\n  body: string | Uint8Array | Record<string, unknown>;\n  /** Full request URL or path+query, when the provider signs it. */\n  url?: string;\n}\n\nexport type WebhookEventType =\n  | 'transaction.succeeded'\n  | 'transaction.failed'\n  | 'transaction.pending'\n  | 'transaction.cancelled'\n  | 'transaction.expired'\n  | 'unknown';\n\nexport interface WebhookEvent {\n  type: WebhookEventType;\n  transaction: Transaction;\n  providerRaw: unknown;\n}\n\n/** Map a normalised {@link TransactionStatus} onto the webhook event type adapters emit. */\nexport function webhookEventTypeForStatus(status: TransactionStatus): WebhookEventType {\n  switch (status) {\n    case 'succeeded':\n      return 'transaction.succeeded';\n    case 'failed':\n      return 'transaction.failed';\n    case 'cancelled':\n      return 'transaction.cancelled';\n    case 'expired':\n      return 'transaction.expired';\n    case 'pending':\n    case 'processing':\n      return 'transaction.pending';\n    default:\n      return 'unknown';\n  }\n}\n\nexport interface RetryPolicy {\n  /** Number of retries after the first attempt. */\n  retries: number;\n  /** Base delay in ms; grows exponentially with full jitter. */\n  baseDelayMs: number;\n  /** Upper bound on a single delay in ms. */\n  maxDelayMs: number;\n}\n\nexport interface RequestOptions {\n  /** Route this call to a specific configured provider by id (skips operator routing). */\n  provider?: string;\n  /** Abort signal forwarded to the underlying transport and retry waits. */\n  signal?: AbortSignal;\n  /** Per-call override of the client retry policy. */\n  retry?: Partial<RetryPolicy>;\n  /** Per-call override of the client `failover` setting (`collection` only). */\n  failover?: boolean;\n}\n","export interface MomorailErrorOptions {\n  /** Id of the adapter that produced the error, when known. */\n  provider?: string;\n  /** Whether a retry with the same input could plausibly succeed. */\n  retryable?: boolean;\n  /** Raw provider payload that triggered the error. */\n  providerRaw?: unknown;\n  cause?: unknown;\n}\n\n/** Base class for every error Momorail throws. Adapters map provider errors onto a subclass. */\nexport class MomorailError extends Error {\n  readonly provider: string | undefined;\n  readonly code: string;\n  readonly retryable: boolean;\n  readonly providerRaw: unknown;\n\n  constructor(message: string, code: string, options: MomorailErrorOptions = {}) {\n    super(message, options.cause !== undefined ? { cause: options.cause } : undefined);\n    this.name = new.target.name;\n    this.code = code;\n    this.provider = options.provider;\n    this.retryable = options.retryable ?? false;\n    this.providerRaw = options.providerRaw;\n  }\n}\n\n/** Credentials were rejected by the provider. */\nexport class AuthError extends MomorailError {\n  constructor(\n    message = 'Authentication with the provider failed',\n    options: MomorailErrorOptions = {},\n  ) {\n    super(message, 'auth_error', { retryable: false, ...options });\n  }\n}\n\n/** The request was malformed before it ever reached the provider. */\nexport class ValidationError extends MomorailError {\n  constructor(message: string, options: MomorailErrorOptions = {}) {\n    super(message, 'validation_error', { retryable: false, ...options });\n  }\n}\n\n/** The provider is reachable but temporarily refusing work; safe to retry. */\nexport class ProviderUnavailableError extends MomorailError {\n  constructor(\n    message = 'The provider is temporarily unavailable',\n    options: MomorailErrorOptions = {},\n  ) {\n    super(message, 'provider_unavailable', { retryable: true, ...options });\n  }\n}\n\n/** The provider throttled the request. Carries a hint of how long to wait. */\nexport class RateLimitError extends MomorailError {\n  readonly retryAfterMs: number | undefined;\n\n  constructor(\n    message = 'Rate limit exceeded',\n    options: MomorailErrorOptions & { retryAfterMs?: number } = {},\n  ) {\n    super(message, 'rate_limit', { retryable: true, ...options });\n    this.retryAfterMs = options.retryAfterMs;\n  }\n}\n\n/** No transaction matched the given id or reference. */\nexport class TransactionNotFoundError extends MomorailError {\n  constructor(message = 'Transaction not found', options: MomorailErrorOptions = {}) {\n    super(message, 'transaction_not_found', { retryable: false, ...options });\n  }\n}\n\n/** A webhook payload failed signature verification and must not be trusted. */\nexport class WebhookVerificationError extends MomorailError {\n  constructor(\n    message = 'Webhook signature verification failed',\n    options: MomorailErrorOptions = {},\n  ) {\n    super(message, 'webhook_verification', { retryable: false, ...options });\n  }\n}\n","import { MomorailError } from './errors.js';\nimport type { RetryPolicy } from './types.js';\n\nexport const DEFAULT_RETRY_POLICY: RetryPolicy = {\n  retries: 2,\n  baseDelayMs: 200,\n  maxDelayMs: 2_000,\n};\n\nfunction isRetryable(error: unknown): boolean {\n  return error instanceof MomorailError && error.retryable;\n}\n\n/** Exponential backoff capped at maxDelayMs, then full jitter in [0, cap]. */\nfunction jitteredDelay(attempt: number, policy: RetryPolicy): number {\n  const cap = Math.min(policy.maxDelayMs, policy.baseDelayMs * 2 ** attempt);\n  return Math.random() * cap;\n}\n\nfunction sleep(ms: number, signal?: AbortSignal): Promise<void> {\n  return new Promise((resolve, reject) => {\n    if (signal?.aborted) {\n      reject(signal.reason ?? new Error('Aborted'));\n      return;\n    }\n    const onAbort = () => {\n      clearTimeout(timer);\n      reject(signal?.reason ?? new Error('Aborted'));\n    };\n    const timer = setTimeout(() => {\n      signal?.removeEventListener('abort', onAbort);\n      resolve();\n    }, ms);\n    signal?.addEventListener('abort', onAbort, { once: true });\n  });\n}\n\nexport interface RetryContext {\n  policy: RetryPolicy;\n  signal?: AbortSignal;\n  onRetry?: (info: { attempt: number; delayMs: number; error: unknown }) => void;\n}\n\n/**\n * Run `fn`, retrying only while it throws a {@link MomorailError} whose `retryable`\n * flag is set. `attempt` is zero-based. A provider-supplied `retryAfterMs`\n * (e.g. on {@link RateLimitError}) lengthens the wait but never shortens it.\n */\nexport async function runWithRetry<T>(\n  fn: (attempt: number) => Promise<T>,\n  ctx: RetryContext,\n): Promise<T> {\n  const { policy, signal } = ctx;\n  let lastError: unknown;\n\n  for (let attempt = 0; attempt <= policy.retries; attempt++) {\n    try {\n      return await fn(attempt);\n    } catch (error) {\n      lastError = error;\n      if (attempt === policy.retries || !isRetryable(error)) throw error;\n\n      let delayMs = jitteredDelay(attempt, policy);\n      const retryAfter = (error as { retryAfterMs?: unknown }).retryAfterMs;\n      if (typeof retryAfter === 'number' && retryAfter > delayMs) delayMs = retryAfter;\n\n      ctx.onRetry?.({ attempt, delayMs, error });\n      await sleep(delayMs, signal);\n    }\n  }\n\n  throw lastError;\n}\n","import type { Transaction } from './types.js';\n\n/**\n * Where an adapter remembers the transactions it has created, so a retried\n * `collection` / `disbursement` with the same `reference` returns the same\n * `Transaction` rather than starting a second one, and so a sparse\n * `getTransaction` / webhook payload can be enriched with what the adapter\n * already knows.\n *\n * The default is {@link MemoryIdempotencyStore} (per process). Pass a shared\n * implementation (Redis, a database) for idempotency that survives restarts and\n * spans instances. Keys are opaque strings; values are plain JSON-serialisable\n * `Transaction` objects.\n */\nexport interface IdempotencyStore {\n  get(key: string): Transaction | undefined | Promise<Transaction | undefined>;\n  set(key: string, value: Transaction): void | Promise<void>;\n}\n\n/** In-memory {@link IdempotencyStore} with a bounded, FIFO-evicting map. */\nexport class MemoryIdempotencyStore implements IdempotencyStore {\n  readonly #max: number;\n  readonly #map = new Map<string, Transaction>();\n\n  constructor(options: { maxEntries?: number } = {}) {\n    this.#max = options.maxEntries ?? 5_000;\n  }\n\n  get(key: string): Transaction | undefined {\n    return this.#map.get(key);\n  }\n\n  set(key: string, value: Transaction): void {\n    if (this.#map.size >= this.#max && !this.#map.has(key)) {\n      const oldest = this.#map.keys().next().value;\n      if (oldest !== undefined) this.#map.delete(oldest);\n    }\n    this.#map.set(key, value);\n  }\n}\n\n/**\n * A namespaced view over an {@link IdempotencyStore} that an adapter uses to\n * store and recall a `Transaction` by either the caller `reference` or the\n * provider-side `id`. The namespace (the adapter id) keeps entries from\n * different adapters apart when they share one backing store.\n */\nexport class IdempotencyCache {\n  readonly #store: IdempotencyStore;\n  readonly #ns: string;\n\n  constructor(store: IdempotencyStore, namespace: string) {\n    this.#store = store;\n    this.#ns = namespace;\n  }\n\n  byReference(reference: string): Promise<Transaction | undefined> {\n    return Promise.resolve(this.#store.get(`${this.#ns}:ref:${reference}`));\n  }\n\n  byId(id: string): Promise<Transaction | undefined> {\n    return Promise.resolve(this.#store.get(`${this.#ns}:pid:${id}`));\n  }\n\n  async remember(txn: Transaction): Promise<void> {\n    await this.#store.set(`${this.#ns}:ref:${txn.reference}`, txn);\n    await this.#store.set(`${this.#ns}:pid:${txn.id}`, txn);\n  }\n}\n","import { ProviderUnavailableError, ValidationError } from './errors.js';\nimport type { Operator } from './operators.js';\nimport type { PaymentProvider } from './provider.js';\nimport { DEFAULT_RETRY_POLICY, runWithRetry } from './retry.js';\nimport {\n  type CollectionInput,\n  type DisbursementInput,\n  type Money,\n  type RawWebhook,\n  type RequestOptions,\n  type RetryPolicy,\n  type Transaction,\n  type TransactionRef,\n  type WebhookEvent,\n  isTerminal,\n} from './types.js';\n\nexport interface MomorailClientOptions {\n  /** One or more configured adapters. Must contain at least one, with unique ids. */\n  providers: PaymentProvider[];\n  /** Id used when a call doesn't name a provider and no adapter matches the operator. Defaults to the first entry. */\n  defaultProvider?: string;\n  /** Overrides merged onto {@link DEFAULT_RETRY_POLICY}. */\n  retry?: Partial<RetryPolicy>;\n  /**\n   * When true, `collection` retries the *next* adapter covering the same\n   * operator if the chosen one raises {@link ProviderUnavailableError} (nothing\n   * was created, so it is safe to move on). Off by default. Never applies to\n   * `disbursement`. Can be overridden per call with `options.failover`.\n   */\n  failover?: boolean;\n  onRetry?: (info: {\n    provider: string;\n    attempt: number;\n    delayMs: number;\n    error: unknown;\n  }) => void;\n  onFailover?: (info: { from: string; to: string; error: unknown }) => void;\n}\n\n/**\n * Fans a single unified surface out to one of several {@link PaymentProvider}\n * adapters. Validates input, routes by provider id, and applies the retry policy\n * so adapters stay small.\n */\nexport class MomorailClient {\n  readonly #providers: Map<string, PaymentProvider>;\n  readonly #defaultProvider: string;\n  readonly #retry: RetryPolicy;\n  readonly #failover: boolean;\n  readonly #onRetry: MomorailClientOptions['onRetry'];\n  readonly #onFailover: MomorailClientOptions['onFailover'];\n\n  constructor(options: MomorailClientOptions) {\n    const [first] = options.providers;\n    if (!first) {\n      throw new ValidationError('MomorailClient requires at least one provider');\n    }\n\n    this.#providers = new Map();\n    for (const provider of options.providers) {\n      if (this.#providers.has(provider.id)) {\n        throw new ValidationError(`Duplicate provider id: ${provider.id}`);\n      }\n      this.#providers.set(provider.id, provider);\n    }\n\n    this.#defaultProvider = options.defaultProvider ?? first.id;\n    if (!this.#providers.has(this.#defaultProvider)) {\n      throw new ValidationError(`Unknown defaultProvider: ${this.#defaultProvider}`);\n    }\n\n    this.#retry = { ...DEFAULT_RETRY_POLICY, ...options.retry };\n    this.#failover = options.failover ?? false;\n    this.#onRetry = options.onRetry;\n    this.#onFailover = options.onFailover;\n  }\n\n  get providerIds(): string[] {\n    return [...this.#providers.keys()];\n  }\n\n  /** Resolve a configured adapter by id, or the default when `id` is omitted. */\n  provider(id?: string): PaymentProvider {\n    const key = id ?? this.#defaultProvider;\n    const provider = this.#providers.get(key);\n    if (!provider) throw new ValidationError(`Unknown provider: ${key}`);\n    return provider;\n  }\n\n  /** Id of the adapter a call for `operator` would be routed to, if any. */\n  route(operator: Operator): string | undefined {\n    return this.#candidatesFor(operator)[0]?.id;\n  }\n\n  /** `operator -> [adapter ids that advertise it]`, default-first. */\n  coverage(): Record<string, string[]> {\n    const out: Record<string, string[]> = {};\n    for (const provider of this.#providers.values()) {\n      for (const op of provider.capabilities().operators) {\n        const list = out[op] ?? [];\n        list.push(provider.id);\n        out[op] = list;\n      }\n    }\n    return out;\n  }\n\n  async collection(input: CollectionInput, options: RequestOptions = {}): Promise<Transaction> {\n    assertReference(input.reference);\n    assertAmount(input.amount);\n    const candidates = this.#candidatesFor(input.customer.operator, options.provider);\n    const failover = options.failover ?? this.#failover;\n    return this.#runAcross(candidates, failover, options, (p, signal) =>\n      p.collection(input, { signal }),\n    );\n  }\n\n  async disbursement(input: DisbursementInput, options: RequestOptions = {}): Promise<Transaction> {\n    assertReference(input.reference);\n    assertAmount(input.amount);\n    // Route by operator, but never fail a payout over to another rail.\n    // #candidatesFor always returns a non-empty list.\n    const provider = this.#candidatesFor(\n      input.recipient.operator,\n      options.provider,\n    )[0] as PaymentProvider;\n    return this.#callProvider(provider, options, (p, signal) => p.disbursement(input, { signal }));\n  }\n\n  async getTransaction(ref: TransactionRef, options: RequestOptions = {}): Promise<Transaction> {\n    if (!ref.id && !ref.reference) {\n      throw new ValidationError('getTransaction requires an id or a reference');\n    }\n    return this.#callProvider(this.provider(options.provider), options, (p, signal) =>\n      p.getTransaction(ref, { signal }),\n    );\n  }\n\n  async parseWebhook(providerId: string, raw: RawWebhook): Promise<WebhookEvent> {\n    return this.provider(providerId).parseWebhook(raw);\n  }\n\n  /**\n   * Re-fetch every non-terminal transaction and return the refreshed list,\n   * preserving order. Terminal transactions are passed through untouched.\n   */\n  reconcile(\n    transactions: readonly Transaction[],\n    options: RequestOptions = {},\n  ): Promise<Transaction[]> {\n    return Promise.all(\n      transactions.map((txn) =>\n        isTerminal(txn.status)\n          ? Promise.resolve(txn)\n          : this.getTransaction(\n              { id: txn.id, reference: txn.reference },\n              { ...options, provider: txn.provider },\n            ),\n      ),\n    );\n  }\n\n  /** Ordered adapters for a call: explicit id wins; else operator match (default first); else default. */\n  #candidatesFor(operator: Operator | undefined, explicit?: string): PaymentProvider[] {\n    if (explicit) return [this.provider(explicit)];\n    const all = [...this.#providers.values()];\n    if (!operator) return [this.provider()];\n\n    const matching = all.filter((p) => p.capabilities().operators.includes(operator));\n    if (matching.length === 0) return [this.provider()];\n\n    const def = this.#providers.get(this.#defaultProvider);\n    return def && matching.includes(def) ? [def, ...matching.filter((p) => p !== def)] : matching;\n  }\n\n  #callProvider<T>(\n    provider: PaymentProvider,\n    options: RequestOptions,\n    run: (provider: PaymentProvider, signal?: AbortSignal) => Promise<T>,\n  ): Promise<T> {\n    const policy = { ...this.#retry, ...options.retry };\n    return runWithRetry((_attempt) => run(provider, options.signal), {\n      policy,\n      signal: options.signal,\n      onRetry: (info) => this.#onRetry?.({ provider: provider.id, ...info }),\n    });\n  }\n\n  async #runAcross<T>(\n    candidates: PaymentProvider[],\n    failover: boolean,\n    options: RequestOptions,\n    run: (provider: PaymentProvider, signal?: AbortSignal) => Promise<T>,\n  ): Promise<T> {\n    const list = failover ? candidates : candidates.slice(0, 1);\n    let lastError: unknown;\n    for (let i = 0; i < list.length; i++) {\n      const provider = list[i]!;\n      try {\n        return await this.#callProvider(provider, options, run);\n      } catch (err) {\n        lastError = err;\n        const next = list[i + 1];\n        if (!(err instanceof ProviderUnavailableError) || !next) throw err;\n        this.#onFailover?.({ from: provider.id, to: next.id, error: err });\n      }\n    }\n    throw lastError;\n  }\n}\n\nfunction assertReference(reference: string): void {\n  if (typeof reference !== 'string' || reference.trim().length === 0) {\n    throw new ValidationError('reference must be a non-empty string');\n  }\n  if (reference.length > 128) {\n    throw new ValidationError('reference must be at most 128 characters');\n  }\n}\n\nfunction assertAmount(amount: Money): void {\n  if (!Number.isFinite(amount.amount) || amount.amount <= 0) {\n    throw new ValidationError('amount.amount must be a positive number');\n  }\n  if (!Number.isInteger(amount.amount)) {\n    throw new ValidationError('amount.amount must be an integer');\n  }\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@momorail/core",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Unified domain model, client and error taxonomy for Momorail payment adapters",
+  "keywords": [
+    "mobile-money",
+    "payments",
+    "west-africa",
+    "africa",
+    "orange-money",
+    "mtn-momo",
+    "wave",
+    "xof",
+    "byo-keys",
+    "typescript",
+    "core"
+  ],
+  "license": "MIT",
+  "author": "Boukymen <boukymen@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Boukymen/momorail.git",
+    "directory": "packages/core"
+  },
+  "homepage": "https://github.com/Boukymen/momorail/tree/main/packages/core#readme",
+  "bugs": "https://github.com/Boukymen/momorail/issues",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}