@sakeetech/viva-payments-core 0.2.1

package/dist/auth/single-flight.js

@@ -0,0 +1,160 @@
+/**
+ * Single-flight primitives for token refresh.
+ *
+ * `AsyncMutex` serializes concurrent in-process callers on a single key.
+ * `singleFlight()` ensures that when N callers race, only one fn() executes
+ * and all N receive the same resolved value.
+ *
+ * For multi-worker deployments a Redis-based lock must be injected via
+ * `RedisLockClient`. The interface is declared here; no Redis runtime dep
+ * is included in this package — the SaaS layer provides the concrete impl.
+ *
+ * Plan ref (A1): forceRefresh on 401 recovery MUST go through the same
+ * single-flight to prevent token stampede during secret rotation.
+ */
+/**
+ * A no-op sentinel implementation that throws if actually invoked.
+ * Satisfies the type when Redis is not configured; safe to pass as default
+ * so callers don't need to guard for undefined.
+ */
+export const noopRedisLock = {
+    acquire() {
+        throw new Error('RedisLockClient not configured. Provide a concrete implementation.');
+    },
+    release() {
+        throw new Error('RedisLockClient not configured. Provide a concrete implementation.');
+    },
+    pollCacheUntil() {
+        throw new Error('RedisLockClient not configured. Provide a concrete implementation.');
+    },
+};
+// ---------------------------------------------------------------------------
+// In-process async mutex
+// ---------------------------------------------------------------------------
+/**
+ * A simple in-process serialising mutex.
+ *
+ * `acquire()` returns a release function. Callers MUST call the release
+ * function in a `finally` block to avoid deadlocks.
+ *
+ * Internally, each acquire appends a promise to a chain. When the current
+ * holder calls release it resolves the next waiter.
+ */
+export class AsyncMutex {
+    _tail = Promise.resolve();
+    /**
+     * Acquires the mutex. Resolves when this caller holds the lock.
+     * Returns a `release` function that MUST be called in `finally`.
+     */
+    acquire() {
+        // Capture the current tail before appending so this waiter chains after it.
+        const prevTail = this._tail;
+        let resolve;
+        // Our slot in the queue: resolves when we call release.
+        const ourTurn = new Promise((res) => {
+            resolve = res;
+        });
+        // The new tail that subsequent acquirers will wait on.
+        this._tail = ourTurn;
+        // We expose a promise that resolves with the release function once it
+        // is our turn to hold the lock.
+        return prevTail.then(() => resolve);
+    }
+}
+/**
+ * Per-key in-flight promises. When a call is in progress, all concurrent
+ * callers with the same key share this promise instead of calling fn() again.
+ *
+ * The map is keyed by the singleFlight key. Entries are removed when the
+ * promise settles (whether resolved or rejected).
+ */
+const inFlight = new Map();
+/**
+ * Ensures that concurrent calls with the same `key` execute `fn` exactly once.
+ * All concurrent waiters share the same promise and receive the same result.
+ *
+ * Design: the in-flight map is checked and populated BEFORE acquiring the mutex.
+ * - If an entry exists: await it directly (no mutex needed, no fn() call).
+ * - If no entry: create the shared promise, store it, then acquire the mutex
+ *   for the re-check + fn() execution. Other concurrent callers that arrive
+ *   between "check" and "set" will see the entry in the map on their first
+ *   check and coalesce.
+ *
+ * When a `{ local: AsyncMutex }` is provided the mutex is used to serialise
+ * the actual fn() execution. The map handles the N-1 waiters.
+ *
+ * When a `{ redis: RedisLockClient }` is provided the first worker to acquire
+ * the Redis lock runs fn(). Other workers (including other processes) poll
+ * the cache via `pollCacheUntil` until the result is available.
+ *
+ * @see plan line 311 — Redis lock key pattern: `viva:isv:token:lock:{client_id}`
+ */
+export function singleFlight(key, fn, locks) {
+    if ('local' in locks) {
+        // ---- In-process path ----
+        // Fast path: if there is already an in-flight promise, piggy-back on it.
+        const existing = inFlight.get(key);
+        if (existing !== undefined) {
+            return existing;
+        }
+        // No in-flight entry yet. We create a new shared promise and register it
+        // SYNCHRONOUSLY before yielding, so any concurrent caller that arrives
+        // on the next tick (or even in the same microtask batch) will find it.
+        let resolveFlight;
+        let rejectFlight;
+        const shared = new Promise((res, rej) => {
+            resolveFlight = res;
+            rejectFlight = rej;
+        });
+        // Register before awaiting anything — this is the critical window.
+        inFlight.set(key, shared);
+        // Now do the actual work: acquire the mutex and run fn().
+        // We return the shared promise to our own caller as well.
+        void (async () => {
+            const release = await locks.local.acquire();
+            try {
+                // Re-check: another waiter may have refreshed while we waited on mutex.
+                // (This re-check is relevant when multiple singleFlight calls for the
+                // same key arrive before the first one has set inFlight — but since we
+                // now set inFlight synchronously that window is much narrower. Still
+                // call the re-check for correctness in the mutex-queue case.)
+                const result = await fn();
+                resolveFlight(result);
+            }
+            catch (err) {
+                rejectFlight(err);
+            }
+            finally {
+                inFlight.delete(key);
+                release();
+            }
+        })();
+        return shared;
+    }
+    else {
+        // ---- Redis path ----
+        const lockKey = `${key}:lock`;
+        return (async () => {
+            const lockResult = await locks.redis.acquire(lockKey, 30_000);
+            if (lockResult !== null) {
+                // This worker won the lock — run fn() and release.
+                try {
+                    return await fn();
+                }
+                finally {
+                    await locks.redis.release(lockKey, lockResult.token);
+                }
+            }
+            else {
+                // Another worker holds the lock — poll the cache until it writes the result.
+                const cached = await locks.redis.pollCacheUntil(async () => null, // caller provides a real getter at the strategy level
+                100, 10_000);
+                if (cached !== null)
+                    return cached;
+                // Fallback: run fn() ourselves if the poll timed out.
+                return fn();
+            }
+        })();
+    }
+}
+//# sourceMappingURL=single-flight.js.map

package/dist/auth/single-flight.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"single-flight.js","sourceRoot":"","sources":["../../src/auth/single-flight.ts"],"names":[],"mappings":"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"}

package/dist/auth/token-cache.d.ts

@@ -0,0 +1,50 @@
+/**
+ * TokenCache interface and built-in implementations.
+ *
+ * `InMemoryTokenCache` is the default for single-worker deployments.
+ * `RedisTokenCache` is declared as an interface; the SaaS layer provides
+ * the concrete implementation via dependency injection (plan P11, Q3).
+ */
+import type { CachedToken } from '../types/auth.js';
+export interface TokenCache {
+    get(key: string): Promise<CachedToken | null>;
+    set(key: string, value: CachedToken): Promise<void>;
+    delete(key: string): Promise<void>;
+}
+export declare class InMemoryTokenCache implements TokenCache {
+    private readonly _store;
+    /** Injectable clock; defaults to `Date.now`. Allows time-travel in tests. */
+    private readonly _now;
+    constructor(opts?: {
+        now?: () => number;
+    });
+    get(key: string): Promise<CachedToken | null>;
+    set(key: string, value: CachedToken): Promise<void>;
+    delete(key: string): Promise<void>;
+}
+/**
+ * Redis-backed token cache interface.
+ *
+ * The concrete implementation lives in the SaaS package. It is injected via
+ * `OAuth2ClientCredentialsStrategy.cache` option at construction time.
+ *
+ * Plan Q3: the interface is published from day one so future adapters
+ * (Memcached, ElastiCache) are additive, not structural changes.
+ */
+export interface RedisTokenCacheClient {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, ttlMs: number): Promise<void>;
+    delete(key: string): Promise<void>;
+}
+/**
+ * Thin wrapper that adapts a `RedisTokenCacheClient` to the `TokenCache`
+ * interface by JSON-serialising `CachedToken` values.
+ */
+export declare class RedisTokenCache implements TokenCache {
+    private readonly client;
+    constructor(client: RedisTokenCacheClient);
+    get(key: string): Promise<CachedToken | null>;
+    set(key: string, value: CachedToken): Promise<void>;
+    delete(key: string): Promise<void>;
+}
+//# sourceMappingURL=token-cache.d.ts.map

package/dist/auth/token-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-cache.d.ts","sourceRoot":"","sources":["../../src/auth/token-cache.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAMpD,MAAM,WAAW,UAAU;IACzB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IAC9C,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpD,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACpC;AAMD,qBAAa,kBAAmB,YAAW,UAAU;IACnD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkC;IAEzD,6EAA6E;IAC7E,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAe;gBAExB,IAAI,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;KAAE;IAInC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;IAW7C,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAInD,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAGzC;AAMD;;;;;;;;GAQG;AACH,MAAM,WAAW,qBAAqB;IACpC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACzC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9D,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACpC;AAED;;;GAGG;AACH,qBAAa,eAAgB,YAAW,UAAU;IACpC,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,qBAAqB;IAEpD,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;IAM7C,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAKnD,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAGzC"}

package/dist/auth/token-cache.js

@@ -0,0 +1,59 @@
+/**
+ * TokenCache interface and built-in implementations.
+ *
+ * `InMemoryTokenCache` is the default for single-worker deployments.
+ * `RedisTokenCache` is declared as an interface; the SaaS layer provides
+ * the concrete implementation via dependency injection (plan P11, Q3).
+ */
+// ---------------------------------------------------------------------------
+// In-memory implementation
+// ---------------------------------------------------------------------------
+export class InMemoryTokenCache {
+    _store = new Map();
+    /** Injectable clock; defaults to `Date.now`. Allows time-travel in tests. */
+    _now;
+    constructor(opts) {
+        this._now = opts?.now ?? (() => Date.now());
+    }
+    async get(key) {
+        const entry = this._store.get(key);
+        if (!entry)
+            return null;
+        // Treat as expired if the current time is at or past `expires_at`.
+        if (this._now() >= entry.expires_at) {
+            this._store.delete(key);
+            return null;
+        }
+        return entry;
+    }
+    async set(key, value) {
+        this._store.set(key, value);
+    }
+    async delete(key) {
+        this._store.delete(key);
+    }
+}
+/**
+ * Thin wrapper that adapts a `RedisTokenCacheClient` to the `TokenCache`
+ * interface by JSON-serialising `CachedToken` values.
+ */
+export class RedisTokenCache {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    async get(key) {
+        const raw = await this.client.get(key);
+        if (!raw)
+            return null;
+        return JSON.parse(raw);
+    }
+    async set(key, value) {
+        const ttlMs = Math.max(0, value.expires_at - Date.now());
+        await this.client.set(key, JSON.stringify(value), ttlMs);
+    }
+    async delete(key) {
+        await this.client.delete(key);
+    }
+}
+//# sourceMappingURL=token-cache.js.map

package/dist/auth/token-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-cache.js","sourceRoot":"","sources":["../../src/auth/token-cache.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAcH,8EAA8E;AAC9E,2BAA2B;AAC3B,8EAA8E;AAE9E,MAAM,OAAO,kBAAkB;IACZ,MAAM,GAAG,IAAI,GAAG,EAAuB,CAAC;IAEzD,6EAA6E;IAC5D,IAAI,CAAe;IAEpC,YAAY,IAA6B;QACvC,IAAI,CAAC,IAAI,GAAG,IAAI,EAAE,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;IAC9C,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,GAAW;QACnB,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACnC,IAAI,CAAC,KAAK;YAAE,OAAO,IAAI,CAAC;QACxB,mEAAmE;QACnE,IAAI,IAAI,CAAC,IAAI,EAAE,IAAI,KAAK,CAAC,UAAU,EAAE,CAAC;YACpC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACxB,OAAO,IAAI,CAAC;QACd,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,GAAW,EAAE,KAAkB;QACvC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IAC9B,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,GAAW;QACtB,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAC1B,CAAC;CACF;AAqBD;;;GAGG;AACH,MAAM,OAAO,eAAe;IACG;IAA7B,YAA6B,MAA6B;QAA7B,WAAM,GAAN,MAAM,CAAuB;IAAG,CAAC;IAE9D,KAAK,CAAC,GAAG,CAAC,GAAW;QACnB,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACvC,IAAI,CAAC,GAAG;YAAE,OAAO,IAAI,CAAC;QACtB,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAgB,CAAC;IACxC,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,GAAW,EAAE,KAAkB;QACvC,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;QACzD,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC,CAAC;IAC3D,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,GAAW;QACtB,MAAM,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAChC,CAAC;CACF"}

package/dist/errors/api-error.d.ts

@@ -0,0 +1,15 @@
+import { VivaError, type VivaErrorOptions } from './base.js';
+/**
+ * Thrown when the Viva API returns a 4xx or 5xx response on a non-auth call,
+ * or when a network-level error occurs.
+ *
+ * The `vivaCode` field carries Viva's error code from the response body when
+ * available. The `cause` field wraps the underlying network or fetch error.
+ *
+ * Maps to `MedusaError(Types.PAYMENT_AUTHORIZATION_ERROR)` in the adapter.
+ */
+export declare class VivaApiError extends VivaError {
+    readonly code: "VIVA_API_ERROR";
+    constructor(opts: VivaErrorOptions);
+}
+//# sourceMappingURL=api-error.d.ts.map

package/dist/errors/api-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-error.d.ts","sourceRoot":"","sources":["../../src/errors/api-error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,KAAK,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAE7D;;;;;;;;GAQG;AACH,qBAAa,YAAa,SAAQ,SAAS;IACzC,QAAQ,CAAC,IAAI,EAAG,gBAAgB,CAAU;gBAE9B,IAAI,EAAE,gBAAgB;CAInC"}

package/dist/errors/api-error.js

@@ -0,0 +1,18 @@
+import { VivaError } from './base.js';
+/**
+ * Thrown when the Viva API returns a 4xx or 5xx response on a non-auth call,
+ * or when a network-level error occurs.
+ *
+ * The `vivaCode` field carries Viva's error code from the response body when
+ * available. The `cause` field wraps the underlying network or fetch error.
+ *
+ * Maps to `MedusaError(Types.PAYMENT_AUTHORIZATION_ERROR)` in the adapter.
+ */
+export class VivaApiError extends VivaError {
+    code = 'VIVA_API_ERROR';
+    constructor(opts) {
+        super(opts);
+        this.name = 'VivaApiError';
+    }
+}
+//# sourceMappingURL=api-error.js.map

package/dist/errors/api-error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-error.js","sourceRoot":"","sources":["../../src/errors/api-error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAyB,MAAM,WAAW,CAAC;AAE7D;;;;;;;;GAQG;AACH,MAAM,OAAO,YAAa,SAAQ,SAAS;IAChC,IAAI,GAAG,gBAAyB,CAAC;IAE1C,YAAY,IAAsB;QAChC,KAAK,CAAC,IAAI,CAAC,CAAC;QACZ,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;IAC7B,CAAC;CACF"}

package/dist/errors/auth-error.d.ts

@@ -0,0 +1,14 @@
+import { VivaError, type VivaErrorOptions } from './base.js';
+/**
+ * Thrown when authentication with Viva fails.
+ *
+ * Causes: bad credentials, expired token, 401/403 from `/connect/token`,
+ * or a second 401 after a forced token refresh (likely rotated client_secret).
+ *
+ * Maps to `MedusaError(Types.UNAUTHORIZED)` in the Medusa adapter layer.
+ */
+export declare class VivaAuthError extends VivaError {
+    readonly code: "VIVA_AUTH_ERROR";
+    constructor(opts: VivaErrorOptions);
+}
+//# sourceMappingURL=auth-error.d.ts.map

package/dist/errors/auth-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-error.d.ts","sourceRoot":"","sources":["../../src/errors/auth-error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,KAAK,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAE7D;;;;;;;GAOG;AACH,qBAAa,aAAc,SAAQ,SAAS;IAC1C,QAAQ,CAAC,IAAI,EAAG,iBAAiB,CAAU;gBAE/B,IAAI,EAAE,gBAAgB;CAInC"}

package/dist/errors/auth-error.js

@@ -0,0 +1,17 @@
+import { VivaError } from './base.js';
+/**
+ * Thrown when authentication with Viva fails.
+ *
+ * Causes: bad credentials, expired token, 401/403 from `/connect/token`,
+ * or a second 401 after a forced token refresh (likely rotated client_secret).
+ *
+ * Maps to `MedusaError(Types.UNAUTHORIZED)` in the Medusa adapter layer.
+ */
+export class VivaAuthError extends VivaError {
+    code = 'VIVA_AUTH_ERROR';
+    constructor(opts) {
+        super(opts);
+        this.name = 'VivaAuthError';
+    }
+}
+//# sourceMappingURL=auth-error.js.map

package/dist/errors/auth-error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-error.js","sourceRoot":"","sources":["../../src/errors/auth-error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAyB,MAAM,WAAW,CAAC;AAE7D;;;;;;;GAOG;AACH,MAAM,OAAO,aAAc,SAAQ,SAAS;IACjC,IAAI,GAAG,iBAA0B,CAAC;IAE3C,YAAY,IAAsB;QAChC,KAAK,CAAC,IAAI,CAAC,CAAC;QACZ,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;IAC9B,CAAC;CACF"}

package/dist/errors/base.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Abstract base class for all Viva Wallet errors.
+ *
+ * Every error carries a plugin-stable `code`, optional Viva API error code,
+ * HTTP status, request correlation ID, and an ES2022-style `cause` chain.
+ *
+ * Subclasses implement `abstract readonly code: string` with a literal value.
+ */
+export interface VivaErrorOptions {
+    message: string;
+    vivaCode?: string | undefined;
+    httpStatus?: number | undefined;
+    requestId?: string | undefined;
+    /**
+     * Viva `x-viva-correlationid` response header value.
+     * Probe-verified 2026-04-25: present on every Viva API response.
+     * Example: "26-115-EDAA55BC". Use for end-to-end tracing + Viva support tickets.
+     */
+    vivaCorrelationId?: string | undefined;
+    /**
+     * Viva `x-viva-eventid` response header value.
+     * Probe-verified 2026-04-25: present on every Viva API response.
+     * Example: "0".
+     */
+    vivaEventId?: string | undefined;
+    cause?: unknown;
+}
+export declare abstract class VivaError extends Error {
+    /**
+     * Plugin-stable string identifier for the error type.
+     * Consumers use this for programmatic branching — never match on `message`.
+     */
+    abstract readonly code: string;
+    /** Viva's own error code extracted from the response body, if available. */
+    readonly vivaCode: string | undefined;
+    /** HTTP status from the Viva API response, if available. */
+    readonly httpStatus: number | undefined;
+    /**
+     * Viva `CorrelationId` response header, or a locally generated ID.
+     * Use this for cross-system correlation when filing support tickets.
+     */
+    readonly requestId: string | undefined;
+    /**
+     * Viva `x-viva-correlationid` response header value.
+     * Probe-verified 2026-04-25: present on every Viva API response.
+     * Example: "26-115-EDAA55BC". Use for end-to-end tracing + Viva support tickets.
+     */
+    readonly vivaCorrelationId: string | undefined;
+    /**
+     * Viva `x-viva-eventid` response header value.
+     * Probe-verified 2026-04-25: present on every Viva API response.
+     * Example: "0".
+     */
+    readonly vivaEventId: string | undefined;
+    /** Chained cause per ES2022 Error.cause semantics. */
+    readonly cause: unknown;
+    constructor({ message, vivaCode, httpStatus, requestId, vivaCorrelationId, vivaEventId, cause }: VivaErrorOptions);
+}
+//# sourceMappingURL=base.d.ts.map

package/dist/errors/base.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../src/errors/base.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACvC;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,8BAAsB,SAAU,SAAQ,KAAK;IAC3C;;;OAGG;IACH,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAE/B,4EAA4E;IAC5E,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;IAEtC,4DAA4D;IAC5D,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;IAExC;;;OAGG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IAEvC;;;;OAIG;IACH,QAAQ,CAAC,iBAAiB,EAAE,MAAM,GAAG,SAAS,CAAC;IAE/C;;;;OAIG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;IAEzC,sDAAsD;IACtD,SAAkB,KAAK,EAAE,OAAO,CAAC;gBAErB,EAAE,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,SAAS,EAAE,iBAAiB,EAAE,WAAW,EAAE,KAAK,EAAE,EAAE,gBAAgB;CAkBlH"}

package/dist/errors/base.js

@@ -0,0 +1,51 @@
+/**
+ * Abstract base class for all Viva Wallet errors.
+ *
+ * Every error carries a plugin-stable `code`, optional Viva API error code,
+ * HTTP status, request correlation ID, and an ES2022-style `cause` chain.
+ *
+ * Subclasses implement `abstract readonly code: string` with a literal value.
+ */
+export class VivaError extends Error {
+    /** Viva's own error code extracted from the response body, if available. */
+    vivaCode;
+    /** HTTP status from the Viva API response, if available. */
+    httpStatus;
+    /**
+     * Viva `CorrelationId` response header, or a locally generated ID.
+     * Use this for cross-system correlation when filing support tickets.
+     */
+    requestId;
+    /**
+     * Viva `x-viva-correlationid` response header value.
+     * Probe-verified 2026-04-25: present on every Viva API response.
+     * Example: "26-115-EDAA55BC". Use for end-to-end tracing + Viva support tickets.
+     */
+    vivaCorrelationId;
+    /**
+     * Viva `x-viva-eventid` response header value.
+     * Probe-verified 2026-04-25: present on every Viva API response.
+     * Example: "0".
+     */
+    vivaEventId;
+    /** Chained cause per ES2022 Error.cause semantics. */
+    cause;
+    constructor({ message, vivaCode, httpStatus, requestId, vivaCorrelationId, vivaEventId, cause }) {
+        super(message);
+        // Ensure the prototype chain is correct for `instanceof` checks when
+        // targeting ES5 or when transpiled.
+        Object.setPrototypeOf(this, new.target.prototype);
+        this.name = new.target.name;
+        this.vivaCode = vivaCode;
+        this.httpStatus = httpStatus;
+        this.requestId = requestId;
+        this.vivaCorrelationId = vivaCorrelationId;
+        this.vivaEventId = vivaEventId;
+        this.cause = cause;
+        // V8 / Node.js: remove the constructor frame from the stack trace.
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, new.target);
+        }
+    }
+}
+//# sourceMappingURL=base.js.map

package/dist/errors/base.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.js","sourceRoot":"","sources":["../../src/errors/base.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAuBH,MAAM,OAAgB,SAAU,SAAQ,KAAK;IAO3C,4EAA4E;IACnE,QAAQ,CAAqB;IAEtC,4DAA4D;IACnD,UAAU,CAAqB;IAExC;;;OAGG;IACM,SAAS,CAAqB;IAEvC;;;;OAIG;IACM,iBAAiB,CAAqB;IAE/C;;;;OAIG;IACM,WAAW,CAAqB;IAEzC,sDAAsD;IACpC,KAAK,CAAU;IAEjC,YAAY,EAAE,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,SAAS,EAAE,iBAAiB,EAAE,WAAW,EAAE,KAAK,EAAoB;QAC/G,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,qEAAqE;QACrE,oCAAoC;QACpC,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QAClD,IAAI,CAAC,IAAI,GAAG,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC;QAC5B,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,IAAI,CAAC,iBAAiB,GAAG,iBAAiB,CAAC;QAC3C,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;QAC/B,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QAEnB,mEAAmE;QACnE,IAAI,KAAK,CAAC,iBAAiB,EAAE,CAAC;YAC5B,KAAK,CAAC,iBAAiB,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;QAC5C,CAAC;IACH,CAAC;CACF"}

package/dist/errors/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * viva-payments-core/errors — barrel export.
+ *
+ * Subpath: `viva-payments-core/errors`
+ *
+ * All error classes extend `VivaError`. Callers can do:
+ *   import { VivaError, VivaAuthError, VivaRateLimitError } from 'viva-payments-core/errors';
+ */
+export { VivaError } from './base.js';
+export type { VivaErrorOptions } from './base.js';
+export { VivaAuthError } from './auth-error.js';
+export { VivaApiError } from './api-error.js';
+export { VivaValidationError } from './validation-error.js';
+export { VivaWebhookError } from './webhook-error.js';
+export { VivaRateLimitError } from './rate-limit-error.js';
+export type { VivaRateLimitErrorOptions } from './rate-limit-error.js';
+export { VivaModeMismatchError } from './mode-mismatch-error.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/errors/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/errors/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,YAAY,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAC3D,YAAY,EAAE,yBAAyB,EAAE,MAAM,uBAAuB,CAAC;AACvE,OAAO,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC"}

package/dist/errors/index.js

@@ -0,0 +1,16 @@
+/**
+ * viva-payments-core/errors — barrel export.
+ *
+ * Subpath: `viva-payments-core/errors`
+ *
+ * All error classes extend `VivaError`. Callers can do:
+ *   import { VivaError, VivaAuthError, VivaRateLimitError } from 'viva-payments-core/errors';
+ */
+export { VivaError } from './base.js';
+export { VivaAuthError } from './auth-error.js';
+export { VivaApiError } from './api-error.js';
+export { VivaValidationError } from './validation-error.js';
+export { VivaWebhookError } from './webhook-error.js';
+export { VivaRateLimitError } from './rate-limit-error.js';
+export { VivaModeMismatchError } from './mode-mismatch-error.js';
+//# sourceMappingURL=index.js.map

package/dist/errors/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/errors/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEtC,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAE3D,OAAO,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC"}

package/dist/errors/mode-mismatch-error.d.ts

@@ -0,0 +1,19 @@
+import { VivaError, type VivaErrorOptions } from './base.js';
+/**
+ * Thrown when a code path is invoked under the wrong plugin mode.
+ *
+ * Example: an ISV-only endpoint (e.g. POST /api/sources, the Connected
+ * Accounts webhook subscriber, the ISV tenant resolver) is invoked while
+ * `VivaPluginConfig.mode === 'merchant'`. Or, in a future merchant-only
+ * code path, while `mode === 'isv'`.
+ *
+ * Plan multi-mode-v0 §5 (config shape) + §10.1 (Vendure parallel).
+ * Migration 0.1→0.2 §2.2.
+ *
+ * Maps to `MedusaError(Types.NOT_ALLOWED)` in the adapter layer.
+ */
+export declare class VivaModeMismatchError extends VivaError {
+    readonly code: "VIVA_MODE_MISMATCH";
+    constructor(opts: VivaErrorOptions);
+}
+//# sourceMappingURL=mode-mismatch-error.d.ts.map

package/dist/errors/mode-mismatch-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mode-mismatch-error.d.ts","sourceRoot":"","sources":["../../src/errors/mode-mismatch-error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,KAAK,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAE7D;;;;;;;;;;;;GAYG;AACH,qBAAa,qBAAsB,SAAQ,SAAS;IAClD,QAAQ,CAAC,IAAI,EAAG,oBAAoB,CAAU;gBAElC,IAAI,EAAE,gBAAgB;CAInC"}

package/dist/errors/mode-mismatch-error.js

@@ -0,0 +1,22 @@
+import { VivaError } from './base.js';
+/**
+ * Thrown when a code path is invoked under the wrong plugin mode.
+ *
+ * Example: an ISV-only endpoint (e.g. POST /api/sources, the Connected
+ * Accounts webhook subscriber, the ISV tenant resolver) is invoked while
+ * `VivaPluginConfig.mode === 'merchant'`. Or, in a future merchant-only
+ * code path, while `mode === 'isv'`.
+ *
+ * Plan multi-mode-v0 §5 (config shape) + §10.1 (Vendure parallel).
+ * Migration 0.1→0.2 §2.2.
+ *
+ * Maps to `MedusaError(Types.NOT_ALLOWED)` in the adapter layer.
+ */
+export class VivaModeMismatchError extends VivaError {
+    code = 'VIVA_MODE_MISMATCH';
+    constructor(opts) {
+        super(opts);
+        this.name = 'VivaModeMismatchError';
+    }
+}
+//# sourceMappingURL=mode-mismatch-error.js.map

package/dist/errors/mode-mismatch-error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mode-mismatch-error.js","sourceRoot":"","sources":["../../src/errors/mode-mismatch-error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAyB,MAAM,WAAW,CAAC;AAE7D;;;;;;;;;;;;GAYG;AACH,MAAM,OAAO,qBAAsB,SAAQ,SAAS;IACzC,IAAI,GAAG,oBAA6B,CAAC;IAE9C,YAAY,IAAsB;QAChC,KAAK,CAAC,IAAI,CAAC,CAAC;QACZ,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;IACtC,CAAC;CACF"}

package/dist/errors/rate-limit-error.d.ts

@@ -0,0 +1,20 @@
+import { VivaError, type VivaErrorOptions } from './base.js';
+export interface VivaRateLimitErrorOptions extends VivaErrorOptions {
+    /** Milliseconds to wait before retrying, derived from `Retry-After` header. */
+    retryAfterMs?: number | undefined;
+}
+/**
+ * Thrown when Viva returns HTTP 429 (Too Many Requests) or a retriable 5xx.
+ *
+ * `retriable` is always `true`. The caller (or retry policy in S3) uses
+ * `retryAfterMs` when present; otherwise falls back to exponential backoff
+ * per plan Auth Flow line 319.
+ */
+export declare class VivaRateLimitError extends VivaError {
+    readonly code: "VIVA_RATE_LIMIT_ERROR";
+    readonly retriable: true;
+    /** Milliseconds to wait before retrying, from `Retry-After` header. */
+    readonly retryAfterMs: number | undefined;
+    constructor(opts: VivaRateLimitErrorOptions);
+}
+//# sourceMappingURL=rate-limit-error.d.ts.map

package/dist/errors/rate-limit-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limit-error.d.ts","sourceRoot":"","sources":["../../src/errors/rate-limit-error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,KAAK,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAE7D,MAAM,WAAW,yBAA0B,SAAQ,gBAAgB;IACjE,+EAA+E;IAC/E,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACnC;AAED;;;;;;GAMG;AACH,qBAAa,kBAAmB,SAAQ,SAAS;IAC/C,QAAQ,CAAC,IAAI,EAAG,uBAAuB,CAAU;IACjD,QAAQ,CAAC,SAAS,EAAG,IAAI,CAAU;IAEnC,uEAAuE;IACvE,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,SAAS,CAAC;gBAE9B,IAAI,EAAE,yBAAyB;CAK5C"}

package/dist/errors/rate-limit-error.js

@@ -0,0 +1,20 @@
+import { VivaError } from './base.js';
+/**
+ * Thrown when Viva returns HTTP 429 (Too Many Requests) or a retriable 5xx.
+ *
+ * `retriable` is always `true`. The caller (or retry policy in S3) uses
+ * `retryAfterMs` when present; otherwise falls back to exponential backoff
+ * per plan Auth Flow line 319.
+ */
+export class VivaRateLimitError extends VivaError {
+    code = 'VIVA_RATE_LIMIT_ERROR';
+    retriable = true;
+    /** Milliseconds to wait before retrying, from `Retry-After` header. */
+    retryAfterMs;
+    constructor(opts) {
+        super(opts);
+        this.name = 'VivaRateLimitError';
+        this.retryAfterMs = opts.retryAfterMs;
+    }
+}
+//# sourceMappingURL=rate-limit-error.js.map

package/dist/errors/rate-limit-error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limit-error.js","sourceRoot":"","sources":["../../src/errors/rate-limit-error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAyB,MAAM,WAAW,CAAC;AAO7D;;;;;;GAMG;AACH,MAAM,OAAO,kBAAmB,SAAQ,SAAS;IACtC,IAAI,GAAG,uBAAgC,CAAC;IACxC,SAAS,GAAG,IAAa,CAAC;IAEnC,uEAAuE;IAC9D,YAAY,CAAqB;IAE1C,YAAY,IAA+B;QACzC,KAAK,CAAC,IAAI,CAAC,CAAC;QACZ,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;QACjC,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC,YAAY,CAAC;IACxC,CAAC;CACF"}