@sakeetech/vendure-payment-viva 0.2.1

package/dist/util/currency.js

@@ -0,0 +1,90 @@
+/**
+ * currency.ts — ISO 4217 alpha ↔ numeric conversion helpers.
+ *
+ * Viva's API requires numeric currency codes (e.g. 826 for GBP).
+ * Vendure stores alpha codes (e.g. 'GBP').
+ *
+ * @see references/viva-docs/md/wh-transaction-payment-created.txt:487
+ * @see docs/plans/vendure-plugin-v0.md §"Constraints" (Currency: Numeric ISO 4217)
+ */
+import { asCurrencyCode } from '@sakeetech/viva-payments-core/types';
+// ---------------------------------------------------------------------------
+// Lookup tables
+// ---------------------------------------------------------------------------
+/**
+ * ISO 4217 alpha → numeric mapping.
+ * Extend as new currencies are onboarded.
+ */
+const ALPHA_TO_NUMERIC = {
+    EUR: '978',
+    GBP: '826',
+    USD: '840',
+    PLN: '985',
+    RON: '946',
+    CZK: '203',
+    HUF: '348',
+    BGN: '975',
+    DKK: '208',
+    SEK: '752',
+    NOK: '578',
+    CHF: '756',
+    AUD: '036',
+    CAD: '124',
+    JPY: '392',
+    SGD: '702',
+    HKD: '344',
+    NZD: '554',
+    MXN: '484',
+    BRL: '986',
+    ZAR: '710',
+    TRY: '949',
+    ILS: '376',
+    AED: '784',
+    THB: '764',
+};
+const NUMERIC_TO_ALPHA = Object.fromEntries(Object.entries(ALPHA_TO_NUMERIC).map(([alpha, numeric]) => [numeric, alpha]));
+// ---------------------------------------------------------------------------
+// Converters
+// ---------------------------------------------------------------------------
+/**
+ * Convert ISO 4217 alpha code to branded numeric CurrencyCode.
+ * Throws if the alpha code is unknown.
+ *
+ * @example alphaToNumeric('GBP') // → '826' (branded CurrencyCode)
+ */
+export function alphaToNumeric(alpha) {
+    const upper = alpha.toUpperCase();
+    const numeric = ALPHA_TO_NUMERIC[upper];
+    if (!numeric) {
+        throw new Error(`Unknown ISO 4217 alpha currency code: "${alpha}"`);
+    }
+    return asCurrencyCode(numeric);
+}
+/**
+ * Convert ISO 4217 numeric string to alpha code.
+ * Coerces numeric input (string or number) defensively.
+ * Throws if the numeric code is unknown.
+ *
+ * @example numericToAlpha('826') // → 'GBP'
+ * @example numericToAlpha(826) // → 'GBP'
+ */
+export function numericToAlpha(numeric) {
+    const key = String(numeric).padStart(3, '0');
+    const alpha = NUMERIC_TO_ALPHA[key];
+    if (!alpha) {
+        throw new Error(`Unknown ISO 4217 numeric currency code: "${numeric}"`);
+    }
+    return alpha;
+}
+/**
+ * Coerce a webhook payload currency value (may be string or number) to the
+ * branded CurrencyCode type.  Throws on unknown code.
+ */
+export function coerceCurrencyCode(raw) {
+    const key = String(raw).padStart(3, '0');
+    if (!NUMERIC_TO_ALPHA[key]) {
+        throw new Error(`Unknown ISO 4217 numeric currency code: "${raw}"`);
+    }
+    return asCurrencyCode(key);
+}
+//# sourceMappingURL=currency.js.map

package/dist/util/currency.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"currency.js","sourceRoot":"","sources":["../../src/util/currency.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,qCAAqC,CAAC;AAGrE,8EAA8E;AAC9E,gBAAgB;AAChB,8EAA8E;AAE9E;;;GAGG;AACH,MAAM,gBAAgB,GAAqC;IACzD,GAAG,EAAE,KAAK;IACV,GAAG,EAAE,KAAK;IACV,GAAG,EAAE,KAAK;IACV,GAAG,EAAE,KAAK;IACV,GAAG,EAAE,KAAK;IACV,GAAG,EAAE,KAAK;IACV,GAAG,EAAE,KAAK;IACV,GAAG,EAAE,KAAK;IACV,GAAG,EAAE,KAAK;IACV,GAAG,EAAE,KAAK;IACV,GAAG,EAAE,KAAK;IACV,GAAG,EAAE,KAAK;IACV,GAAG,EAAE,KAAK;IACV,GAAG,EAAE,KAAK;IACV,GAAG,EAAE,KAAK;IACV,GAAG,EAAE,KAAK;IACV,GAAG,EAAE,KAAK;IACV,GAAG,EAAE,KAAK;IACV,GAAG,EAAE,KAAK;IACV,GAAG,EAAE,KAAK;IACV,GAAG,EAAE,KAAK;IACV,GAAG,EAAE,KAAK;IACV,GAAG,EAAE,KAAK;IACV,GAAG,EAAE,KAAK;IACV,GAAG,EAAE,KAAK;CACX,CAAC;AAEF,MAAM,gBAAgB,GAAqC,MAAM,CAAC,WAAW,CAC3E,MAAM,CAAC,OAAO,CAAC,gBAAgB,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,EAAE,OAAO,CAAC,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,CAC7E,CAAC;AAEF,8EAA8E;AAC9E,aAAa;AACb,8EAA8E;AAE9E;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,KAAa;IAC1C,MAAM,KAAK,GAAG,KAAK,CAAC,WAAW,EAAE,CAAC;IAClC,MAAM,OAAO,GAAG,gBAAgB,CAAC,KAAK,CAAC,CAAC;IACxC,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CAAC,0CAA0C,KAAK,GAAG,CAAC,CAAC;IACtE,CAAC;IACD,OAAO,cAAc,CAAC,OAAO,CAAC,CAAC;AACjC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAAC,OAAwB;IACrD,MAAM,GAAG,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IAC7C,MAAM,KAAK,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAC;IACpC,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CAAC,4CAA4C,OAAO,GAAG,CAAC,CAAC;IAC1E,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,GAAoB;IACrD,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IACzC,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,EAAE,CAAC;QAC3B,MAAM,IAAI,KAAK,CAAC,4CAA4C,GAAG,GAAG,CAAC,CAAC;IACtE,CAAC;IACD,OAAO,cAAc,CAAC,GAAG,CAAC,CAAC;AAC7B,CAAC"}

package/dist/util/error-envelope.d.ts

@@ -0,0 +1,51 @@
+/**
+ * error-envelope.ts — VivaPluginError class for all plugin-level errors.
+ *
+ * One error class with static factories per error code.
+ * Mirrors the §"Error Contract" section of docs/plans/vendure-plugin-v0.md.
+ */
+export type VivaErrorCode = 'VIVA_AUTH_DOWN' | 'VIVA_API_ERROR' | 'VIVA_ACCOUNT_NOT_VERIFIED' | 'VIVA_ISV_AMOUNT_TOO_HIGH' | 'VIVA_CHANNEL_MISCONFIGURED' | 'VIVA_ORDER_NOT_FOUND' | 'VIVA_AMOUNT_MISMATCH' | 'VIVA_REFUND_REJECTED' | 'VIVA_FAST_REFUND_INELIGIBLE' | 'VIVA_MODE_MISMATCH' | 'VIVA_PAYMENT_ALREADY_SETTLED' | 'VIVA_PAYMENT_NOT_CANCELLABLE' | 'VIVA_ALREADY_ONBOARDED' | 'VIVA_RESELLER_CREDENTIALS_MISSING' | 'VIVA_SOURCE_CREATION_FAILED' | 'VIVA_INTERNAL_ERROR';
+export interface VivaPluginErrorOptions {
+    code: VivaErrorCode;
+    message: string;
+    retryable: boolean;
+    vivaErrorCode?: number;
+    vivaErrorMessage?: string;
+    cause?: unknown;
+}
+export declare class VivaPluginError extends Error {
+    readonly code: VivaErrorCode;
+    readonly retryable: boolean;
+    readonly vivaErrorCode: number | undefined;
+    readonly vivaErrorMessage: string | undefined;
+    readonly cause: unknown;
+    constructor(opts: VivaPluginErrorOptions);
+    toJSON(): Record<string, unknown>;
+    static authDown(message: string, cause?: unknown): VivaPluginError;
+    static apiError(opts: {
+        message: string;
+        vivaErrorCode?: number;
+        vivaErrorMessage?: string;
+        cause?: unknown;
+    }): VivaPluginError;
+    static accountNotVerified(message?: string): VivaPluginError;
+    static isvAmountTooHigh(isvAmount: number, amount: number): VivaPluginError;
+    static channelMisconfigured(message?: string): VivaPluginError;
+    static orderNotFound(message?: string): VivaPluginError;
+    static amountMismatch(expected: bigint | number, actual: bigint | number): VivaPluginError;
+    static refundRejected(message: string, cause?: unknown): VivaPluginError;
+    static fastRefundIneligible(message?: string, cause?: unknown): VivaPluginError;
+    static modeMismatch(message: string, cause?: unknown): VivaPluginError;
+    static paymentAlreadySettled(): VivaPluginError;
+    static paymentNotCancellable(reason?: string): VivaPluginError;
+    static alreadyOnboarded(accountId: string): VivaPluginError;
+    static resellerCredentialsMissing(message?: string): VivaPluginError;
+    static sourceCreationFailed(opts: {
+        message: string;
+        vivaStatus?: number;
+        vivaErrorCode?: number;
+        cause?: unknown;
+    }): VivaPluginError;
+    static internalError(message: string, cause?: unknown): VivaPluginError;
+}
+//# sourceMappingURL=error-envelope.d.ts.map

package/dist/util/error-envelope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-envelope.d.ts","sourceRoot":"","sources":["../../src/util/error-envelope.ts"],"names":[],"mappings":"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"}

package/dist/util/error-envelope.js

@@ -0,0 +1,157 @@
+/**
+ * error-envelope.ts — VivaPluginError class for all plugin-level errors.
+ *
+ * One error class with static factories per error code.
+ * Mirrors the §"Error Contract" section of docs/plans/vendure-plugin-v0.md.
+ */
+export class VivaPluginError extends Error {
+    code;
+    retryable;
+    vivaErrorCode;
+    vivaErrorMessage;
+    cause;
+    constructor(opts) {
+        super(opts.message);
+        Object.setPrototypeOf(this, new.target.prototype);
+        this.name = 'VivaPluginError';
+        this.code = opts.code;
+        this.retryable = opts.retryable;
+        this.vivaErrorCode = opts.vivaErrorCode;
+        this.vivaErrorMessage = opts.vivaErrorMessage;
+        this.cause = opts.cause;
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, new.target);
+        }
+    }
+    toJSON() {
+        return {
+            code: this.code,
+            message: this.message,
+            retryable: this.retryable,
+            ...(this.vivaErrorCode !== undefined ? { vivaErrorCode: this.vivaErrorCode } : {}),
+            ...(this.vivaErrorMessage !== undefined ? { vivaErrorMessage: this.vivaErrorMessage } : {}),
+        };
+    }
+    // ---------------------------------------------------------------------------
+    // Static factories
+    // ---------------------------------------------------------------------------
+    static authDown(message, cause) {
+        return new VivaPluginError({ code: 'VIVA_AUTH_DOWN', message, retryable: true, cause });
+    }
+    static apiError(opts) {
+        const o = {
+            code: 'VIVA_API_ERROR',
+            message: opts.message,
+            retryable: false,
+        };
+        if (opts.vivaErrorCode !== undefined)
+            o.vivaErrorCode = opts.vivaErrorCode;
+        if (opts.vivaErrorMessage !== undefined)
+            o.vivaErrorMessage = opts.vivaErrorMessage;
+        if (opts.cause !== undefined)
+            o.cause = opts.cause;
+        return new VivaPluginError(o);
+    }
+    static accountNotVerified(message) {
+        return new VivaPluginError({
+            code: 'VIVA_ACCOUNT_NOT_VERIFIED',
+            message: message ?? 'Viva payouts not enabled for this channel. Complete merchant verification first.',
+            retryable: false,
+        });
+    }
+    static isvAmountTooHigh(isvAmount, amount) {
+        return new VivaPluginError({
+            code: 'VIVA_ISV_AMOUNT_TOO_HIGH',
+            message: `ISV amount (${isvAmount}) must be strictly less than order amount (${amount}).`,
+            retryable: false,
+        });
+    }
+    static channelMisconfigured(message) {
+        return new VivaPluginError({
+            code: 'VIVA_CHANNEL_MISCONFIGURED',
+            message: message ?? 'Channel is missing vivaMerchantId configuration.',
+            retryable: false,
+        });
+    }
+    static orderNotFound(message) {
+        return new VivaPluginError({
+            code: 'VIVA_ORDER_NOT_FOUND',
+            message: message ?? 'Viva order or transaction not found.',
+            retryable: false,
+        });
+    }
+    static amountMismatch(expected, actual) {
+        return new VivaPluginError({
+            code: 'VIVA_AMOUNT_MISMATCH',
+            message: `Amount mismatch: expected ${expected}, got ${actual} from Viva.`,
+            retryable: false,
+        });
+    }
+    static refundRejected(message, cause) {
+        return new VivaPluginError({ code: 'VIVA_REFUND_REJECTED', message, retryable: false, cause });
+    }
+    static fastRefundIneligible(message, cause) {
+        return new VivaPluginError({
+            code: 'VIVA_FAST_REFUND_INELIGIBLE',
+            message: message ??
+                "Fast Refund ineligible (HTTP 403). Configured strategy 'fast' does not fall back. " +
+                    "Set refundStrategy='auto' to enable automatic Standard-refund fallback.",
+            retryable: false,
+            cause,
+        });
+    }
+    static modeMismatch(message, cause) {
+        return new VivaPluginError({
+            code: 'VIVA_MODE_MISMATCH',
+            message,
+            retryable: false,
+            cause,
+        });
+    }
+    static paymentAlreadySettled() {
+        return new VivaPluginError({
+            code: 'VIVA_PAYMENT_ALREADY_SETTLED',
+            message: 'Payment is already settled.',
+            retryable: false,
+        });
+    }
+    static paymentNotCancellable(reason) {
+        return new VivaPluginError({
+            code: 'VIVA_PAYMENT_NOT_CANCELLABLE',
+            message: reason ?? 'Payment cannot be cancelled in its current state.',
+            retryable: false,
+        });
+    }
+    static alreadyOnboarded(accountId) {
+        return new VivaPluginError({
+            code: 'VIVA_ALREADY_ONBOARDED',
+            message: `Channel already has accountId ${accountId}. Use the reconcile endpoint to refresh.`,
+            retryable: false,
+        });
+    }
+    static resellerCredentialsMissing(message) {
+        return new VivaPluginError({
+            code: 'VIVA_RESELLER_CREDENTIALS_MISSING',
+            message: message ??
+                'POST /viva/admin/connected-accounts/:id/sources requires reseller credentials. ' +
+                    'Set options.reseller = { resellerId, merchantId, resellerApiKey } in VivaPaymentPlugin.init().',
+            retryable: false,
+        });
+    }
+    static sourceCreationFailed(opts) {
+        const o = {
+            code: 'VIVA_SOURCE_CREATION_FAILED',
+            message: opts.message,
+            retryable: false,
+        };
+        if (opts.vivaErrorCode !== undefined)
+            o.vivaErrorCode = opts.vivaErrorCode;
+        if (opts.cause !== undefined)
+            o.cause = opts.cause;
+        return new VivaPluginError(o);
+    }
+    static internalError(message, cause) {
+        return new VivaPluginError({ code: 'VIVA_INTERNAL_ERROR', message, retryable: false, cause });
+    }
+}
+//# sourceMappingURL=error-envelope.js.map

package/dist/util/error-envelope.js.map

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

package/dist/util/ip-allowlist.d.ts

@@ -0,0 +1,44 @@
+/**
+ * util/ip-allowlist.ts — IP allowlist helpers for the webhook receiver.
+ *
+ * Viva Wallet does not sign webhook bodies (no HMAC). Instead it publishes
+ * a set of source IPs/CIDRs that all webhook POSTs will originate from.
+ * We reject anything outside the allowlist.
+ *
+ * Source: references/viva-docs/md/webhooks-for-payments.txt lines 272–301.
+ *
+ * @see docs/plans/vendure-plugin-v0.md §D16
+ * @see docs/VENDURE-CONTRACT.MD §4 "Webhook receiver"
+ */
+import type { IncomingMessage } from 'node:http';
+/**
+ * Default allowlist = demo + production combined.
+ * A single deployment receives both (environment flag is for outbound calls only).
+ */
+export declare const DEFAULT_VIVA_IP_ALLOWLIST: string[];
+/**
+ * Determine whether the given source IP is permitted by the allowlist.
+ *
+ * Allowlist behaviour:
+ * - `false`      → allowlist disabled (dev/test convenience); always returns true.
+ * - `[]`         → empty list; behaves the same as disabled (always true) so that
+ *                  accidentally passing an empty array doesn't lock out every call.
+ * - `undefined`  → use Viva's published demo + production CIDRs.
+ * - `string[]`   → custom list; enforce it.
+ *
+ * Each entry may be a single IPv4 address or an IPv4 CIDR range.
+ */
+export declare function isIpAllowed(sourceIp: string, allowlist: string[] | false | undefined): boolean;
+/**
+ * Extract the source IP from an incoming request.
+ *
+ * Delegates to the core `extractClientIp` helper which walks `X-Forwarded-For`
+ * from the **rightmost** end, counting back `trustedProxyDepth` hops. The old
+ * "take leftmost X-F-F" behaviour was vulnerable to header spoofing (CSO
+ * Finding #2); see `docs/TODO-CSO.md`.
+ *
+ * @param trustedProxyDepth — number of trailing X-F-F hops set by trusted
+ *   proxies. 0 = ignore X-F-F (use socket); 1 = one reverse proxy; 2 = CDN+LB.
+ */
+export declare function getSourceIp(req: IncomingMessage, trustedProxyDepth?: number): string;
+//# sourceMappingURL=ip-allowlist.d.ts.map

package/dist/util/ip-allowlist.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ip-allowlist.d.ts","sourceRoot":"","sources":["../../src/util/ip-allowlist.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAqCjD;;;GAGG;AACH,eAAO,MAAM,yBAAyB,EAAE,MAAM,EAG7C,CAAC;AAyDF;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CACzB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EAAE,GAAG,KAAK,GAAG,SAAS,GACtC,OAAO,CAYT;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,eAAe,EAAE,iBAAiB,SAAI,GAAG,MAAM,CAE/E"}

package/dist/util/ip-allowlist.js

@@ -0,0 +1,139 @@
+/**
+ * util/ip-allowlist.ts — IP allowlist helpers for the webhook receiver.
+ *
+ * Viva Wallet does not sign webhook bodies (no HMAC). Instead it publishes
+ * a set of source IPs/CIDRs that all webhook POSTs will originate from.
+ * We reject anything outside the allowlist.
+ *
+ * Source: references/viva-docs/md/webhooks-for-payments.txt lines 272–301.
+ *
+ * @see docs/plans/vendure-plugin-v0.md §D16
+ * @see docs/VENDURE-CONTRACT.MD §4 "Webhook receiver"
+ */
+import { extractClientIp } from '@sakeetech/viva-payments-core/webhooks';
+// ---------------------------------------------------------------------------
+// Viva's published CIDRs (webhooks-for-payments.txt lines 274–301)
+// ---------------------------------------------------------------------------
+/**
+ * Production IP allowlist.
+ * Source: webhooks-for-payments.txt lines 276–287.
+ */
+const VIVA_PRODUCTION_IPS = [
+    '51.138.37.238',
+    '13.80.70.181',
+    '13.80.71.223',
+    '13.79.28.70',
+    '40.127.253.112/28',
+    '51.105.129.192/28',
+    '20.54.89.16',
+    '4.223.76.50',
+    '51.12.157.0/28',
+];
+/**
+ * Demo IP allowlist.
+ * Source: webhooks-for-payments.txt lines 291–301.
+ */
+const VIVA_DEMO_IPS = [
+    '20.50.240.57',
+    '40.74.20.78',
+    '195.167.87.181',
+    '195.167.87.180',
+    '20.13.195.185',
+    '135.225.16.50',
+];
+/**
+ * Default allowlist = demo + production combined.
+ * A single deployment receives both (environment flag is for outbound calls only).
+ */
+export const DEFAULT_VIVA_IP_ALLOWLIST = [
+    ...VIVA_PRODUCTION_IPS,
+    ...VIVA_DEMO_IPS,
+];
+// ---------------------------------------------------------------------------
+// CIDR / IP parsing helpers (zero-dep)
+// ---------------------------------------------------------------------------
+/**
+ * Parse an IPv4 address string into a 32-bit unsigned integer.
+ * Returns NaN on malformed input.
+ */
+function ipv4ToInt(ip) {
+    const parts = ip.trim().split('.');
+    if (parts.length !== 4)
+        return NaN;
+    let result = 0;
+    for (const part of parts) {
+        const n = Number(part);
+        if (!Number.isInteger(n) || n < 0 || n > 255)
+            return NaN;
+        result = (result << 8) | n;
+    }
+    // Force unsigned 32-bit.
+    return result >>> 0;
+}
+/**
+ * Check whether `ip` falls within the CIDR block `cidr`.
+ * Handles both single-host notation (`"1.2.3.4"`) and range notation
+ * (`"1.2.3.0/24"`).
+ */
+function isInCidr(ip, cidr) {
+    const slashIdx = cidr.indexOf('/');
+    if (slashIdx === -1) {
+        // Single IP comparison.
+        return ip.trim() === cidr.trim();
+    }
+    const networkIp = cidr.slice(0, slashIdx);
+    const prefixLen = Number(cidr.slice(slashIdx + 1));
+    if (!Number.isInteger(prefixLen) || prefixLen < 0 || prefixLen > 32)
+        return false;
+    const ipInt = ipv4ToInt(ip);
+    const netInt = ipv4ToInt(networkIp);
+    if (isNaN(ipInt) || isNaN(netInt))
+        return false;
+    if (prefixLen === 0)
+        return true; // 0.0.0.0/0 = all
+    const mask = prefixLen === 32 ? 0xffffffff : ~((1 << (32 - prefixLen)) - 1);
+    const maskU = mask >>> 0;
+    return (ipInt & maskU) === (netInt & maskU);
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Determine whether the given source IP is permitted by the allowlist.
+ *
+ * Allowlist behaviour:
+ * - `false`      → allowlist disabled (dev/test convenience); always returns true.
+ * - `[]`         → empty list; behaves the same as disabled (always true) so that
+ *                  accidentally passing an empty array doesn't lock out every call.
+ * - `undefined`  → use Viva's published demo + production CIDRs.
+ * - `string[]`   → custom list; enforce it.
+ *
+ * Each entry may be a single IPv4 address or an IPv4 CIDR range.
+ */
+export function isIpAllowed(sourceIp, allowlist) {
+    // Disabled check — dev/test bypass.
+    if (allowlist === false || (Array.isArray(allowlist) && allowlist.length === 0)) {
+        return true;
+    }
+    const list = allowlist ?? DEFAULT_VIVA_IP_ALLOWLIST;
+    for (const entry of list) {
+        if (isInCidr(sourceIp, entry))
+            return true;
+    }
+    return false;
+}
+/**
+ * Extract the source IP from an incoming request.
+ *
+ * Delegates to the core `extractClientIp` helper which walks `X-Forwarded-For`
+ * from the **rightmost** end, counting back `trustedProxyDepth` hops. The old
+ * "take leftmost X-F-F" behaviour was vulnerable to header spoofing (CSO
+ * Finding #2); see `docs/TODO-CSO.md`.
+ *
+ * @param trustedProxyDepth — number of trailing X-F-F hops set by trusted
+ *   proxies. 0 = ignore X-F-F (use socket); 1 = one reverse proxy; 2 = CDN+LB.
+ */
+export function getSourceIp(req, trustedProxyDepth = 0) {
+    return extractClientIp(req, trustedProxyDepth);
+}
+//# sourceMappingURL=ip-allowlist.js.map

package/dist/util/ip-allowlist.js.map

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

package/dist/util/normalize-options.d.ts

@@ -0,0 +1,24 @@
+/**
+ * util/normalize-options.ts — input validation + back-compat handling for
+ * `VivaPaymentPlugin.init()`.
+ *
+ * Takes the loose `VivaPaymentPluginInitInput` shape (which accepts deprecated
+ * field aliases and an optional `mode`) and returns the strict discriminated
+ * `VivaPaymentPluginOptions` union.
+ *
+ * Responsibilities:
+ *  1. Resolve deprecated `isvClientId`/`isvClientSecret` → `clientId`/`clientSecret`,
+ *     with one-time deprecation warnings.
+ *  2. Resolve `mode`: default to `'merchant'` (with a warning), or auto-detect
+ *     `'isv'` when ISV-only fields are present (no warning — strong hint).
+ *  3. Warn (don't throw) when merchant mode is paired with ISV-only resolvers.
+ *  4. Throw a single aggregated error if required fields are missing.
+ *
+ * Mirrors `medusa-payment-viva/src/config.ts` defaulting + back-compat behaviour
+ * (multi-mode-v0 plan §5, §10).
+ */
+import type { VivaPaymentPluginInitInput, VivaPaymentPluginOptions } from '../types.js';
+/** @internal Test-only: reset all one-time warning latches. */
+export declare function _resetInitNoticesForTesting(): void;
+export declare function normalizePluginOptions(input: VivaPaymentPluginInitInput): VivaPaymentPluginOptions;
+//# sourceMappingURL=normalize-options.d.ts.map

package/dist/util/normalize-options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize-options.d.ts","sourceRoot":"","sources":["../../src/util/normalize-options.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,KAAK,EAIV,0BAA0B,EAC1B,wBAAwB,EACzB,MAAM,aAAa,CAAC;AAWrB,+DAA+D;AAC/D,wBAAgB,2BAA2B,IAAI,IAAI,CAKlD;AAqBD,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,0BAA0B,GAChC,wBAAwB,CAgK1B"}