@dojocoding/whatsapp-sdk 0.8.0

package/dist/receiver-C_yfwg6g.d.ts

@@ -0,0 +1,167 @@
+import { S as Storage } from './index-CDfzGvQJ.js';
+
+type WhatsAppEvent = MessageEvent | StatusEvent | TemplateStatusEvent | TemplateQualityUpdateEvent | TemplateCategoryUpdateEvent | PhoneNumberQualityUpdateEvent | AccountAlertEvent | AccountReviewEvent | UnknownEvent;
+interface BaseEvent {
+    /** WhatsApp Business Account id this event originated from. */
+    wabaId: string;
+    /** Phone number id when the event ties to a specific phone (messages, statuses, quality). */
+    phoneNumberId?: string;
+    /** E.164 display number when known. */
+    displayPhoneNumber?: string;
+    /** Event timestamp normalised to epoch milliseconds. */
+    timestamp: number;
+}
+type IncomingMessageKind = "text" | "image" | "video" | "audio" | "document" | "sticker" | "location" | "contacts" | "interactive_button_reply" | "interactive_list_reply" | "button" | "order" | "reaction" | "system" | "unsupported";
+interface MessageEvent extends BaseEvent {
+    kind: "message";
+    /** wamid — Meta's unique message id. */
+    id: string;
+    from: string;
+    type: IncomingMessageKind;
+    /** The originating message wamid this is a reply to (when present). */
+    contextId?: string;
+    /**
+     * Arbitrary type-specific body. Kept as the raw Meta object on purpose;
+     * this lets consumers progressively narrow without locking the SDK to
+     * every possible inbound shape. Outbound shapes are handled by
+     * {@link WhatsAppMessage}.
+     */
+    body: Record<string, unknown>;
+}
+/**
+ * Documented status transitions Meta sends most often. The union widens
+ * to `string` because Meta has shipped new transitions in the past
+ * (e.g., `accepted`) without a major-version bump — typing this as a
+ * literal-only union would force consumers to upgrade in lockstep.
+ */
+type DeliveryStatus = "sent" | "delivered" | "read" | "failed" | (string & {});
+interface StatusEvent extends BaseEvent {
+    kind: "status";
+    /** wamid the status update applies to. */
+    id: string;
+    status: DeliveryStatus;
+    /** Recipient WA id. */
+    recipientId?: string;
+    conversationId?: string;
+    /** Pricing model ("CBP" vs "PMP" vs "regular") when Meta provides it. */
+    pricingCategory?: string;
+    /** Raw error envelope when status === "failed". */
+    errors?: ReadonlyArray<{
+        code?: number;
+        title?: string;
+        message?: string;
+    }>;
+}
+interface TemplateStatusEvent extends BaseEvent {
+    kind: "template_status";
+    templateId: string;
+    templateName?: string;
+    language?: string;
+    /** APPROVED | REJECTED | DISABLED | PENDING | PAUSED | FLAGGED */
+    event: string;
+    reason?: string;
+}
+interface TemplateQualityUpdateEvent extends BaseEvent {
+    kind: "template_quality";
+    templateId: string;
+    templateName?: string;
+    /** GREEN | YELLOW | RED */
+    newQualityScore: string;
+    previousQualityScore?: string;
+}
+interface TemplateCategoryUpdateEvent extends BaseEvent {
+    kind: "template_category";
+    templateId: string;
+    templateName?: string;
+    newCategory: string;
+    previousCategory?: string;
+}
+interface PhoneNumberQualityUpdateEvent extends BaseEvent {
+    kind: "phone_number_quality";
+    /** GREEN | YELLOW | RED */
+    newQualityScore: string;
+}
+interface AccountAlertEvent extends BaseEvent {
+    kind: "account_alert";
+    /** Severity / type Meta provides. */
+    alertSeverity?: string;
+    alertType?: string;
+    raw: unknown;
+}
+interface AccountReviewEvent extends BaseEvent {
+    kind: "account_review";
+    decision: string;
+    raw: unknown;
+}
+interface UnknownEvent extends BaseEvent {
+    kind: "unknown";
+    field: string;
+    value: unknown;
+}
+
+interface WebhookReceiverOptions {
+    appSecret: string;
+    verifyToken: string;
+    storage?: Storage;
+    dedupeTtlMs?: number;
+    /** Invoked once per handler error (in addition to the `error` event). */
+    onError?: (err: unknown, event: WhatsAppEvent | undefined) => void;
+}
+type EventKindMap = {
+    message: MessageEvent;
+    status: StatusEvent;
+    template_status: TemplateStatusEvent;
+    template_quality: TemplateQualityUpdateEvent;
+    template_category: TemplateCategoryUpdateEvent;
+    phone_number_quality: PhoneNumberQualityUpdateEvent;
+    account_alert: AccountAlertEvent;
+    account_review: AccountReviewEvent;
+    unknown: UnknownEvent;
+};
+type Handler<E> = (event: E) => void | Promise<void>;
+type ErrorHandler = (err: unknown, event: WhatsAppEvent | undefined) => void | Promise<void>;
+interface VerifyRequestInput {
+    mode: string | null | undefined;
+    verifyToken: string | null | undefined;
+    challenge: string | null | undefined;
+}
+type VerifyRequestResult = {
+    status: 200;
+    body: string;
+} | {
+    status: 403;
+};
+type HandlePayloadResult = {
+    status: 200;
+    dispatchPromise: Promise<void>;
+} | {
+    status: 401;
+};
+/**
+ * Framework-agnostic WhatsApp webhook receiver.
+ *
+ * Phase 8 wires this into Express via a sub-module adapter. Today,
+ * consumers can use it directly:
+ *
+ *   const r = new WebhookReceiver({ appSecret, verifyToken });
+ *   r.on("message", async (e) => { … });
+ *   const { status, dispatchPromise } = await r.handlePayload(rawBody, sig, body);
+ *   res.status(status).end();
+ *   // dispatchPromise resolves once handlers complete; do not await
+ *   // it inside the HTTP handler (Meta's 30s ack rule).
+ */
+declare class WebhookReceiver {
+    #private;
+    constructor(options: WebhookReceiverOptions);
+    on<K extends keyof EventKindMap>(kind: K, handler: Handler<EventKindMap[K]>): this;
+    on(kind: "error", handler: ErrorHandler): this;
+    off<K extends keyof EventKindMap>(kind: K, handler: Handler<EventKindMap[K]>): this;
+    off(kind: "error", handler: ErrorHandler): this;
+    verify(rawBody: Buffer | Uint8Array | string, signatureHeader: string | null | undefined): Promise<boolean>;
+    handleVerifyRequest(input: VerifyRequestInput): VerifyRequestResult;
+    handlePayload(rawBody: Buffer | Uint8Array | string, signatureHeader: string | null | undefined, parsedBody: unknown): Promise<HandlePayloadResult>;
+    /** @internal — used by mock-mode (Phase 6) to inject synthetic events. */
+    _dispatchEvents(events: ReadonlyArray<WhatsAppEvent>): Promise<void>;
+}
+
+export { type AccountAlertEvent as A, type BaseEvent as B, type DeliveryStatus as D, type ErrorHandler as E, type HandlePayloadResult as H, type IncomingMessageKind as I, type MessageEvent as M, type PhoneNumberQualityUpdateEvent as P, type StatusEvent as S, type TemplateCategoryUpdateEvent as T, type UnknownEvent as U, type VerifyRequestInput as V, WebhookReceiver as W, type WhatsAppEvent as a, type AccountReviewEvent as b, type EventKindMap as c, type Handler as d, type TemplateQualityUpdateEvent as e, type TemplateStatusEvent as f, type VerifyRequestResult as g, type WebhookReceiverOptions as h };

package/dist/receiver-DWJm571Z.d.cts

@@ -0,0 +1,167 @@
+import { S as Storage } from './index-CDfzGvQJ.cjs';
+
+type WhatsAppEvent = MessageEvent | StatusEvent | TemplateStatusEvent | TemplateQualityUpdateEvent | TemplateCategoryUpdateEvent | PhoneNumberQualityUpdateEvent | AccountAlertEvent | AccountReviewEvent | UnknownEvent;
+interface BaseEvent {
+    /** WhatsApp Business Account id this event originated from. */
+    wabaId: string;
+    /** Phone number id when the event ties to a specific phone (messages, statuses, quality). */
+    phoneNumberId?: string;
+    /** E.164 display number when known. */
+    displayPhoneNumber?: string;
+    /** Event timestamp normalised to epoch milliseconds. */
+    timestamp: number;
+}
+type IncomingMessageKind = "text" | "image" | "video" | "audio" | "document" | "sticker" | "location" | "contacts" | "interactive_button_reply" | "interactive_list_reply" | "button" | "order" | "reaction" | "system" | "unsupported";
+interface MessageEvent extends BaseEvent {
+    kind: "message";
+    /** wamid — Meta's unique message id. */
+    id: string;
+    from: string;
+    type: IncomingMessageKind;
+    /** The originating message wamid this is a reply to (when present). */
+    contextId?: string;
+    /**
+     * Arbitrary type-specific body. Kept as the raw Meta object on purpose;
+     * this lets consumers progressively narrow without locking the SDK to
+     * every possible inbound shape. Outbound shapes are handled by
+     * {@link WhatsAppMessage}.
+     */
+    body: Record<string, unknown>;
+}
+/**
+ * Documented status transitions Meta sends most often. The union widens
+ * to `string` because Meta has shipped new transitions in the past
+ * (e.g., `accepted`) without a major-version bump — typing this as a
+ * literal-only union would force consumers to upgrade in lockstep.
+ */
+type DeliveryStatus = "sent" | "delivered" | "read" | "failed" | (string & {});
+interface StatusEvent extends BaseEvent {
+    kind: "status";
+    /** wamid the status update applies to. */
+    id: string;
+    status: DeliveryStatus;
+    /** Recipient WA id. */
+    recipientId?: string;
+    conversationId?: string;
+    /** Pricing model ("CBP" vs "PMP" vs "regular") when Meta provides it. */
+    pricingCategory?: string;
+    /** Raw error envelope when status === "failed". */
+    errors?: ReadonlyArray<{
+        code?: number;
+        title?: string;
+        message?: string;
+    }>;
+}
+interface TemplateStatusEvent extends BaseEvent {
+    kind: "template_status";
+    templateId: string;
+    templateName?: string;
+    language?: string;
+    /** APPROVED | REJECTED | DISABLED | PENDING | PAUSED | FLAGGED */
+    event: string;
+    reason?: string;
+}
+interface TemplateQualityUpdateEvent extends BaseEvent {
+    kind: "template_quality";
+    templateId: string;
+    templateName?: string;
+    /** GREEN | YELLOW | RED */
+    newQualityScore: string;
+    previousQualityScore?: string;
+}
+interface TemplateCategoryUpdateEvent extends BaseEvent {
+    kind: "template_category";
+    templateId: string;
+    templateName?: string;
+    newCategory: string;
+    previousCategory?: string;
+}
+interface PhoneNumberQualityUpdateEvent extends BaseEvent {
+    kind: "phone_number_quality";
+    /** GREEN | YELLOW | RED */
+    newQualityScore: string;
+}
+interface AccountAlertEvent extends BaseEvent {
+    kind: "account_alert";
+    /** Severity / type Meta provides. */
+    alertSeverity?: string;
+    alertType?: string;
+    raw: unknown;
+}
+interface AccountReviewEvent extends BaseEvent {
+    kind: "account_review";
+    decision: string;
+    raw: unknown;
+}
+interface UnknownEvent extends BaseEvent {
+    kind: "unknown";
+    field: string;
+    value: unknown;
+}
+
+interface WebhookReceiverOptions {
+    appSecret: string;
+    verifyToken: string;
+    storage?: Storage;
+    dedupeTtlMs?: number;
+    /** Invoked once per handler error (in addition to the `error` event). */
+    onError?: (err: unknown, event: WhatsAppEvent | undefined) => void;
+}
+type EventKindMap = {
+    message: MessageEvent;
+    status: StatusEvent;
+    template_status: TemplateStatusEvent;
+    template_quality: TemplateQualityUpdateEvent;
+    template_category: TemplateCategoryUpdateEvent;
+    phone_number_quality: PhoneNumberQualityUpdateEvent;
+    account_alert: AccountAlertEvent;
+    account_review: AccountReviewEvent;
+    unknown: UnknownEvent;
+};
+type Handler<E> = (event: E) => void | Promise<void>;
+type ErrorHandler = (err: unknown, event: WhatsAppEvent | undefined) => void | Promise<void>;
+interface VerifyRequestInput {
+    mode: string | null | undefined;
+    verifyToken: string | null | undefined;
+    challenge: string | null | undefined;
+}
+type VerifyRequestResult = {
+    status: 200;
+    body: string;
+} | {
+    status: 403;
+};
+type HandlePayloadResult = {
+    status: 200;
+    dispatchPromise: Promise<void>;
+} | {
+    status: 401;
+};
+/**
+ * Framework-agnostic WhatsApp webhook receiver.
+ *
+ * Phase 8 wires this into Express via a sub-module adapter. Today,
+ * consumers can use it directly:
+ *
+ *   const r = new WebhookReceiver({ appSecret, verifyToken });
+ *   r.on("message", async (e) => { … });
+ *   const { status, dispatchPromise } = await r.handlePayload(rawBody, sig, body);
+ *   res.status(status).end();
+ *   // dispatchPromise resolves once handlers complete; do not await
+ *   // it inside the HTTP handler (Meta's 30s ack rule).
+ */
+declare class WebhookReceiver {
+    #private;
+    constructor(options: WebhookReceiverOptions);
+    on<K extends keyof EventKindMap>(kind: K, handler: Handler<EventKindMap[K]>): this;
+    on(kind: "error", handler: ErrorHandler): this;
+    off<K extends keyof EventKindMap>(kind: K, handler: Handler<EventKindMap[K]>): this;
+    off(kind: "error", handler: ErrorHandler): this;
+    verify(rawBody: Buffer | Uint8Array | string, signatureHeader: string | null | undefined): Promise<boolean>;
+    handleVerifyRequest(input: VerifyRequestInput): VerifyRequestResult;
+    handlePayload(rawBody: Buffer | Uint8Array | string, signatureHeader: string | null | undefined, parsedBody: unknown): Promise<HandlePayloadResult>;
+    /** @internal — used by mock-mode (Phase 6) to inject synthetic events. */
+    _dispatchEvents(events: ReadonlyArray<WhatsAppEvent>): Promise<void>;
+}
+
+export { type AccountAlertEvent as A, type BaseEvent as B, type DeliveryStatus as D, type ErrorHandler as E, type HandlePayloadResult as H, type IncomingMessageKind as I, type MessageEvent as M, type PhoneNumberQualityUpdateEvent as P, type StatusEvent as S, type TemplateCategoryUpdateEvent as T, type UnknownEvent as U, type VerifyRequestInput as V, WebhookReceiver as W, type WhatsAppEvent as a, type AccountReviewEvent as b, type EventKindMap as c, type Handler as d, type TemplateQualityUpdateEvent as e, type TemplateStatusEvent as f, type VerifyRequestResult as g, type WebhookReceiverOptions as h };

package/dist/storage/postgres.cjs

@@ -0,0 +1,66 @@
+'use strict';
+
+// src/storage/postgres.ts
+var POSTGRES_STORAGE_SCHEMA = `
+CREATE TABLE IF NOT EXISTS whatsapp_storage (
+  key TEXT PRIMARY KEY,
+  value JSONB NOT NULL,
+  expires_at TIMESTAMPTZ NOT NULL
+);
+CREATE INDEX IF NOT EXISTS whatsapp_storage_expires_at_idx
+  ON whatsapp_storage (expires_at);
+`.trim();
+var INFINITY_TS = "infinity";
+function createPostgresStorage(client, options = {}) {
+  const prefix = options.keyPrefix ?? "whatsapp:";
+  const table = options.table ?? "whatsapp_storage";
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(table)) {
+    throw new TypeError(
+      `PostgresStorage: table name must be alphanumeric+underscore; got ${JSON.stringify(table)}.`
+    );
+  }
+  const k = (key) => prefix + key;
+  return {
+    async get(key) {
+      const result = await client.query(
+        `SELECT value FROM ${table} WHERE key = $1 AND expires_at > now()`,
+        [k(key)]
+      );
+      if (result.rows.length === 0) return void 0;
+      return result.rows[0].value;
+    },
+    async set(key, value, ttlMs) {
+      const expiresExpr = ttlMs > 0 ? `now() + ($3 || ' milliseconds')::interval` : `'${INFINITY_TS}'::timestamptz`;
+      const params = [k(key), JSON.stringify(value)];
+      if (ttlMs > 0) params.push(String(ttlMs));
+      await client.query(
+        `INSERT INTO ${table} (key, value, expires_at)
+         VALUES ($1, $2::jsonb, ${expiresExpr})
+         ON CONFLICT (key) DO UPDATE
+           SET value = excluded.value, expires_at = excluded.expires_at`,
+        params
+      );
+    },
+    async setIfAbsent(key, value, ttlMs) {
+      const expiresExpr = ttlMs > 0 ? `now() + ($3 || ' milliseconds')::interval` : `'${INFINITY_TS}'::timestamptz`;
+      const params = [k(key), JSON.stringify(value)];
+      if (ttlMs > 0) params.push(String(ttlMs));
+      const result = await client.query(
+        `INSERT INTO ${table} (key, value, expires_at)
+         VALUES ($1, $2::jsonb, ${expiresExpr})
+         ON CONFLICT (key) DO UPDATE
+           SET value = excluded.value, expires_at = excluded.expires_at
+           WHERE ${table}.expires_at <= now()
+         RETURNING key`,
+        params
+      );
+      return result.rows.length > 0;
+    },
+    async delete(key) {
+      await client.query(`DELETE FROM ${table} WHERE key = $1`, [k(key)]);
+    }
+  };
+}
+
+exports.POSTGRES_STORAGE_SCHEMA = POSTGRES_STORAGE_SCHEMA;
+exports.createPostgresStorage = createPostgresStorage;

package/dist/storage/postgres.d.cts

@@ -0,0 +1,38 @@
+import { S as Storage } from '../index-CDfzGvQJ.cjs';
+
+/**
+ * Minimal structural interface of a `pg`-shaped client. Anything
+ * that provides `query<R>(sql, params?): Promise<{ rows: R[] }>`
+ * works — production `pg.Pool`, `pg.Client`, or a test fake. The
+ * SDK does NOT import `pg` at runtime.
+ */
+interface PgLike {
+    query<R = unknown>(sql: string, params?: ReadonlyArray<unknown>): Promise<{
+        rows: R[];
+    }>;
+}
+interface PostgresStorageOptions {
+    /** Prepended to every key. Defaults to `"whatsapp:"`. */
+    keyPrefix?: string;
+    /** Table name. Defaults to `"whatsapp_storage"`. */
+    table?: string;
+}
+/**
+ * DDL for the storage table. Consumers MUST run this once (via
+ * their own migration tool) before using `createPostgresStorage`.
+ * Idempotent; safe to run repeatedly.
+ *
+ * The default table name is `whatsapp_storage`. If you override
+ * the `table` option, edit this SQL accordingly.
+ */
+declare const POSTGRES_STORAGE_SCHEMA: string;
+/**
+ * Create a {@link Storage} backed by a `PgLike` client. The
+ * caller owns the connection (pool, TLS, retries). Expired rows
+ * are filtered on `get` (`WHERE expires_at > now()`) but not
+ * proactively deleted — schedule a `DELETE FROM <table> WHERE
+ * expires_at < now()` job if table growth becomes a concern.
+ */
+declare function createPostgresStorage(client: PgLike, options?: PostgresStorageOptions): Storage;
+
+export { POSTGRES_STORAGE_SCHEMA, type PgLike, type PostgresStorageOptions, createPostgresStorage };

package/dist/storage/postgres.d.ts

@@ -0,0 +1,38 @@
+import { S as Storage } from '../index-CDfzGvQJ.js';
+
+/**
+ * Minimal structural interface of a `pg`-shaped client. Anything
+ * that provides `query<R>(sql, params?): Promise<{ rows: R[] }>`
+ * works — production `pg.Pool`, `pg.Client`, or a test fake. The
+ * SDK does NOT import `pg` at runtime.
+ */
+interface PgLike {
+    query<R = unknown>(sql: string, params?: ReadonlyArray<unknown>): Promise<{
+        rows: R[];
+    }>;
+}
+interface PostgresStorageOptions {
+    /** Prepended to every key. Defaults to `"whatsapp:"`. */
+    keyPrefix?: string;
+    /** Table name. Defaults to `"whatsapp_storage"`. */
+    table?: string;
+}
+/**
+ * DDL for the storage table. Consumers MUST run this once (via
+ * their own migration tool) before using `createPostgresStorage`.
+ * Idempotent; safe to run repeatedly.
+ *
+ * The default table name is `whatsapp_storage`. If you override
+ * the `table` option, edit this SQL accordingly.
+ */
+declare const POSTGRES_STORAGE_SCHEMA: string;
+/**
+ * Create a {@link Storage} backed by a `PgLike` client. The
+ * caller owns the connection (pool, TLS, retries). Expired rows
+ * are filtered on `get` (`WHERE expires_at > now()`) but not
+ * proactively deleted — schedule a `DELETE FROM <table> WHERE
+ * expires_at < now()` job if table growth becomes a concern.
+ */
+declare function createPostgresStorage(client: PgLike, options?: PostgresStorageOptions): Storage;
+
+export { POSTGRES_STORAGE_SCHEMA, type PgLike, type PostgresStorageOptions, createPostgresStorage };

package/dist/storage/postgres.js

@@ -0,0 +1,63 @@
+// src/storage/postgres.ts
+var POSTGRES_STORAGE_SCHEMA = `
+CREATE TABLE IF NOT EXISTS whatsapp_storage (
+  key TEXT PRIMARY KEY,
+  value JSONB NOT NULL,
+  expires_at TIMESTAMPTZ NOT NULL
+);
+CREATE INDEX IF NOT EXISTS whatsapp_storage_expires_at_idx
+  ON whatsapp_storage (expires_at);
+`.trim();
+var INFINITY_TS = "infinity";
+function createPostgresStorage(client, options = {}) {
+  const prefix = options.keyPrefix ?? "whatsapp:";
+  const table = options.table ?? "whatsapp_storage";
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(table)) {
+    throw new TypeError(
+      `PostgresStorage: table name must be alphanumeric+underscore; got ${JSON.stringify(table)}.`
+    );
+  }
+  const k = (key) => prefix + key;
+  return {
+    async get(key) {
+      const result = await client.query(
+        `SELECT value FROM ${table} WHERE key = $1 AND expires_at > now()`,
+        [k(key)]
+      );
+      if (result.rows.length === 0) return void 0;
+      return result.rows[0].value;
+    },
+    async set(key, value, ttlMs) {
+      const expiresExpr = ttlMs > 0 ? `now() + ($3 || ' milliseconds')::interval` : `'${INFINITY_TS}'::timestamptz`;
+      const params = [k(key), JSON.stringify(value)];
+      if (ttlMs > 0) params.push(String(ttlMs));
+      await client.query(
+        `INSERT INTO ${table} (key, value, expires_at)
+         VALUES ($1, $2::jsonb, ${expiresExpr})
+         ON CONFLICT (key) DO UPDATE
+           SET value = excluded.value, expires_at = excluded.expires_at`,
+        params
+      );
+    },
+    async setIfAbsent(key, value, ttlMs) {
+      const expiresExpr = ttlMs > 0 ? `now() + ($3 || ' milliseconds')::interval` : `'${INFINITY_TS}'::timestamptz`;
+      const params = [k(key), JSON.stringify(value)];
+      if (ttlMs > 0) params.push(String(ttlMs));
+      const result = await client.query(
+        `INSERT INTO ${table} (key, value, expires_at)
+         VALUES ($1, $2::jsonb, ${expiresExpr})
+         ON CONFLICT (key) DO UPDATE
+           SET value = excluded.value, expires_at = excluded.expires_at
+           WHERE ${table}.expires_at <= now()
+         RETURNING key`,
+        params
+      );
+      return result.rows.length > 0;
+    },
+    async delete(key) {
+      await client.query(`DELETE FROM ${table} WHERE key = $1`, [k(key)]);
+    }
+  };
+}
+
+export { POSTGRES_STORAGE_SCHEMA, createPostgresStorage };

package/dist/storage/redis.cjs

@@ -0,0 +1,32 @@
+'use strict';
+
+// src/storage/redis.ts
+function createRedisStorage(client, options = {}) {
+  const prefix = options.keyPrefix ?? "whatsapp:";
+  const k = (key) => prefix + key;
+  return {
+    async get(key) {
+      const raw = await client.get(k(key));
+      if (raw === null) return void 0;
+      return JSON.parse(raw);
+    },
+    async set(key, value, ttlMs) {
+      const serialized = JSON.stringify(value);
+      if (ttlMs > 0) {
+        await client.set(k(key), serialized, "PX", ttlMs);
+      } else {
+        await client.set(k(key), serialized);
+      }
+    },
+    async setIfAbsent(key, value, ttlMs) {
+      const serialized = JSON.stringify(value);
+      const result = ttlMs > 0 ? await client.set(k(key), serialized, "PX", ttlMs, "NX") : await client.set(k(key), serialized, "NX");
+      return result === "OK";
+    },
+    async delete(key) {
+      await client.del(k(key));
+    }
+  };
+}
+
+exports.createRedisStorage = createRedisStorage;

package/dist/storage/redis.d.cts

@@ -0,0 +1,38 @@
+import { S as Storage } from '../index-CDfzGvQJ.cjs';
+
+/**
+ * Minimal structural interface of an `ioredis`-shaped client.
+ * Anything that provides these three methods works — production
+ * `ioredis`, the `node-redis` v4 legacy mode, or a test fake. The
+ * SDK does NOT import `ioredis` at runtime.
+ */
+interface RedisLike {
+    get(key: string): Promise<string | null>;
+    /**
+     * `ioredis`'s variadic `SET`. Accepts the value followed by an
+     * arbitrary list of `["PX", ttlMs, "NX"]` etc. Returns `"OK"`
+     * on success, `null` when `NX` rejected.
+     */
+    set(key: string, value: string, ...args: Array<string | number>): Promise<string | null>;
+    del(...keys: string[]): Promise<number>;
+}
+interface RedisStorageOptions {
+    /**
+     * Prepended to every key. Lets multiple consumers share one
+     * Redis instance. Defaults to `"whatsapp:"`.
+     */
+    keyPrefix?: string;
+}
+/**
+ * Create a {@link Storage} backed by a `RedisLike` client. The
+ * client is owned by the consumer (connection pooling, TLS, auth,
+ * retries are upstream concerns).
+ *
+ * Values are JSON-encoded; TTL is enforced by Redis itself via
+ * the `PX` argument on `SET`. `ttlMs <= 0` stores forever (no
+ * `PX` argument). `setIfAbsent` uses `SET NX` and is atomic by
+ * Redis semantics.
+ */
+declare function createRedisStorage(client: RedisLike, options?: RedisStorageOptions): Storage;
+
+export { type RedisLike, type RedisStorageOptions, createRedisStorage };

package/dist/storage/redis.d.ts

@@ -0,0 +1,38 @@
+import { S as Storage } from '../index-CDfzGvQJ.js';
+
+/**
+ * Minimal structural interface of an `ioredis`-shaped client.
+ * Anything that provides these three methods works — production
+ * `ioredis`, the `node-redis` v4 legacy mode, or a test fake. The
+ * SDK does NOT import `ioredis` at runtime.
+ */
+interface RedisLike {
+    get(key: string): Promise<string | null>;
+    /**
+     * `ioredis`'s variadic `SET`. Accepts the value followed by an
+     * arbitrary list of `["PX", ttlMs, "NX"]` etc. Returns `"OK"`
+     * on success, `null` when `NX` rejected.
+     */
+    set(key: string, value: string, ...args: Array<string | number>): Promise<string | null>;
+    del(...keys: string[]): Promise<number>;
+}
+interface RedisStorageOptions {
+    /**
+     * Prepended to every key. Lets multiple consumers share one
+     * Redis instance. Defaults to `"whatsapp:"`.
+     */
+    keyPrefix?: string;
+}
+/**
+ * Create a {@link Storage} backed by a `RedisLike` client. The
+ * client is owned by the consumer (connection pooling, TLS, auth,
+ * retries are upstream concerns).
+ *
+ * Values are JSON-encoded; TTL is enforced by Redis itself via
+ * the `PX` argument on `SET`. `ttlMs <= 0` stores forever (no
+ * `PX` argument). `setIfAbsent` uses `SET NX` and is atomic by
+ * Redis semantics.
+ */
+declare function createRedisStorage(client: RedisLike, options?: RedisStorageOptions): Storage;
+
+export { type RedisLike, type RedisStorageOptions, createRedisStorage };

package/dist/storage/redis.js

@@ -0,0 +1,30 @@
+// src/storage/redis.ts
+function createRedisStorage(client, options = {}) {
+  const prefix = options.keyPrefix ?? "whatsapp:";
+  const k = (key) => prefix + key;
+  return {
+    async get(key) {
+      const raw = await client.get(k(key));
+      if (raw === null) return void 0;
+      return JSON.parse(raw);
+    },
+    async set(key, value, ttlMs) {
+      const serialized = JSON.stringify(value);
+      if (ttlMs > 0) {
+        await client.set(k(key), serialized, "PX", ttlMs);
+      } else {
+        await client.set(k(key), serialized);
+      }
+    },
+    async setIfAbsent(key, value, ttlMs) {
+      const serialized = JSON.stringify(value);
+      const result = ttlMs > 0 ? await client.set(k(key), serialized, "PX", ttlMs, "NX") : await client.set(k(key), serialized, "NX");
+      return result === "OK";
+    },
+    async delete(key) {
+      await client.del(k(key));
+    }
+  };
+}
+
+export { createRedisStorage };