@dojocoding/whatsapp-sdk 0.8.0

package/dist/adapters/hono/index.d.ts

@@ -0,0 +1,38 @@
+import { Handler } from 'hono';
+import { W as WebhookReceiver } from '../../receiver-C_yfwg6g.js';
+import { CreateWhatsAppHandlerOptions } from '../web/index.js';
+import '../../index-CDfzGvQJ.js';
+
+/**
+ * Hono adapter for `@dojocoding/whatsapp`.
+ *
+ * Thin wrapper around the web-standard `createWhatsAppHandler` core,
+ * adapted to Hono's `Handler` signature. The web core does all the
+ * work; this file just unwraps Hono's `c.req.raw` (which is a
+ * Fetch-API `Request`) and returns the `Response` Hono expects.
+ *
+ * Mount with:
+ *
+ *   import { Hono } from "hono";
+ *   import { WebhookReceiver } from "@dojocoding/whatsapp";
+ *   import { whatsappHandler } from "@dojocoding/whatsapp/hono";
+ *
+ *   const receiver = new WebhookReceiver({ appSecret, verifyToken });
+ *   receiver.on("message", async (e) => { … });
+ *
+ *   const app = new Hono();
+ *   app.all("/webhooks/whatsapp", whatsappHandler(receiver));
+ *
+ * See `docs/hono.md` for a full Cloudflare Workers + Hono walkthrough.
+ */
+
+/** Alias for the web-core options shape; same fields, same semantics. */
+type WhatsAppHonoHandlerOptions = CreateWhatsAppHandlerOptions;
+/**
+ * Build a Hono `Handler` that wires Meta's webhook contract to a
+ * framework-agnostic {@link WebhookReceiver} via the web-standard
+ * core. Mount with `app.all(path, whatsappHandler(receiver))`.
+ */
+declare function whatsappHandler(receiver: WebhookReceiver, options?: WhatsAppHonoHandlerOptions): Handler;
+
+export { type WhatsAppHonoHandlerOptions, whatsappHandler };

package/dist/adapters/hono/index.js

@@ -0,0 +1,50 @@
+// src/adapters/web/index.ts
+function createWhatsAppHandler(receiver, options = {}) {
+  const onUnhandledHandlerError = options.onUnhandledHandlerError ?? ((err) => {
+    console.error("[whatsapp/web] unhandled handler error:", err);
+  });
+  return async (req) => {
+    const method = req.method.toUpperCase();
+    if (method === "GET") {
+      const url = new URL(req.url);
+      const mode = url.searchParams.get("hub.mode") ?? void 0;
+      const verifyToken = url.searchParams.get("hub.verify_token") ?? void 0;
+      const challenge = url.searchParams.get("hub.challenge") ?? void 0;
+      const result = receiver.handleVerifyRequest({ mode, verifyToken, challenge });
+      if (result.status === 200) {
+        return new Response(result.body, {
+          status: 200,
+          headers: { "content-type": "text/plain" }
+        });
+      }
+      return new Response(null, { status: 403 });
+    }
+    if (method === "POST") {
+      const rawBody = new Uint8Array(await req.arrayBuffer());
+      const sigHeader = req.headers.get("x-hub-signature-256");
+      let parsed = void 0;
+      if (rawBody.length > 0) {
+        try {
+          parsed = JSON.parse(new TextDecoder("utf-8").decode(rawBody));
+        } catch {
+          parsed = void 0;
+        }
+      }
+      const result = await receiver.handlePayload(rawBody, sigHeader, parsed);
+      if (result.status === 200) {
+        result.dispatchPromise.catch(onUnhandledHandlerError);
+        return new Response(null, { status: 200 });
+      }
+      return new Response(null, { status: 401 });
+    }
+    return new Response(null, { status: 405, headers: { allow: "GET, POST" } });
+  };
+}
+
+// src/adapters/hono/index.ts
+function whatsappHandler(receiver, options = {}) {
+  const core = createWhatsAppHandler(receiver, options);
+  return (c) => core(c.req.raw);
+}
+
+export { whatsappHandler };

package/dist/adapters/web/index.cjs

@@ -0,0 +1,46 @@
+'use strict';
+
+// src/adapters/web/index.ts
+function createWhatsAppHandler(receiver, options = {}) {
+  const onUnhandledHandlerError = options.onUnhandledHandlerError ?? ((err) => {
+    console.error("[whatsapp/web] unhandled handler error:", err);
+  });
+  return async (req) => {
+    const method = req.method.toUpperCase();
+    if (method === "GET") {
+      const url = new URL(req.url);
+      const mode = url.searchParams.get("hub.mode") ?? void 0;
+      const verifyToken = url.searchParams.get("hub.verify_token") ?? void 0;
+      const challenge = url.searchParams.get("hub.challenge") ?? void 0;
+      const result = receiver.handleVerifyRequest({ mode, verifyToken, challenge });
+      if (result.status === 200) {
+        return new Response(result.body, {
+          status: 200,
+          headers: { "content-type": "text/plain" }
+        });
+      }
+      return new Response(null, { status: 403 });
+    }
+    if (method === "POST") {
+      const rawBody = new Uint8Array(await req.arrayBuffer());
+      const sigHeader = req.headers.get("x-hub-signature-256");
+      let parsed = void 0;
+      if (rawBody.length > 0) {
+        try {
+          parsed = JSON.parse(new TextDecoder("utf-8").decode(rawBody));
+        } catch {
+          parsed = void 0;
+        }
+      }
+      const result = await receiver.handlePayload(rawBody, sigHeader, parsed);
+      if (result.status === 200) {
+        result.dispatchPromise.catch(onUnhandledHandlerError);
+        return new Response(null, { status: 200 });
+      }
+      return new Response(null, { status: 401 });
+    }
+    return new Response(null, { status: 405, headers: { allow: "GET, POST" } });
+  };
+}
+
+exports.createWhatsAppHandler = createWhatsAppHandler;

package/dist/adapters/web/index.d.cts

@@ -0,0 +1,40 @@
+import { W as WebhookReceiver } from '../../receiver-DWJm571Z.cjs';
+import '../../index-CDfzGvQJ.cjs';
+
+/**
+ * Web-standard (Fetch-API) adapter for `@dojocoding/whatsapp`.
+ *
+ * Returns a function with shape `(req: Request) => Promise<Response>` —
+ * mountable as a Cloudflare Workers `fetch` handler, a Hono / Next.js
+ * App Router route handler, a Bun `Bun.serve` handler, or anywhere
+ * else that speaks the Fetch API.
+ *
+ * The Express adapter (`@dojocoding/whatsapp/express`) is a thin shim
+ * over this same core; see `docs/web.md` for runtime examples.
+ *
+ * Behaviour:
+ *   - GET → verify-token handshake via `receiver.handleVerifyRequest`.
+ *           200 text/plain with the challenge body on success, 403 on
+ *           mismatch.
+ *   - POST → raw bytes via `req.arrayBuffer()` (read exactly once),
+ *           passed verbatim to `receiver.handlePayload`. Acks 200
+ *           BEFORE awaiting handlers (Meta's 30 s rule), then runs
+ *           handlers asynchronously.
+ *   - Other verbs → 405 Method Not Allowed.
+ */
+
+interface CreateWhatsAppHandlerOptions {
+    /**
+     * Invoked when a handler thrown error escapes the dispatch promise.
+     * Defaults to `console.error`.
+     */
+    onUnhandledHandlerError?: (err: unknown) => void;
+}
+type WhatsAppHandler = (req: Request) => Promise<Response>;
+/**
+ * Build a Fetch-API handler wiring Meta's webhook contract to a
+ * framework-agnostic {@link WebhookReceiver}.
+ */
+declare function createWhatsAppHandler(receiver: WebhookReceiver, options?: CreateWhatsAppHandlerOptions): WhatsAppHandler;
+
+export { type CreateWhatsAppHandlerOptions, type WhatsAppHandler, createWhatsAppHandler };

package/dist/adapters/web/index.d.ts

@@ -0,0 +1,40 @@
+import { W as WebhookReceiver } from '../../receiver-C_yfwg6g.js';
+import '../../index-CDfzGvQJ.js';
+
+/**
+ * Web-standard (Fetch-API) adapter for `@dojocoding/whatsapp`.
+ *
+ * Returns a function with shape `(req: Request) => Promise<Response>` —
+ * mountable as a Cloudflare Workers `fetch` handler, a Hono / Next.js
+ * App Router route handler, a Bun `Bun.serve` handler, or anywhere
+ * else that speaks the Fetch API.
+ *
+ * The Express adapter (`@dojocoding/whatsapp/express`) is a thin shim
+ * over this same core; see `docs/web.md` for runtime examples.
+ *
+ * Behaviour:
+ *   - GET → verify-token handshake via `receiver.handleVerifyRequest`.
+ *           200 text/plain with the challenge body on success, 403 on
+ *           mismatch.
+ *   - POST → raw bytes via `req.arrayBuffer()` (read exactly once),
+ *           passed verbatim to `receiver.handlePayload`. Acks 200
+ *           BEFORE awaiting handlers (Meta's 30 s rule), then runs
+ *           handlers asynchronously.
+ *   - Other verbs → 405 Method Not Allowed.
+ */
+
+interface CreateWhatsAppHandlerOptions {
+    /**
+     * Invoked when a handler thrown error escapes the dispatch promise.
+     * Defaults to `console.error`.
+     */
+    onUnhandledHandlerError?: (err: unknown) => void;
+}
+type WhatsAppHandler = (req: Request) => Promise<Response>;
+/**
+ * Build a Fetch-API handler wiring Meta's webhook contract to a
+ * framework-agnostic {@link WebhookReceiver}.
+ */
+declare function createWhatsAppHandler(receiver: WebhookReceiver, options?: CreateWhatsAppHandlerOptions): WhatsAppHandler;
+
+export { type CreateWhatsAppHandlerOptions, type WhatsAppHandler, createWhatsAppHandler };

package/dist/adapters/web/index.js

@@ -0,0 +1,44 @@
+// src/adapters/web/index.ts
+function createWhatsAppHandler(receiver, options = {}) {
+  const onUnhandledHandlerError = options.onUnhandledHandlerError ?? ((err) => {
+    console.error("[whatsapp/web] unhandled handler error:", err);
+  });
+  return async (req) => {
+    const method = req.method.toUpperCase();
+    if (method === "GET") {
+      const url = new URL(req.url);
+      const mode = url.searchParams.get("hub.mode") ?? void 0;
+      const verifyToken = url.searchParams.get("hub.verify_token") ?? void 0;
+      const challenge = url.searchParams.get("hub.challenge") ?? void 0;
+      const result = receiver.handleVerifyRequest({ mode, verifyToken, challenge });
+      if (result.status === 200) {
+        return new Response(result.body, {
+          status: 200,
+          headers: { "content-type": "text/plain" }
+        });
+      }
+      return new Response(null, { status: 403 });
+    }
+    if (method === "POST") {
+      const rawBody = new Uint8Array(await req.arrayBuffer());
+      const sigHeader = req.headers.get("x-hub-signature-256");
+      let parsed = void 0;
+      if (rawBody.length > 0) {
+        try {
+          parsed = JSON.parse(new TextDecoder("utf-8").decode(rawBody));
+        } catch {
+          parsed = void 0;
+        }
+      }
+      const result = await receiver.handlePayload(rawBody, sigHeader, parsed);
+      if (result.status === 200) {
+        result.dispatchPromise.catch(onUnhandledHandlerError);
+        return new Response(null, { status: 200 });
+      }
+      return new Response(null, { status: 401 });
+    }
+    return new Response(null, { status: 405, headers: { allow: "GET, POST" } });
+  };
+}
+
+export { createWhatsAppHandler };

package/dist/index-CDfzGvQJ.d.cts

@@ -0,0 +1,42 @@
+/**
+ * Pluggable async key-value storage with TTL semantics. Implementations
+ * MUST honour `ttlMs`: entries past their `expiresAt` SHALL NOT be
+ * returned by `get`. Implementations SHOULD NOT spawn background timers;
+ * lazy eviction (on access) is preferred so consumers do not leak timers
+ * that prevent process exit.
+ */
+interface Storage {
+    get<T>(key: string): Promise<T | undefined>;
+    set<T>(key: string, value: T, ttlMs: number): Promise<void>;
+    /**
+     * Atomically write `value` for `key` only if no live entry exists.
+     * Returns `true` when the value was written, `false` when an unexpired
+     * entry was already present. Implementations MUST honour `ttlMs` the
+     * same way as `set`.
+     */
+    setIfAbsent<T>(key: string, value: T, ttlMs: number): Promise<boolean>;
+    delete(key: string): Promise<void>;
+}
+/**
+ * In-memory implementation of {@link Storage}. Backed by a `Map`. TTL is
+ * enforced lazily — expired entries are evicted only on access. No
+ * background timers are spawned.
+ *
+ * Suitable for development, tests, and single-process deployments. For
+ * multi-process or cross-instance dedupe, implement `Storage` against
+ * Redis / Postgres / your shared cache.
+ */
+declare class InMemoryStorage implements Storage {
+    #private;
+    constructor(options?: {
+        now?: () => number;
+    });
+    get<T>(key: string): Promise<T | undefined>;
+    set<T>(key: string, value: T, ttlMs: number): Promise<void>;
+    setIfAbsent<T>(key: string, value: T, ttlMs: number): Promise<boolean>;
+    delete(key: string): Promise<void>;
+    /** Test-only — returns the current map size (including expired entries). */
+    _rawSize(): number;
+}
+
+export { InMemoryStorage as I, type Storage as S };

package/dist/index-CDfzGvQJ.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Pluggable async key-value storage with TTL semantics. Implementations
+ * MUST honour `ttlMs`: entries past their `expiresAt` SHALL NOT be
+ * returned by `get`. Implementations SHOULD NOT spawn background timers;
+ * lazy eviction (on access) is preferred so consumers do not leak timers
+ * that prevent process exit.
+ */
+interface Storage {
+    get<T>(key: string): Promise<T | undefined>;
+    set<T>(key: string, value: T, ttlMs: number): Promise<void>;
+    /**
+     * Atomically write `value` for `key` only if no live entry exists.
+     * Returns `true` when the value was written, `false` when an unexpired
+     * entry was already present. Implementations MUST honour `ttlMs` the
+     * same way as `set`.
+     */
+    setIfAbsent<T>(key: string, value: T, ttlMs: number): Promise<boolean>;
+    delete(key: string): Promise<void>;
+}
+/**
+ * In-memory implementation of {@link Storage}. Backed by a `Map`. TTL is
+ * enforced lazily — expired entries are evicted only on access. No
+ * background timers are spawned.
+ *
+ * Suitable for development, tests, and single-process deployments. For
+ * multi-process or cross-instance dedupe, implement `Storage` against
+ * Redis / Postgres / your shared cache.
+ */
+declare class InMemoryStorage implements Storage {
+    #private;
+    constructor(options?: {
+        now?: () => number;
+    });
+    get<T>(key: string): Promise<T | undefined>;
+    set<T>(key: string, value: T, ttlMs: number): Promise<void>;
+    setIfAbsent<T>(key: string, value: T, ttlMs: number): Promise<boolean>;
+    delete(key: string): Promise<void>;
+    /** Test-only — returns the current map size (including expired entries). */
+    _rawSize(): number;
+}
+
+export { InMemoryStorage as I, type Storage as S };