@sakeetech/viva-payments-core 0.2.1

package/dist/refunds/fast-refund-client.d.ts

@@ -0,0 +1,128 @@
+/**
+ * FastRefundClient — Viva Fast Refund API (OAuth2 acquiring scopes).
+ *
+ * Wraps `POST /acquiring/v1/transactions/{transactionId}:fastrefund` on the
+ * v2 API surface. Requires an OAuth2 token with `acquiring` +
+ * `acquiring:transactions` scopes (see AUTH.md §3.2). Eligibility is
+ * server-enforced by Viva:
+ *   - Visa / MasterCard / Maestro card schemes
+ *   - E-commerce (card-not-present) transactions
+ *   - Merchant must be approved by Viva sales for fast refunds
+ *
+ * If the merchant is not approved or the original transaction is not eligible,
+ * Viva returns HTTP 403. Callers are expected to catch the resulting
+ * `VivaApiError` and fall back to the standard (legacy) refund path. See
+ * {@link resolveRefundStrategy} for the upstream pure decision helper.
+ *
+ * Design notes:
+ *   - Caller-driven fallback: this client never silently retries on a
+ *     standard refund — caller decides whether to fall back.
+ *   - Idempotent: `false`. POST is non-idempotent at the transport layer; no
+ *     4xx/5xx retries. Connection-level errors retry once (request never acked).
+ *   - Mirrors the style of {@link BasicAuthClient.request} / Payments.refundPayment
+ *     for validation, error handling, and JSDoc references.
+ *
+ * @see docs/ENDPOINTS.md §4 (Fast vs Standard refund matrix)
+ * @see docs/AUTH.md §3.2 (OAuth2 acquiring scopes)
+ * @see docs/plans/multi-mode-v0.md §8.5a (FastRefundClient class shape)
+ * @see docs/STATE-MACHINE.md §3.1 (card-scheme detection)
+ * @see references/payment-api.yaml:9255 (POST /acquiring/v1/transactions/{id}:fastrefund)
+ * @see references/payment-api.yaml:9268 (eligibility — Visa/MC/Maestro)
+ */
+import type { IsvHttpClient } from '../isv/client.js';
+import type { TransactionId, MinorUnits } from '../types/index.js';
+export interface FastRefundClientConfig {
+    /**
+     * OAuth2 HTTP client whose underlying AuthStrategy yields a token with
+     * `acquiring` + `acquiring:transactions` scopes (see AUTH.md §3.2).
+     */
+    client: IsvHttpClient;
+}
+/**
+ * Input for {@link FastRefundClient.refund}.
+ *
+ * All fields are required — Fast Refund does not support a "full refund by
+ * omission" convention (unlike the legacy refund path). Pass the original
+ * transaction's full amount in minor units for a full refund.
+ */
+export interface FastRefundRequest {
+    /** UUID of the ORIGINAL captured transaction to refund. */
+    transactionId: TransactionId;
+    /** Amount in integer minor units. Must be > 0. */
+    amount: MinorUnits;
+    /** Payment source code (Viva merchant source). Non-empty string. */
+    sourceCode: string;
+    /** Merchant-side reference for the refund. Non-empty string. */
+    merchantTrns: string;
+    /**
+     * Idempotency key. Forwarded as the `Idempotency-Key` HTTP header per the
+     * shared {@link IsvHttpClient} convention. Non-empty string.
+     *
+     * NOTE: Viva does not appear to deduplicate server-side (probe F2,
+     * 2026-04-25). Local dedup remains the authoritative mechanism. Header is
+     * retained for forward-compat.
+     */
+    idempotencyKey: string;
+}
+/**
+ * Response from {@link FastRefundClient.refund}.
+ *
+ * Field names are normalized to camelCase. Viva responds with a transaction
+ * envelope describing the REFUND transaction (a new transaction id, distinct
+ * from the original `transactionId` passed in the request).
+ *
+ * @see references/payment-api.yaml:9255
+ */
+export interface FastRefundResponse {
+    /** The refund transaction's OWN id (not the original captured transaction). */
+    transactionId: TransactionId;
+    /** Viva event id correlated with the refund. */
+    eventId: number;
+    /** Refunded amount in minor units, as JSON number from Viva. */
+    amount: number;
+}
+/**
+ * Thin POST wrapper for the Viva Fast Refund endpoint.
+ *
+ * Eligibility (per Viva docs):
+ *   - Visa / MasterCard / Maestro
+ *   - E-commerce (card-not-present)
+ *   - Merchant approved by Viva sales for Fast Refunds
+ *
+ * On 403 the caller should fall back to the standard refund flow
+ * (`Payments.refundPayment` via the legacy `BasicAuthClient`). The decision
+ * helper {@link resolveRefundStrategy} returns `auto-ineligible-*` reasons up
+ * front so most ineligible cases never reach the wire.
+ *
+ * @see references/payment-api.yaml:9255
+ * @see docs/ENDPOINTS.md §4
+ * @see docs/AUTH.md §3.2
+ */
+export declare class FastRefundClient {
+    private readonly client;
+    constructor(config: FastRefundClientConfig);
+    /**
+     * POST `/acquiring/v1/transactions/{transactionId}:fastrefund`.
+     *
+     * Body: `{ amount, sourceCode, merchantTrns, idempotencyKey }` — no extra
+     * fields. Auth: OAuth2 Bearer (acquiring scopes) handled by the underlying
+     * {@link IsvHttpClient}.
+     *
+     * Local validation (throws VivaValidationError before HTTP call):
+     *   - `amount` must be > 0 minor units
+     *   - `sourceCode`, `merchantTrns`, `idempotencyKey` must be non-empty strings
+     *
+     * Errors:
+     *   - 403  → VivaApiError. Caller decides whether to fall back to standard refund.
+     *   - 404  → VivaApiError (transaction not found).
+     *   - 422  → VivaApiError (invalid BIN / scheme).
+     *   - 423  → VivaApiError (refund already in progress).
+     *   - 452  → VivaApiError (insufficient funds for fast refund).
+     *   - 5xx  → VivaApiError (no retry — POST is non-idempotent).
+     *
+     * @see references/payment-api.yaml:9255
+     * @see docs/ERRORS.md §2 (error code matrix)
+     */
+    refund(input: FastRefundRequest): Promise<FastRefundResponse>;
+}
+//# sourceMappingURL=fast-refund-client.d.ts.map

package/dist/refunds/fast-refund-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fast-refund-client.d.ts","sourceRoot":"","sources":["../../src/refunds/fast-refund-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAOnE,MAAM,WAAW,sBAAsB;IACrC;;;OAGG;IACH,MAAM,EAAE,aAAa,CAAC;CACvB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IAChC,2DAA2D;IAC3D,aAAa,EAAE,aAAa,CAAC;IAC7B,kDAAkD;IAClD,MAAM,EAAE,UAAU,CAAC;IACnB,oEAAoE;IACpE,UAAU,EAAE,MAAM,CAAC;IACnB,gEAAgE;IAChE,YAAY,EAAE,MAAM,CAAC;IACrB;;;;;;;OAOG;IACH,cAAc,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,kBAAkB;IACjC,+EAA+E;IAC/E,aAAa,EAAE,aAAa,CAAC;IAC7B,gDAAgD;IAChD,OAAO,EAAE,MAAM,CAAC;IAChB,gEAAgE;IAChE,MAAM,EAAE,MAAM,CAAC;CAChB;AAMD;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgB;gBAE3B,MAAM,EAAE,sBAAsB;IAI1C;;;;;;;;;;;;;;;;;;;;;OAqBG;IACG,MAAM,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,kBAAkB,CAAC;CA0EpE"}

package/dist/refunds/fast-refund-client.js

@@ -0,0 +1,138 @@
+/**
+ * FastRefundClient — Viva Fast Refund API (OAuth2 acquiring scopes).
+ *
+ * Wraps `POST /acquiring/v1/transactions/{transactionId}:fastrefund` on the
+ * v2 API surface. Requires an OAuth2 token with `acquiring` +
+ * `acquiring:transactions` scopes (see AUTH.md §3.2). Eligibility is
+ * server-enforced by Viva:
+ *   - Visa / MasterCard / Maestro card schemes
+ *   - E-commerce (card-not-present) transactions
+ *   - Merchant must be approved by Viva sales for fast refunds
+ *
+ * If the merchant is not approved or the original transaction is not eligible,
+ * Viva returns HTTP 403. Callers are expected to catch the resulting
+ * `VivaApiError` and fall back to the standard (legacy) refund path. See
+ * {@link resolveRefundStrategy} for the upstream pure decision helper.
+ *
+ * Design notes:
+ *   - Caller-driven fallback: this client never silently retries on a
+ *     standard refund — caller decides whether to fall back.
+ *   - Idempotent: `false`. POST is non-idempotent at the transport layer; no
+ *     4xx/5xx retries. Connection-level errors retry once (request never acked).
+ *   - Mirrors the style of {@link BasicAuthClient.request} / Payments.refundPayment
+ *     for validation, error handling, and JSDoc references.
+ *
+ * @see docs/ENDPOINTS.md §4 (Fast vs Standard refund matrix)
+ * @see docs/AUTH.md §3.2 (OAuth2 acquiring scopes)
+ * @see docs/plans/multi-mode-v0.md §8.5a (FastRefundClient class shape)
+ * @see docs/STATE-MACHINE.md §3.1 (card-scheme detection)
+ * @see references/payment-api.yaml:9255 (POST /acquiring/v1/transactions/{id}:fastrefund)
+ * @see references/payment-api.yaml:9268 (eligibility — Visa/MC/Maestro)
+ */
+import { VivaValidationError } from '../errors/index.js';
+// ---------------------------------------------------------------------------
+// FastRefundClient
+// ---------------------------------------------------------------------------
+/**
+ * Thin POST wrapper for the Viva Fast Refund endpoint.
+ *
+ * Eligibility (per Viva docs):
+ *   - Visa / MasterCard / Maestro
+ *   - E-commerce (card-not-present)
+ *   - Merchant approved by Viva sales for Fast Refunds
+ *
+ * On 403 the caller should fall back to the standard refund flow
+ * (`Payments.refundPayment` via the legacy `BasicAuthClient`). The decision
+ * helper {@link resolveRefundStrategy} returns `auto-ineligible-*` reasons up
+ * front so most ineligible cases never reach the wire.
+ *
+ * @see references/payment-api.yaml:9255
+ * @see docs/ENDPOINTS.md §4
+ * @see docs/AUTH.md §3.2
+ */
+export class FastRefundClient {
+    client;
+    constructor(config) {
+        this.client = config.client;
+    }
+    /**
+     * POST `/acquiring/v1/transactions/{transactionId}:fastrefund`.
+     *
+     * Body: `{ amount, sourceCode, merchantTrns, idempotencyKey }` — no extra
+     * fields. Auth: OAuth2 Bearer (acquiring scopes) handled by the underlying
+     * {@link IsvHttpClient}.
+     *
+     * Local validation (throws VivaValidationError before HTTP call):
+     *   - `amount` must be > 0 minor units
+     *   - `sourceCode`, `merchantTrns`, `idempotencyKey` must be non-empty strings
+     *
+     * Errors:
+     *   - 403  → VivaApiError. Caller decides whether to fall back to standard refund.
+     *   - 404  → VivaApiError (transaction not found).
+     *   - 422  → VivaApiError (invalid BIN / scheme).
+     *   - 423  → VivaApiError (refund already in progress).
+     *   - 452  → VivaApiError (insufficient funds for fast refund).
+     *   - 5xx  → VivaApiError (no retry — POST is non-idempotent).
+     *
+     * @see references/payment-api.yaml:9255
+     * @see docs/ERRORS.md §2 (error code matrix)
+     */
+    async refund(input) {
+        // --- local validation (mirror style of Payments.refundPayment / createOrder) ---
+        if (input.amount <= 0n) {
+            throw new VivaValidationError({
+                message: `FastRefundClient.refund: amount must be > 0 minor units, got ${input.amount}`,
+            });
+        }
+        if (typeof input.sourceCode !== 'string' || input.sourceCode.length === 0) {
+            throw new VivaValidationError({
+                message: 'FastRefundClient.refund: sourceCode must be a non-empty string',
+            });
+        }
+        if (typeof input.merchantTrns !== 'string' || input.merchantTrns.length === 0) {
+            throw new VivaValidationError({
+                message: 'FastRefundClient.refund: merchantTrns must be a non-empty string',
+            });
+        }
+        if (typeof input.idempotencyKey !== 'string' || input.idempotencyKey.length === 0) {
+            throw new VivaValidationError({
+                message: 'FastRefundClient.refund: idempotencyKey must be a non-empty string',
+            });
+        }
+        if (typeof input.transactionId !== 'string' || input.transactionId.length === 0) {
+            throw new VivaValidationError({
+                message: 'FastRefundClient.refund: transactionId must be a non-empty string',
+            });
+        }
+        // URL-encode the transactionId so the path segment is safe even for ids
+        // that contain reserved characters (defensive — Viva UUIDs do not, but
+        // the type is a branded string so future ids could).
+        const encodedId = encodeURIComponent(input.transactionId);
+        const path = `/acquiring/v1/transactions/${encodedId}:fastrefund`;
+        // Wire body — exactly the four fields per spec. `amount` is bigint and
+        // is handled by the shared bigint-safe stringify in IsvHttpClient.
+        const body = {
+            amount: input.amount,
+            sourceCode: input.sourceCode,
+            merchantTrns: input.merchantTrns,
+            idempotencyKey: input.idempotencyKey,
+        };
+        const raw = await this.client.request({
+            method: 'POST',
+            path,
+            body,
+            idempotencyKey: input.idempotencyKey,
+            idempotent: false,
+            endpoint: 'POST /acquiring/v1/transactions/{transactionId}:fastrefund',
+        });
+        const refundTxId = (raw.transactionId ?? raw.TransactionId ?? '');
+        const eventId = (raw.eventId ?? raw.EventId ?? 0);
+        const amount = (raw.amount ?? raw.Amount ?? 0);
+        return {
+            transactionId: refundTxId,
+            eventId,
+            amount,
+        };
+    }
+}
+//# sourceMappingURL=fast-refund-client.js.map

package/dist/refunds/fast-refund-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fast-refund-client.js","sourceRoot":"","sources":["../../src/refunds/fast-refund-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAIH,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AA2DzD,8EAA8E;AAC9E,mBAAmB;AACnB,8EAA8E;AAE9E;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,OAAO,gBAAgB;IACV,MAAM,CAAgB;IAEvC,YAAY,MAA8B;QACxC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;IAC9B,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,KAAK,CAAC,MAAM,CAAC,KAAwB;QACnC,kFAAkF;QAClF,IAAI,KAAK,CAAC,MAAM,IAAI,EAAE,EAAE,CAAC;YACvB,MAAM,IAAI,mBAAmB,CAAC;gBAC5B,OAAO,EAAE,gEAAgE,KAAK,CAAC,MAAM,EAAE;aACxF,CAAC,CAAC;QACL,CAAC;QACD,IAAI,OAAO,KAAK,CAAC,UAAU,KAAK,QAAQ,IAAI,KAAK,CAAC,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC1E,MAAM,IAAI,mBAAmB,CAAC;gBAC5B,OAAO,EAAE,gEAAgE;aAC1E,CAAC,CAAC;QACL,CAAC;QACD,IAAI,OAAO,KAAK,CAAC,YAAY,KAAK,QAAQ,IAAI,KAAK,CAAC,YAAY,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC9E,MAAM,IAAI,mBAAmB,CAAC;gBAC5B,OAAO,EAAE,kEAAkE;aAC5E,CAAC,CAAC;QACL,CAAC;QACD,IAAI,OAAO,KAAK,CAAC,cAAc,KAAK,QAAQ,IAAI,KAAK,CAAC,cAAc,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAClF,MAAM,IAAI,mBAAmB,CAAC;gBAC5B,OAAO,EAAE,oEAAoE;aAC9E,CAAC,CAAC;QACL,CAAC;QACD,IAAI,OAAO,KAAK,CAAC,aAAa,KAAK,QAAQ,IAAI,KAAK,CAAC,aAAa,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAChF,MAAM,IAAI,mBAAmB,CAAC;gBAC5B,OAAO,EAAE,mEAAmE;aAC7E,CAAC,CAAC;QACL,CAAC;QAED,wEAAwE;QACxE,uEAAuE;QACvE,qDAAqD;QACrD,MAAM,SAAS,GAAG,kBAAkB,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC;QAC1D,MAAM,IAAI,GAAG,8BAA8B,SAAS,aAAa,CAAC;QAElE,uEAAuE;QACvE,mEAAmE;QACnE,MAAM,IAAI,GAAG;YACX,MAAM,EAAE,KAAK,CAAC,MAAM;YACpB,UAAU,EAAE,KAAK,CAAC,UAAU;YAC5B,YAAY,EAAE,KAAK,CAAC,YAAY;YAChC,cAAc,EAAE,KAAK,CAAC,cAAc;SACrC,CAAC;QAcF,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,OAAO,CAAgB;YACnD,MAAM,EAAE,MAAM;YACd,IAAI;YACJ,IAAI;YACJ,cAAc,EAAE,KAAK,CAAC,cAAc;YACpC,UAAU,EAAE,KAAK;YACjB,QAAQ,EAAE,4DAA4D;SACvE,CAAC,CAAC;QAEH,MAAM,UAAU,GAAG,CAAC,GAAG,CAAC,aAAa,IAAI,GAAG,CAAC,aAAa,IAAI,EAAE,CAAkB,CAAC;QACnF,MAAM,OAAO,GAAG,CAAC,GAAG,CAAC,OAAO,IAAI,GAAG,CAAC,OAAO,IAAI,CAAC,CAAW,CAAC;QAC5D,MAAM,MAAM,GAAG,CAAC,GAAG,CAAC,MAAM,IAAI,GAAG,CAAC,MAAM,IAAI,CAAC,CAAW,CAAC;QAEzD,OAAO;YACL,aAAa,EAAE,UAAU;YACzB,OAAO;YACP,MAAM;SACP,CAAC;IACJ,CAAC;CACF"}

package/dist/refunds/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * viva-payments-core/refunds — barrel export.
+ *
+ * Subpath: `@sakeetech/viva-payments-core/refunds`
+ *
+ * Public surface:
+ *   - {@link FastRefundClient} — OAuth2 acquiring-scopes wrapper for
+ *     `POST /acquiring/v1/transactions/{transactionId}:fastrefund`.
+ *   - {@link resolveRefundStrategy} — pure decision function for the
+ *     `auto | fast | standard` strategy resolver consumed by adapters.
+ *
+ * @see docs/plans/multi-mode-v0.md §8.5a
+ * @see docs/ENDPOINTS.md §4
+ */
+export { FastRefundClient } from './fast-refund-client.js';
+export type { FastRefundClientConfig, FastRefundRequest, FastRefundResponse, } from './fast-refund-client.js';
+export { resolveRefundStrategy } from './strategy.js';
+export type { RefundStrategy, RefundContext, RefundDecision } from './strategy.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/refunds/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,YAAY,EACV,sBAAsB,EACtB,iBAAiB,EACjB,kBAAkB,GACnB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AACtD,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC"}

package/dist/refunds/index.js

@@ -0,0 +1,17 @@
+/**
+ * viva-payments-core/refunds — barrel export.
+ *
+ * Subpath: `@sakeetech/viva-payments-core/refunds`
+ *
+ * Public surface:
+ *   - {@link FastRefundClient} — OAuth2 acquiring-scopes wrapper for
+ *     `POST /acquiring/v1/transactions/{transactionId}:fastrefund`.
+ *   - {@link resolveRefundStrategy} — pure decision function for the
+ *     `auto | fast | standard` strategy resolver consumed by adapters.
+ *
+ * @see docs/plans/multi-mode-v0.md §8.5a
+ * @see docs/ENDPOINTS.md §4
+ */
+export { FastRefundClient } from './fast-refund-client.js';
+export { resolveRefundStrategy } from './strategy.js';
+//# sourceMappingURL=index.js.map

package/dist/refunds/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/refunds/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAO3D,OAAO,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC"}

package/dist/refunds/strategy.d.ts

@@ -0,0 +1,78 @@
+/**
+ * resolveRefundStrategy — pure decision function for refund routing.
+ *
+ * Given a configured strategy (`auto` | `fast` | `standard`) and a refund
+ * context (card scheme + card-present flag), returns a {@link RefundDecision}
+ * describing which refund path to take and why. The caller (adapter refund
+ * handler) is responsible for executing the chosen path and — when the
+ * strategy is `auto` and Fast Refund returns 403 — falling back to standard.
+ *
+ * This is deliberately a pure function with no I/O so it is trivial to unit
+ * test and reuse from any adapter.
+ *
+ * @see docs/ENDPOINTS.md §4 (Fast vs Standard matrix)
+ * @see docs/STATE-MACHINE.md §3.1 (card scheme detection from retrieveTransaction)
+ * @see docs/plans/multi-mode-v0.md §8.5a
+ * @see references/payment-api.yaml:9268 (eligibility: Visa / MC / Maestro)
+ */
+export type RefundStrategy = 'auto' | 'fast' | 'standard';
+/**
+ * Refund context surfaced from the adapter refund handler.
+ *
+ * Populated from a prior `retrieveTransaction` call (for `cardType`) plus
+ * a flag from the originating payment session indicating whether the
+ * transaction was card-not-present (e-commerce / Smart Checkout) — which
+ * every plugin-initiated payment is.
+ */
+export interface RefundContext {
+    /**
+     * `cardType` field from {@link RetrieveTransactionResponse}. Viva returns
+     * PascalCase scheme names: `'Visa' | 'MasterCard' | 'Maestro' | 'Amex' | ...`.
+     * Undefined when Viva omits the field (some non-card payment types).
+     *
+     * @see docs/STATE-MACHINE.md §3.1
+     */
+    cardType?: string;
+    /**
+     * Whether the original transaction was card-not-present (e-commerce).
+     * For plugin-initiated payments via Smart Checkout this is always `true`.
+     * Kept as an explicit input for future POS / in-store integrations where
+     * Fast Refund is not allowed.
+     */
+    isCardNotPresent: boolean;
+}
+/**
+ * Decision returned by {@link resolveRefundStrategy}.
+ *
+ * `kind` selects the path; `reason` is a stable, machine-readable explanation
+ * suitable for structured logging and observability dashboards. The set of
+ * reason strings is a closed enum — extend only with explicit plan review.
+ */
+export type RefundDecision = {
+    kind: 'fast';
+    reason: 'configured' | 'auto-eligible';
+} | {
+    kind: 'standard';
+    reason: 'configured' | 'auto-ineligible-scheme' | 'auto-ineligible-card-present' | 'auto-no-card-info';
+};
+/**
+ * Pure decision function. Does not perform any I/O.
+ *
+ * Behaviour:
+ *   - `strategy === 'fast'`     → always `{ kind: 'fast', reason: 'configured' }`.
+ *     Caller has explicitly opted in; eligibility is enforced server-side.
+ *   - `strategy === 'standard'` → always `{ kind: 'standard', reason: 'configured' }`.
+ *   - `strategy === 'auto'`     → decided from {@link RefundContext}:
+ *       - card-present              → standard (`auto-ineligible-card-present`)
+ *       - undefined cardType        → standard (`auto-no-card-info`)
+ *       - eligible scheme + CNP     → fast    (`auto-eligible`)
+ *       - non-eligible scheme + CNP → standard (`auto-ineligible-scheme`)
+ *
+ * On Fast Refund 403 the caller should still fall back to standard refund —
+ * this function only handles the pre-call decision, not server-side rejection.
+ *
+ * @see docs/ENDPOINTS.md §4
+ * @see references/payment-api.yaml:9268
+ */
+export declare function resolveRefundStrategy(strategy: RefundStrategy, ctx: RefundContext): RefundDecision;
+//# sourceMappingURL=strategy.d.ts.map

package/dist/refunds/strategy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"strategy.d.ts","sourceRoot":"","sources":["../../src/refunds/strategy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAMH,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,MAAM,GAAG,UAAU,CAAC;AAmB1D;;;;;;;GAOG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;;OAKG;IACH,gBAAgB,EAAE,OAAO,CAAC;CAC3B;AAED;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,GACtB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,YAAY,GAAG,eAAe,CAAA;CAAE,GACxD;IACE,IAAI,EAAE,UAAU,CAAC;IACjB,MAAM,EACF,YAAY,GACZ,wBAAwB,GACxB,8BAA8B,GAC9B,mBAAmB,CAAC;CACzB,CAAC;AAMN;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,cAAc,EACxB,GAAG,EAAE,aAAa,GACjB,cAAc,CAkBhB"}

package/dist/refunds/strategy.js

@@ -0,0 +1,75 @@
+/**
+ * resolveRefundStrategy — pure decision function for refund routing.
+ *
+ * Given a configured strategy (`auto` | `fast` | `standard`) and a refund
+ * context (card scheme + card-present flag), returns a {@link RefundDecision}
+ * describing which refund path to take and why. The caller (adapter refund
+ * handler) is responsible for executing the chosen path and — when the
+ * strategy is `auto` and Fast Refund returns 403 — falling back to standard.
+ *
+ * This is deliberately a pure function with no I/O so it is trivial to unit
+ * test and reuse from any adapter.
+ *
+ * @see docs/ENDPOINTS.md §4 (Fast vs Standard matrix)
+ * @see docs/STATE-MACHINE.md §3.1 (card scheme detection from retrieveTransaction)
+ * @see docs/plans/multi-mode-v0.md §8.5a
+ * @see references/payment-api.yaml:9268 (eligibility: Visa / MC / Maestro)
+ */
+/**
+ * Card schemes eligible for Fast Refund per Viva docs.
+ *
+ * Matched case-sensitively against `cardType` from `retrieveTransaction`
+ * (PascalCase per Viva convention). If Viva ever returns a differently-cased
+ * value, the decision falls through to the `auto-ineligible-scheme` branch
+ * and the caller routes to standard refund.
+ *
+ * @see references/payment-api.yaml:9268
+ * @see docs/STATE-MACHINE.md §3.1
+ */
+const FAST_REFUND_ELIGIBLE_SCHEMES = new Set([
+    'Visa',
+    'MasterCard',
+    'Maestro',
+]);
+// ---------------------------------------------------------------------------
+// Decision function
+// ---------------------------------------------------------------------------
+/**
+ * Pure decision function. Does not perform any I/O.
+ *
+ * Behaviour:
+ *   - `strategy === 'fast'`     → always `{ kind: 'fast', reason: 'configured' }`.
+ *     Caller has explicitly opted in; eligibility is enforced server-side.
+ *   - `strategy === 'standard'` → always `{ kind: 'standard', reason: 'configured' }`.
+ *   - `strategy === 'auto'`     → decided from {@link RefundContext}:
+ *       - card-present              → standard (`auto-ineligible-card-present`)
+ *       - undefined cardType        → standard (`auto-no-card-info`)
+ *       - eligible scheme + CNP     → fast    (`auto-eligible`)
+ *       - non-eligible scheme + CNP → standard (`auto-ineligible-scheme`)
+ *
+ * On Fast Refund 403 the caller should still fall back to standard refund —
+ * this function only handles the pre-call decision, not server-side rejection.
+ *
+ * @see docs/ENDPOINTS.md §4
+ * @see references/payment-api.yaml:9268
+ */
+export function resolveRefundStrategy(strategy, ctx) {
+    if (strategy === 'fast') {
+        return { kind: 'fast', reason: 'configured' };
+    }
+    if (strategy === 'standard') {
+        return { kind: 'standard', reason: 'configured' };
+    }
+    // auto
+    if (!ctx.isCardNotPresent) {
+        return { kind: 'standard', reason: 'auto-ineligible-card-present' };
+    }
+    if (!ctx.cardType) {
+        return { kind: 'standard', reason: 'auto-no-card-info' };
+    }
+    if (FAST_REFUND_ELIGIBLE_SCHEMES.has(ctx.cardType)) {
+        return { kind: 'fast', reason: 'auto-eligible' };
+    }
+    return { kind: 'standard', reason: 'auto-ineligible-scheme' };
+}
+//# sourceMappingURL=strategy.js.map

package/dist/refunds/strategy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"strategy.js","sourceRoot":"","sources":["../../src/refunds/strategy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAQH;;;;;;;;;;GAUG;AACH,MAAM,4BAA4B,GAAwB,IAAI,GAAG,CAAC;IAChE,MAAM;IACN,YAAY;IACZ,SAAS;CACV,CAAC,CAAC;AA8CH,8EAA8E;AAC9E,oBAAoB;AACpB,8EAA8E;AAE9E;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,qBAAqB,CACnC,QAAwB,EACxB,GAAkB;IAElB,IAAI,QAAQ,KAAK,MAAM,EAAE,CAAC;QACxB,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,CAAC;IAChD,CAAC;IACD,IAAI,QAAQ,KAAK,UAAU,EAAE,CAAC;QAC5B,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,YAAY,EAAE,CAAC;IACpD,CAAC;IACD,OAAO;IACP,IAAI,CAAC,GAAG,CAAC,gBAAgB,EAAE,CAAC;QAC1B,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,8BAA8B,EAAE,CAAC;IACtE,CAAC;IACD,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC;QAClB,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,mBAAmB,EAAE,CAAC;IAC3D,CAAC;IACD,IAAI,4BAA4B,CAAC,GAAG,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;QACnD,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe,EAAE,CAAC;IACnD,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,wBAAwB,EAAE,CAAC;AAChE,CAAC"}

package/dist/types/auth.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Authentication types for the Viva Wallet ISV OAuth 2.0 and reseller
+ * basic-auth flows.
+ *
+ * Implementations live in S2 (packages/viva-payments-core/src/auth/).
+ * This file declares interfaces and response shapes only — no runtime code.
+ *
+ * @see references/viva-docs/md/oauth2-authentication.txt:179
+ * @see references/viva-docs/md/isv-credentials.txt:107
+ */
+/**
+ * Raw token response from `POST /connect/token` (client_credentials grant).
+ *
+ * Each token lasts for 3600 seconds (one hour). The `scope` field reflects
+ * the scopes granted to the ISV client application.
+ *
+ * @see references/viva-docs/md/oauth2-authentication.txt:179
+ */
+export interface OAuth2TokenResponse {
+    /** JWT bearer token. Include as `Authorization: Bearer <access_token>`. */
+    readonly access_token: string;
+    /** Lifetime in seconds. Typically 3600. */
+    readonly expires_in: number;
+    /** Always `"Bearer"` for this grant type. */
+    readonly token_type: 'Bearer';
+    /** Space-delimited scopes granted. */
+    readonly scope: string;
+}
+/**
+ * Enriched token value stored in the cache after a successful fetch.
+ * `expires_at` is `Date.now() + (expires_in * 1000)` at fetch time.
+ */
+export interface CachedToken {
+    readonly access_token: string;
+    /** Unix epoch milliseconds when the token expires. */
+    readonly expires_at: number;
+    readonly scope: string;
+}
+/**
+ * Credentials for the ISV Reseller basic-auth strategy.
+ *
+ * Some ISV API calls (e.g. cancelOrder) require Reseller-level credentials
+ * rather than the OAuth2 bearer token. These are distinct from the
+ * Client ID + Client Secret used for client_credentials.
+ *
+ * @see references/viva-docs/md/isv-credentials.txt:107
+ */
+export interface ResellerBasicAuthCredentials {
+    /** ISV Partner Reseller ID provided by Viva. */
+    readonly resellerId: string;
+    /** Target merchant's Merchant ID. */
+    readonly merchantId: string;
+    /** ISV Partner Reseller API Key provided by Viva. */
+    readonly resellerApiKey: string;
+}
+/**
+ * Pluggable authentication strategy interface.
+ *
+ * Implementations (OAuth2ClientCredentialsStrategy, ResellerBasicAuthStrategy)
+ * are defined in S2. The HTTP client accepts an `AuthStrategy` and calls
+ * `getBearerToken()` before each outbound request.
+ *
+ * Single-flight token refresh and caching are implementation concerns;
+ * callers only invoke `getBearerToken()`.
+ *
+ * @see references/viva-docs/md/oauth2-authentication.txt:128
+ */
+export interface AuthStrategy {
+    /**
+     * Returns a valid bearer token string (without the `Bearer ` prefix).
+     *
+     * @param opts.forceRefresh - If true, bypass the cache and fetch a fresh token.
+     */
+    getBearerToken(opts?: {
+        readonly forceRefresh?: boolean;
+    }): Promise<string>;
+    /** Stable name used in logs and metrics (e.g. `"oauth2"`, `"reseller"`). */
+    readonly name: string;
+}
+//# sourceMappingURL=auth.d.ts.map

package/dist/types/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/types/auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH;;;;;;;GAOG;AACH,MAAM,WAAW,mBAAmB;IAClC,2EAA2E;IAC3E,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,2CAA2C;IAC3C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,6CAA6C;IAC7C,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC;IAC9B,sCAAsC;IACtC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,sDAAsD;IACtD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAMD;;;;;;;;GAQG;AACH,MAAM,WAAW,4BAA4B;IAC3C,gDAAgD;IAChD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,qCAAqC;IACrC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,qDAAqD;IACrD,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAMD;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;OAIG;IACH,cAAc,CAAC,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAE5E,4EAA4E;IAC5E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB"}

package/dist/types/auth.js

@@ -0,0 +1,12 @@
+/**
+ * Authentication types for the Viva Wallet ISV OAuth 2.0 and reseller
+ * basic-auth flows.
+ *
+ * Implementations live in S2 (packages/viva-payments-core/src/auth/).
+ * This file declares interfaces and response shapes only — no runtime code.
+ *
+ * @see references/viva-docs/md/oauth2-authentication.txt:179
+ * @see references/viva-docs/md/isv-credentials.txt:107
+ */
+export {};
+//# sourceMappingURL=auth.js.map

package/dist/types/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../../src/types/auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG"}

package/dist/types/card-types.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Viva's numeric CardTypeId → string scheme name mapping.
+ *
+ * Used by `Payments.retrieveTransaction` to populate the normalized
+ * `cardType: string` field for downstream consumers (e.g.,
+ * {@link import('../refunds/strategy.js').resolveRefundStrategy resolveRefundStrategy}).
+ *
+ * Mapping source: `references/viva-docs/md/wh-transaction-payment-created.txt`
+ * (search for `CardTypeId`). Viva documents the following nine values:
+ *
+ *   0 = Visa
+ *   1 = Mastercard
+ *   2 = Diners
+ *   3 = Amex
+ *   4 = Invalid
+ *   5 = Unknown
+ *   6 = Maestro
+ *   7 = Discover
+ *   8 = JCB
+ *
+ * Casing note:
+ *   `resolveRefundStrategy` matches the Fast-Refund eligible-scheme set
+ *   case-sensitively against the string emitted here. The strategy's set
+ *   uses `'MasterCard'` (camelCase). We emit `'MasterCard'` for cardTypeId
+ *   `1` to match — this is the only difference from the doc's raw casing.
+ *   Diners is emitted as the doc's `'Diners'` (no "Club") so future
+ *   eligibility additions key off a single canonical string.
+ *
+ *   The sentinel categories `Invalid` (4) and `Unknown` (5) are intentionally
+ *   NOT exposed as scheme strings — they indicate "no useful card info" and
+ *   `resolveCardType` returns `undefined` for them so the auto-refund
+ *   decision falls through to `auto-no-card-info`.
+ *
+ * @see references/viva-docs/md/wh-transaction-payment-created.txt — search "CardTypeId"
+ * @see ../refunds/strategy.ts (FAST_REFUND_ELIGIBLE_SCHEMES)
+ * @see docs/STATE-MACHINE.md §3.1
+ */
+export declare const CARD_TYPE_BY_ID: Readonly<Record<number, string>>;
+/**
+ * Pure helper — returns the string scheme name for a Viva numeric cardTypeId,
+ * or `undefined` if the id is null/undefined, a known sentinel (Invalid /
+ * Unknown), or not present in the documented mapping.
+ *
+ * Pure, no I/O. Safe to call from anywhere — including refund strategy
+ * decisions and tests.
+ */
+export declare function resolveCardType(cardTypeId: number | null | undefined): string | undefined;
+//# sourceMappingURL=card-types.d.ts.map

package/dist/types/card-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"card-types.d.ts","sourceRoot":"","sources":["../../src/types/card-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,eAAO,MAAM,eAAe,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAU3D,CAAC;AAEH;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,UAAU,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GACpC,MAAM,GAAG,SAAS,CAGpB"}