@vaam-apps/vpay-sdk 0.2.1

package/dist/types.js

@@ -0,0 +1,48 @@
+/**
+ * Wire types for vpay's `/v1` resource contract
+ * (docs/api/README.md, docs/flows/merchant-auth.md's "Objects" table).
+ */
+/** Narrows a {@link PaymentIntent}-shaped value out of `event.data.object`. */
+export function isPaymentIntentEvent(event) {
+    return event.type.startsWith("payment_intent.");
+}
+/** Narrows a {@link Refund}-shaped value out of `event.data.object`. */
+export function isRefundEvent(event) {
+    return event.type.startsWith("charge.refund");
+}
+/**
+ * Narrows a {@link CheckoutSession}-shaped value out of `event.data.object`.
+ *
+ * Matched on the `checkout.session.` prefix rather than on the one literal
+ * type vpay emits today, exactly as the two guards above are: a later
+ * `checkout.session.*` type carries the same object, and a guard that had to
+ * be edited for each one is a guard that will be out of date before the
+ * `switch` that calls it is.
+ *
+ * The session on an event **never** carries `client_secret`, and its `url` is
+ * always `null`: both would put a live payer credential in a body that is
+ * stored, delivered at-least-once and replayed
+ * (`vpay_api::model::CheckoutSessionObject::expired_snapshot`). So
+ * {@link CheckoutSession.url} being `null` here does not mean the session was
+ * embedded — read {@link CheckoutSession.ui_mode} for that.
+ */
+export function isCheckoutSessionEvent(event) {
+    return event.type.startsWith("checkout.session.");
+}
+/**
+ * Narrows an {@link Invoice}-shaped value out of `event.data.object`, for one
+ * of the four `invoice.*` events (S4b).
+ *
+ * Matched on the `invoice.` prefix rather than on the four literals, as every
+ * guard above is.
+ *
+ * **The invoice on an event carries no lines.** `data.object.lines.data` is
+ * empty on every `invoice.*` body — the event is rendered inside the
+ * transition's own transaction, where the lines are not read — so
+ * {@link Invoice.lines} here is an empty {@link List}, and that is not the
+ * same statement as "this invoice has no lines". A handler that needs them
+ * calls `client.invoices.retrieve`, whose response always carries them.
+ */
+export function isInvoiceEvent(event) {
+    return event.type.startsWith("invoice.");
+}

package/dist/validate.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Shared request-shape validation, run before anything reaches the wire.
+ */
+/**
+ * Mirrors `@vpay/api-client`'s `formatAmount` integer check
+ * (frontends/packages/api-client/src/index.ts) and
+ * docs/flows/money.md's rule that money is an integer count of a currency's
+ * minor unit — no floating point in the money path, ever.
+ *
+ * `Number.isInteger` alone is not that rule: it accepts `-1`, `1e21` (which
+ * `String()` renders as `1e+21`, not a decimal integer) and integers past
+ * `Number.MAX_SAFE_INTEGER`, where the value the caller wrote and the value
+ * JavaScript holds have already diverged. An amount must be a non-negative
+ * **safe** integer or nothing goes to the wire.
+ */
+export declare function assertIntegerAmount(amount: number, field?: string): void;

package/dist/validate.js

@@ -0,0 +1,20 @@
+/**
+ * Shared request-shape validation, run before anything reaches the wire.
+ */
+/**
+ * Mirrors `@vpay/api-client`'s `formatAmount` integer check
+ * (frontends/packages/api-client/src/index.ts) and
+ * docs/flows/money.md's rule that money is an integer count of a currency's
+ * minor unit — no floating point in the money path, ever.
+ *
+ * `Number.isInteger` alone is not that rule: it accepts `-1`, `1e21` (which
+ * `String()` renders as `1e+21`, not a decimal integer) and integers past
+ * `Number.MAX_SAFE_INTEGER`, where the value the caller wrote and the value
+ * JavaScript holds have already diverged. An amount must be a non-negative
+ * **safe** integer or nothing goes to the wire.
+ */
+export function assertIntegerAmount(amount, field = "amount") {
+    if (!Number.isSafeInteger(amount) || amount < 0) {
+        throw new TypeError(`${field} must be a non-negative safe integer in minor units, got ${amount}`);
+    }
+}

package/dist/version.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The SDK's own version, sent as the `vpay-sdk-node/<version>` User-Agent
+ * suffix (docs/flows/merchant-auth.md, "Headers" table).
+ *
+ * Kept as a hand-written constant rather than read from `package.json` at
+ * runtime: this package builds to plain Node ESM via `tsc`
+ * (`moduleResolution: "NodeNext"`), and importing JSON across that boundary
+ * needs an import attribute whose support has shifted between Node
+ * releases. A hand-written constant has no such landmine — it just needs to
+ * be bumped alongside `package.json`'s own `version` field.
+ */
+export declare const SDK_VERSION = "0.2.1";

package/dist/version.js

@@ -0,0 +1,12 @@
+/**
+ * The SDK's own version, sent as the `vpay-sdk-node/<version>` User-Agent
+ * suffix (docs/flows/merchant-auth.md, "Headers" table).
+ *
+ * Kept as a hand-written constant rather than read from `package.json` at
+ * runtime: this package builds to plain Node ESM via `tsc`
+ * (`moduleResolution: "NodeNext"`), and importing JSON across that boundary
+ * needs an import attribute whose support has shifted between Node
+ * releases. A hand-written constant has no such landmine — it just needs to
+ * be bumped alongside `package.json`'s own `version` field.
+ */
+export const SDK_VERSION = "0.2.1"; // x-release-please-version

package/dist/webhooks.d.ts

@@ -0,0 +1,22 @@
+import type { Event } from "./types.js";
+export interface VerifyWebhookOptions {
+    /** The exact bytes vpay sent. A parsed-and-reserialised body breaks the HMAC. */
+    rawBody: string | Buffer;
+    /** The `Vpay-Signature` header value: `t=<unix seconds>,v1=<hex>[,v1=<hex>...]`. */
+    signatureHeader: string;
+    /** The webhook endpoint's signing secret. */
+    secret: string;
+    /** Default 300 (5 minutes), per docs/flows/webhooks.md. */
+    toleranceSeconds?: number | undefined;
+    /** Unix seconds. Defaults to `Date.now() / 1000`, injectable for tests. */
+    now?: number | undefined;
+}
+/**
+ * Verifies a `Vpay-Signature` header against `rawBody` and returns the
+ * parsed {@link Event} only once verification succeeds.
+ *
+ * @throws {WebhookSignatureError} on a malformed header, a timestamp outside
+ *   `toleranceSeconds`, no matching signature, or a body that is not valid
+ *   JSON once the signature checks out.
+ */
+export declare function verifyWebhook(options: VerifyWebhookOptions): Event;

package/dist/webhooks.js

@@ -0,0 +1,94 @@
+/**
+ * Verifier for vpay's outbound webhook signature scheme — Stripe's own,
+ * copied exactly (docs/flows/webhooks.md, docs/flows/merchant-auth.md's
+ * "Webhook verification" section). Productises the hand-rolled version in
+ * `examples/webhook-receiver/index.mjs`.
+ */
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { WebhookSignatureError } from "./errors.js";
+const DEFAULT_TOLERANCE_SECONDS = 300;
+/**
+ * The only `t` this verifier accepts: one or more decimal digits, nothing
+ * else. `Number()` is far more permissive — it reads `0x65566CC0` as
+ * 1700000000, `1700000000.0` as 1700000000 and `""` as 0 — which would turn
+ * a malformed header into either a *tolerance* failure or a signature that is
+ * computed over bytes the sender never signed.
+ */
+const TIMESTAMP_PATTERN = /^\d+$/;
+function parseSignatureHeader(header) {
+    let timestampText;
+    const signatures = [];
+    for (const part of header.split(",")) {
+        const separatorIndex = part.indexOf("=");
+        if (separatorIndex === -1) {
+            continue;
+        }
+        const key = part.slice(0, separatorIndex).trim();
+        const value = part.slice(separatorIndex + 1).trim();
+        if (key === "t") {
+            timestampText = value;
+        }
+        else if (key === "v1" && value.length > 0) {
+            signatures.push(value);
+        }
+    }
+    if (timestampText === undefined || !TIMESTAMP_PATTERN.test(timestampText)) {
+        throw new WebhookSignatureError('malformed Vpay-Signature header: missing or invalid "t"');
+    }
+    const timestamp = Number(timestampText);
+    if (!Number.isFinite(timestamp)) {
+        throw new WebhookSignatureError('malformed Vpay-Signature header: missing or invalid "t"');
+    }
+    if (signatures.length === 0) {
+        throw new WebhookSignatureError('malformed Vpay-Signature header: no "v1" signature present');
+    }
+    return { timestampText, timestamp, signatures };
+}
+function constantTimeHexEquals(a, b) {
+    const bufferA = Buffer.from(a, "utf8");
+    const bufferB = Buffer.from(b, "utf8");
+    // Length check first: `timingSafeEqual` throws on a length mismatch
+    // rather than returning false.
+    return bufferA.length === bufferB.length && timingSafeEqual(bufferA, bufferB);
+}
+/**
+ * Verifies a `Vpay-Signature` header against `rawBody` and returns the
+ * parsed {@link Event} only once verification succeeds.
+ *
+ * @throws {WebhookSignatureError} on a malformed header, a timestamp outside
+ *   `toleranceSeconds`, no matching signature, or a body that is not valid
+ *   JSON once the signature checks out.
+ */
+export function verifyWebhook(options) {
+    const tolerance = options.toleranceSeconds ?? DEFAULT_TOLERANCE_SECONDS;
+    const now = options.now ?? Math.floor(Date.now() / 1000);
+    const { timestampText, timestamp, signatures } = parseSignatureHeader(options.signatureHeader);
+    if (Math.abs(now - timestamp) > tolerance) {
+        throw new WebhookSignatureError(`webhook timestamp ${timestamp} is outside the ${tolerance}s tolerance (now=${now})`);
+    }
+    const rawBodyBuffer = typeof options.rawBody === "string"
+        ? Buffer.from(options.rawBody, "utf8")
+        : options.rawBody;
+    // The signed payload is the literal bytes `"<t>.<raw body>"`
+    // (docs/flows/merchant-auth.md). `timestampText`, not `timestamp`: the
+    // number is a lossy re-rendering of the header text, and any difference
+    // between the two — a leading zero, say — computes an HMAC over bytes the
+    // sender never signed, rejecting a genuine delivery.
+    const signedPayload = Buffer.concat([
+        Buffer.from(`${timestampText}.`, "utf8"),
+        rawBodyBuffer,
+    ]);
+    const expectedSignature = createHmac("sha256", options.secret)
+        .update(signedPayload)
+        .digest("hex");
+    const matched = signatures.some((candidate) => constantTimeHexEquals(candidate, expectedSignature));
+    if (!matched) {
+        throw new WebhookSignatureError('no "v1" signature in the header matches the computed HMAC');
+    }
+    try {
+        return JSON.parse(rawBodyBuffer.toString("utf8"));
+    }
+    catch (err) {
+        throw new WebhookSignatureError("signature verified but the body is not valid JSON", { cause: err });
+    }
+}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@vaam-apps/vpay-sdk",
+  "version": "0.2.1",
+  "description": "The Node.js merchant SDK for vpay's /v1 API: OAuth2 private_key_jwt, payment intents, checkout sessions, refunds, events and webhook verification.",
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vaam-apps/vpay.git",
+    "directory": "sdks/nodejs"
+  },
+  "homepage": "https://github.com/vaam-apps/vpay/tree/master/sdks/nodejs#readme",
+  "bugs": {
+    "url": "https://github.com/vaam-apps/vpay/issues"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=22.11.0"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./stripe": {
+      "types": "./dist/stripe-auth.d.ts",
+      "default": "./dist/stripe-auth.js"
+    }
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "scripts",
+    "README.md"
+  ],
+  "peerDependencies": {
+    "stripe": "^22.6.1"
+  },
+  "peerDependenciesMeta": {
+    "stripe": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "eslint": "9.39.5",
+    "stripe": "^22.6.1",
+    "typescript": "^5.7.0",
+    "vitest": "^4.1.11",
+    "@vpay/config": "0.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "test:live": "vitest run -c vitest.live.config.ts",
+    "lint": "eslint . --max-warnings 0"
+  }
+}

package/scripts/mint-assertion.mjs

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+/**
+ * Mints one `private_key_jwt` client assertion and prints it, alongside the
+ * public JWK derived from the same private key, as JSON on stdout:
+ *
+ *   { "assertion": "<jwt>", "jwks": { "keys": [<public JWK>] } }
+ *
+ * Intended for a Rust example to feed straight into the real
+ * `authkestra_op::client_assertion::verify_client_assertion` — see
+ * docs/flows/merchant-auth.md and docs/status.md's "Node SDK" row.
+ *
+ * Reads from the environment:
+ *   VPAY_CLIENT_ID          required
+ *   VPAY_PRIVATE_KEY_FILE   required — path to a PEM private key
+ *   VPAY_AUDIENCE           required — the assertion's `aud` (token endpoint URL)
+ *   VPAY_KID                optional
+ *
+ * Run after `pnpm --filter @vaam-apps/vpay-sdk build` (imports from ../dist).
+ */
+import { readFileSync } from "node:fs";
+import { createPrivateKey, createPublicKey } from "node:crypto";
+import { mintClientAssertion } from "../dist/index.js";
+
+function requireEnv(name) {
+  const value = process.env[name];
+  if (!value) {
+    console.error(`missing required environment variable: ${name}`);
+    process.exit(1);
+  }
+  return value;
+}
+
+const clientId = requireEnv("VPAY_CLIENT_ID");
+const privateKeyFile = requireEnv("VPAY_PRIVATE_KEY_FILE");
+const audience = requireEnv("VPAY_AUDIENCE");
+const kid = process.env.VPAY_KID || undefined;
+
+let privateKeyPem;
+try {
+  privateKeyPem = readFileSync(privateKeyFile, "utf8");
+} catch (err) {
+  console.error(
+    `cannot read VPAY_PRIVATE_KEY_FILE (${privateKeyFile}): ${err.message}`,
+  );
+  process.exit(1);
+}
+
+let privateKey;
+try {
+  privateKey = createPrivateKey(privateKeyPem);
+} catch (err) {
+  console.error(
+    `VPAY_PRIVATE_KEY_FILE (${privateKeyFile}) is not a readable PEM private key: ${err.message}`,
+  );
+  process.exit(1);
+}
+const publicKey = createPublicKey(privateKey);
+
+const assertion = mintClientAssertion({
+  clientId,
+  privateKey,
+  audience,
+  ...(kid ? { kid } : {}),
+});
+
+const jwk = publicKey.export({ format: "jwk" });
+if (kid) {
+  jwk.kid = kid;
+}
+
+process.stdout.write(
+  `${JSON.stringify({ assertion, jwks: { keys: [jwk] } })}\n`,
+);