@izapai/sdk 0.0.0 → 0.4.1

package/dist/webhooks.js

@@ -0,0 +1,153 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+/** Header names iZap sends with every webhook delivery. */
+export const WEBHOOK_HEADERS = {
+    id: "izap-webhook-id",
+    event: "izap-webhook-event",
+    timestamp: "izap-webhook-timestamp",
+    signature: "izap-webhook-signature",
+    v2: "izap-webhook-signature-v2",
+};
+export const DEFAULT_TOLERANCE_SEC = 300;
+const SIGNATURE_VERSION = "v1";
+const SIGNATURE_VERSION_V2 = "v2";
+export class WebhookVerificationError extends Error {
+    name = "WebhookVerificationError";
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+/**
+ * Verifies an iZap webhook delivery and returns the parsed event.
+ *
+ * By default, requires `izap-webhook-signature-v2`
+ * (`v2=<hex HMAC-SHA256 of "{id}.{timestamp}.{raw_body}">`) — it covers the
+ * delivery id, so a captured delivery cannot be replayed under a new id the way
+ * it can under v1. Pass `allowV1: true` to accept a v1-only
+ * `izap-webhook-signature` (`v1=<hex HMAC-SHA256 of "{timestamp}.{raw_body}">`)
+ * when v2 is absent (senders from before v2 existed). Either check runs in
+ * constant time. Both checks also reject timestamps outside `toleranceSec`.
+ *
+ * @throws {WebhookVerificationError} when the delivery is not authentic or is stale.
+ */
+export function verify(options) {
+    const { secret, toleranceSec = DEFAULT_TOLERANCE_SEC, allowV1 = false, } = options;
+    if (typeof secret !== "string" || secret === "") {
+        throw new TypeError("webhooks.verify: `secret` is required.");
+    }
+    const body = rawBytes(options.payload);
+    const id = readHeader(options.headers, WEBHOOK_HEADERS.id);
+    const timestamp = readHeader(options.headers, WEBHOOK_HEADERS.timestamp);
+    const signature = readHeader(options.headers, WEBHOOK_HEADERS.signature);
+    const signatureV2 = readHeader(options.headers, WEBHOOK_HEADERS.v2);
+    const missing = [
+        [WEBHOOK_HEADERS.id, id],
+        [WEBHOOK_HEADERS.timestamp, timestamp],
+    ]
+        .filter(([, value]) => !value)
+        .map(([name]) => name);
+    if (!signatureV2 && !allowV1) {
+        missing.push(WEBHOOK_HEADERS.v2);
+    }
+    else if (!signature && !signatureV2) {
+        missing.push(`${WEBHOOK_HEADERS.signature} or ${WEBHOOK_HEADERS.v2}`);
+    }
+    if (!id ||
+        !timestamp ||
+        (!signatureV2 && !allowV1) ||
+        (!signature && !signatureV2)) {
+        throw new WebhookVerificationError("missing_header", `Missing webhook header(s): ${missing.join(", ")}.`);
+    }
+    if (!/^\d+$/.test(timestamp)) {
+        throw new WebhookVerificationError("invalid_timestamp", `${WEBHOOK_HEADERS.timestamp} is not a Unix timestamp.`);
+    }
+    const timestampSec = Number(timestamp);
+    if (Math.abs(Date.now() / 1000 - timestampSec) > toleranceSec) {
+        throw new WebhookVerificationError("timestamp_out_of_tolerance", `${WEBHOOK_HEADERS.timestamp} is more than ${toleranceSec}s away from the current time.`);
+    }
+    // v2 wins whenever it is present: it is the stronger check (it covers `id`,
+    // closing v1's replay-under-a-new-id gap), and a delivery must not silently
+    // fall back to a v1 signature that happens to still verify.
+    const usingV2 = Boolean(signatureV2);
+    const activeHeaderName = usingV2
+        ? WEBHOOK_HEADERS.v2
+        : WEBHOOK_HEADERS.signature;
+    const activeSignature = (usingV2 ? signatureV2 : signature);
+    const activeVersion = usingV2 ? SIGNATURE_VERSION_V2 : SIGNATURE_VERSION;
+    const expectedHex = usingV2
+        ? computeSignatureV2(secret, id, timestamp, body)
+        : computeSignature(secret, timestamp, body);
+    if (!signatureMatches(activeSignature, activeVersion, expectedHex)) {
+        throw new WebhookVerificationError("invalid_signature", `${activeHeaderName} does not match the payload.`);
+    }
+    let data;
+    try {
+        data = JSON.parse(body.toString("utf8"));
+    }
+    catch {
+        throw new WebhookVerificationError("invalid_payload", "The signed payload is not valid JSON.");
+    }
+    const event = readHeader(options.headers, WEBHOOK_HEADERS.event) ??
+        (typeof data === "object" && data !== null && "event" in data
+            ? String(data.event)
+            : "");
+    return { id, event, timestamp: timestampSec, data };
+}
+/**
+ * Produces the `izap-webhook-signature` (v1) value for a payload, e.g. to exercise
+ * a receiver locally with a known secret. See {@link signV2} for the v2 scheme.
+ */
+export function sign(options) {
+    const timestamp = String(options.timestamp ?? Math.floor(Date.now() / 1000));
+    return `${SIGNATURE_VERSION}=${computeSignature(options.secret, timestamp, rawBytes(options.payload))}`;
+}
+/**
+ * Produces the `izap-webhook-signature-v2` value for a payload, e.g. to exercise a
+ * receiver locally with a known secret. Unlike v1, this also signs `id`.
+ */
+export function signV2(options) {
+    const timestamp = String(options.timestamp ?? Math.floor(Date.now() / 1000));
+    return `${SIGNATURE_VERSION_V2}=${computeSignatureV2(options.secret, options.id, timestamp, rawBytes(options.payload))}`;
+}
+function computeSignature(secret, timestamp, body) {
+    return createHmac("sha256", secret)
+        .update(`${timestamp}.`)
+        .update(body)
+        .digest("hex");
+}
+function computeSignatureV2(secret, id, timestamp, body) {
+    return createHmac("sha256", secret)
+        .update(`${id}.${timestamp}.`)
+        .update(body)
+        .digest("hex");
+}
+function signatureMatches(headerValue, version, expectedHex) {
+    const expected = Buffer.from(expectedHex, "hex");
+    return headerValue
+        .split(/[\s,]+/)
+        .filter((entry) => entry.startsWith(`${version}=`))
+        .map((entry) => entry.slice(version.length + 1))
+        .filter((hex) => /^[0-9a-f]{64}$/i.test(hex))
+        .some((hex) => timingSafeEqual(Buffer.from(hex, "hex"), expected));
+}
+function rawBytes(payload) {
+    if (typeof payload === "string")
+        return Buffer.from(payload, "utf8");
+    if (payload instanceof Uint8Array) {
+        return Buffer.from(payload.buffer, payload.byteOffset, payload.byteLength);
+    }
+    throw new TypeError("webhooks: `payload` must be the raw request body as a string or Buffer, not a parsed object.");
+}
+function readHeader(headers, name) {
+    if (headers instanceof Headers)
+        return headers.get(name) ?? undefined;
+    for (const [key, value] of Object.entries(headers)) {
+        if (key.toLowerCase() !== name)
+            continue;
+        const first = Array.isArray(value) ? value[0] : value;
+        return first || undefined;
+    }
+    return undefined;
+}
+//# sourceMappingURL=webhooks.js.map

package/dist/webhooks.js.map

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

package/package.json

@@ -1,7 +1,62 @@
 {
   "name": "@izapai/sdk",
-  "version": "0.0.0",
-  "description": "Placeholder to enable npm Trusted Publishing. Real releases start at 0.3.0.",
+  "version": "0.4.1",
+  "description": "TypeScript SDK for the iZap REST API: WhatsApp business messaging, templates, chats and webhooks.",
+  "type": "module",
   "license": "MIT",
-  "publishConfig": { "access": "public" }
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/versariai/izap-sdk-typescript.git"
+  },
+  "homepage": "https://devs.izap.ai",
+  "bugs": {
+    "url": "https://github.com/versariai/izap-sdk-typescript/issues",
+    "email": "support@izap.ai"
+  },
+  "keywords": [
+    "izap",
+    "whatsapp",
+    "sdk",
+    "api",
+    "webhooks"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist/",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "generate": "openapi-ts",
+    "sync:schema": "node scripts/sync-schema.mjs",
+    "check:generated": "node scripts/check-generated.mjs",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "npm run typecheck && vitest run",
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "prepublishOnly": "npm test && npm run build"
+  },
+  "devDependencies": {
+    "@hey-api/openapi-ts": "0.99.0",
+    "@types/node": "20.19.43",
+    "prettier": "3.9.6",
+    "typescript": "5.9.3",
+    "vitest": "4.1.11"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
 }