orqo-node-sdk 0.1.0

package/dist/webhook-handler.js

@@ -0,0 +1,161 @@
+/**
+ * Webhook Handler — Zero-dependency event dispatcher
+ *
+ * Creates a request handler that verifies HMAC signatures
+ * and dispatches typed events to registered callbacks.
+ *
+ * Works with any HTTP framework (Express, Hono, Fastify, etc.)
+ * via a generic interface.
+ *
+ * @example Express
+ * ```ts
+ * import express from 'express';
+ * import { createWebhookHandler } from '@orqo/sdk';
+ *
+ * const app = express();
+ * app.use(express.json());
+ *
+ * app.post('/webhooks/orqo', createWebhookHandler({
+ *   secret: 'my-hmac-secret',
+ *   onConnectionChanged: (e) => console.log(`${e.instanceId} → ${e.state}`),
+ *   onMessageReceived: (e) => console.log(`From ${e.from}: ${e.text}`),
+ *   onMessageProcessed: (e) => console.log(`Processed: ${e.messageId}`),
+ *   onHandoff: (e) => console.log(`Handoff: ${e.sessionId}`),
+ * }));
+ * ```
+ */
+/**
+ * Creates a webhook handler function compatible with Express/Hono/etc.
+ *
+ * The handler:
+ * 1. Verifies the HMAC signature (if secret is configured)
+ * 2. Parses the event
+ * 3. Dispatches to the appropriate typed callback
+ * 4. Returns 200 OK
+ */
+export function createWebhookHandler(options) {
+    return async (req, res) => {
+        try {
+            // 1. Verify HMAC signature
+            if (options.secret) {
+                const signature = getHeader(req, 'x-webhook-signature');
+                if (!signature) {
+                    sendResponse(res, 401, { error: 'Missing X-Webhook-Signature header' });
+                    options.onVerificationFailed?.(new Error('Missing signature'));
+                    return;
+                }
+                const body = typeof req.body === 'string' ? req.body : JSON.stringify(req.body);
+                const isValid = await verifyHmac(options.secret, body, signature);
+                if (!isValid) {
+                    sendResponse(res, 403, { error: 'Invalid signature' });
+                    options.onVerificationFailed?.(new Error('Invalid HMAC signature'));
+                    return;
+                }
+            }
+            // 2. Parse event
+            const event = (typeof req.body === 'string' ? JSON.parse(req.body) : req.body);
+            if (!event || !event.event) {
+                sendResponse(res, 400, { error: 'Invalid event payload' });
+                return;
+            }
+            // 3. Dispatch to typed callbacks
+            switch (event.event) {
+                case 'connection:changed':
+                    await options.onConnectionChanged?.(event);
+                    break;
+                case 'message:received':
+                    await options.onMessageReceived?.(event);
+                    break;
+                case 'message:processed':
+                    await options.onMessageProcessed?.(event);
+                    break;
+                case 'session:handoff':
+                    await options.onHandoff?.(event);
+                    break;
+            }
+            // Always call onEvent for catch-all
+            await options.onEvent?.(event);
+            // 4. Acknowledge
+            sendResponse(res, 200, { received: true });
+        }
+        catch (error) {
+            sendResponse(res, 500, { error: 'Webhook handler error' });
+        }
+    };
+}
+// ============================================================================
+// HMAC Verification (works in Node.js and Web Crypto)
+// ============================================================================
+async function verifyHmac(secret, body, signature) {
+    // Expected format: "sha256=<hex>"
+    const expectedHex = signature.startsWith('sha256=')
+        ? signature.slice(7)
+        : signature;
+    // Try Web Crypto API first (universal), then Node.js crypto
+    if (typeof globalThis.crypto?.subtle !== 'undefined') {
+        return verifyHmacWebCrypto(secret, body, expectedHex);
+    }
+    // Node.js fallback
+    try {
+        const crypto = await import('crypto');
+        const expected = crypto
+            .createHmac('sha256', secret)
+            .update(body)
+            .digest('hex');
+        return timingSafeEqual(expected, expectedHex);
+    }
+    catch {
+        return false;
+    }
+}
+async function verifyHmacWebCrypto(secret, body, expectedHex) {
+    const encoder = new TextEncoder();
+    const key = await crypto.subtle.importKey('raw', encoder.encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+    const sig = await crypto.subtle.sign('HMAC', key, encoder.encode(body));
+    const computed = Array.from(new Uint8Array(sig))
+        .map(b => b.toString(16).padStart(2, '0'))
+        .join('');
+    return timingSafeEqual(computed, expectedHex);
+}
+/** Constant-time string comparison to prevent timing attacks. */
+function timingSafeEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let result = 0;
+    for (let i = 0; i < a.length; i++) {
+        result |= a.charCodeAt(i) ^ b.charCodeAt(i);
+    }
+    return result === 0;
+}
+// ============================================================================
+// Helpers
+// ============================================================================
+function getHeader(req, name) {
+    if (!req.headers)
+        return null;
+    // Express-style: req.headers[name]
+    if (typeof req.headers === 'object' && !('get' in req.headers)) {
+        const headers = req.headers;
+        const value = headers[name] ?? headers[name.toLowerCase()];
+        return Array.isArray(value) ? value[0] : value ?? null;
+    }
+    // Hono/Fetch-style: req.headers.get(name)
+    if ('get' in req.headers && typeof req.headers.get === 'function') {
+        return req.headers.get(name);
+    }
+    return null;
+}
+function sendResponse(res, status, body) {
+    // Express-style
+    if (res.status && res.json) {
+        const r = res.status(status);
+        if (r && r.json)
+            r.json(body);
+        return;
+    }
+    // Node http-style
+    if (res.writeHead && res.end) {
+        res.writeHead(status, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify(body));
+    }
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+    "name": "orqo-node-sdk",
+    "version": "0.1.0",
+    "description": "Orqo Gateway — TypeScript SDK for plug-and-play WhatsApp integration",
+    "type": "module",
+    "main": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "exports": {
+        ".": {
+            "import": "./dist/index.js",
+            "types": "./dist/index.d.ts"
+        }
+    },
+    "files": [
+        "dist",
+        "README.md"
+    ],
+    "scripts": {
+        "build": "tsc",
+        "test": "vitest run",
+        "prepublishOnly": "npm run build"
+    },
+    "keywords": [
+        "orqo",
+        "whatsapp",
+        "sdk",
+        "bot",
+        "gateway"
+    ],
+    "license": "MIT",
+    "devDependencies": {
+        "@types/node": "^25.3.0",
+        "typescript": "^5.4.0",
+        "vitest": "^4.0.18"
+    }
+}