@sakeetech/medusa-payment-viva 0.2.2

package/dist/api/viva/webhook/route.d.ts

@@ -0,0 +1,57 @@
+/**
+ * route.ts — Viva Wallet webhook endpoint.
+ *
+ * Two handlers:
+ *   GET  /viva/webhook  — challenge-response for URL registration.
+ *   POST /viva/webhook  — event ingest: IP check, INSERT + emit.
+ *
+ * Security model (plan P7):
+ *   (a) IP allowlist   — 403 on mismatch. Source IP is extracted with
+ *                        trustedProxyDepth-bounded X-Forwarded-For walking
+ *                        (CSO Finding #2). Configure via
+ *                        VIVA_TRUSTED_PROXY_DEPTH (default 0 = socket only).
+ *   (b) DB dedup       — INSERT ... ON CONFLICT (message_id) DO NOTHING.
+ *   (c) A2 gate        — only emit 'viva.webhook.received' when RETURNING non-empty.
+ *
+ * HMAC verification is intentionally not performed here. Event 7936 (the
+ * only HMAC-signed Viva event) is not subscribed; if it is ever added,
+ * route a separate VIVA_WEBHOOK_HMAC_SECRET, NOT the public
+ * VIVA_WEBHOOK_VERIFICATION_KEY. See CSO Finding #3.
+ *
+ * Metrics emitted (P16):
+ *   viva_webhook_received_total{event_type_id, result}
+ *   viva_webhook_processing_lag_seconds
+ *   viva_tenant_resolution_failures_total
+ *   viva_webhook_ordercode_mismatch_total
+ *
+ * @see references/viva-docs/md/webhooks-for-payments.txt:270 (IP allowlist)
+ * @see references/viva-docs/md/webhooks-for-payments.txt:254 (security model P7)
+ * @see docs/TODO-CSO.md (Findings 1, 2, 3)
+ */
+import type { MedusaRequest, MedusaResponse } from '@medusajs/framework/http';
+/**
+ * Challenge-response for webhook URL registration.
+ * Returns `{"Key": "<webhook_verification_key>"}` per Viva protocol.
+ * No auth gate; only exercised at deployment time.
+ *
+ * @see references/viva-docs/md/webhooks-for-payments.txt:284 (challenge response)
+ */
+export declare const GET: (_req: MedusaRequest, res: MedusaResponse) => Promise<void>;
+/**
+ * POST event ingest handler.
+ *
+ * Steps:
+ *   1. IP allowlist check (env-configured). 403 on rejection.
+ *   2. Read rawBody captured by vivaWebhookRawBodyMiddleware.
+ *   3. Parse JSON.
+ *   4. If EventTypeId 7936: verify HMAC. 401 on mismatch.
+ *   5. Resolve tenant via viva_tenant_merchant.
+ *   6. INSERT INTO viva_webhook_event ... ON CONFLICT (message_id) DO NOTHING RETURNING viva_webhook_event_id.
+ *   7. A2: only emit 'viva.webhook.received' when RETURNING produced a row.
+ *   8. Always respond 200.
+ *
+ * @see references/viva-docs/md/webhooks-for-payments.txt:286 (POST flow)
+ * @see references/viva-docs/md/wh-transaction-payment-created.txt:158 (event envelope)
+ */
+export declare const POST: (req: MedusaRequest, res: MedusaResponse) => Promise<void>;
+//# sourceMappingURL=route.d.ts.map

package/dist/api/viva/webhook/route.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"route.d.ts","sourceRoot":"","sources":["../../../../src/api/viva/webhook/route.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAiB9E;;;;;;GAMG;AACH,eAAO,MAAM,GAAG,GACd,MAAM,aAAa,EACnB,KAAK,cAAc,KAClB,OAAO,CAAC,IAAI,CAQd,CAAC;AAMF;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,IAAI,GACf,KAAK,aAAa,EAClB,KAAK,cAAc,KAClB,OAAO,CAAC,IAAI,CAwMd,CAAC"}

package/dist/api/viva/webhook/route.js

@@ -0,0 +1,269 @@
+"use strict";
+/**
+ * route.ts — Viva Wallet webhook endpoint.
+ *
+ * Two handlers:
+ *   GET  /viva/webhook  — challenge-response for URL registration.
+ *   POST /viva/webhook  — event ingest: IP check, INSERT + emit.
+ *
+ * Security model (plan P7):
+ *   (a) IP allowlist   — 403 on mismatch. Source IP is extracted with
+ *                        trustedProxyDepth-bounded X-Forwarded-For walking
+ *                        (CSO Finding #2). Configure via
+ *                        VIVA_TRUSTED_PROXY_DEPTH (default 0 = socket only).
+ *   (b) DB dedup       — INSERT ... ON CONFLICT (message_id) DO NOTHING.
+ *   (c) A2 gate        — only emit 'viva.webhook.received' when RETURNING non-empty.
+ *
+ * HMAC verification is intentionally not performed here. Event 7936 (the
+ * only HMAC-signed Viva event) is not subscribed; if it is ever added,
+ * route a separate VIVA_WEBHOOK_HMAC_SECRET, NOT the public
+ * VIVA_WEBHOOK_VERIFICATION_KEY. See CSO Finding #3.
+ *
+ * Metrics emitted (P16):
+ *   viva_webhook_received_total{event_type_id, result}
+ *   viva_webhook_processing_lag_seconds
+ *   viva_tenant_resolution_failures_total
+ *   viva_webhook_ordercode_mismatch_total
+ *
+ * @see references/viva-docs/md/webhooks-for-payments.txt:270 (IP allowlist)
+ * @see references/viva-docs/md/webhooks-for-payments.txt:254 (security model P7)
+ * @see docs/TODO-CSO.md (Findings 1, 2, 3)
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.POST = exports.GET = void 0;
+const utils_1 = require("@medusajs/framework/utils");
+const pg_1 = __importDefault(require("pg"));
+const webhooks_1 = require("@sakeetech/viva-payments-core/webhooks");
+const index_js_1 = require("../../../observability/index.js");
+// ---------------------------------------------------------------------------
+// GET — challenge-response
+// ---------------------------------------------------------------------------
+/**
+ * Challenge-response for webhook URL registration.
+ * Returns `{"Key": "<webhook_verification_key>"}` per Viva protocol.
+ * No auth gate; only exercised at deployment time.
+ *
+ * @see references/viva-docs/md/webhooks-for-payments.txt:284 (challenge response)
+ */
+const GET = async (_req, res) => {
+    const key = process.env['VIVA_WEBHOOK_VERIFICATION_KEY'] ?? '';
+    if (!key) {
+        res.status(500).json({ error: 'VIVA_WEBHOOK_VERIFICATION_KEY is not configured' });
+        return;
+    }
+    res.setHeader('Cache-Control', 'no-store');
+    res.status(200).json({ Key: key });
+};
+exports.GET = GET;
+// ---------------------------------------------------------------------------
+// POST — event ingest
+// ---------------------------------------------------------------------------
+/**
+ * POST event ingest handler.
+ *
+ * Steps:
+ *   1. IP allowlist check (env-configured). 403 on rejection.
+ *   2. Read rawBody captured by vivaWebhookRawBodyMiddleware.
+ *   3. Parse JSON.
+ *   4. If EventTypeId 7936: verify HMAC. 401 on mismatch.
+ *   5. Resolve tenant via viva_tenant_merchant.
+ *   6. INSERT INTO viva_webhook_event ... ON CONFLICT (message_id) DO NOTHING RETURNING viva_webhook_event_id.
+ *   7. A2: only emit 'viva.webhook.received' when RETURNING produced a row.
+ *   8. Always respond 200.
+ *
+ * @see references/viva-docs/md/webhooks-for-payments.txt:286 (POST flow)
+ * @see references/viva-docs/md/wh-transaction-payment-created.txt:158 (event envelope)
+ */
+const POST = async (req, res) => {
+    const environment = (process.env['VIVA_ENVIRONMENT'] ?? 'demo');
+    const extraAllowlist = parseExtraAllowlist(process.env['VIVA_WEBHOOK_IP_ALLOWLIST']);
+    const trustedProxyDepth = parseTrustedProxyDepth(process.env['VIVA_TRUSTED_PROXY_DEPTH']);
+    const metrics = (0, index_js_1.getSharedMetrics)();
+    // ---- Step 1: IP allowlist (CSO Finding #2) ----
+    // VIVA_TRUSTED_PROXY_DEPTH controls how many trailing X-Forwarded-For hops we
+    // trust. Default 0 = socket only (safe for direct exposure); set to 1 for a
+    // single reverse proxy, 2 for CDN+LB. Walking from the rightmost end means
+    // attacker-injected leftmost values are ignored.
+    const clientIp = (0, webhooks_1.extractClientIp)(req, trustedProxyDepth);
+    if (!(0, webhooks_1.isAllowedSourceIp)(clientIp, environment, extraAllowlist)) {
+        // Log metric for IP rejection but only 403 in non-dev environments.
+        // In dev/test with IP_ALLOWLIST_BYPASS=true, allow through.
+        if (process.env['VIVA_WEBHOOK_IP_ALLOWLIST_BYPASS'] !== 'true') {
+            req.scope?.resolve?.('logger')?.warn?.(`[viva] Rejected webhook from disallowed IP ${clientIp} (env=${environment})`);
+            metrics.counter('viva_webhook_received_total', { event_type_id: 'unknown', result: 'ip_rejected' });
+            res.status(403).json({ error: 'Forbidden' });
+            return;
+        }
+    }
+    // ---- Step 2: Raw body ----
+    const rawBody = req.rawBody;
+    if (!rawBody || rawBody.length === 0) {
+        res.status(200).end();
+        return;
+    }
+    // ---- Step 3: Parse JSON ----
+    let envelope;
+    try {
+        envelope = JSON.parse(rawBody.toString('utf-8'));
+    }
+    catch {
+        // Malformed JSON — return 200 per plan (Viva retries are not helpful here)
+        const logger = req.scope?.resolve?.('logger');
+        logger?.error?.('[viva] Webhook POST: failed to parse JSON body');
+        res.status(200).end();
+        return;
+    }
+    const eventTypeId = envelope.EventTypeId;
+    const messageId = envelope.MessageId;
+    // ---- Compute processing lag (P16) ----
+    // envelope.Created is an ISO8601 timestamp when present
+    const createdTs = envelope['Created'];
+    if (typeof createdTs === 'string') {
+        const createdMs = new Date(createdTs).getTime();
+        if (!isNaN(createdMs)) {
+            const lagSeconds = (Date.now() - createdMs) / 1000;
+            metrics.histogram('viva_webhook_processing_lag_seconds', lagSeconds);
+        }
+    }
+    // ---- Step 4: HMAC verification ----
+    // Plugin does NOT subscribe to event 7936 (Sale Transactions) — the only
+    // Viva event that ships an HMAC signature. The handler used to verify 7936
+    // signatures here, but it reused VIVA_WEBHOOK_VERIFICATION_KEY (a public,
+    // browser-fetchable value) as the HMAC secret, which is incorrect by
+    // Viva's protocol design (CSO Finding #3, dormant).
+    //
+    // If 7936 is ever added to the subscribed event list, route a SEPARATE
+    // VIVA_WEBHOOK_HMAC_SECRET env var, NOT VIVA_WEBHOOK_VERIFICATION_KEY.
+    // The `verifyHmacSignature` helper remains in
+    // @sakeetech/viva-payments-core/webhooks for that future wiring.
+    // @see docs/TODO-CSO.md "Finding 3"
+    // @see references/viva-docs/md/wh-sale-transactions.txt:174
+    // ---- Step 5: Resolve tenant ----
+    const connString = process.env['DATABASE_URL'] ??
+        `postgresql://${process.env['USER'] ?? 'postgres'}@localhost:5432/postgres`;
+    const pool = new pg_1.default.Pool({ connectionString: connString, max: 1 });
+    const logger = req.scope?.resolve?.('logger');
+    let tenantId = null;
+    let vivaMerchantId = null;
+    let connectedAccountId = null;
+    let transactionId = null;
+    try {
+        const eventData = envelope.EventData;
+        if ((0, webhooks_1.isTransactionEvent)(eventTypeId)) {
+            const txData = eventData;
+            vivaMerchantId = txData.MerchantId ?? null;
+            transactionId = txData.TransactionId ?? null;
+            connectedAccountId = txData.ConnectedAccountId ?? null;
+            if (vivaMerchantId) {
+                const client = await pool.connect();
+                try {
+                    const row = await client.query(`SELECT tenant_id FROM viva_tenant_merchant WHERE viva_merchant_id = $1 LIMIT 1`, [vivaMerchantId]);
+                    tenantId = row.rows[0]?.tenant_id ?? null;
+                }
+                finally {
+                    client.release();
+                }
+            }
+        }
+        else if ((0, webhooks_1.isOnboardingEvent)(eventTypeId)) {
+            const onbData = eventData;
+            connectedAccountId = onbData.ConnectedAccountId ?? null;
+            if (connectedAccountId) {
+                const client = await pool.connect();
+                try {
+                    const row = await client.query(`SELECT tenant_id FROM viva_tenant_merchant WHERE connected_account_id = $1 LIMIT 1`, [connectedAccountId]);
+                    tenantId = row.rows[0]?.tenant_id ?? null;
+                }
+                finally {
+                    client.release();
+                }
+            }
+        }
+        if (!tenantId) {
+            // A6: log metric but continue — INSERT with tenant_id=NULL
+            logger?.warn?.(`[viva] Tenant resolution failed for event ${eventTypeId} message ${messageId} ` +
+                `vivaMerchantId=${vivaMerchantId ?? 'null'} connectedAccountId=${connectedAccountId ?? 'null'}. ` +
+                `Metric: viva_tenant_resolution_failures_total`);
+            metrics.counter('viva_tenant_resolution_failures_total', { event_type_id: String(eventTypeId) });
+        }
+        // ---- Step 6: INSERT ... ON CONFLICT DO NOTHING RETURNING ----
+        const client = await pool.connect();
+        let insertedEventId = null;
+        try {
+            const result = await client.query(`INSERT INTO viva_webhook_event
+           (transaction_id, event_type_id, message_id, viva_merchant_id, connected_account_id, raw_payload)
+         VALUES ($1, $2, $3, $4, $5, $6)
+         ON CONFLICT (message_id) DO NOTHING
+         RETURNING viva_webhook_event_id`, [
+                transactionId,
+                eventTypeId,
+                messageId,
+                vivaMerchantId,
+                connectedAccountId,
+                JSON.stringify(envelope),
+            ]);
+            insertedEventId = result.rows[0]?.viva_webhook_event_id ?? null;
+        }
+        finally {
+            client.release();
+        }
+        // ---- Step 7: A2 dispatch gate — only emit when RETURNING returned a row ----
+        if (insertedEventId) {
+            metrics.counter('viva_webhook_received_total', {
+                event_type_id: String(eventTypeId),
+                result: tenantId ? 'accepted' : 'tenant_unresolved',
+            });
+            const eventBus = req.scope?.resolve?.(utils_1.Modules.EVENT_BUS);
+            if (eventBus) {
+                await eventBus.emit({
+                    name: 'viva.webhook.received',
+                    data: {
+                        eventId: insertedEventId,
+                        tenantId: tenantId,
+                        eventTypeId,
+                        transactionId,
+                        vivaMerchantId,
+                        connectedAccountId,
+                    },
+                });
+            }
+        }
+        else {
+            // Duplicate — ON CONFLICT hit
+            metrics.counter('viva_webhook_received_total', {
+                event_type_id: String(eventTypeId),
+                result: 'duplicate',
+            });
+        }
+    }
+    catch (err) {
+        logger?.error?.(`[viva] Webhook POST error for message ${messageId}: ${err instanceof Error ? err.message : String(err)}`);
+        // Still return 200 so Viva doesn't retry unnecessarily
+    }
+    finally {
+        await pool.end().catch(() => undefined);
+    }
+    // ---- Step 8: Always 200 ----
+    res.status(200).end();
+};
+exports.POST = POST;
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function parseExtraAllowlist(raw) {
+    if (!raw)
+        return [];
+    return raw.split(',').map((s) => s.trim()).filter(Boolean);
+}
+function parseTrustedProxyDepth(raw) {
+    if (!raw)
+        return 0;
+    const n = Number.parseInt(raw, 10);
+    if (Number.isNaN(n) || n < 0)
+        return 0;
+    return n;
+}
+//# sourceMappingURL=route.js.map

package/dist/api/viva/webhook/route.js.map

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

package/dist/cli/bin.d.ts

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+/**
+ * bin.ts — CLI shim for viva-register-webhooks.
+ *
+ * Parses CLI flags with node:util.parseArgs (no npm dependency) and
+ * delegates to run() from register-webhooks.ts.
+ *
+ * @see references/viva-docs/md/isv-partner-program.txt:196 (ISV webhook setup)
+ * @see references/viva-docs/md/webhooks-for-payments.txt:134 (10-URL limit)
+ */
+export {};
+//# sourceMappingURL=bin.d.ts.map

package/dist/cli/bin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.d.ts","sourceRoot":"","sources":["../../src/cli/bin.ts"],"names":[],"mappings":";AACA;;;;;;;;GAQG"}

package/dist/cli/bin.js

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * bin.ts — CLI shim for viva-register-webhooks.
+ *
+ * Parses CLI flags with node:util.parseArgs (no npm dependency) and
+ * delegates to run() from register-webhooks.ts.
+ *
+ * @see references/viva-docs/md/isv-partner-program.txt:196 (ISV webhook setup)
+ * @see references/viva-docs/md/webhooks-for-payments.txt:134 (10-URL limit)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_util_1 = require("node:util");
+const register_webhooks_js_1 = require("./register-webhooks.js");
+const { values } = (0, node_util_1.parseArgs)({
+    options: {
+        'dry-run': { type: 'boolean', default: false },
+        apply: { type: 'boolean', default: false },
+        'webhook-base-url': { type: 'string' },
+        'reconcile-drift': { type: 'boolean', default: false },
+        output: { type: 'string', default: 'human' },
+        help: { type: 'boolean', default: false, short: 'h' },
+    },
+    strict: true,
+});
+if (values.help) {
+    console.log(`
+viva-register-webhooks — Set up V1 webhook URLs for the configured Viva account.
+
+Mode is auto-detected from VIVA_MODE (or VIVA_RESELLER_* presence):
+  - ISV mode:      idempotently POSTs to /isv/v1/webhooks for every event type.
+  - Merchant mode: prints the URLs to paste into Viva Self Care → Sales →
+                   API Access → Webhooks and the verification key.
+
+Usage:
+  viva-register-webhooks --dry-run [--output json]
+  viva-register-webhooks --apply [--reconcile-drift]
+  viva-register-webhooks --apply --webhook-base-url https://api.example.com
+
+Environment:
+  VIVA_MODE                     merchant | isv (auto-detected if unset)
+  VIVA_ENVIRONMENT              demo | production    (default: demo)
+  VIVA_CLIENT_ID                required (alias: VIVA_ISV_CLIENT_ID, deprecated)
+  VIVA_CLIENT_SECRET            required (alias: VIVA_ISV_CLIENT_SECRET, deprecated)
+  VIVA_MERCHANT_ID              required (Basic-auth username; used in both modes)
+  VIVA_API_KEY                  required (Basic-auth password; used in both modes)
+  VIVA_WEBHOOK_VERIFICATION_KEY required
+  VIVA_WEBHOOK_BASE_URL         required; e.g., https://api.example.com
+
+Notes:
+  --reconcile-drift is non-applicable in merchant mode (manual setup only).
+
+Exit codes:
+  0  clean / applied successfully / merchant manual setup printed
+  1  plan has actions but --apply was not passed (CI gate use case — ISV mode)
+  2  apply failed (HTTP/Viva error)
+  3  fatal precondition (config invalid, near-limit abort)
+`);
+    process.exit(0);
+}
+if (!values['dry-run'] && !values.apply) {
+    console.error('Specify --dry-run or --apply (or --help).');
+    process.exit(3);
+}
+const runOpts = {
+    dryRun: !!values['dry-run'],
+    apply: !!values.apply,
+    reconcileDrift: !!values['reconcile-drift'],
+    output: values.output ?? 'human',
+};
+if (values['webhook-base-url'] !== undefined) {
+    runOpts.webhookBaseUrl = values['webhook-base-url'];
+}
+void (async () => {
+    const exitCode = await (0, register_webhooks_js_1.run)(runOpts);
+    process.exit(exitCode);
+})();
+//# sourceMappingURL=bin.js.map

package/dist/cli/bin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.js","sourceRoot":"","sources":["../../src/cli/bin.ts"],"names":[],"mappings":";;AACA;;;;;;;;GAQG;;AAEH,yCAAsC;AACtC,iEAA6C;AAE7C,MAAM,EAAE,MAAM,EAAE,GAAG,IAAA,qBAAS,EAAC;IAC3B,OAAO,EAAE;QACP,SAAS,EAAW,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,KAAK,EAAE;QACvD,KAAK,EAAe,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,KAAK,EAAE;QACvD,kBAAkB,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;QACtC,iBAAiB,EAAG,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,KAAK,EAAE;QACvD,MAAM,EAAc,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE;QACxD,IAAI,EAAgB,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE;KACpE;IACD,MAAM,EAAE,IAAI;CACb,CAAC,CAAC;AAEH,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC;IAChB,OAAO,CAAC,GAAG,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+Bb,CAAC,CAAC;IACD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AAED,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;IACxC,OAAO,CAAC,KAAK,CAAC,2CAA2C,CAAC,CAAC;IAC3D,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AAED,MAAM,OAAO,GAA8B;IACzC,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC;IAC3B,KAAK,EAAE,CAAC,CAAC,MAAM,CAAC,KAAK;IACrB,cAAc,EAAE,CAAC,CAAC,MAAM,CAAC,iBAAiB,CAAC;IAC3C,MAAM,EAAG,MAAM,CAAC,MAA2B,IAAI,OAAO;CACvD,CAAC;AAEF,IAAI,MAAM,CAAC,kBAAkB,CAAC,KAAK,SAAS,EAAE,CAAC;IAC7C,OAAO,CAAC,cAAc,GAAG,MAAM,CAAC,kBAAkB,CAAC,CAAC;AACtD,CAAC;AAED,KAAK,CAAC,KAAK,IAAI,EAAE;IACf,MAAM,QAAQ,GAAG,MAAM,IAAA,0BAAG,EAAC,OAAO,CAAC,CAAC;IACpC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;AACzB,CAAC,CAAC,EAAE,CAAC"}

package/dist/cli/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * CLI barrel — re-exports the public surface of the register-webhooks CLI.
+ *
+ * @see references/viva-docs/md/isv-partner-program.txt:196
+ * @see references/viva-docs/md/webhooks-for-payments.txt:134
+ */
+export { run } from './register-webhooks.js';
+export type { RunOptions } from './register-webhooks.js';
+export { computePlan } from './plan.js';
+export type { ComputePlanInput } from './plan.js';
+export type { DesiredWebhook, WebhookPlanAction, PlanResult, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,GAAG,EAAE,MAAM,wBAAwB,CAAC;AAC7C,YAAY,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACxC,YAAY,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAClD,YAAY,EACV,cAAc,EACd,iBAAiB,EACjB,UAAU,GACX,MAAM,YAAY,CAAC"}

package/dist/cli/index.js

@@ -0,0 +1,14 @@
+"use strict";
+/**
+ * CLI barrel — re-exports the public surface of the register-webhooks CLI.
+ *
+ * @see references/viva-docs/md/isv-partner-program.txt:196
+ * @see references/viva-docs/md/webhooks-for-payments.txt:134
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computePlan = exports.run = void 0;
+var register_webhooks_js_1 = require("./register-webhooks.js");
+Object.defineProperty(exports, "run", { enumerable: true, get: function () { return register_webhooks_js_1.run; } });
+var plan_js_1 = require("./plan.js");
+Object.defineProperty(exports, "computePlan", { enumerable: true, get: function () { return plan_js_1.computePlan; } });
+//# sourceMappingURL=index.js.map

package/dist/cli/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;AAEH,+DAA6C;AAApC,2GAAA,GAAG,OAAA;AAEZ,qCAAwC;AAA/B,sGAAA,WAAW,OAAA"}

package/dist/cli/plan.d.ts

@@ -0,0 +1,51 @@
+/**
+ * plan.ts — pure, IO-free webhook plan computation.
+ *
+ * Computes the diff between desired webhook state (from config) and current
+ * registrations (from Viva API), returning a deterministic action list.
+ *
+ * Per Viva docs, max 10 webhook URLs per event type.
+ *
+ * @see references/viva-docs/md/webhooks-for-payments.txt:134 (10-URL limit)
+ * @see references/viva-docs/md/isv-partner-program.txt:196 (ISV webhook setup flow)
+ */
+import type { DesiredWebhook, PlanResult, WebhookRegistration } from './types.js';
+export interface ComputePlanInput {
+    desired: readonly DesiredWebhook[];
+    current: readonly WebhookRegistration[];
+    /**
+     * Per Viva: 10 URLs per event type.
+     * @see references/viva-docs/md/webhooks-for-payments.txt:134
+     */
+    perEventTypeLimit?: number;
+    /**
+     * Warn when registered URLs reach this fraction of the limit.
+     * Default 0.8 → warn at 8.
+     */
+    nearLimitFraction?: number;
+    /**
+     * Whether to deactivate URLs that match our hostname pattern but aren't in
+     * `desired`. Disabled by default (safer for shared ISV accounts).
+     */
+    reconcileDrift?: boolean;
+    /**
+     * Hostname pattern that identifies "our" registrations for drift reconciliation.
+     * Required when reconcileDrift is true to avoid touching foreign webhooks.
+     */
+    ownedHostnamePattern?: RegExp;
+}
+/**
+ * Computes the desired-vs-current diff and returns an ordered action list.
+ *
+ * Action ordering for human readability:
+ *   1. REGISTER (sorted by eventTypeId)
+ *   2. SKIP_ALREADY_REGISTERED (sorted by eventTypeId)
+ *   3. DEACTIVATE_DRIFT (sorted by eventTypeId)
+ *   4. WARN_LIMIT_NEAR (sorted by eventTypeId)
+ *   5. ABORT_LIMIT_HIT (sorted by eventTypeId)
+ *
+ * This is deterministic: same logical inputs always produce the same output
+ * regardless of input ordering.
+ */
+export declare function computePlan(input: ComputePlanInput): PlanResult;
+//# sourceMappingURL=plan.d.ts.map

package/dist/cli/plan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan.d.ts","sourceRoot":"","sources":["../../src/cli/plan.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EACV,cAAc,EAEd,UAAU,EACV,mBAAmB,EACpB,MAAM,YAAY,CAAC;AAMpB,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,SAAS,cAAc,EAAE,CAAC;IACnC,OAAO,EAAE,SAAS,mBAAmB,EAAE,CAAC;IACxC;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B;;;OAGG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;;;OAGG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B;AAMD;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,gBAAgB,GAAG,UAAU,CAyH/D"}