@sakeetech/viva-payments-core 0.2.1

package/dist/webhooks/status-lattice.js

@@ -0,0 +1,208 @@
+/**
+ * Viva transaction status mapping and monotonic status lattice.
+ *
+ * Implements plan P17 (status letter → plugin enum) and plan A9
+ * (authorized → cancelled allowed — void-before-capture transition).
+ *
+ * Status lattice (per P17 + A9):
+ *   initiated  → authorized | captured | failed
+ *   authorized → captured | cancelled | failed | disputed   ← A9 added cancelled
+ *   captured   → refunded | disputed
+ *   refunded   → disputed
+ *   failed, cancelled, disputed → TERMINAL (no further transitions)
+ *
+ * Terminal states never transition except to themselves (idempotent re-apply).
+ *
+ * @see references/viva-docs/md/wh-sale-transactions.txt:210
+ * @see references/viva-docs/md/wh-transaction-payment-created.txt:398
+ */
+/**
+ * Pure mapping from Viva's `StatusId` letter to the plugin's canonical status.
+ *
+ * M-family letters (M, MA, MI, ML, MS, MW) all map to `'disputed'` with the
+ * specific letter preserved as `claimSubstate`.
+ *
+ * @see references/viva-docs/md/wh-sale-transactions.txt:210
+ * @see references/viva-docs/md/wh-transaction-payment-created.txt:398
+ */
+export function mapStatusLetter(letter) {
+    switch (letter) {
+        case 'F':
+            return { status: 'captured', claimSubstate: null };
+        case 'A':
+            return { status: 'authorized', claimSubstate: null };
+        case 'C':
+            return { status: 'captured', claimSubstate: null };
+        case 'E':
+            return { status: 'failed', claimSubstate: null };
+        case 'R':
+            return { status: 'refunded', claimSubstate: null };
+        case 'X':
+            return { status: 'cancelled', claimSubstate: null };
+        case 'M':
+            return { status: 'disputed', claimSubstate: 'M' };
+        case 'MA':
+            return { status: 'disputed', claimSubstate: 'MA' };
+        case 'MI':
+            return { status: 'disputed', claimSubstate: 'MI' };
+        case 'ML':
+            return { status: 'disputed', claimSubstate: 'ML' };
+        case 'MS':
+            return { status: 'disputed', claimSubstate: 'MS' };
+        case 'MW':
+            return { status: 'disputed', claimSubstate: 'MW' };
+    }
+}
+// ---------------------------------------------------------------------------
+// Status transition lattice
+// ---------------------------------------------------------------------------
+/**
+ * Terminal states — no transitions out (other than idempotent self-transition).
+ *
+ * Derived from the lattice: any state whose allowed-set is empty.
+ * `captured` and `refunded` are NOT terminal because they can still
+ * transition to `refunded`/`disputed` respectively.
+ *
+ * @see Plan P17, Plan A9
+ */
+const TERMINAL_STATES = new Set([
+    'failed',
+    'cancelled',
+    'disputed',
+]);
+/**
+ * Allowed forward transitions per source state.
+ *
+ * Lattice (per P17 + A9):
+ *   initiated  → authorized | captured | failed
+ *   authorized → captured | cancelled | failed | disputed   ← A9 added cancelled
+ *   captured   → refunded | disputed
+ *   refunded   → disputed
+ *   failed     → (terminal — no transitions)
+ *   cancelled  → (terminal — no transitions)
+ *   disputed   → (terminal — no transitions)
+ *
+ * Note: `captured` is terminal in the sense that no real-world event takes a
+ * captured payment backwards, but it can still transition forward to `refunded`
+ * or `disputed`.
+ *
+ * @see references/viva-docs/md/wh-transaction-payment-created.txt:398
+ */
+const LATTICE = new Map([
+    ['initiated', new Set(['authorized', 'captured', 'failed'])],
+    ['authorized', new Set(['captured', 'cancelled', 'failed', 'disputed'])],
+    ['captured', new Set(['refunded', 'disputed'])],
+    ['refunded', new Set(['disputed'])],
+    // Terminal states — empty sets (no forward transitions).
+    ['failed', new Set()],
+    ['cancelled', new Set()],
+    ['disputed', new Set()],
+]);
+// Verify the lattice is fully specified (TypeScript does not enforce exhaustive
+// Map entries, so we do a runtime assertion at module load time).
+const _ALL_STATUSES = [
+    'initiated',
+    'authorized',
+    'captured',
+    'refunded',
+    'failed',
+    'cancelled',
+    'disputed',
+];
+for (const s of _ALL_STATUSES) {
+    if (!LATTICE.has(s)) {
+        throw new Error(`BUG: status-lattice.ts is missing an entry for status '${s}'`);
+    }
+}
+// ---------------------------------------------------------------------------
+// Backward-reachability: used to classify BACKWARD vs ILLEGAL
+// ---------------------------------------------------------------------------
+/**
+ * Build the set of all states that are ancestors (upstream) of `target` in the
+ * DAG. Used to classify a rejected transition as BACKWARD vs ILLEGAL.
+ *
+ * The disputed state is a "side-exit" reachable from multiple states; we walk
+ * the full DAG regardless.
+ */
+function computeAncestors(target) {
+    const ancestors = new Set();
+    const queue = [];
+    // Find direct parents of `target`.
+    for (const [from, allowed] of LATTICE) {
+        if (allowed.has(target)) {
+            queue.push(from);
+        }
+    }
+    while (queue.length > 0) {
+        const node = queue.shift();
+        if (ancestors.has(node))
+            continue;
+        ancestors.add(node);
+        // Walk further up.
+        for (const [from, allowed] of LATTICE) {
+            if (allowed.has(node) && !ancestors.has(from)) {
+                queue.push(from);
+            }
+        }
+    }
+    return ancestors;
+}
+// Pre-compute ancestor sets for all statuses (module-load-time, not per-call).
+const _ANCESTORS = new Map(_ALL_STATUSES.map((s) => [s, computeAncestors(s)]));
+// ---------------------------------------------------------------------------
+// Public validator
+// ---------------------------------------------------------------------------
+/**
+ * Pure validator. Does NOT mutate state. Returns a typed result describing
+ * whether the `current → next` transition is allowed by the lattice.
+ *
+ * Returns:
+ * - `{ ok: true, next }` if the transition is allowed OR if `next === current`
+ *   (idempotent re-apply).
+ * - `{ ok: false, reason: 'TERMINAL' }` if `current` is terminal and
+ *   `next !== current`.
+ * - `{ ok: false, reason: 'BACKWARD' }` if `next` is an ancestor of `current`
+ *   in the DAG.
+ * - `{ ok: false, reason: 'ILLEGAL' }` for any other invalid pair.
+ *
+ * Callers (the Medusa subscriber) use this before issuing an UPDATE to
+ * `viva_transaction.status`.
+ *
+ * @see Plan P17 (status lattice), Plan A9 (authorized → cancelled)
+ * @see references/viva-docs/md/wh-transaction-payment-created.txt:398
+ */
+export function validateStatusTransition(current, next) {
+    // Idempotent re-apply: same → same is always OK.
+    if (current === next) {
+        return { ok: true, next };
+    }
+    const allowed = LATTICE.get(current);
+    // Terminal state: current has no allowed transitions.
+    if (TERMINAL_STATES.has(current) && (allowed === undefined || allowed.size === 0)) {
+        return { ok: false, reason: 'TERMINAL', current, attempted: next };
+    }
+    // Allowed forward transition.
+    if (allowed !== undefined && allowed.has(next)) {
+        return { ok: true, next };
+    }
+    // Check if `next` is an ancestor of `current` → BACKWARD.
+    const ancestors = _ANCESTORS.get(current);
+    if (ancestors !== undefined && ancestors.has(next)) {
+        return { ok: false, reason: 'BACKWARD', current, attempted: next };
+    }
+    // Anything else (cross-edge, unrelated state) → ILLEGAL.
+    return { ok: false, reason: 'ILLEGAL', current, attempted: next };
+}
+/**
+ * Convenience wrapper: looks up `mapStatusLetter` then calls
+ * `validateStatusTransition`. Returns the full result so callers can decide
+ * whether to apply or log.
+ *
+ * Not part of the core interface spec, provided for S8 convenience.
+ */
+export function applyStatusTransition(current, incomingLetter) {
+    const { status: next, claimSubstate } = mapStatusLetter(incomingLetter);
+    const result = validateStatusTransition(current, next);
+    return { ...result, claimSubstate };
+}
+//# sourceMappingURL=status-lattice.js.map

package/dist/webhooks/status-lattice.js.map

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

package/package.json

@@ -0,0 +1,85 @@
+{
+  "name": "@sakeetech/viva-payments-core",
+  "version": "0.2.1",
+  "description": "Framework-agnostic Viva Wallet client for ISV integrations. Used by medusa-payment-viva and vendure-payment-viva.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sakee-tech/vivawallet-npm-public.git",
+    "directory": "packages/viva-payments-core"
+  },
+  "homepage": "https://github.com/sakee-tech/vivawallet-npm-public/tree/main/packages/viva-payments-core#readme",
+  "bugs": {
+    "url": "https://github.com/sakee-tech/vivawallet-npm-public/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./auth": {
+      "types": "./dist/auth/index.d.ts",
+      "import": "./dist/auth/index.js"
+    },
+    "./isv": {
+      "types": "./dist/isv/index.d.ts",
+      "import": "./dist/isv/index.js"
+    },
+    "./payments": {
+      "types": "./dist/payments/index.d.ts",
+      "import": "./dist/payments/index.js"
+    },
+    "./legacy": {
+      "types": "./dist/legacy/index.d.ts",
+      "import": "./dist/legacy/index.js"
+    },
+    "./refunds": {
+      "types": "./dist/refunds/index.d.ts",
+      "import": "./dist/refunds/index.js"
+    },
+    "./webhooks": {
+      "types": "./dist/webhooks/index.d.ts",
+      "import": "./dist/webhooks/index.js"
+    },
+    "./types": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/types/index.js"
+    },
+    "./errors": {
+      "types": "./dist/errors/index.d.ts",
+      "import": "./dist/errors/index.js"
+    },
+    "./observability": {
+      "types": "./dist/observability/index.d.ts",
+      "import": "./dist/observability/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "undici": "^7.2.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "clean": "rm -rf dist .tsbuildinfo coverage"
+  }
+}