@sakeetech/vendure-payment-viva 0.2.1

package/dist/services/state-machine.service.js

@@ -0,0 +1,233 @@
+/**
+ * services/state-machine.service.ts — Low-level VivaTransaction row helpers
+ * AND Vendure order/payment transition wrappers (V7 extension).
+ *
+ * Row helpers: INSERT-OR-NOTHING idempotent writes + lookups for VivaTransaction.
+ * Transition helpers: wraps OrderService + PaymentService state-machine calls;
+ *   used exclusively by the webhook worker (V7). Implements the stale-recovery
+ *   re-walk (AddingItems → ArrangingPayment → PaymentAuthorized → PaymentSettled)
+ *   with fail-loud semantics per Q4 decision.
+ *
+ * Repository injection via Vendure's TransactionalConnection.
+ *
+ * @see docs/plans/vendure-plugin-v0.md §"Build Plan — V5 + V7"
+ * @see docs/plans/vendure-plugin-v0.md §D6 (state transitions via OrderService)
+ * @see docs/plans/vendure-plugin-v0.md §D11 (idempotency)
+ */
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+import { Injectable, Logger as NestLogger } from '@nestjs/common';
+import { TransactionalConnection, Logger, OrderService, PaymentService } from '@vendure/core';
+import { QueryFailedError } from 'typeorm';
+import { VivaTransaction } from '../entities/viva-transaction.entity.js';
+import { VIVA_LOG_CONTEXT } from '../constants.js';
+// ---------------------------------------------------------------------------
+// Service
+// ---------------------------------------------------------------------------
+let StateMachineService = class StateMachineService {
+    connection;
+    orderService;
+    paymentService;
+    constructor(connection, orderService, paymentService) {
+        this.connection = connection;
+        this.orderService = orderService;
+        this.paymentService = paymentService;
+    }
+    /**
+     * Load a VivaTransaction row by (channelId, paymentId).
+     * Returns null if not found.
+     */
+    async getVivaTransaction(ctx, channelId, paymentId) {
+        const repo = this.connection.getRepository(ctx, VivaTransaction);
+        return repo.findOne({
+            where: { channelId: channelId, paymentId: paymentId },
+        });
+    }
+    /**
+     * INSERT-OR-NOTHING write of a pending VivaTransaction row.
+     *
+     * Idempotency key D11: keyed on (channelId, paymentId).
+     * If a row already exists with the same key and a non-null vivaOrderCode,
+     * returns that existing row so the handler can skip the Viva API call.
+     *
+     * Returns: { row, wasInserted }
+     *   wasInserted=true  → freshly inserted; handler must call Viva.
+     *   wasInserted=false → already existed; check row.vivaOrderCode.
+     */
+    async upsertPendingTransaction(ctx, input) {
+        const repo = this.connection.getRepository(ctx, VivaTransaction);
+        // Check if already exists
+        const existing = await repo.findOne({
+            where: {
+                channelId: input.channelId,
+                paymentId: input.paymentId,
+            },
+        });
+        if (existing) {
+            return { row: existing, wasInserted: false };
+        }
+        // Try to INSERT; handle race condition via duplicate-key error.
+        const row = repo.create({
+            channelId: input.channelId,
+            paymentId: input.paymentId,
+            status: 'pending',
+            vivaOrderCode: null,
+            vivaTransactionId: null,
+            amountMinor: input.amountMinor.toString(),
+            currencyCode: input.currencyCode,
+            isvAmountMinor: input.isvAmountMinor.toString(),
+            metadata: { idempotencyKey: input.idempotencyKey },
+        });
+        try {
+            const saved = await repo.save(row);
+            return { row: saved, wasInserted: true };
+        }
+        catch (err) {
+            // Duplicate key: another request beat us to the insert (race).
+            if (err instanceof QueryFailedError && this._isDuplicateKeyError(err)) {
+                const existing2 = await repo.findOne({
+                    where: {
+                        channelId: input.channelId,
+                        paymentId: input.paymentId,
+                    },
+                });
+                if (existing2) {
+                    return { row: existing2, wasInserted: false };
+                }
+            }
+            throw err;
+        }
+    }
+    /**
+     * Update the vivaOrderCode on a pending row after createOrder succeeds.
+     */
+    async setOrderCode(ctx, rowId, vivaOrderCode, metadata) {
+        const repo = this.connection.getRepository(ctx, VivaTransaction);
+        // Use query builder to avoid exactOptionalPropertyTypes issues with TypeORM _QueryDeepPartialEntity.
+        await repo
+            .createQueryBuilder()
+            .update(VivaTransaction)
+            .set({ vivaOrderCode, metadata: () => ':meta' })
+            .where('id = :id', { id: rowId })
+            .setParameter('meta', JSON.stringify(metadata))
+            .execute();
+    }
+    /**
+     * Update row status (e.g. pending → captured, pending → cancelled).
+     */
+    async setStatus(ctx, rowId, status, metadata) {
+        const repo = this.connection.getRepository(ctx, VivaTransaction);
+        if (metadata !== undefined) {
+            await repo
+                .createQueryBuilder()
+                .update(VivaTransaction)
+                .set({ status, metadata: () => ':meta' })
+                .where('id = :id', { id: rowId })
+                .setParameter('meta', JSON.stringify(metadata))
+                .execute();
+        }
+        else {
+            await repo
+                .createQueryBuilder()
+                .update(VivaTransaction)
+                .set({ status })
+                .where('id = :id', { id: rowId })
+                .execute();
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // Order / Payment transition helpers (V7)
+    // ---------------------------------------------------------------------------
+    /**
+     * Transition a Payment to `Settled` via `PaymentService.transitionToState`.
+     *
+     * Vendure's canonical path for webhook-driven settlement.
+     * @see docs/plans/vendure-plugin-v0.md §D6, §D5 (1796 settle path)
+     */
+    async transitionPaymentToSettled(ctx, orderId, paymentId) {
+        // Vendure state machine: Created → Authorized → Settled
+        // OrderService.settlePayment handles the two-step transition internally.
+        const result = await this.orderService.settlePayment(ctx, paymentId);
+        if ('errorCode' in result) {
+            throw new Error(`[StateMachineService] Failed to settle payment ${String(paymentId)} for order ${String(orderId)}: ${result.message ?? JSON.stringify(result)}`);
+        }
+    }
+    /**
+     * Transition a Payment to `Declined` via `PaymentService.transitionToState`.
+     *
+     * Called on webhook 1798 (Transaction Failed). Order stays in ArrangingPayment.
+     * @see docs/plans/vendure-plugin-v0.md §D5 (1798 path)
+     */
+    async transitionPaymentToDeclined(ctx, paymentId) {
+        await this.paymentService.transitionToState(ctx, paymentId, 'Declined');
+    }
+    /**
+     * Transition a Payment to `Cancelled` via `PaymentService.transitionToState`.
+     *
+     * Called on webhook 4865 user-cancel detection.
+     * @see docs/plans/vendure-plugin-v0.md §D5 (4865 path)
+     */
+    async transitionPaymentToCancelled(ctx, paymentId) {
+        await this.paymentService.transitionToState(ctx, paymentId, 'Cancelled');
+    }
+    /**
+     * Stale-order re-walk: AddingItems → ArrangingPayment → PaymentSettled.
+     *
+     * Implements the Q4 decision: fail-loud on any transition failure — log an
+     * ERROR-level message, throw, let the webhook row stay unprocessed. The
+     * storefront will surface "basket changed" via the live order state.
+     *
+     * Sequence:
+     *   1. AddingItems → ArrangingPayment    (transitionOrderToState)
+     *   2. ArrangingPayment → settlePayment  (OrderService.settlePayment)
+     *
+     * @see docs/plans/vendure-plugin-v0.md §"Process flow" step 4e
+     * @see docs/plans/vendure-plugin-v0.md §"Architecture Decisions Q4"
+     */
+    async recoverStaleOrderAndSettle(ctx, orderId, paymentId) {
+        Logger.info(`[StateMachineService] Starting stale-order re-walk for order ${String(orderId)}, payment ${String(paymentId)}.`, VIVA_LOG_CONTEXT);
+        // Step 1: AddingItems → ArrangingPayment
+        const transitionResult = await this.orderService.transitionToState(ctx, orderId, 'ArrangingPayment');
+        if ('errorCode' in transitionResult) {
+            const msg = `[StateMachineService] Stale re-walk FAILED on AddingItems→ArrangingPayment for order ${String(orderId)}: ${transitionResult.message ?? JSON.stringify(transitionResult)}`;
+            Logger.error(msg, VIVA_LOG_CONTEXT);
+            throw new Error(msg);
+        }
+        // Step 2: ArrangingPayment → settle (Created → Authorized → Settled)
+        const settleResult = await this.orderService.settlePayment(ctx, paymentId);
+        if ('errorCode' in settleResult) {
+            const msg = `[StateMachineService] Stale re-walk FAILED on settlePayment for order ${String(orderId)}, payment ${String(paymentId)}: ${settleResult.message ?? JSON.stringify(settleResult)}`;
+            Logger.error(msg, VIVA_LOG_CONTEXT);
+            throw new Error(msg);
+        }
+        Logger.info(`[StateMachineService] Stale re-walk complete: order ${String(orderId)} now PaymentSettled.`, VIVA_LOG_CONTEXT);
+    }
+    // ---------------------------------------------------------------------------
+    // Private helpers
+    // ---------------------------------------------------------------------------
+    _isDuplicateKeyError(err) {
+        const msg = err.code ?? '';
+        // Postgres unique violation
+        if (msg === '23505')
+            return true;
+        // SQLite UNIQUE constraint
+        if (err.message.toLowerCase().includes('unique'))
+            return true;
+        return false;
+    }
+};
+StateMachineService = __decorate([
+    Injectable(),
+    __metadata("design:paramtypes", [TransactionalConnection,
+        OrderService,
+        PaymentService])
+], StateMachineService);
+export { StateMachineService };
+//# sourceMappingURL=state-machine.service.js.map

package/dist/services/state-machine.service.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,286 @@
+/**
+ * types.ts — Public configuration types for VivaPaymentPlugin.
+ *
+ * v0.2.0: `VivaPaymentPluginOptions` is now a **discriminated union** on `mode`.
+ *
+ * - `mode: 'isv'` (default until 0.3.0) — multi-merchant ISV partner setup.
+ * - `mode: 'merchant'` — single direct Viva merchant, no reseller hierarchy.
+ *
+ * Field rename (one-minor back-compat):
+ *   - `isvClientId`  → `clientId`     (old name accepted with deprecation warning)
+ *   - `isvClientSecret` → `clientSecret`
+ *
+ * Plan ref: docs/plans/multi-mode-v0.md §5 (config shape), §10 (Vendure adapter).
+ *
+ * Vendure types (RequestContext, Order) are imported as peer-dep types only —
+ * no runtime Vendure import here so the types module is safe to import in
+ * non-Vendure test environments.
+ *
+ * viva-payments-core types are imported from sub-paths to avoid pulling in
+ * implementation code.
+ */
+import type { MetricsHook, OTelTracerHook, Logger } from '@sakeetech/viva-payments-core/observability';
+import type { VivaEnvironment } from '@sakeetech/viva-payments-core/types';
+/**
+ * Minimal shape of Vendure's RequestContext used in plugin callbacks.
+ * Avoids importing @vendure/core in this file so unit tests don't require
+ * the full Vendure dependency graph.
+ */
+export interface VendureRequestContext {
+    readonly channelId: string | number;
+    readonly channel: {
+        readonly id: string | number;
+        readonly code: string;
+        readonly customFields: Record<string, any>;
+    };
+    readonly apiType: string;
+}
+/**
+ * Minimal shape of Vendure's Order used in plugin callbacks.
+ */
+export interface VendureOrder {
+    readonly id: string | number;
+    readonly code: string;
+    readonly totalWithTax: number;
+    readonly currencyCode: string;
+    readonly state: string;
+}
+export interface RedlockClient {
+    acquire(resources: string[], duration: number): Promise<{
+        release(): Promise<void>;
+    }>;
+}
+export type VivaMode = 'merchant' | 'isv';
+/**
+ * Fields shared by both merchant and ISV mode configurations.
+ *
+ * Field-name rationale:
+ *  - `clientId` / `clientSecret` — mode-agnostic OAuth2 client_credentials.
+ *    Renamed from `isvClientId` / `isvClientSecret` in 0.2.0. Old names still
+ *    accepted via `init()` with a deprecation warning (removal in 0.3.0).
+ *  - `legacyMerchantId` / `legacyApiKey` — Basic-auth pair against the legacy
+ *    host. Required in both modes for Standard refund + IsvSources merchant
+ *    variant. Probe-verified 2026-04-25 (F1): POST /checkout/v2/transactions/{id}
+ *    returns 405, only the legacy host works for refunds.
+ */
+export interface VivaCommonOptions {
+    /** Target environment. Switches Viva API base URL. */
+    environment: VivaEnvironment;
+    /**
+     * OAuth2 client_credentials — mode-agnostic.
+     * (The credential pair differs by Self Care location, but the field shape
+     * is the same in both modes.)
+     *
+     * @see references/viva-docs/md/oauth2-authentication.txt:119
+     */
+    clientId: string;
+    /** OAuth2 client_credentials — paired with `clientId`. */
+    clientSecret: string;
+    /**
+     * Viva Merchant ID (UUID) for the legacy Basic-auth API.
+     * Required for `createRefund` to work.
+     *
+     * @see references/viva-docs/md/merchant-id-and-api-key.txt:1
+     * @see references/viva-docs/md/tut-create-recurring-payment.txt:288
+     */
+    legacyMerchantId: string;
+    /**
+     * Viva API Key for the legacy Basic-auth API.
+     * Required for `createRefund` to work. Paired with `legacyMerchantId`.
+     *
+     * @see references/viva-docs/md/merchant-id-and-api-key.txt:1
+     */
+    legacyApiKey: string;
+    /**
+     * URL-verification key returned on Viva's GET probe at registration.
+     * NOT a per-request HMAC. Generated by `vendure-viva-register-webhooks` CLI.
+     */
+    webhookVerificationKey: string;
+    /**
+     * Storefront success URL after Smart Checkout completes.
+     * `{orderCode}` placeholder is substituted server-side after Viva returns the
+     * order code. `{channel.origin}` substitution is the SaaS's responsibility.
+     */
+    successUrl: string | ((ctx: VendureRequestContext) => string);
+    /**
+     * Storefront failure URL after Smart Checkout is cancelled or fails.
+     * Same substitution rules as `successUrl`.
+     */
+    failureUrl: string | ((ctx: VendureRequestContext) => string);
+    /**
+     * Refund strategy. Defaults to `'auto'`.
+     *
+     * 'auto'     — pick fast or standard based on transaction state.
+     * 'fast'     — POST /api/transactions/refund (fast/OAuth2 path).
+     * 'standard' — POST /api/transactions/{id} (legacy Basic auth).
+     */
+    refundStrategy?: 'auto' | 'fast' | 'standard';
+    /**
+     * Redlock client for multi-worker distributed semaphore.
+     * Default: in-process semaphore only (5 permits per merchantId).
+     */
+    redlock?: RedlockClient;
+    /**
+     * Structured logger. Default: Vendure's built-in logger (Logger from
+     * @sakeetech/viva-payments-core/observability).
+     */
+    logger?: Logger;
+    /**
+     * Metrics hook for Prometheus-style counters + histograms.
+     * Default: NoopMetricsHook.
+     */
+    metricsHook?: MetricsHook;
+    /**
+     * OpenTelemetry tracer hook.
+     * Default: NoopTracerHook (no-op).
+     */
+    tracer?: OTelTracerHook;
+    /**
+     * IP allowlist for webhook receiver.
+     * Default: Viva's published demo + production CIDRs.
+     */
+    webhookIpAllowlist?: string[];
+    /**
+     * How many trailing `X-Forwarded-For` hops are set by infrastructure you
+     * actually control. The webhook source-IP check walks the X-F-F chain from
+     * the **rightmost** end and picks the entry `trustedProxyDepth` from the
+     * end. Defaults to `0` — ignore X-F-F entirely and use the socket address,
+     * which is safe for direct exposure but rejects every webhook when a real
+     * proxy sits in front.
+     *
+     * Typical values:
+     *   0 — no proxy / direct exposure (default)
+     *   1 — one reverse proxy (nginx, Caddy, ALB)
+     *   2 — CDN in front of LB (e.g. Cloudflare → ALB)
+     *
+     * CSO Finding #2 (HIGH): leaving this at the implicit "trust leftmost X-F-F"
+     * default lets any client claim to be a whitelisted Viva IP.
+     *
+     * @see docs/TODO-CSO.md "Finding 2"
+     */
+    trustedProxyDepth?: number;
+}
+/**
+ * Merchant-mode config. Used when the plugin acts on behalf of a single
+ * direct Viva merchant account (no reseller hierarchy).
+ *
+ * NOTE (slice A, v0.2.0): runtime entry points (createPayment, settlePayment,
+ * cancelPayment, createRefund) currently throw `VIVA_MODE_MISMATCH` —
+ * merchant-mode handlers ship in Phase 3 slice B.
+ */
+export interface VivaMerchantOptions extends VivaCommonOptions {
+    mode: 'merchant';
+    /**
+     * Optional Smart Checkout sourceCode. Defaults to `'Default'` when unset.
+     *
+     * @see references/viva-docs/md/payment-source-for-isv.txt:101
+     */
+    sourceCode?: string;
+    /**
+     * Optional hex color (no leading `#`) for Smart Checkout theming.
+     * Appended as `&color=<value>` to the Smart Checkout redirect URL.
+     */
+    checkoutColor?: string;
+}
+/**
+ * ISV-mode config. Used when the plugin acts on behalf of merchants under
+ * an ISV partner agreement. All per-tenant resolvers + onboarding fields
+ * live here.
+ */
+export interface VivaIsvOptions extends VivaCommonOptions {
+    mode: 'isv';
+    /**
+     * Resolve the Viva merchantId UUID for the current channel.
+     * Default: reads `ctx.channel.customFields.vivaMerchantId`.
+     */
+    resolveMerchantId?: (ctx: VendureRequestContext) => string;
+    /**
+     * Resolve the Viva source code for the current channel.
+     * Default: reads `ctx.channel.customFields.vivaSourceCode ?? 'Default'`.
+     */
+    resolveSourceCode?: (ctx: VendureRequestContext) => string;
+    /**
+     * Resolve the ISV platform fee (in minor units) for an order.
+     * MUST return a value strictly less than the order total; plugin validates
+     * this and throws `VIVA_ISV_AMOUNT_TOO_HIGH` if violated.
+     * Default: `() => 0`.
+     */
+    resolveIsvAmount?: (order: VendureOrder, ctx: VendureRequestContext) => number;
+    /**
+     * Resolve an optional checkout theme color (hex string, no leading `#`).
+     * Appended as `&color=<value>` to the Smart Checkout redirect URL.
+     * Default: `() => undefined` (no color param).
+     */
+    resolveCheckoutColor?: (ctx: VendureRequestContext) => string | undefined;
+    /**
+     * Required by `POST /isv/v1/accounts` — the URL the merchant is sent back to
+     * after completing the Viva-hosted onboarding flow. Probe-verified 2026-05-11:
+     * the ISV API rejects the create call when this field is absent.
+     *
+     * The admin-onboarding controller falls back to the per-request `overrides.returnUrl`
+     * if a caller supplies one; otherwise this value is used.
+     */
+    onboardingReturnUrl: string | ((ctx: VendureRequestContext) => string);
+    /**
+     * Optional ISV branding shown on Viva's onboarding pages.
+     * When supplied, all three of `partnerName`, `logoUrl` (and optionally
+     * `primaryColor`) are passed verbatim to `POST /isv/v1/accounts`.
+     */
+    onboardingBranding?: {
+        partnerName: string;
+        logoUrl: string;
+        /** Hex code, e.g. `#1F2439`. */
+        primaryColor?: string;
+    };
+    /**
+     * Reseller Basic-auth — required only when the plugin will call
+     * POST /api/sources (IsvSources). All three fields are all-or-nothing.
+     *
+     * @see references/viva-docs/md/payment-isv-api.txt:1
+     */
+    reseller?: {
+        resellerId: string;
+        merchantId: string;
+        resellerApiKey: string;
+    };
+}
+/**
+ * Configuration passed to `VivaPaymentPlugin.init(options)`.
+ *
+ * Discriminated union on `mode`. See `VivaMerchantOptions` and `VivaIsvOptions`.
+ *
+ * @see docs/plans/multi-mode-v0.md §5, §10
+ */
+export type VivaPaymentPluginOptions = VivaMerchantOptions | VivaIsvOptions;
+/**
+ * Loose shape `VivaPaymentPlugin.init()` accepts before normalization.
+ *
+ * - `mode` is optional — defaults to `'merchant'` with a startup warning (or
+ *   auto-detected as `'isv'` when ISV-only fields are present).
+ * - `clientId` / `clientSecret` may be replaced by their deprecated aliases
+ *   `isvClientId` / `isvClientSecret` (one-minor back-compat, removal in 0.3.0).
+ *
+ * Callers may pass any mix of merchant + ISV fields here; `init()` validates +
+ * narrows to the strict `VivaPaymentPluginOptions` union.
+ */
+export interface VivaPaymentPluginInitInput extends Partial<Omit<VivaCommonOptions, 'clientId' | 'clientSecret'>> {
+    mode?: VivaMode;
+    /** Preferred name (0.2.0+). */
+    clientId?: string;
+    /** Preferred name (0.2.0+). */
+    clientSecret?: string;
+    /** @deprecated Use `clientId`. Accepted for one minor (removal in 0.3.0). */
+    isvClientId?: string;
+    /** @deprecated Use `clientSecret`. Accepted for one minor (removal in 0.3.0). */
+    isvClientSecret?: string;
+    sourceCode?: string;
+    checkoutColor?: string;
+    resolveMerchantId?: (ctx: VendureRequestContext) => string;
+    resolveSourceCode?: (ctx: VendureRequestContext) => string;
+    resolveIsvAmount?: (order: VendureOrder, ctx: VendureRequestContext) => number;
+    resolveCheckoutColor?: (ctx: VendureRequestContext) => string | undefined;
+    onboardingReturnUrl?: string | ((ctx: VendureRequestContext) => string);
+    onboardingBranding?: VivaIsvOptions['onboardingBranding'];
+    reseller?: VivaIsvOptions['reseller'];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,23 @@
+/**
+ * types.ts — Public configuration types for VivaPaymentPlugin.
+ *
+ * v0.2.0: `VivaPaymentPluginOptions` is now a **discriminated union** on `mode`.
+ *
+ * - `mode: 'isv'` (default until 0.3.0) — multi-merchant ISV partner setup.
+ * - `mode: 'merchant'` — single direct Viva merchant, no reseller hierarchy.
+ *
+ * Field rename (one-minor back-compat):
+ *   - `isvClientId`  → `clientId`     (old name accepted with deprecation warning)
+ *   - `isvClientSecret` → `clientSecret`
+ *
+ * Plan ref: docs/plans/multi-mode-v0.md §5 (config shape), §10 (Vendure adapter).
+ *
+ * Vendure types (RequestContext, Order) are imported as peer-dep types only —
+ * no runtime Vendure import here so the types module is safe to import in
+ * non-Vendure test environments.
+ *
+ * viva-payments-core types are imported from sub-paths to avoid pulling in
+ * implementation code.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

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

package/dist/util/currency.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 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 type { CurrencyCode } from '@sakeetech/viva-payments-core/types';
+/**
+ * Convert ISO 4217 alpha code to branded numeric CurrencyCode.
+ * Throws if the alpha code is unknown.
+ *
+ * @example alphaToNumeric('GBP') // → '826' (branded CurrencyCode)
+ */
+export declare function alphaToNumeric(alpha: string): CurrencyCode;
+/**
+ * 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 declare function numericToAlpha(numeric: string | number): string;
+/**
+ * Coerce a webhook payload currency value (may be string or number) to the
+ * branded CurrencyCode type.  Throws on unknown code.
+ */
+export declare function coerceCurrencyCode(raw: string | number): CurrencyCode;
+//# sourceMappingURL=currency.d.ts.map

package/dist/util/currency.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"currency.d.ts","sourceRoot":"","sources":["../../src/util/currency.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qCAAqC,CAAC;AA8CxE;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY,CAO1D;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAO/D;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,YAAY,CAMrE"}