@sakeetech/medusa-payment-viva 0.2.2

package/dist/providers/payment-provider.d.ts

@@ -0,0 +1,19 @@
+/**
+ * providers/payment-provider.ts — Medusa v2 module provider definition.
+ *
+ * Exports the ModuleProvider wiring for the Viva payment provider.
+ * Use `ModuleProvider(Modules.PAYMENT, { services })` per Medusa v2 docs.
+ *
+ * Registration in medusa-config.ts:
+ *   {
+ *     resolve: "medusa-payment-viva",
+ *     id: "viva",
+ *     options: { config: loadConfigFromEnv() }
+ *   }
+ *
+ * @see https://docs.medusajs.com/resources/references/payment/provider#3-create-module-provider-definition-file
+ * @see references/viva-docs/md/isv-partner-program.txt:104
+ */
+declare const _default: import("@medusajs/types").ModuleProviderExports;
+export default _default;
+//# sourceMappingURL=payment-provider.d.ts.map

package/dist/providers/payment-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"payment-provider.d.ts","sourceRoot":"","sources":["../../src/providers/payment-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;;AAKH,wBAEG"}

package/dist/providers/payment-provider.js

@@ -0,0 +1,24 @@
+"use strict";
+/**
+ * providers/payment-provider.ts — Medusa v2 module provider definition.
+ *
+ * Exports the ModuleProvider wiring for the Viva payment provider.
+ * Use `ModuleProvider(Modules.PAYMENT, { services })` per Medusa v2 docs.
+ *
+ * Registration in medusa-config.ts:
+ *   {
+ *     resolve: "medusa-payment-viva",
+ *     id: "viva",
+ *     options: { config: loadConfigFromEnv() }
+ *   }
+ *
+ * @see https://docs.medusajs.com/resources/references/payment/provider#3-create-module-provider-definition-file
+ * @see references/viva-docs/md/isv-partner-program.txt:104
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const utils_1 = require("@medusajs/framework/utils");
+const service_js_1 = require("../service.js");
+exports.default = (0, utils_1.ModuleProvider)(utils_1.Modules.PAYMENT, {
+    services: [service_js_1.VivaPaymentProvider],
+});
+//# sourceMappingURL=payment-provider.js.map

package/dist/providers/payment-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"payment-provider.js","sourceRoot":"","sources":["../../src/providers/payment-provider.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;GAeG;;AAEH,qDAAoE;AACpE,8CAAoD;AAEpD,kBAAe,IAAA,sBAAc,EAAC,eAAO,CAAC,OAAO,EAAE;IAC7C,QAAQ,EAAE,CAAC,gCAAmB,CAAC;CAChC,CAAC,CAAC"}

package/dist/resolvers/auth-strategy-factory.d.ts

@@ -0,0 +1,42 @@
+/**
+ * auth-strategy-factory.ts — builds AuthStrategy instances from VivaPluginConfig.
+ *
+ * Constructs OAuth2ClientCredentialsStrategy with:
+ *   - InMemoryTokenCache + AsyncMutex (single-worker default, plan P11)
+ *   - Redis lock when config.redis is provided (multi-worker, plan P11)
+ *
+ * Builds ResellerBasicAuthStrategy only when `config.mode === 'isv'` and
+ * `config.reseller` is present (Q5 — some endpoints require reseller auth).
+ *
+ * @see references/viva-docs/md/oauth2-authentication.txt:119 (client_credentials)
+ * @see references/viva-docs/md/payment-isv-api.txt:1 (reseller credentials)
+ * @see references/viva-docs/md/isv-credentials.txt:107 (credential types)
+ */
+import { OAuth2ClientCredentialsStrategy, ResellerBasicAuthStrategy } from '@sakeetech/viva-payments-core/auth';
+import type { VivaPluginConfig } from '../config.js';
+export interface AuthStrategySet {
+    /** Primary OAuth2 bearer strategy — used for all standard ISV API calls. */
+    primary: OAuth2ClientCredentialsStrategy;
+    /**
+     * Reseller basic-auth strategy — used for endpoints that require it (Q5).
+     * Absent if config.mode !== 'isv' or config.reseller is not configured.
+     *
+     * @see references/viva-docs/md/payment-isv-api.txt:1 (reseller auth)
+     */
+    reseller?: ResellerBasicAuthStrategy;
+}
+/**
+ * Builds the full AuthStrategySet from the plugin config.
+ *
+ * Token lifecycle:
+ *   - InMemoryTokenCache is always created for the in-process cache.
+ *   - AsyncMutex is always created for single-flight de-duplication.
+ *   - If config.redis is provided, it is passed as `redisLock` to the
+ *     OAuth2 strategy which prefers the Redis distributed lock over the
+ *     in-process mutex (plan P11).
+ *
+ * @see references/viva-docs/md/oauth2-authentication.txt:128 (token endpoint)
+ * @see references/viva-docs/md/isv-credentials.txt:107 (auth strategies)
+ */
+export declare function buildAuthStrategies(config: VivaPluginConfig): AuthStrategySet;
+//# sourceMappingURL=auth-strategy-factory.d.ts.map

package/dist/resolvers/auth-strategy-factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-strategy-factory.d.ts","sourceRoot":"","sources":["../../src/resolvers/auth-strategy-factory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EACL,+BAA+B,EAC/B,yBAAyB,EAG1B,MAAM,oCAAoC,CAAC;AAC5C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAMrD,MAAM,WAAW,eAAe;IAC9B,4EAA4E;IAC5E,OAAO,EAAE,+BAA+B,CAAC;IACzC;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,yBAAyB,CAAC;CACtC;AAMD;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,gBAAgB,GAAG,eAAe,CA6B7E"}

package/dist/resolvers/auth-strategy-factory.js

@@ -0,0 +1,60 @@
+"use strict";
+/**
+ * auth-strategy-factory.ts — builds AuthStrategy instances from VivaPluginConfig.
+ *
+ * Constructs OAuth2ClientCredentialsStrategy with:
+ *   - InMemoryTokenCache + AsyncMutex (single-worker default, plan P11)
+ *   - Redis lock when config.redis is provided (multi-worker, plan P11)
+ *
+ * Builds ResellerBasicAuthStrategy only when `config.mode === 'isv'` and
+ * `config.reseller` is present (Q5 — some endpoints require reseller auth).
+ *
+ * @see references/viva-docs/md/oauth2-authentication.txt:119 (client_credentials)
+ * @see references/viva-docs/md/payment-isv-api.txt:1 (reseller credentials)
+ * @see references/viva-docs/md/isv-credentials.txt:107 (credential types)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildAuthStrategies = buildAuthStrategies;
+const auth_1 = require("@sakeetech/viva-payments-core/auth");
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+/**
+ * Builds the full AuthStrategySet from the plugin config.
+ *
+ * Token lifecycle:
+ *   - InMemoryTokenCache is always created for the in-process cache.
+ *   - AsyncMutex is always created for single-flight de-duplication.
+ *   - If config.redis is provided, it is passed as `redisLock` to the
+ *     OAuth2 strategy which prefers the Redis distributed lock over the
+ *     in-process mutex (plan P11).
+ *
+ * @see references/viva-docs/md/oauth2-authentication.txt:128 (token endpoint)
+ * @see references/viva-docs/md/isv-credentials.txt:107 (auth strategies)
+ */
+function buildAuthStrategies(config) {
+    const cache = new auth_1.InMemoryTokenCache();
+    const mutex = new auth_1.AsyncMutex();
+    const primary = new auth_1.OAuth2ClientCredentialsStrategy({
+        environment: config.environment,
+        clientId: config.clientId,
+        clientSecret: config.clientSecret,
+        cache,
+        mutex,
+        ...(config.redis !== undefined ? { redisLock: config.redis } : {}),
+    });
+    // Reseller strategy is ISV-only. Type-narrowed via discriminant.
+    const resellerConfig = config.mode === 'isv' ? config.reseller : undefined;
+    const reseller = resellerConfig !== undefined
+        ? new auth_1.ResellerBasicAuthStrategy({
+            resellerId: resellerConfig.resellerId,
+            merchantId: resellerConfig.merchantId,
+            resellerApiKey: resellerConfig.resellerApiKey,
+        })
+        : undefined;
+    return {
+        primary,
+        ...(reseller !== undefined ? { reseller } : {}),
+    };
+}
+//# sourceMappingURL=auth-strategy-factory.js.map

package/dist/resolvers/auth-strategy-factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-strategy-factory.js","sourceRoot":"","sources":["../../src/resolvers/auth-strategy-factory.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;GAaG;;AA2CH,kDA6BC;AAtED,6DAK4C;AAmB5C,8EAA8E;AAC9E,UAAU;AACV,8EAA8E;AAE9E;;;;;;;;;;;;GAYG;AACH,SAAgB,mBAAmB,CAAC,MAAwB;IAC1D,MAAM,KAAK,GAAG,IAAI,yBAAkB,EAAE,CAAC;IACvC,MAAM,KAAK,GAAG,IAAI,iBAAU,EAAE,CAAC;IAE/B,MAAM,OAAO,GAAG,IAAI,sCAA+B,CAAC;QAClD,WAAW,EAAE,MAAM,CAAC,WAAW;QAC/B,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,YAAY,EAAE,MAAM,CAAC,YAAY;QACjC,KAAK;QACL,KAAK;QACL,GAAG,CAAC,MAAM,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACnE,CAAC,CAAC;IAEH,iEAAiE;IACjE,MAAM,cAAc,GAClB,MAAM,CAAC,IAAI,KAAK,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC;IACtD,MAAM,QAAQ,GACZ,cAAc,KAAK,SAAS;QAC1B,CAAC,CAAC,IAAI,gCAAyB,CAAC;YAC5B,UAAU,EAAE,cAAc,CAAC,UAAU;YACrC,UAAU,EAAE,cAAc,CAAC,UAAU;YACrC,cAAc,EAAE,cAAc,CAAC,cAAc;SAC9C,CAAC;QACJ,CAAC,CAAC,SAAS,CAAC;IAEhB,OAAO;QACL,OAAO;QACP,GAAG,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAChD,CAAC;AACJ,CAAC"}

package/dist/resolvers/tenant-resolver.d.ts

@@ -0,0 +1,104 @@
+/**
+ * tenant-resolver.ts — Cart-to-tenant resolution for multi-tenant ISV routing.
+ *
+ * Every payment in the ISV model must be scoped to a single Viva merchant.
+ * This module resolves a Medusa cart to its tenant's Viva credentials by:
+ *   1. Reading `cart.metadata.tenant_id` (default strategy) or delegating to
+ *      a custom resolver injected via VivaPluginConfig.
+ *   2. Looking up `viva_tenant_merchant` in the plugin DB to get
+ *      `{connected_account_id, viva_merchant_id}`.
+ *
+ * P19 invariant: `assertSingleTenantCart` is called before any network I/O
+ * to reject multi-tenant carts early (Marketplace mode is deferred, see P3).
+ *
+ * @see references/viva-docs/md/isv-partner-program.txt:61 (P1 merchant scoping)
+ * @see references/viva-docs/md/payment-isv-api.txt:1 (merchantId query param)
+ */
+import type { EntityManager } from '@medusajs/framework/mikro-orm/core';
+import type { ConnectedAccountId, MerchantId } from '@sakeetech/viva-payments-core/types';
+export interface CartLike {
+    id: string;
+    metadata?: Record<string, unknown> | null;
+    items?: Array<{
+        metadata?: Record<string, unknown> | null;
+    }>;
+}
+/**
+ * Resolves a Medusa cart to its Viva tenant + account credentials.
+ *
+ * Custom implementations may inspect cart items, metadata, or an external
+ * mapping service. The plugin ships `DefaultTenantResolver` which reads
+ * `cart.metadata.tenant_id`.
+ *
+ * @see references/viva-docs/md/isv-partner-program.txt:61 (P5 tenant→account mapping)
+ */
+export interface TenantResolver {
+    /**
+     * Extract the tenant identifier from a cart.
+     * Throws VivaValidationError if the tenant cannot be determined.
+     */
+    resolveTenantFromCart(cart: CartLike): Promise<{
+        tenantId: string;
+    }>;
+    /**
+     * Look up the Viva account credentials for a tenant.
+     * Throws VivaValidationError if the tenant is not found.
+     */
+    resolveVivaAccount(tenantId: string): Promise<{
+        connectedAccountId: ConnectedAccountId;
+        vivaMerchantId: MerchantId;
+    }>;
+}
+/**
+ * Validates that a cart contains items from at most one tenant.
+ *
+ * Inspects each line item's `metadata.tenant_id`. If two distinct values are
+ * found, throws VivaValidationError with both tenant IDs in the message.
+ *
+ * Rationale: Multi-seller (Marketplace) split payments are explicitly out of
+ * scope for v1 (plan P3/P19). A payment must be scoped to a single merchant.
+ *
+ * Items without `metadata.tenant_id` are ignored here — the cart-level
+ * metadata is the authoritative tenant source via `resolveTenantFromCart`.
+ *
+ * @throws VivaValidationError if items contain two distinct tenant_id values.
+ *
+ * @see references/viva-docs/md/isv-partner-program.txt:61 (P19 invariant)
+ */
+export declare function assertSingleTenantCart(cart: {
+    items?: Array<{
+        metadata?: Record<string, unknown> | null;
+    }>;
+}): void;
+/**
+ * Default resolver: reads `cart.metadata.tenant_id` (string).
+ * Looks up `viva_tenant_merchant` for the Viva account credentials.
+ *
+ * Inject a custom TenantResolver into VivaPaymentProviderOptions to override
+ * (e.g. if tenant_id is stored in an item's metadata or an external service).
+ *
+ * @see references/viva-docs/md/isv-partner-program.txt:61 (P5)
+ */
+export declare class DefaultTenantResolver implements TenantResolver {
+    private readonly em;
+    constructor(em: EntityManager);
+    /**
+     * Reads `cart.metadata.tenant_id`. Throws VivaValidationError if absent.
+     *
+     * @see references/viva-docs/md/isv-partner-program.txt:61 (P5)
+     */
+    resolveTenantFromCart(cart: CartLike): Promise<{
+        tenantId: string;
+    }>;
+    /**
+     * Queries viva_tenant_merchant by tenant_id.
+     * Throws VivaValidationError if the tenant is not found.
+     *
+     * @see references/viva-docs/md/isv-partner-program.txt:61 (P5 tenant→account)
+     */
+    resolveVivaAccount(tenantId: string): Promise<{
+        connectedAccountId: ConnectedAccountId;
+        vivaMerchantId: MerchantId;
+    }>;
+}
+//# sourceMappingURL=tenant-resolver.d.ts.map

package/dist/resolvers/tenant-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tenant-resolver.d.ts","sourceRoot":"","sources":["../../src/resolvers/tenant-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oCAAoC,CAAC;AACxE,OAAO,KAAK,EAAE,kBAAkB,EAAE,UAAU,EAAE,MAAM,qCAAqC,CAAC;AAQ1F,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC1C,KAAK,CAAC,EAAE,KAAK,CAAC;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAA;KAAE,CAAC,CAAC;CAC9D;AAMD;;;;;;;;GAQG;AACH,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,qBAAqB,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAErE;;;OAGG;IACH,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;QAC5C,kBAAkB,EAAE,kBAAkB,CAAC;QACvC,cAAc,EAAE,UAAU,CAAC;KAC5B,CAAC,CAAC;CACJ;AAMD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE;IAC3C,KAAK,CAAC,EAAE,KAAK,CAAC;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAA;KAAE,CAAC,CAAC;CAC9D,GAAG,IAAI,CAqBP;AAMD;;;;;;;;GAQG;AACH,qBAAa,qBAAsB,YAAW,cAAc;IAC9C,OAAO,CAAC,QAAQ,CAAC,EAAE;gBAAF,EAAE,EAAE,aAAa;IAE9C;;;;OAIG;IACG,qBAAqB,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IAc1E;;;;;OAKG;IACG,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;QAClD,kBAAkB,EAAE,kBAAkB,CAAC;QACvC,cAAc,EAAE,UAAU,CAAC;KAC5B,CAAC;CAiBH"}

package/dist/resolvers/tenant-resolver.js

@@ -0,0 +1,118 @@
+"use strict";
+/**
+ * tenant-resolver.ts — Cart-to-tenant resolution for multi-tenant ISV routing.
+ *
+ * Every payment in the ISV model must be scoped to a single Viva merchant.
+ * This module resolves a Medusa cart to its tenant's Viva credentials by:
+ *   1. Reading `cart.metadata.tenant_id` (default strategy) or delegating to
+ *      a custom resolver injected via VivaPluginConfig.
+ *   2. Looking up `viva_tenant_merchant` in the plugin DB to get
+ *      `{connected_account_id, viva_merchant_id}`.
+ *
+ * P19 invariant: `assertSingleTenantCart` is called before any network I/O
+ * to reject multi-tenant carts early (Marketplace mode is deferred, see P3).
+ *
+ * @see references/viva-docs/md/isv-partner-program.txt:61 (P1 merchant scoping)
+ * @see references/viva-docs/md/payment-isv-api.txt:1 (merchantId query param)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DefaultTenantResolver = void 0;
+exports.assertSingleTenantCart = assertSingleTenantCart;
+const errors_1 = require("@sakeetech/viva-payments-core/errors");
+// ---------------------------------------------------------------------------
+// P19: single-tenant cart invariant
+// ---------------------------------------------------------------------------
+/**
+ * Validates that a cart contains items from at most one tenant.
+ *
+ * Inspects each line item's `metadata.tenant_id`. If two distinct values are
+ * found, throws VivaValidationError with both tenant IDs in the message.
+ *
+ * Rationale: Multi-seller (Marketplace) split payments are explicitly out of
+ * scope for v1 (plan P3/P19). A payment must be scoped to a single merchant.
+ *
+ * Items without `metadata.tenant_id` are ignored here — the cart-level
+ * metadata is the authoritative tenant source via `resolveTenantFromCart`.
+ *
+ * @throws VivaValidationError if items contain two distinct tenant_id values.
+ *
+ * @see references/viva-docs/md/isv-partner-program.txt:61 (P19 invariant)
+ */
+function assertSingleTenantCart(cart) {
+    if (!cart.items || cart.items.length === 0)
+        return;
+    const tenantIds = new Set();
+    for (const item of cart.items) {
+        const tenantId = item.metadata?.['tenant_id'];
+        if (typeof tenantId === 'string' && tenantId.length > 0) {
+            tenantIds.add(tenantId);
+        }
+        if (tenantIds.size >= 2)
+            break;
+    }
+    if (tenantIds.size >= 2) {
+        const [first, second] = [...tenantIds];
+        throw new errors_1.VivaValidationError({
+            message: `Cart contains items from multiple tenants: '${first ?? ''}' and '${second ?? ''}'. ` +
+                `Multi-tenant carts are not supported in v1 (plan P19). ` +
+                `Each cart must contain items from a single tenant.`,
+        });
+    }
+}
+// ---------------------------------------------------------------------------
+// DefaultTenantResolver
+// ---------------------------------------------------------------------------
+/**
+ * Default resolver: reads `cart.metadata.tenant_id` (string).
+ * Looks up `viva_tenant_merchant` for the Viva account credentials.
+ *
+ * Inject a custom TenantResolver into VivaPaymentProviderOptions to override
+ * (e.g. if tenant_id is stored in an item's metadata or an external service).
+ *
+ * @see references/viva-docs/md/isv-partner-program.txt:61 (P5)
+ */
+class DefaultTenantResolver {
+    em;
+    constructor(em) {
+        this.em = em;
+    }
+    /**
+     * Reads `cart.metadata.tenant_id`. Throws VivaValidationError if absent.
+     *
+     * @see references/viva-docs/md/isv-partner-program.txt:61 (P5)
+     */
+    async resolveTenantFromCart(cart) {
+        const tenantId = cart.metadata?.['tenant_id'];
+        if (typeof tenantId !== 'string' || tenantId.trim() === '') {
+            throw new errors_1.VivaValidationError({
+                message: `Cannot resolve tenant for cart '${cart.id}': ` +
+                    `cart.metadata.tenant_id is missing or not a string. ` +
+                    `Set cart.metadata.tenant_id to the tenant identifier, or ` +
+                    `inject a custom TenantResolver via VivaPaymentProviderOptions.`,
+            });
+        }
+        return { tenantId: tenantId.trim() };
+    }
+    /**
+     * Queries viva_tenant_merchant by tenant_id.
+     * Throws VivaValidationError if the tenant is not found.
+     *
+     * @see references/viva-docs/md/isv-partner-program.txt:61 (P5 tenant→account)
+     */
+    async resolveVivaAccount(tenantId) {
+        const repo = this.em.getRepository('VivaTenantMerchant');
+        const record = await repo.findOne({ tenant_id: tenantId });
+        if (!record) {
+            throw new errors_1.VivaValidationError({
+                message: `Tenant '${tenantId}' is not registered in viva_tenant_merchant. ` +
+                    `Onboard this tenant via the ISV partner flow before accepting payments.`,
+            });
+        }
+        return {
+            connectedAccountId: record.connected_account_id,
+            vivaMerchantId: record.viva_merchant_id,
+        };
+    }
+}
+exports.DefaultTenantResolver = DefaultTenantResolver;
+//# sourceMappingURL=tenant-resolver.js.map

package/dist/resolvers/tenant-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tenant-resolver.js","sourceRoot":"","sources":["../../src/resolvers/tenant-resolver.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;GAeG;;;AAmEH,wDAuBC;AAtFD,iEAA2E;AA2C3E,8EAA8E;AAC9E,oCAAoC;AACpC,8EAA8E;AAE9E;;;;;;;;;;;;;;;GAeG;AACH,SAAgB,sBAAsB,CAAC,IAEtC;IACC,IAAI,CAAC,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO;IAEnD,MAAM,SAAS,GAAG,IAAI,GAAG,EAAU,CAAC;IACpC,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;QAC9B,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,EAAE,CAAC,WAAW,CAAC,CAAC;QAC9C,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACxD,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAC1B,CAAC;QACD,IAAI,SAAS,CAAC,IAAI,IAAI,CAAC;YAAE,MAAM;IACjC,CAAC;IAED,IAAI,SAAS,CAAC,IAAI,IAAI,CAAC,EAAE,CAAC;QACxB,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,GAAG,CAAC,GAAG,SAAS,CAAC,CAAC;QACvC,MAAM,IAAI,4BAAmB,CAAC;YAC5B,OAAO,EACL,+CAA+C,KAAK,IAAI,EAAE,UAAU,MAAM,IAAI,EAAE,KAAK;gBACrF,yDAAyD;gBACzD,oDAAoD;SACvD,CAAC,CAAC;IACL,CAAC;AACH,CAAC;AAED,8EAA8E;AAC9E,wBAAwB;AACxB,8EAA8E;AAE9E;;;;;;;;GAQG;AACH,MAAa,qBAAqB;IACH;IAA7B,YAA6B,EAAiB;QAAjB,OAAE,GAAF,EAAE,CAAe;IAAG,CAAC;IAElD;;;;OAIG;IACH,KAAK,CAAC,qBAAqB,CAAC,IAAc;QACxC,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,EAAE,CAAC,WAAW,CAAC,CAAC;QAC9C,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAI,QAAQ,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;YAC3D,MAAM,IAAI,4BAAmB,CAAC;gBAC5B,OAAO,EACL,mCAAmC,IAAI,CAAC,EAAE,KAAK;oBAC/C,sDAAsD;oBACtD,2DAA2D;oBAC3D,gEAAgE;aACnE,CAAC,CAAC;QACL,CAAC;QACD,OAAO,EAAE,QAAQ,EAAE,QAAQ,CAAC,IAAI,EAAE,EAAE,CAAC;IACvC,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,kBAAkB,CAAC,QAAgB;QAIvC,MAAM,IAAI,GAAG,IAAI,CAAC,EAAE,CAAC,aAAa,CAAqB,oBAAoB,CAAC,CAAC;QAC7E,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC,CAAC;QAE3D,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,IAAI,4BAAmB,CAAC;gBAC5B,OAAO,EACL,WAAW,QAAQ,+CAA+C;oBAClE,yEAAyE;aAC5E,CAAC,CAAC;QACL,CAAC;QAED,OAAO;YACL,kBAAkB,EAAE,MAAM,CAAC,oBAA0C;YACrE,cAAc,EAAE,MAAM,CAAC,gBAA8B;SACtD,CAAC;IACJ,CAAC;CACF;AAhDD,sDAgDC"}

package/dist/service.d.ts

@@ -0,0 +1,200 @@
+/**
+ * service.ts — VivaPaymentProvider (Medusa v2 AbstractPaymentProvider)
+ *
+ * Implements all required Medusa v2 payment provider methods, bridging the
+ * Medusa payment lifecycle to the Viva Wallet ISV Smart Checkout flow.
+ *
+ * Key design choices:
+ * - A4 (write-pending-first): INSERT into viva_transaction with status='initiated'
+ *   and viva_order_code=NULL BEFORE calling Viva's createOrder API.
+ * - P14 (idempotency): deduplicate by idempotency_key = medusa_payment_id.
+ * - P18 (refund validation): validate amount <= captured - refunded before Viva API.
+ * - P19 (single-tenant invariant): assertSingleTenantCart before any DB write.
+ * - Error model (plan lines 339–344): wrap all Viva errors into MedusaError types.
+ *
+ * AbstractPaymentProvider required methods (read from @medusajs/utils dist):
+ *   capturePayment, authorizePayment, cancelPayment, initiatePayment,
+ *   deletePayment, getPaymentStatus, refundPayment, retrievePayment,
+ *   updatePayment, getWebhookActionAndData
+ *
+ * Smart Checkout redirect URL:
+ * - Demo:       https://demo.vivapayments.com/web/checkout?ref={OrderCode}
+ * - Production: https://www.vivapayments.com/web/checkout?ref={OrderCode}
+ *
+ * @see references/viva-docs/md/payment-isv-api.txt:1 (ISV API overview)
+ * @see references/viva-docs/md/smart-checkout-save-payment.txt:1 (redirect URL)
+ * @see references/viva-docs/md/tut-create-recurring-payment.txt:1 (checkout URL format)
+ * @see references/viva-docs/md/isv-partner-program.txt:61 (P14, P15, P18, P19, A4)
+ * @see references/viva-docs/md/isv-credentials.txt:107 (auth credential types)
+ * @see references/viva-docs/md/oauth2-authentication.txt:128 (token endpoint)
+ */
+import { AbstractPaymentProvider } from '@medusajs/framework/utils';
+import type { InitiatePaymentInput, InitiatePaymentOutput, AuthorizePaymentInput, AuthorizePaymentOutput, CapturePaymentInput, CapturePaymentOutput, RefundPaymentInput, RefundPaymentOutput, CancelPaymentInput, CancelPaymentOutput, RetrievePaymentInput, RetrievePaymentOutput, GetPaymentStatusInput, GetPaymentStatusOutput, DeletePaymentInput, DeletePaymentOutput, UpdatePaymentInput, UpdatePaymentOutput, ProviderWebhookPayload, WebhookActionResult } from '@medusajs/framework/types';
+import type { EntityManager } from '@medusajs/framework/mikro-orm/core';
+import { Payments } from '@sakeetech/viva-payments-core/payments';
+import { BasicAuthClient } from '@sakeetech/viva-payments-core/legacy';
+import { FastRefundClient } from '@sakeetech/viva-payments-core/refunds';
+import type { MinorUnits, TransactionId } from '@sakeetech/viva-payments-core/types';
+import type { VivaPluginConfig } from './config.js';
+import type { TenantResolver } from './resolvers/tenant-resolver.js';
+export interface VivaPaymentProviderOptions {
+    config: VivaPluginConfig;
+    /**
+     * Injected tenant resolver. Defaults to DefaultTenantResolver which reads
+     * `cart.metadata.tenant_id`.
+     *
+     * @see references/viva-docs/md/isv-partner-program.txt:61 (P5)
+     */
+    tenantResolver?: TenantResolver;
+}
+/**
+ * Medusa v2 payment provider for Viva Wallet Smart Checkout (ISV multi-tenant).
+ *
+ * Identifier: 'viva'. Payment provider ID format: pp_viva_<id>.
+ * The <id> comes from the `id` field in medusa-config.ts providers array.
+ *
+ * @see references/viva-docs/md/payment-isv-api.txt:1 (ISV payment creation)
+ * @see references/viva-docs/md/smart-checkout-save-payment.txt:1 (redirect URL)
+ * @see references/viva-docs/md/isv-partner-program.txt:61 (ISV overview)
+ */
+export declare class VivaPaymentProvider extends AbstractPaymentProvider<VivaPaymentProviderOptions> {
+    static readonly identifier = "viva";
+    protected readonly vivaConfig: VivaPluginConfig;
+    protected readonly isvPayments: Payments;
+    protected readonly legacyClient: BasicAuthClient;
+    protected readonly fastRefundClient: FastRefundClient;
+    protected readonly tenantResolver: TenantResolver;
+    protected readonly em: EntityManager;
+    constructor(container: Record<string, unknown>, options: VivaPaymentProviderOptions);
+    /**
+     * Initiates a payment session (Medusa calls this when customer selects Viva):
+     * 1. P19: assert single-tenant cart (from input.context)
+     * 2. Resolve tenant → Viva merchant
+     * 3. P14 dedup: check for existing transaction by idempotency_key
+     * 4. A4 write-pending-first: INSERT transaction row BEFORE Viva API call
+     * 5. Call Viva createOrder
+     * 6. Update row with viva_order_code
+     * 7. Return redirect URL in data (storefront uses this to redirect customer)
+     *
+     * The medusa_payment_id is derived from input.context.idempotency_key (set by
+     * Medusa Payment Module) or generated per call.
+     *
+     * @see references/viva-docs/md/payment-isv-api.txt:1 (createOrder)
+     * @see references/viva-docs/md/smart-checkout-save-payment.txt:1 (redirect URL)
+     * @see references/viva-docs/md/isv-partner-program.txt:61 (P14, P19, A4)
+     */
+    initiatePayment(input: InitiatePaymentInput): Promise<InitiatePaymentOutput>;
+    /**
+     * Consults the DB for the latest transaction status.
+     * For Smart Checkout, authorization is off-band (redirect + webhook).
+     * Called during cart-completion; returns current DB status.
+     *
+     * @see references/viva-docs/md/payment-isv-api.txt:1 (Smart Checkout flow)
+     * @see references/viva-docs/md/isv-partner-program.txt:61 (P6 Smart Checkout)
+     */
+    authorizePayment(input: AuthorizePaymentInput): Promise<AuthorizePaymentOutput>;
+    /**
+     * Capture is implicit on Smart Checkout completion (1796 webhook).
+     * This method is idempotent: if already captured, returns success.
+     * If not yet captured, logs a warning and returns current state.
+     *
+     * NOTE: Do NOT call Viva's capture endpoint. Capture is automatic on
+     * Smart Checkout completion per Viva's ISV model.
+     *
+     * @see references/viva-docs/md/payment-isv-api.txt:1 (implicit capture)
+     * @see references/viva-docs/md/isv-partner-program.txt:61 (P6 Smart Checkout)
+     */
+    capturePayment(input: CapturePaymentInput): Promise<CapturePaymentOutput>;
+    /**
+     * Issues a full or partial refund via Viva ISV API.
+     *
+     * P18 validation: refundAmountMinor <= capturedAmount - alreadyRefunded.
+     * Auth: primary OAuth2 strategy (Q5 — if Viva rejects with 401/403, reseller
+     * auth may be required; log warning and re-raise for now).
+     * Partial refund: increments refunded_amount_minor; status stays 'captured'.
+     * Full refund: transitions status to 'refunded' via lattice.
+     *
+     * @see references/viva-docs/md/isv-partner-program.txt:296 (P18 refund, ISV fee reversal)
+     * @see references/viva-docs/md/payment-isv-api.txt:1 (refund endpoint)
+     */
+    refundPayment(input: RefundPaymentInput): Promise<RefundPaymentOutput>;
+    /**
+     * Merchant-mode refund routing — Fast vs Standard with auto-fallback.
+     *
+     * Flow:
+     *   1. retrieveTransaction → cardType (for refund-strategy decision).
+     *   2. resolveRefundStrategy(config.refundStrategy ?? 'auto', { cardType, CNP: true }).
+     *   3. If decision.kind === 'fast': call FastRefundClient.refund.
+     *      - 403 + strategy === 'fast' → throw VivaApiError with vivaCode
+     *        'VIVA_FAST_REFUND_INELIGIBLE'.
+     *      - 403 + strategy === 'auto' → fall through to Standard refund.
+     *      - any other error → re-throw.
+     *   4. Otherwise call BasicAuthClient via Payments.refundPayment (Standard).
+     *
+     * Smart Checkout is always card-not-present (CNP), so `isCardNotPresent: true`.
+     *
+     * @see docs/ENDPOINTS.md §4
+     * @see docs/plans/multi-mode-v0.md §9
+     * @see references/payment-api.yaml:9255 (Fast Refund 403 semantics)
+     */
+    protected refundPaymentMerchantMode(params: {
+        vivaTransactionId: TransactionId;
+        refundAmountMinor: MinorUnits;
+        refundIdempotencyKey: string;
+        medusaRefundId: string;
+    }): Promise<void>;
+    /**
+     * Cancels a Viva order (valid for unpaid orders not yet captured).
+     * Idempotent: skip API call if already in terminal cancelled state.
+     * Apply lattice: authorized → cancelled (A9 path).
+     *
+     * @see references/viva-docs/md/payment-isv-api.txt:1 (cancelOrder)
+     * @see references/viva-docs/md/isv-partner-program.txt:61 (P18, A9)
+     */
+    cancelPayment(input: CancelPaymentInput): Promise<CancelPaymentOutput>;
+    /**
+     * Returns the serialized viva_transaction row for the given payment.
+     *
+     * @see references/viva-docs/md/isv-partner-program.txt:104
+     */
+    retrievePayment(input: RetrievePaymentInput): Promise<RetrievePaymentOutput>;
+    /**
+     * Returns the current Medusa-mapped payment status from the DB.
+     *
+     * @see references/viva-docs/md/isv-partner-program.txt:104
+     */
+    getPaymentStatus(input: GetPaymentStatusInput): Promise<GetPaymentStatusOutput>;
+    /**
+     * Logical-only deletion — does NOT delete the Viva transaction (audit trail).
+     * The viva_transaction row is preserved for forensics and idempotency replay.
+     *
+     * @see references/viva-docs/md/isv-partner-program.txt:104
+     */
+    deletePayment(input: DeletePaymentInput): Promise<DeletePaymentOutput>;
+    /**
+     * No-op for Smart Checkout: Viva orders cannot be updated after creation.
+     * If amount changes, caller should cancel and re-initiate.
+     *
+     * @see references/viva-docs/md/payment-isv-api.txt:1 (order immutability)
+     */
+    updatePayment(input: UpdatePaymentInput): Promise<UpdatePaymentOutput>;
+    /**
+     * Processes Viva webhook events received via the /viva/webhook route (S8).
+     * S8 routes the verified webhook payload here.
+     *
+     * Viva webhook event types in v1 scope:
+     *   1796 - Transaction Payment Created → action: 'captured'
+     *   1797 - Transaction Reversal Created → action: 'authorized' (refund)
+     *   1798 - Transaction Failed → action: 'failed'
+     *   4865 - Order Updated (cancellation) → action: 'canceled'
+     *
+     * NOTE: This is the minimal implementation for S6. The full webhook processing
+     * subscriber (status lattice updates, Retrieve Transaction API call per plan
+     * step 4.a) is implemented in S8.
+     *
+     * @see references/viva-docs/md/isv-partner-program.txt:104 (webhook flow)
+     * @see references/viva-docs/md/webhooks-for-payments.txt:248 (retrieve before update)
+     */
+    getWebhookActionAndData(data: ProviderWebhookPayload['payload']): Promise<WebhookActionResult>;
+}
+//# sourceMappingURL=service.d.ts.map

package/dist/service.d.ts.map

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