@sakeetech/viva-payments-core 0.2.1

package/dist/isv/legacy-basic-client.d.ts

@@ -0,0 +1,122 @@
+/**
+ * LegacyBasicClient — HTTP client for Viva legacy API endpoints (Basic auth).
+ *
+ * Viva exposes a subset of endpoints ONLY on their legacy host
+ * (`demo.vivapayments.com` / `www.vivapayments.com`) behind Basic auth
+ * (MerchantId:ApiKey). These endpoints are NOT available on the v2/OAuth2
+ * surface (`demo-api.vivapayments.com`).
+ *
+ * Verified against Viva sandbox 2026-04-25:
+ * - Refund: `POST /api/transactions/{transactionId}` on legacy host with Basic auth.
+ *   - Body: `application/x-www-form-urlencoded` — `Amount={minor}&SourceCode={code}`.
+ *   - Response: PascalCase JSON `{StatusId, Amount, TransactionId, ...}`.
+ *   - `POST /checkout/v2/transactions/{id}` (v2) returns 405 → NOT valid.
+ *
+ * Design:
+ *   - NOT a fallback. This is the PRIMARY (and only) client for legacy endpoints.
+ *   - Same retry / error-shape conventions as IsvHttpClient.
+ *   - Form-encoded body builder via URLSearchParams (built-in, zero deps).
+ *   - Tracing headers (`x-viva-correlationid`, `x-viva-eventid`) extracted and
+ *     attached to errors and successful responses.
+ *
+ * @see references/viva-docs/md/tut-create-recurring-payment.txt:288
+ * @see references/viva-docs/md/merchant-id-and-api-key.txt:1
+ */
+import type { Dispatcher } from 'undici';
+import type { VivaEnvironment } from '../types/index.js';
+import type { MetricsHook } from '../observability/index.js';
+export interface LegacyBasicClientConfig {
+    /**
+     * Viva environment selector. Determines legacy host.
+     *   demo       → https://demo.vivapayments.com
+     *   production → https://www.vivapayments.com
+     */
+    environment: VivaEnvironment;
+    /**
+     * Merchant ID (UUID). Used as the Basic-auth username.
+     * @see references/viva-docs/md/merchant-id-and-api-key.txt:1
+     */
+    merchantId: string;
+    /**
+     * API Key. Used as the Basic-auth password.
+     * @see references/viva-docs/md/merchant-id-and-api-key.txt:1
+     */
+    apiKey: string;
+    /** Override undici dispatcher for tests (e.g. MockAgent). */
+    dispatcher?: Dispatcher;
+    /** Override global fetch. Defaults to undici fetch when dispatcher is provided. */
+    fetchImpl?: typeof fetch;
+    /** Clock override for tests. Defaults to Date.now. */
+    now?: () => number;
+    /**
+     * Exponential backoff schedule in milliseconds.
+     * Default: [500, 1500, 4500].
+     */
+    retryBackoffsMs?: number[];
+    /** Jitter ratio applied to each backoff (±ratio * backoff). Default: 0.2. */
+    jitterRatio?: number;
+    /** Default per-request timeout in milliseconds. Default: 30_000. */
+    defaultTimeoutMs?: number;
+    /** Optional metrics hook. */
+    metrics?: MetricsHook;
+}
+export interface LegacyRequestOptions {
+    method: 'GET' | 'POST';
+    path: string;
+    /** Form-encoded key-value pairs (values coerced to string). */
+    formBody?: Record<string, string | number | bigint | undefined>;
+    /**
+     * When true: retries on 429 and 5xx per the backoff schedule.
+     * When false: only retries on connection-level errors.
+     */
+    idempotent: boolean;
+    timeoutMs?: number;
+    /** Endpoint label for metrics. */
+    endpoint?: string;
+}
+/**
+ * Wrapper returned from successful legacy API calls.
+ * Includes Viva tracing headers for observability.
+ */
+export interface LegacyApiResult<T> {
+    data: T;
+    /** `x-viva-correlationid` header value (e.g. "26-115-EDAA55BC"). */
+    vivaCorrelationId: string | undefined;
+    /** `x-viva-eventid` header value (e.g. "0"). */
+    vivaEventId: string | undefined;
+}
+/**
+ * HTTP client for Viva legacy API endpoints (Basic auth + legacy host).
+ *
+ * Instantiate once per (merchantId + apiKey + environment) tuple.
+ * Thread-safe; no shared mutable state.
+ */
+export declare class LegacyBasicClient {
+    private readonly legacyBaseUrl;
+    private readonly authorizationHeader;
+    private readonly dispatcher;
+    private readonly fetchImpl;
+    private readonly now;
+    private readonly backoffsMs;
+    private readonly jitterRatio;
+    private readonly defaultTimeoutMs;
+    private readonly metrics;
+    constructor(config: LegacyBasicClientConfig);
+    /**
+     * Execute a request against the Viva legacy API.
+     *
+     * Returns a `LegacyApiResult<T>` wrapping both the parsed response and the
+     * Viva tracing headers (`x-viva-correlationid`, `x-viva-eventid`).
+     *
+     * @see references/viva-docs/md/tut-create-recurring-payment.txt:288
+     */
+    request<T>(opts: LegacyRequestOptions): Promise<LegacyApiResult<T>>;
+    private _executeWithRetry;
+    private _attempt;
+    private _backoffMs;
+    private _retryAfterMs;
+    private _parseErrorBody;
+    private _isConnectionError;
+    private _sleep;
+}
+//# sourceMappingURL=legacy-basic-client.d.ts.map

package/dist/isv/legacy-basic-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"legacy-basic-client.d.ts","sourceRoot":"","sources":["../../src/isv/legacy-basic-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AAGzC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEzD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAO7D,MAAM,WAAW,uBAAuB;IACtC;;;;OAIG;IACH,WAAW,EAAE,eAAe,CAAC;IAE7B;;;OAGG;IACH,UAAU,EAAE,MAAM,CAAC;IAEnB;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf,6DAA6D;IAC7D,UAAU,CAAC,EAAE,UAAU,CAAC;IAExB,mFAAmF;IACnF,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IAEzB,sDAAsD;IACtD,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IAEnB;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAE3B,6EAA6E;IAC7E,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,oEAAoE;IACpE,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B,6BAA6B;IAC7B,OAAO,CAAC,EAAE,WAAW,CAAC;CACvB;AAED,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,KAAK,GAAG,MAAM,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC,CAAC;IAChE;;;OAGG;IACH,UAAU,EAAE,OAAO,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kCAAkC;IAClC,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC;IAChC,IAAI,EAAE,CAAC,CAAC;IACR,oEAAoE;IACpE,iBAAiB,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,gDAAgD;IAChD,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;CACjC;AA0BD;;;;;GAKG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAS;IAC7C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAyB;IACpD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;IACzC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAoB;IAC/C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAc;gBAE1B,MAAM,EAAE,uBAAuB;IAuB3C;;;;;;;OAOG;IACG,OAAO,CAAC,CAAC,EAAE,IAAI,EAAE,oBAAoB,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC;YAa3D,iBAAiB;YA0EjB,QAAQ;IA+DtB,OAAO,CAAC,UAAU;IAMlB,OAAO,CAAC,aAAa;IAUrB,OAAO,CAAC,eAAe;IA2BvB,OAAO,CAAC,kBAAkB;IAQ1B,OAAO,CAAC,MAAM;CAGf"}

package/dist/isv/legacy-basic-client.js

@@ -0,0 +1,281 @@
+/**
+ * LegacyBasicClient — HTTP client for Viva legacy API endpoints (Basic auth).
+ *
+ * Viva exposes a subset of endpoints ONLY on their legacy host
+ * (`demo.vivapayments.com` / `www.vivapayments.com`) behind Basic auth
+ * (MerchantId:ApiKey). These endpoints are NOT available on the v2/OAuth2
+ * surface (`demo-api.vivapayments.com`).
+ *
+ * Verified against Viva sandbox 2026-04-25:
+ * - Refund: `POST /api/transactions/{transactionId}` on legacy host with Basic auth.
+ *   - Body: `application/x-www-form-urlencoded` — `Amount={minor}&SourceCode={code}`.
+ *   - Response: PascalCase JSON `{StatusId, Amount, TransactionId, ...}`.
+ *   - `POST /checkout/v2/transactions/{id}` (v2) returns 405 → NOT valid.
+ *
+ * Design:
+ *   - NOT a fallback. This is the PRIMARY (and only) client for legacy endpoints.
+ *   - Same retry / error-shape conventions as IsvHttpClient.
+ *   - Form-encoded body builder via URLSearchParams (built-in, zero deps).
+ *   - Tracing headers (`x-viva-correlationid`, `x-viva-eventid`) extracted and
+ *     attached to errors and successful responses.
+ *
+ * @see references/viva-docs/md/tut-create-recurring-payment.txt:288
+ * @see references/viva-docs/md/merchant-id-and-api-key.txt:1
+ */
+import { fetch as undiciFetch } from 'undici';
+import { LEGACY_HOST } from '../types/index.js';
+import { VivaApiError, VivaAuthError, VivaRateLimitError } from '../errors/index.js';
+import { NoopMetricsHook } from '../observability/index.js';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+const DEFAULT_BACKOFFS_MS = [500, 1500, 4500];
+const DEFAULT_JITTER_RATIO = 0.2;
+const DEFAULT_TIMEOUT_MS = 30_000;
+const MAX_RETRIES = 3;
+const CONNECTION_ERROR_CODES = new Set([
+    'ECONNRESET',
+    'ENOTFOUND',
+    'ETIMEDOUT',
+    'ECONNREFUSED',
+    'ECONNABORTED',
+    'UND_ERR_CONNECT_TIMEOUT',
+    'UND_ERR_HEADERS_TIMEOUT',
+    'UND_ERR_BODY_TIMEOUT',
+]);
+// ---------------------------------------------------------------------------
+// LegacyBasicClient
+// ---------------------------------------------------------------------------
+/**
+ * HTTP client for Viva legacy API endpoints (Basic auth + legacy host).
+ *
+ * Instantiate once per (merchantId + apiKey + environment) tuple.
+ * Thread-safe; no shared mutable state.
+ */
+export class LegacyBasicClient {
+    legacyBaseUrl;
+    authorizationHeader;
+    dispatcher;
+    fetchImpl;
+    now;
+    backoffsMs;
+    jitterRatio;
+    defaultTimeoutMs;
+    metrics;
+    constructor(config) {
+        this.legacyBaseUrl = LEGACY_HOST[config.environment];
+        // Basic auth: Base64(merchantId:apiKey)
+        // @see references/viva-docs/md/merchant-id-and-api-key.txt:1
+        const encoded = Buffer.from(`${config.merchantId}:${config.apiKey}`).toString('base64');
+        this.authorizationHeader = `Basic ${encoded}`;
+        this.now = config.now ?? (() => Date.now());
+        this.backoffsMs = config.retryBackoffsMs ?? DEFAULT_BACKOFFS_MS;
+        this.jitterRatio = config.jitterRatio ?? DEFAULT_JITTER_RATIO;
+        this.defaultTimeoutMs = config.defaultTimeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.metrics = config.metrics ?? new NoopMetricsHook();
+        if (config.dispatcher) {
+            this.dispatcher = config.dispatcher;
+            this.fetchImpl = config.fetchImpl ?? undiciFetch;
+        }
+        else {
+            this.dispatcher = undefined;
+            this.fetchImpl = config.fetchImpl ?? undiciFetch;
+        }
+    }
+    /**
+     * Execute a request against the Viva legacy API.
+     *
+     * Returns a `LegacyApiResult<T>` wrapping both the parsed response and the
+     * Viva tracing headers (`x-viva-correlationid`, `x-viva-eventid`).
+     *
+     * @see references/viva-docs/md/tut-create-recurring-payment.txt:288
+     */
+    async request(opts) {
+        const endpoint = opts.endpoint ?? `${opts.method} ${opts.path}`;
+        return this.metrics.timeAsync('viva_legacy_api_request_duration_seconds', () => this._executeWithRetry(opts), { endpoint });
+    }
+    // --------------------------------------------------------------------------
+    // Private helpers
+    // --------------------------------------------------------------------------
+    async _executeWithRetry(opts) {
+        let attempt = 0;
+        // eslint-disable-next-line no-constant-condition
+        while (true) {
+            const { response, text } = await this._attempt(opts);
+            const vivaCorrelationId = response.headers.get('x-viva-correlationid') ?? undefined;
+            const vivaEventId = response.headers.get('x-viva-eventid') ?? undefined;
+            // --- happy path ---
+            if (response.status >= 200 && response.status < 300) {
+                if (!text || response.status === 204) {
+                    return { data: undefined, vivaCorrelationId, vivaEventId };
+                }
+                const data = JSON.parse(text);
+                return { data, vivaCorrelationId, vivaEventId };
+            }
+            // --- 401 ---
+            if (response.status === 401) {
+                throw new VivaAuthError({
+                    message: 'Viva legacy API authentication failed (HTTP 401) — check merchantId and apiKey',
+                    httpStatus: 401,
+                    requestId: vivaCorrelationId,
+                });
+            }
+            // --- 429 ---
+            if (response.status === 429) {
+                if (opts.idempotent && attempt < MAX_RETRIES) {
+                    const retryAfterMs = this._retryAfterMs(response) ?? this._backoffMs(attempt);
+                    await this._sleep(retryAfterMs);
+                    attempt++;
+                    continue;
+                }
+                const retryAfterMs = this._retryAfterMs(response);
+                throw new VivaRateLimitError({
+                    message: 'Viva legacy API rate limited (HTTP 429)',
+                    httpStatus: 429,
+                    requestId: vivaCorrelationId,
+                    ...(retryAfterMs !== undefined ? { retryAfterMs } : {}),
+                });
+            }
+            // --- 5xx ---
+            if (response.status >= 500) {
+                if (opts.idempotent && attempt < MAX_RETRIES) {
+                    const backoffMs = this._backoffMs(attempt);
+                    await this._sleep(backoffMs);
+                    attempt++;
+                    continue;
+                }
+                const { vivaCode, vivaMessage } = this._parseErrorBody(text);
+                throw new VivaApiError({
+                    message: vivaMessage ?? `Viva legacy API error (HTTP ${response.status})`,
+                    httpStatus: response.status,
+                    vivaCode,
+                    requestId: vivaCorrelationId,
+                });
+            }
+            // --- other 4xx ---
+            {
+                const { vivaCode, vivaMessage } = this._parseErrorBody(text);
+                throw new VivaApiError({
+                    message: vivaMessage ?? `Viva legacy API error (HTTP ${response.status})`,
+                    httpStatus: response.status,
+                    vivaCode,
+                    requestId: vivaCorrelationId,
+                });
+            }
+        }
+    }
+    async _attempt(opts) {
+        const url = `${this.legacyBaseUrl}${opts.path}`;
+        const timeoutMs = opts.timeoutMs ?? this.defaultTimeoutMs;
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+        const headers = {
+            Authorization: this.authorizationHeader,
+            Accept: 'application/json',
+        };
+        const fetchOptions = {
+            method: opts.method,
+            headers,
+            signal: controller.signal,
+        };
+        // Form-encode the body (Viva legacy API uses application/x-www-form-urlencoded)
+        if (opts.formBody && Object.keys(opts.formBody).length > 0) {
+            const params = new URLSearchParams();
+            for (const [k, v] of Object.entries(opts.formBody)) {
+                if (v !== undefined) {
+                    params.set(k, String(v));
+                }
+            }
+            fetchOptions.body = params.toString();
+            headers['Content-Type'] = 'application/x-www-form-urlencoded';
+        }
+        if (this.dispatcher) {
+            fetchOptions['dispatcher'] = this.dispatcher;
+        }
+        let maxConnectionRetries = opts.idempotent ? 0 : 1;
+        let connAttempt = 0;
+        // eslint-disable-next-line no-constant-condition
+        while (true) {
+            try {
+                const response = await this.fetchImpl(url, fetchOptions);
+                clearTimeout(timeoutId);
+                const text = await response.text();
+                return { response, text };
+            }
+            catch (err) {
+                clearTimeout(timeoutId);
+                const isConnectionError = this._isConnectionError(err);
+                const isAbort = err instanceof Error && err.name === 'AbortError';
+                if ((isConnectionError || isAbort) && !opts.idempotent && connAttempt < maxConnectionRetries) {
+                    connAttempt++;
+                    continue;
+                }
+                throw new VivaApiError({
+                    message: isAbort
+                        ? `Viva legacy API request timed out after ${timeoutMs}ms`
+                        : `Viva legacy API network error: ${err instanceof Error ? err.message : String(err)}`,
+                    cause: err,
+                });
+            }
+        }
+    }
+    _backoffMs(attempt) {
+        const base = this.backoffsMs[attempt] ?? this.backoffsMs[this.backoffsMs.length - 1] ?? 500;
+        const jitter = base * this.jitterRatio * (Math.random() * 2 - 1);
+        return Math.max(0, Math.round(base + jitter));
+    }
+    _retryAfterMs(response) {
+        const header = response.headers.get('Retry-After');
+        if (!header)
+            return undefined;
+        const seconds = parseFloat(header);
+        if (!isNaN(seconds))
+            return Math.max(0, Math.round(seconds * 1000));
+        const date = new Date(header).getTime();
+        if (!isNaN(date))
+            return Math.max(0, date - this.now());
+        return undefined;
+    }
+    _parseErrorBody(text) {
+        if (!text)
+            return {};
+        try {
+            const parsed = JSON.parse(text);
+            const vivaCode = typeof parsed['ErrorCode'] === 'number'
+                ? String(parsed['ErrorCode'])
+                : typeof parsed['errorCode'] === 'number'
+                    ? String(parsed['errorCode'])
+                    : typeof parsed['error'] === 'string'
+                        ? parsed['error']
+                        : undefined;
+            const vivaMessage = typeof parsed['Message'] === 'string'
+                ? parsed['Message']
+                : typeof parsed['message'] === 'string'
+                    ? parsed['message']
+                    : undefined;
+            const result = {};
+            if (vivaCode !== undefined)
+                result.vivaCode = vivaCode;
+            if (vivaMessage !== undefined)
+                result.vivaMessage = vivaMessage;
+            return result;
+        }
+        catch {
+            return {};
+        }
+    }
+    _isConnectionError(err) {
+        if (!(err instanceof Error))
+            return false;
+        const code = err.code;
+        if (code && CONNECTION_ERROR_CODES.has(code))
+            return true;
+        if (err.message.includes('ECONNRESET') || err.message.includes('ENOTFOUND'))
+            return true;
+        return false;
+    }
+    _sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+}
+//# sourceMappingURL=legacy-basic-client.js.map

package/dist/isv/legacy-basic-client.js.map

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

package/dist/isv/payments.d.ts

@@ -0,0 +1,199 @@
+/**
+ * IsvPayments — ISV Payment API methods.
+ *
+ * Covers:
+ *   - createOrder         → POST /checkout/v2/orders?merchantId={merchantId} (OAuth2)
+ *   - retrieveTransaction → GET /checkout/v2/transactions/{transactionId}    (OAuth2)
+ *   - refundPayment       → POST /api/transactions/{transactionId}           (Legacy/Basic)
+ *   - cancelOrder         → DELETE /checkout/v2/orders/{orderCode}           (OAuth2)
+ *
+ * All methods validate inputs locally before making HTTP calls.
+ * Amounts are in integer minor units (bigint) per plan P15.
+ *
+ * Idempotency: createOrder and refundPayment are non-idempotent (idempotent: false).
+ * retrieveTransaction and cancelOrder are idempotent.
+ *
+ * --- Refund path (F1 — probe-verified 2026-04-25) ---
+ * Viva returns 405 on `POST /checkout/v2/transactions/{id}` (v2/OAuth2 path).
+ * The ONLY working refund path is `POST /api/transactions/{transactionId}` on the
+ * LEGACY HOST (`demo.vivapayments.com` / `www.vivapayments.com`) with Basic auth
+ * (MerchantId + ApiKey). The 401-fallback design is NOT applicable here — Viva
+ * returns 405 (not 401) on the v2 path, so no fallback would ever trigger.
+ * refundPayment now calls `legacyClient` DIRECTLY without any v2 attempt.
+ *
+ * @see references/viva-docs/md/tut-create-recurring-payment.txt:288 (legacy refund endpoint)
+ *
+ * --- retrieveTransaction / cancelOrder fallback (D15 — kept defensive) ---
+ *   The optional `secondaryClient` is a fallback for retrieveTransaction and
+ *   cancelOrder. When the primary OAuth2 client returns 401 (after force-refresh),
+ *   the call retries once with the secondary client. A 401 from secondary surfaces
+ *   as VivaAuthError — no further retry.
+ *   Note: cancelOrder is unverified against live sandbox as of 2026-04-25 probe;
+ *   kept on OAuth2 + 401-fallback path defensively.
+ *
+ * --- Idempotency-Key header (F2 — probe-verified 2026-04-25) ---
+ *   The `Idempotency-Key` header is sent on createOrder but Viva does NOT appear
+ *   to deduplicate server-side (same key returned two different orderCodes in probe).
+ *   Local dedup via `viva_transaction` row is the authoritative dedup mechanism.
+ *   Header is retained for forward-compat (zero cost, may be honoured in future).
+ *
+ * @see references/viva-docs/md/payment-isv-api.txt:1
+ * @see references/viva-docs/md/webhooks-for-payments.txt:248 (retrieve before update)
+ * @see references/viva-docs/md/isv-partner-program.txt:104 (ISV overview)
+ * @see references/viva-docs/md/isv-credentials.txt:107 (reseller credentials)
+ * @see docs/plans/vendure-plugin-v0.md §D15 (reseller fallback scope)
+ */
+import type { IsvHttpClient } from './client.js';
+import type { LegacyBasicClient } from './legacy-basic-client.js';
+import type { CreateOrderRequest, CreateOrderResponse, RetrieveTransactionResponse, RefundResponse, CancelOrderResponse, MerchantId, TransactionId, OrderCode, MinorUnits } from '../types/index.js';
+/**
+ * ISV Payment API client.
+ *
+ * Constructed with an IsvHttpClient instance shared across all ISV modules.
+ * Each method scopes its request to a specific merchant via the merchantId
+ * query parameter per the ISV integration model.
+ *
+ * - `client`: primary OAuth2 client for createOrder, retrieveTransaction, cancelOrder.
+ * - `secondaryClient`: optional 401-fallback for retrieveTransaction and cancelOrder.
+ *   When undefined, 401 errors propagate normally.
+ * - `legacyClient`: REQUIRED for refundPayment. Calls `POST /api/transactions/{id}`
+ *   on the legacy host with Basic auth (MerchantId + ApiKey). If absent, refundPayment
+ *   throws `VIVA_REFUND_REJECTED` with a config-missing message.
+ *
+ * Probe-verified 2026-04-25: refund MUST go through legacy client — v2/OAuth2 path
+ * returns 405. cancelOrder is unverified but kept on v2/OAuth2 + 401-fallback defensively.
+ *
+ * @see references/viva-docs/md/tut-create-recurring-payment.txt:288 (legacy refund path)
+ * @see references/viva-docs/md/payment-isv-api.txt:1
+ * @see references/viva-docs/md/isv-partner-program.txt:61 (P1: merchant scoping)
+ * @see references/viva-docs/md/isv-credentials.txt:107 (reseller credentials)
+ * @see docs/plans/vendure-plugin-v0.md §D15 (reseller fallback)
+ */
+export declare class IsvPayments {
+    private readonly client;
+    private readonly secondaryClient?;
+    private readonly legacyClient?;
+    constructor(client: IsvHttpClient, secondaryClient?: IsvHttpClient | undefined, legacyClient?: LegacyBasicClient | undefined);
+    /**
+     * Create a payment order for a specific ISV merchant.
+     *
+     * Sends a POST /checkout/v2/orders?merchantId={merchantId} request.
+     * The `Idempotency-Key` header is sent on every call but Viva does NOT appear
+     * to deduplicate server-side as of 2026-04-25 (probe: same key → two different
+     * orderCodes). Local dedup via `viva_transaction` row is the authoritative
+     * dedup mechanism. Header retained for forward-compat only.
+     *
+     * Input validation (throws VivaValidationError before HTTP call):
+     *   - amountMinor must be > 0 (per plan P15)
+     *   - currencyCode must be a valid 3-digit numeric string (per plan P15)
+     *
+     * Non-idempotent: does not retry on 4xx/5xx (only connection-level errors).
+     *
+     * @see references/viva-docs/md/payment-isv-api.txt:1
+     * @see references/viva-docs/md/isv-partner-program.txt:61 (P14 idempotency)
+     * @see references/viva-docs/md/isv-partner-program.txt:83 (P15 amounts)
+     */
+    createOrder(req: CreateOrderRequest, opts: {
+        merchantId: MerchantId;
+        idempotencyKey: string;
+    }): Promise<CreateOrderResponse>;
+    /**
+     * Retrieve transaction details for a specific ISV merchant transaction.
+     *
+     * Per Viva docs, this SHOULD be called before updating any local transaction
+     * status on receipt of a webhook. Validates orderCode and statusId from Viva.
+     *
+     * Idempotent: safe to retry on 429 and 5xx.
+     *
+     * Path + auth verified 2026-04-25 (F3):
+     *   `GET /checkout/v2/transactions/{transactionId}` with OAuth2 Bearer → correct.
+     *   404 error envelope shape: `{"status": 404, "message": null, "eventId": "0"}`.
+     *   Note: `message` can be null — handle defensively.
+     *
+     * 401 → reseller fallback (D15) — kept DEFENSIVE:
+     *   If the primary OAuth2 client receives a 401 and secondaryClient is configured,
+     *   the request is retried once with the secondary (Reseller basic-auth) client.
+     *   A 401 from the secondary surfaces immediately as VivaAuthError — no further retry.
+     *   The primary path is verified working; fallback is defensive for edge-case tenants.
+     *
+     * @see references/viva-docs/md/webhooks-for-payments.txt:248 (retrieve before update)
+     * @see references/viva-docs/md/payment-isv-api.txt:1
+     * @see references/viva-docs/md/isv-credentials.txt:107 (reseller basic-auth)
+     * @see docs/plans/vendure-plugin-v0.md §D15 (reseller fallback scope)
+     */
+    retrieveTransaction(transactionId: TransactionId, opts?: {
+        merchantId?: MerchantId;
+    }): Promise<RetrieveTransactionResponse>;
+    /**
+     * Issue a full or partial refund for a captured transaction.
+     *
+     * IMPORTANT — probe-verified 2026-04-25 (F1):
+     *   Viva returns 405 Method Not Allowed on `POST /checkout/v2/transactions/{id}`
+     *   (the v2/OAuth2 path). The ONLY working refund path is:
+     *     `POST /api/transactions/{transactionId}` on the LEGACY HOST
+     *     (`demo.vivapayments.com` / `www.vivapayments.com`) with Basic auth
+     *     (MerchantId:ApiKey) and form-urlencoded body.
+     *
+     *   This method calls `legacyClient` DIRECTLY. The 401-fallback (D15) does NOT
+     *   apply here — Viva returns 405 (not 401) on the v2 path, so no fallback
+     *   could ever trigger.
+     *
+     *   If `legacyClient` is not configured (absent from constructor), this method
+     *   throws VivaValidationError with code VIVA_REFUND_REJECTED indicating that
+     *   the basic-auth credentials are required and missing.
+     *
+     * Per plan P18:
+     *   - Full refund: omit amountMinor (no Amount in form body per Viva convention).
+     *   - Partial refund: provide amountMinor > 0 (Amount sent in form body).
+     *   - ISV fee reverses automatically on refund (per isv-partner-program.txt:296).
+     *   - Failed refund (4xx) surfaces as VivaApiError; payment NOT marked refunded.
+     *
+     * Non-idempotent: does not retry on 4xx/5xx.
+     *
+     * Viva response fields (PascalCase, mapped to camelCase):
+     *   StatusId → statusId, Amount → amount, TransactionId → transactionId.
+     *
+     * @see references/viva-docs/md/tut-create-recurring-payment.txt:288 (legacy path + basic auth)
+     * @see references/viva-docs/md/isv-partner-program.txt:296 (ISV fee reversal on refund)
+     * @see references/viva-docs/md/merchant-id-and-api-key.txt:1 (basic auth credentials)
+     */
+    refundPayment(transactionId: TransactionId, opts: {
+        merchantId: MerchantId;
+        amountMinor?: MinorUnits;
+        sourceCode?: string;
+        idempotencyKey: string;
+    }): Promise<RefundResponse>;
+    /**
+     * Cancel an order that has not yet been paid.
+     *
+     * Idempotent per Viva docs: calling cancel on an already-cancelled or
+     * captured order returns the existing Viva response without error.
+     *
+     * Per plan P18: cancellation triggers webhook 4865 (Order Updated).
+     *
+     * Path: `DELETE /checkout/v2/orders/{orderCode}?merchantId={merchantId}` (OAuth2).
+     *
+     * UNVERIFIED against live sandbox as of 2026-04-25 probe. Only
+     * cancel-transaction (refund/reverse) was tested; cancel-order was not.
+     * Kept on v2/OAuth2 + 401-fallback path defensively.
+     *
+     * 401 → reseller fallback (D15) — kept DEFENSIVE:
+     *   If the primary OAuth2 client receives a 401 and secondaryClient is configured,
+     *   the request is retried once with the secondary (Reseller basic-auth) client.
+     *   A 401 from the secondary surfaces immediately as VivaAuthError — no further retry.
+     *
+     * Note: if cancelOrder already succeeded on Viva's side before any 401 is
+     * observed, a 4xx from Viva on a subsequent attempt signals the order is
+     * already cancelled (idempotent). The fallback does NOT apply to non-401
+     * errors — those propagate as VivaApiError unchanged.
+     *
+     * @see references/viva-docs/md/payment-isv-api.txt:1
+     * @see references/viva-docs/md/webhooks-for-payments.txt:205 (4865 Order Updated)
+     * @see references/viva-docs/md/isv-credentials.txt:107 (reseller basic-auth)
+     * @see docs/plans/vendure-plugin-v0.md §D15 (reseller fallback scope)
+     */
+    cancelOrder(orderCode: OrderCode, opts: {
+        merchantId: MerchantId;
+    }): Promise<CancelOrderResponse>;
+}
+//# sourceMappingURL=payments.d.ts.map

package/dist/isv/payments.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"payments.d.ts","sourceRoot":"","sources":["../../src/isv/payments.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,KAAK,EACV,kBAAkB,EAClB,mBAAmB,EACnB,2BAA2B,EAC3B,cAAc,EACd,mBAAmB,EACnB,UAAU,EACV,aAAa,EACb,SAAS,EACT,UAAU,EACX,MAAM,mBAAmB,CAAC;AAuB3B;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,WAAW;IAEpB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAC;IACjC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC;gBAFb,MAAM,EAAE,aAAa,EACrB,eAAe,CAAC,EAAE,aAAa,YAAA,EAC/B,YAAY,CAAC,EAAE,iBAAiB,YAAA;IAGnD;;;;;;;;;;;;;;;;;;OAkBG;IACG,WAAW,CACf,GAAG,EAAE,kBAAkB,EACvB,IAAI,EAAE;QAAE,UAAU,EAAE,UAAU,CAAC;QAAC,cAAc,EAAE,MAAM,CAAA;KAAE,GACvD,OAAO,CAAC,mBAAmB,CAAC;IA4C/B;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACG,mBAAmB,CACvB,aAAa,EAAE,aAAa,EAC5B,IAAI,GAAE;QAAE,UAAU,CAAC,EAAE,UAAU,CAAA;KAAO,GACrC,OAAO,CAAC,2BAA2B,CAAC;IA+DvC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgCG;IACG,aAAa,CACjB,aAAa,EAAE,aAAa,EAC5B,IAAI,EAAE;QACJ,UAAU,EAAE,UAAU,CAAC;QACvB,WAAW,CAAC,EAAE,UAAU,CAAC;QACzB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,cAAc,EAAE,MAAM,CAAC;KACxB,GACA,OAAO,CAAC,cAAc,CAAC;IAuD1B;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACG,WAAW,CACf,SAAS,EAAE,SAAS,EACpB,IAAI,EAAE;QAAE,UAAU,EAAE,UAAU,CAAA;KAAE,GAC/B,OAAO,CAAC,mBAAmB,CAAC;CAgChC"}