@sakeetech/viva-payments-core 0.2.1

package/dist/auth/oauth2-strategy.d.ts

@@ -0,0 +1,117 @@
+/**
+ * OAuth 2.0 client_credentials strategy for Viva Wallet ISV API calls.
+ *
+ * Handles the full token lifecycle: obtain, cache, refresh, and single-flight
+ * de-duplication to prevent stampede under concurrent load.
+ *
+ * @see references/viva-docs/md/oauth2-authentication.txt:128 (token endpoint)
+ * @see references/viva-docs/md/oauth2-authentication.txt:145 (demo/prod URLs)
+ * @see references/viva-docs/md/oauth2-authentication.txt:167 (grant_type, Basic auth header)
+ * @see references/viva-docs/md/oauth2-authentication.txt:179 (token response shape, expires_in)
+ * @see references/viva-docs/md/oauth2-authentication.txt:192 (3600s expiry)
+ */
+import type { Dispatcher } from 'undici';
+import type { AuthStrategy } from '../types/auth.js';
+import type { VivaEnvironment } from '../types/common.js';
+import { AsyncMutex } from './single-flight.js';
+import type { RedisLockClient } from './single-flight.js';
+import type { TokenCache } from './token-cache.js';
+import type { MetricsHook, Logger } from '../observability/index.js';
+export interface OAuth2StrategyOptions {
+    /** Target environment — determines token endpoint host. */
+    environment: VivaEnvironment;
+    /** OAuth2 Client ID. @see references/viva-docs/md/oauth2-authentication.txt:119 */
+    clientId: string;
+    /** OAuth2 Client Secret. @see references/viva-docs/md/oauth2-authentication.txt:119 */
+    clientSecret: string;
+    /** Token cache implementation. Defaults to `InMemoryTokenCache`. */
+    cache?: TokenCache;
+    /** In-process mutex. Defaults to a fresh `AsyncMutex`. */
+    mutex?: AsyncMutex;
+    /**
+     * Redis lock client for multi-worker deployments (plan P11).
+     * When provided, single-flight uses Redis instead of the in-proc mutex.
+     */
+    redisLock?: RedisLockClient;
+    /**
+     * Milliseconds before expiry at which the token is proactively refreshed.
+     * Default: 5 * 60_000 = 300_000 ms (T-5min, per plan P11 line 73).
+     */
+    refreshSkewMs?: number;
+    /** Backoff between retries when used by the caller. Default: 500 ms. */
+    retryBackoffMs?: number;
+    /** Injectable fetch. Defaults to the global `fetch`. Tests pass MockAgent fetch. */
+    fetchImpl?: typeof fetch;
+    /** Dispatcher override. Tests inject a MockAgent here. */
+    dispatcher?: Dispatcher;
+    /** Injectable clock. Defaults to `Date.now`. */
+    now?: () => number;
+    /** Optional metrics hook. Records viva_auth_token_refresh_duration_seconds. */
+    metrics?: MetricsHook;
+    /** Optional logger. Emits structured info on each token refresh. */
+    logger?: Logger;
+}
+/**
+ * OAuth 2.0 `client_credentials` token strategy.
+ *
+ * Flow:
+ * 1. Check cache. If token is fresh (expires_at > now + refreshSkewMs), return it.
+ * 2. Acquire single-flight lock. Re-check cache (avoid duplicate fetch after waking).
+ * 3. POST `grant_type=client_credentials` to the token endpoint.
+ * 4. Cache result with `expires_at = now + (expires_in * 1000) - 60_000`.
+ *
+ * A1 property: `forceRefresh=true` (used by S3 on 401-recovery) ALSO acquires
+ * the single-flight lock, so even during concurrent secret rotation only one
+ * worker calls `/connect/token`. This is naturally satisfied because
+ * `getBearerToken` unconditionally enters `singleFlight` when the cache check
+ * is bypassed or fails.
+ */
+export declare class OAuth2ClientCredentialsStrategy implements AuthStrategy {
+    readonly name = "oauth2-client-credentials";
+    private readonly _env;
+    private readonly _clientId;
+    private readonly _clientSecret;
+    private readonly _cache;
+    private readonly _mutex;
+    private readonly _redisLock;
+    private readonly _refreshSkewMs;
+    private readonly _fetchImpl;
+    private readonly _dispatcher;
+    private readonly _now;
+    private readonly _metrics;
+    private readonly _logger;
+    constructor(opts: OAuth2StrategyOptions);
+    /** Exposes the token cache for auth-status inspection. */
+    get tokenCache(): TokenCache;
+    /** Cache key format: `viva:isv:token:{clientId}:{environment}` */
+    private get _cacheKey();
+    /**
+     * Returns a valid bearer token for use in `Authorization: Bearer <token>`.
+     *
+     * When `forceRefresh` is true the cache lookup is skipped but the request
+     * STILL goes through the single-flight lock — this is the A1 property:
+     * multiple workers calling `getBearerToken({ forceRefresh: true })` after
+     * receiving a 401 will not stampede the token endpoint.
+     * // A1: forceRefresh bypasses cache but not the lock — stampede prevention
+     * //     holds even during secret rotation. All concurrent 401-recovery calls
+     * //     will coalesce into one token fetch. (Plan amendment A1.)
+     */
+    getBearerToken(opts?: {
+        forceRefresh?: boolean;
+    }): Promise<string>;
+    /**
+     * Fetches a fresh token from the Viva identity server.
+     *
+     * Endpoint:
+     *   Demo:       https://demo-accounts.vivapayments.com/connect/token
+     *   Production: https://accounts.vivapayments.com/connect/token
+     *
+     * @see references/viva-docs/md/oauth2-authentication.txt:145 (endpoint URLs)
+     * @see references/viva-docs/md/oauth2-authentication.txt:167 (curl example: grant_type, Basic header)
+     * @see references/viva-docs/md/oauth2-authentication.txt:179 (response: access_token, expires_in)
+     * @see references/viva-docs/md/oauth2-authentication.txt:192 (3600s token lifetime)
+     */
+    private _fetchToken;
+    private _doFetchToken;
+}
+//# sourceMappingURL=oauth2-strategy.d.ts.map

package/dist/auth/oauth2-strategy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth2-strategy.d.ts","sourceRoot":"","sources":["../../src/auth/oauth2-strategy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AACzC,OAAO,KAAK,EAAE,YAAY,EAAuB,MAAM,kBAAkB,CAAC;AAC1E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAK1D,OAAO,EAAE,UAAU,EAAgB,MAAM,oBAAoB,CAAC;AAC9D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAE1D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,2BAA2B,CAAC;AAOrE,MAAM,WAAW,qBAAqB;IACpC,2DAA2D;IAC3D,WAAW,EAAE,eAAe,CAAC;IAC7B,mFAAmF;IACnF,QAAQ,EAAE,MAAM,CAAC;IACjB,uFAAuF;IACvF,YAAY,EAAE,MAAM,CAAC;IACrB,oEAAoE;IACpE,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB,0DAA0D;IAC1D,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB;;;OAGG;IACH,SAAS,CAAC,EAAE,eAAe,CAAC;IAC5B;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,wEAAwE;IACxE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,oFAAoF;IACpF,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,0DAA0D;IAC1D,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,gDAAgD;IAChD,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,+EAA+E;IAC/E,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB,oEAAoE;IACpE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAMD;;;;;;;;;;;;;;GAcG;AACH,qBAAa,+BAAgC,YAAW,YAAY;IAClE,QAAQ,CAAC,IAAI,+BAA+B;IAE5C,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAkB;IACvC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAa;IACpC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAa;IACpC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA8B;IACzD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAe;IAC1C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAyB;IACrD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAe;IACpC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAc;IACvC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqB;gBAEjC,IAAI,EAAE,qBAAqB;IAevC,0DAA0D;IAC1D,IAAI,UAAU,IAAI,UAAU,CAE3B;IAED,kEAAkE;IAClE,OAAO,KAAK,SAAS,GAEpB;IAED;;;;;;;;;;OAUG;IACG,cAAc,CAAC,IAAI,CAAC,EAAE;QAAE,YAAY,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,CAAC;IAqCxE;;;;;;;;;;;OAWG;YACW,WAAW;YAOX,aAAa;CAoG5B"}

package/dist/auth/oauth2-strategy.js

@@ -0,0 +1,217 @@
+/**
+ * OAuth 2.0 client_credentials strategy for Viva Wallet ISV API calls.
+ *
+ * Handles the full token lifecycle: obtain, cache, refresh, and single-flight
+ * de-duplication to prevent stampede under concurrent load.
+ *
+ * @see references/viva-docs/md/oauth2-authentication.txt:128 (token endpoint)
+ * @see references/viva-docs/md/oauth2-authentication.txt:145 (demo/prod URLs)
+ * @see references/viva-docs/md/oauth2-authentication.txt:167 (grant_type, Basic auth header)
+ * @see references/viva-docs/md/oauth2-authentication.txt:179 (token response shape, expires_in)
+ * @see references/viva-docs/md/oauth2-authentication.txt:192 (3600s expiry)
+ */
+import { ENVIRONMENT_URLS } from '../types/common.js';
+import { VivaAuthError } from '../errors/auth-error.js';
+import { VivaApiError } from '../errors/api-error.js';
+import { VivaRateLimitError } from '../errors/rate-limit-error.js';
+import { AsyncMutex, singleFlight } from './single-flight.js';
+import { InMemoryTokenCache } from './token-cache.js';
+import { getAuthDispatcher } from './http.js';
+import { NoopMetricsHook } from '../observability/index.js';
+// ---------------------------------------------------------------------------
+// Strategy implementation
+// ---------------------------------------------------------------------------
+/**
+ * OAuth 2.0 `client_credentials` token strategy.
+ *
+ * Flow:
+ * 1. Check cache. If token is fresh (expires_at > now + refreshSkewMs), return it.
+ * 2. Acquire single-flight lock. Re-check cache (avoid duplicate fetch after waking).
+ * 3. POST `grant_type=client_credentials` to the token endpoint.
+ * 4. Cache result with `expires_at = now + (expires_in * 1000) - 60_000`.
+ *
+ * A1 property: `forceRefresh=true` (used by S3 on 401-recovery) ALSO acquires
+ * the single-flight lock, so even during concurrent secret rotation only one
+ * worker calls `/connect/token`. This is naturally satisfied because
+ * `getBearerToken` unconditionally enters `singleFlight` when the cache check
+ * is bypassed or fails.
+ */
+export class OAuth2ClientCredentialsStrategy {
+    name = 'oauth2-client-credentials';
+    _env;
+    _clientId;
+    _clientSecret;
+    _cache;
+    _mutex;
+    _redisLock;
+    _refreshSkewMs;
+    _fetchImpl;
+    _dispatcher;
+    _now;
+    _metrics;
+    _logger;
+    constructor(opts) {
+        this._env = opts.environment;
+        this._clientId = opts.clientId;
+        this._clientSecret = opts.clientSecret;
+        this._cache = opts.cache ?? new InMemoryTokenCache();
+        this._mutex = opts.mutex ?? new AsyncMutex();
+        this._redisLock = opts.redisLock;
+        this._refreshSkewMs = opts.refreshSkewMs ?? 5 * 60_000;
+        this._fetchImpl = opts.fetchImpl ?? globalThis.fetch;
+        this._dispatcher = opts.dispatcher;
+        this._now = opts.now ?? (() => Date.now());
+        this._metrics = opts.metrics ?? new NoopMetricsHook();
+        this._logger = opts.logger;
+    }
+    /** Exposes the token cache for auth-status inspection. */
+    get tokenCache() {
+        return this._cache;
+    }
+    /** Cache key format: `viva:isv:token:{clientId}:{environment}` */
+    get _cacheKey() {
+        return `viva:isv:token:${this._clientId}:${this._env}`;
+    }
+    /**
+     * Returns a valid bearer token for use in `Authorization: Bearer <token>`.
+     *
+     * When `forceRefresh` is true the cache lookup is skipped but the request
+     * STILL goes through the single-flight lock — this is the A1 property:
+     * multiple workers calling `getBearerToken({ forceRefresh: true })` after
+     * receiving a 401 will not stampede the token endpoint.
+     * // A1: forceRefresh bypasses cache but not the lock — stampede prevention
+     * //     holds even during secret rotation. All concurrent 401-recovery calls
+     * //     will coalesce into one token fetch. (Plan amendment A1.)
+     */
+    async getBearerToken(opts) {
+        const forceRefresh = opts?.forceRefresh === true;
+        // Step 1: fast-path cache hit (skipped on forceRefresh).
+        if (!forceRefresh) {
+            const cached = await this._cache.get(this._cacheKey);
+            if (cached && cached.expires_at > this._now() + this._refreshSkewMs) {
+                return cached.access_token;
+            }
+        }
+        // Step 2–4: go through single-flight lock regardless of forceRefresh.
+        // A1: forceRefresh bypasses cache but not the lock — stampede prevention
+        //     holds even during secret rotation. All concurrent 401-recovery calls
+        //     coalesce into a single /connect/token fetch. (Plan amendment A1.)
+        const locks = this._redisLock
+            ? { redis: this._redisLock }
+            : { local: this._mutex };
+        return singleFlight(this._cacheKey, async () => {
+            // Re-check cache after acquiring the lock; another waiter may have
+            // already refreshed the token while we were queued.
+            if (!forceRefresh) {
+                const reChecked = await this._cache.get(this._cacheKey);
+                if (reChecked && reChecked.expires_at > this._now() + this._refreshSkewMs) {
+                    return reChecked.access_token;
+                }
+            }
+            return this._fetchToken();
+        }, locks);
+    }
+    /**
+     * Fetches a fresh token from the Viva identity server.
+     *
+     * Endpoint:
+     *   Demo:       https://demo-accounts.vivapayments.com/connect/token
+     *   Production: https://accounts.vivapayments.com/connect/token
+     *
+     * @see references/viva-docs/md/oauth2-authentication.txt:145 (endpoint URLs)
+     * @see references/viva-docs/md/oauth2-authentication.txt:167 (curl example: grant_type, Basic header)
+     * @see references/viva-docs/md/oauth2-authentication.txt:179 (response: access_token, expires_in)
+     * @see references/viva-docs/md/oauth2-authentication.txt:192 (3600s token lifetime)
+     */
+    async _fetchToken() {
+        return this._metrics.timeAsync('viva_auth_token_refresh_duration_seconds', () => this._doFetchToken());
+    }
+    async _doFetchToken() {
+        const { authBaseUrl } = ENVIRONMENT_URLS[this._env];
+        const url = `${authBaseUrl}/connect/token`;
+        // Base64-encode Client_ID:Client_Secret per Viva OAuth2 docs line 153.
+        // @see references/viva-docs/md/oauth2-authentication.txt:153
+        const credentials = Buffer.from(`${this._clientId}:${this._clientSecret}`).toString('base64');
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), 30_000);
+        const dispatcher = this._dispatcher ?? getAuthDispatcher(this._env);
+        let response;
+        try {
+            response = await this._fetchImpl(url, {
+                method: 'POST',
+                headers: {
+                    // Authorization: Basic <base64(clientId:clientSecret)>
+                    // @see references/viva-docs/md/oauth2-authentication.txt:166
+                    Authorization: `Basic ${credentials}`,
+                    // Content-Type required for form-encoded body.
+                    // @see references/viva-docs/md/oauth2-authentication.txt:165
+                    'Content-Type': 'application/x-www-form-urlencoded',
+                    Accept: 'application/json',
+                },
+                // grant_type=client_credentials
+                // @see references/viva-docs/md/oauth2-authentication.txt:167
+                body: 'grant_type=client_credentials',
+                signal: controller.signal,
+                // undici 7 supports the `dispatcher` option on global fetch.
+                // @ts-expect-error undici dispatcher option not in standard fetch types
+                dispatcher,
+            });
+        }
+        catch (err) {
+            clearTimeout(timer);
+            // Network / abort error — caller handles retry policy (plan Auth Flow line 316).
+            throw new VivaApiError({
+                message: `Network error fetching Viva token: ${String(err)}`,
+                cause: err,
+            });
+        }
+        clearTimeout(timer);
+        const requestId = response.headers.get('CorrelationId') ?? undefined;
+        if (response.status === 401 || response.status === 403) {
+            throw new VivaAuthError({
+                message: `Viva token endpoint returned ${response.status}. Check client credentials.`,
+                httpStatus: response.status,
+                requestId,
+            });
+        }
+        if (response.status === 429) {
+            const retryAfterHeader = response.headers.get('Retry-After');
+            const retryAfterMs = retryAfterHeader ? parseFloat(retryAfterHeader) * 1000 : undefined;
+            throw new VivaRateLimitError({
+                message: 'Viva token endpoint rate-limited (429).',
+                httpStatus: 429,
+                requestId,
+                retryAfterMs,
+            });
+        }
+        if (response.status >= 500) {
+            throw new VivaRateLimitError({
+                message: `Viva token endpoint server error (${response.status}). Retriable.`,
+                httpStatus: response.status,
+                requestId,
+            });
+        }
+        if (!response.ok) {
+            throw new VivaApiError({
+                message: `Unexpected status ${response.status} from Viva token endpoint.`,
+                httpStatus: response.status,
+                requestId,
+            });
+        }
+        // Parse the OAuth2TokenResponse.
+        // @see references/viva-docs/md/oauth2-authentication.txt:185 (response JSON shape)
+        const body = (await response.json());
+        // Compute expiry: now + (expires_in * 1000) - 60_000 (1-min safety margin).
+        // Plan Auth Flow step 4 / line 314: store expires_at = now + expires_in - 60s.
+        // @see references/viva-docs/md/oauth2-authentication.txt:192 (expires_in = 3600)
+        const expires_at = this._now() + body.expires_in * 1000 - 60_000;
+        await this._cache.set(this._cacheKey, {
+            access_token: body.access_token,
+            expires_at,
+            scope: body.scope,
+        });
+        this._logger?.info('viva:auth:token-refresh', { environment: this._env });
+        return body.access_token;
+    }
+}
+//# sourceMappingURL=oauth2-strategy.js.map

package/dist/auth/oauth2-strategy.js.map

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

package/dist/auth/reseller-strategy.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Reseller basic-auth strategy for ISV endpoints that require it.
+ *
+ * Some ISV API calls (e.g. `cancelOrder`) require a Reseller-level basic-auth
+ * credential rather than the OAuth2 bearer token. This strategy computes the
+ * `Authorization: Basic <base64(merchantId:resellerApiKey)>` header value and
+ * returns it from `getBearerToken()` so the S3 HTTP client remains uniform —
+ * it always calls `getBearerToken()` and uses the result verbatim.
+ *
+ * Credential combination used:
+ *   Username = merchantId, Password = resellerApiKey
+ *
+ * TODO(impl): verify exact merchantId:resellerApiKey concatenation against
+ * live demo. The ISV docs (`payment-isv-api.txt`) confirm Reseller ID +
+ * Merchant ID + Reseller API Key are required credentials but the precise
+ * Basic-auth encoding (which field is "username" vs "password") should be
+ * validated against a live Viva demo response before shipping.
+ * @see references/viva-docs/md/payment-isv-api.txt:1
+ */
+import type { AuthStrategy } from '../types/auth.js';
+export interface ResellerStrategyOptions {
+    /** ISV Partner Reseller ID provided by Viva. */
+    resellerId: string;
+    /** Target merchant's Merchant ID. */
+    merchantId: string;
+    /** ISV Partner Reseller API Key provided by Viva. */
+    resellerApiKey: string;
+}
+/**
+ * Returns a Basic-auth Authorization header value for ISV reseller calls.
+ *
+ * `getBearerToken()` returns `Basic <base64(merchantId:resellerApiKey)>`.
+ * The S3 layer sets `Authorization: <value>` — for this strategy the value
+ * includes the `Basic ` prefix so it can be used identically to a bearer value.
+ *
+ * `getAuthorizationHeader()` is exposed as a convenience alias.
+ */
+export declare class ResellerBasicAuthStrategy implements AuthStrategy {
+    readonly name = "reseller-basic-auth";
+    private readonly _resellerId;
+    private readonly _merchantId;
+    private readonly _resellerApiKey;
+    constructor({ resellerId, merchantId, resellerApiKey }: ResellerStrategyOptions);
+    /**
+     * Returns the `Authorization` header value.
+     *
+     * Note: for this strategy the returned string includes the `Basic ` prefix
+     * (e.g. `"Basic dXNlcjpwYXNz"`). The S3 client places it verbatim in the
+     * Authorization header.  This is intentional — the abstraction is "value to
+     * put in Authorization header", not "raw bearer token".
+     */
+    getBearerToken(_opts?: {
+        forceRefresh?: boolean;
+    }): Promise<string>;
+    /**
+     * Returns `Basic <base64(merchantId:resellerApiKey)>`.
+     *
+     * TODO(impl): verify merchantId:resellerApiKey encoding against live demo.
+     * @see references/viva-docs/md/payment-isv-api.txt:1
+     */
+    getAuthorizationHeader(): string;
+    /** Reseller ID accessor for S3 correlation (not part of AuthStrategy). */
+    get resellerId(): string;
+}
+//# sourceMappingURL=reseller-strategy.d.ts.map

package/dist/auth/reseller-strategy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reseller-strategy.d.ts","sourceRoot":"","sources":["../../src/auth/reseller-strategy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAErD,MAAM,WAAW,uBAAuB;IACtC,gDAAgD;IAChD,UAAU,EAAE,MAAM,CAAC;IACnB,qCAAqC;IACrC,UAAU,EAAE,MAAM,CAAC;IACnB,qDAAqD;IACrD,cAAc,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;GAQG;AACH,qBAAa,yBAA0B,YAAW,YAAY;IAC5D,QAAQ,CAAC,IAAI,yBAAyB;IAEtC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;gBAE7B,EAAE,UAAU,EAAE,UAAU,EAAE,cAAc,EAAE,EAAE,uBAAuB;IAM/E;;;;;;;OAOG;IACG,cAAc,CAAC,KAAK,CAAC,EAAE;QAAE,YAAY,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,CAAC;IAIzE;;;;;OAKG;IACH,sBAAsB,IAAI,MAAM;IAUhC,0EAA0E;IAC1E,IAAI,UAAU,IAAI,MAAM,CAEvB;CACF"}

package/dist/auth/reseller-strategy.js

@@ -0,0 +1,68 @@
+/**
+ * Reseller basic-auth strategy for ISV endpoints that require it.
+ *
+ * Some ISV API calls (e.g. `cancelOrder`) require a Reseller-level basic-auth
+ * credential rather than the OAuth2 bearer token. This strategy computes the
+ * `Authorization: Basic <base64(merchantId:resellerApiKey)>` header value and
+ * returns it from `getBearerToken()` so the S3 HTTP client remains uniform —
+ * it always calls `getBearerToken()` and uses the result verbatim.
+ *
+ * Credential combination used:
+ *   Username = merchantId, Password = resellerApiKey
+ *
+ * TODO(impl): verify exact merchantId:resellerApiKey concatenation against
+ * live demo. The ISV docs (`payment-isv-api.txt`) confirm Reseller ID +
+ * Merchant ID + Reseller API Key are required credentials but the precise
+ * Basic-auth encoding (which field is "username" vs "password") should be
+ * validated against a live Viva demo response before shipping.
+ * @see references/viva-docs/md/payment-isv-api.txt:1
+ */
+/**
+ * Returns a Basic-auth Authorization header value for ISV reseller calls.
+ *
+ * `getBearerToken()` returns `Basic <base64(merchantId:resellerApiKey)>`.
+ * The S3 layer sets `Authorization: <value>` — for this strategy the value
+ * includes the `Basic ` prefix so it can be used identically to a bearer value.
+ *
+ * `getAuthorizationHeader()` is exposed as a convenience alias.
+ */
+export class ResellerBasicAuthStrategy {
+    name = 'reseller-basic-auth';
+    _resellerId;
+    _merchantId;
+    _resellerApiKey;
+    constructor({ resellerId, merchantId, resellerApiKey }) {
+        this._resellerId = resellerId;
+        this._merchantId = merchantId;
+        this._resellerApiKey = resellerApiKey;
+    }
+    /**
+     * Returns the `Authorization` header value.
+     *
+     * Note: for this strategy the returned string includes the `Basic ` prefix
+     * (e.g. `"Basic dXNlcjpwYXNz"`). The S3 client places it verbatim in the
+     * Authorization header.  This is intentional — the abstraction is "value to
+     * put in Authorization header", not "raw bearer token".
+     */
+    async getBearerToken(_opts) {
+        return this.getAuthorizationHeader();
+    }
+    /**
+     * Returns `Basic <base64(merchantId:resellerApiKey)>`.
+     *
+     * TODO(impl): verify merchantId:resellerApiKey encoding against live demo.
+     * @see references/viva-docs/md/payment-isv-api.txt:1
+     */
+    getAuthorizationHeader() {
+        // Encode merchantId:resellerApiKey in Base64 per HTTP Basic-auth spec.
+        // resellerId is stored for correlation / logging but is not part of the
+        // Basic credential header — it is typically a query or path parameter.
+        const encoded = Buffer.from(`${this._merchantId}:${this._resellerApiKey}`).toString('base64');
+        return `Basic ${encoded}`;
+    }
+    /** Reseller ID accessor for S3 correlation (not part of AuthStrategy). */
+    get resellerId() {
+        return this._resellerId;
+    }
+}
+//# sourceMappingURL=reseller-strategy.js.map

package/dist/auth/reseller-strategy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reseller-strategy.js","sourceRoot":"","sources":["../../src/auth/reseller-strategy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAaH;;;;;;;;GAQG;AACH,MAAM,OAAO,yBAAyB;IAC3B,IAAI,GAAG,qBAAqB,CAAC;IAErB,WAAW,CAAS;IACpB,WAAW,CAAS;IACpB,eAAe,CAAS;IAEzC,YAAY,EAAE,UAAU,EAAE,UAAU,EAAE,cAAc,EAA2B;QAC7E,IAAI,CAAC,WAAW,GAAG,UAAU,CAAC;QAC9B,IAAI,CAAC,WAAW,GAAG,UAAU,CAAC;QAC9B,IAAI,CAAC,eAAe,GAAG,cAAc,CAAC;IACxC,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,cAAc,CAAC,KAAkC;QACrD,OAAO,IAAI,CAAC,sBAAsB,EAAE,CAAC;IACvC,CAAC;IAED;;;;;OAKG;IACH,sBAAsB;QACpB,uEAAuE;QACvE,wEAAwE;QACxE,uEAAuE;QACvE,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CACzB,GAAG,IAAI,CAAC,WAAW,IAAI,IAAI,CAAC,eAAe,EAAE,CAC9C,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;QACrB,OAAO,SAAS,OAAO,EAAE,CAAC;IAC5B,CAAC;IAED,0EAA0E;IAC1E,IAAI,UAAU;QACZ,OAAO,IAAI,CAAC,WAAW,CAAC;IAC1B,CAAC;CACF"}

package/dist/auth/single-flight.d.ts

@@ -0,0 +1,81 @@
+/**
+ * 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.
+ */
+export interface RedisLockClient {
+    /**
+     * Try to acquire a distributed lock for `key` with the given TTL.
+     * Returns `{ token }` on success, `null` if the lock is already held.
+     */
+    acquire(key: string, ttlMs: number): Promise<{
+        token: string;
+    } | null>;
+    /** Release the lock identified by `key` and `token`. */
+    release(key: string, token: string): Promise<void>;
+    /**
+     * Poll `getter` every `intervalMs` until it returns a non-null value
+     * (meaning another worker wrote the result to cache) or `timeoutMs` elapses.
+     */
+    pollCacheUntil<T>(getter: () => Promise<T | null>, intervalMs: number, timeoutMs: number): Promise<T | null>;
+}
+/**
+ * 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 declare const noopRedisLock: RedisLockClient;
+/**
+ * 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 declare class AsyncMutex {
+    private _tail;
+    /**
+     * Acquires the mutex. Resolves when this caller holds the lock.
+     * Returns a `release` function that MUST be called in `finally`.
+     */
+    acquire(): Promise<() => void>;
+}
+type Locks = {
+    local: AsyncMutex;
+} | {
+    redis: RedisLockClient;
+};
+/**
+ * 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 declare function singleFlight<T>(key: string, fn: () => Promise<T>, locks: Locks): Promise<T>;
+export {};
+//# sourceMappingURL=single-flight.d.ts.map

package/dist/auth/single-flight.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"single-flight.d.ts","sourceRoot":"","sources":["../../src/auth/single-flight.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAMH,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC,CAAC;IAEvE,wDAAwD;IACxD,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEnD;;;OAGG;IACH,cAAc,CAAC,CAAC,EACd,MAAM,EAAE,MAAM,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,EAC/B,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;CACtB;AAED;;;;GAIG;AACH,eAAO,MAAM,aAAa,EAAE,eAU3B,CAAC;AAMF;;;;;;;;GAQG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,KAAK,CAAoC;IAEjD;;;OAGG;IACH,OAAO,IAAI,OAAO,CAAC,MAAM,IAAI,CAAC;CAiB/B;AAMD,KAAK,KAAK,GAAG;IAAE,KAAK,EAAE,UAAU,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,eAAe,CAAA;CAAE,CAAC;AAWhE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,CAAC,CAAC,CAqE3F"}