@glitchgrab/whatsapp 0.1.0

package/README.md

@@ -0,0 +1,147 @@
+# @glitchgrab/whatsapp
+
+WhatsApp Business messaging for SaaS products, without the Meta integration.
+
+Your business owners connect **their own** WhatsApp number, so messages arrive
+under *their* verified name — not yours. You get templates, sending, a shared
+inbox, autoreply and per-owner billing; you never touch a WABA id, a phone number
+id, or a Meta access token.
+
+This is not the `glitchgrab` package (that one files GitHub issues). Different
+product, different key.
+
+## Install
+
+```bash
+bun add @glitchgrab/whatsapp
+```
+
+## The one rule
+
+**`WhatsappClient` holds your platform API key and must only run on a server.**
+That key reaches every one of your customers' numbers. The package logs an error
+if it detects a browser, but the fix is architectural: keep it in route handlers
+and server actions, and let `createInboxHandler` serve the UI.
+
+`ownerId` throughout is *your* id for the business owner — a library id, a clinic
+id. We map it to a tenant on our side.
+
+## Connect an owner's number
+
+```ts
+// server
+const client = createWhatsappClient({ apiKey: process.env.GG_WA_KEY! });
+const config = await client.connect({ ownerId: library.id, name: library.name });
+```
+
+```tsx
+// browser — Meta's JS SDK must already be on the page
+const { code, state } = await launchSignup(config);
+await fetch("/api/whatsapp/complete", { method: "POST", body: JSON.stringify({ code, state }) });
+```
+
+```ts
+// server, in that route
+await client.completeConnect({ ownerId: library.id, code, state });
+```
+
+The owner picks or creates their WhatsApp Business Account inside Meta's popup
+and verifies their own number. Nothing is connected until `completeConnect`
+returns — and check `warnings` on the result, which reports things that are worth
+surfacing but are not failures (no number added yet, webhook subscription
+refused).
+
+## Send
+
+```ts
+await client.send({
+  ownerId: library.id,
+  to: student.phone,
+  template: "fee_due",
+  components: [{ type: "body", parameters: [{ type: "text", text: "₹500" }] }],
+  refKey: `fee-${invoice.id}`, // a retry with the same key never charges twice
+});
+```
+
+Free-form text (`body` instead of `template`) is legal only within 24 hours of
+the contact's last inbound message. Outside that window this throws — Meta
+answers 200 and delivers nothing, so failing loudly is the point.
+
+Out of balance throws with `code: "INSUFFICIENT_FUNDS"` and a `detail.shortfallPaise`.
+
+## Shared inbox
+
+One route:
+
+```ts
+// app/api/whatsapp/[...action]/route.ts
+import { createWhatsappClient, createInboxHandler } from "@glitchgrab/whatsapp";
+
+const client = createWhatsappClient({ apiKey: process.env.GG_WA_KEY! });
+
+const handler = createInboxHandler({
+  client,
+  // Derive the owner from YOUR session. Never from the request body — that
+  // would let any signed-in user read any other owner's WhatsApp.
+  resolveOwnerId: async () => (await auth()).user.libraryId,
+});
+
+export const GET = handler;
+export const POST = handler;
+export const PATCH = handler;
+```
+
+One component:
+
+```tsx
+import { WhatsappInbox } from "@glitchgrab/whatsapp/react";
+
+<WhatsappInbox api="/api/whatsapp" height={640} />
+```
+
+Live updates arrive over SSE. The component mints a short-lived ticket through
+your route, so your API key never reaches the browser, and reconnects on its own
+when the stream is closed or the ticket expires.
+
+Restyle with CSS custom properties — `--gg-wa-accent`, `--gg-wa-bg`,
+`--gg-wa-bubble-out`, `--gg-wa-border`, `--gg-wa-text`, `--gg-wa-muted`,
+`--gg-wa-panel`, `--gg-wa-danger`. For a different layout, use the `useInbox`
+hook directly and render your own.
+
+## Billing
+
+Prepaid, per owner. Collect payment however you already do, then:
+
+```ts
+await client.credit({ ownerId: library.id, amountPaise: 50_000, refKey: payment.id });
+```
+
+We hold the ledger; we never hold your customers' money. Balances are integer
+paise. A send debits before it calls Meta and refunds if Meta refuses, so a
+failed message never costs anyone anything.
+
+## Autoreply
+
+```ts
+await client.createAutoreplyRule({
+  ownerId: library.id,
+  name: "Timings",
+  matchType: "CONTAINS",
+  pattern: "timing",
+  replyText: "We're open 6am–10pm, every day.",
+  priority: 10, // lower runs first; first match wins
+});
+```
+
+Rules never fire for someone who has just asked to stop.
+
+## API
+
+`connect` · `completeConnect` · `numbers` · `templates` · `saveTemplate` ·
+`submitTemplate` · `syncTemplates` · `send` · `messages` · `conversations` ·
+`conversation` · `updateConversation` · `agents` · `saveAgent` ·
+`autoreplyRules` · `createAutoreplyRule` · `credit` · `balance` ·
+`createInboxSession`
+
+Every failure is a `WhatsappError` with a stable `code`. Branch on that, not on
+the message.

package/dist/index.d.mts

@@ -0,0 +1,280 @@
+import { k as WaSignupLaunch, i as WaNumber, l as WaTemplate, m as WaTemplateCategory, j as WaSendResult, f as WaMessage, b as WaConversation, W as WaAgent, e as WaMatchType, a as WaBalance } from './types-BKOEzRzb.mjs';
+export { c as WaConversationStatus, d as WaErrorCode, g as WaMessageDirection, h as WaMessageStatus, n as WaTemplateStatus, o as WhatsappError } from './types-BKOEzRzb.mjs';
+
+/**
+ * The server-side client.
+ *
+ * **This holds your platform API key. It must never run in a browser** — the key
+ * is scoped to your whole account, and every one of your customers' numbers is
+ * reachable with it. Call it from a route handler or a server action, and give
+ * the browser only what it needs. `createInboxSession()` exists precisely so the
+ * inbox UI can work without the key ever leaving your server.
+ *
+ * `ownerId` is *your* user id for the business owner. We map it to a tenant on
+ * our side, so you never handle a WABA id, a phone number id, or a Meta token.
+ */
+interface WhatsappClientOptions {
+    apiKey: string;
+    /** Override for local development against a tunnel. */
+    baseUrl?: string;
+    fetch?: typeof globalThis.fetch;
+}
+declare class WhatsappClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    constructor(options: WhatsappClientOptions);
+    private request;
+    /**
+     * Starts Embedded Signup for one of your business owners.
+     *
+     * Returns config for Meta's JS SDK, not a redirect URL — a plain OAuth
+     * redirect yields a token but skips WABA creation, which is the part the owner
+     * actually needs. Pass the result to `launchSignup()` in the browser.
+     */
+    connect(params: {
+        ownerId: string;
+        ownerName?: string;
+    }): Promise<WaSignupLaunch>;
+    /** Exchanges the code Meta's popup returns. Call this from your server. */
+    completeConnect(params: {
+        ownerId: string;
+        code: string;
+        state?: string;
+    }): Promise<{
+        wabaId: string;
+        numbers: WaNumber[];
+        creditLineShared: boolean;
+        warnings: string[];
+    }>;
+    numbers(params: {
+        ownerId: string;
+        refresh?: boolean;
+    }): Promise<{
+        numbers: WaNumber[];
+    }>;
+    templates(params: {
+        ownerId: string;
+        status?: string;
+    }): Promise<{
+        templates: WaTemplate[];
+    }>;
+    saveTemplate(params: {
+        ownerId: string;
+        name: string;
+        language: string;
+        category: WaTemplateCategory;
+        components: unknown[];
+    }): Promise<{
+        template: WaTemplate;
+    }>;
+    /** Sends a draft to Meta. The verdict arrives asynchronously — poll or wait. */
+    submitTemplate(params: {
+        ownerId: string;
+        templateId: string;
+    }): Promise<{
+        template: WaTemplate;
+    }>;
+    /** Reconciles against Meta now, rather than waiting for the hourly sweep. */
+    syncTemplates(params: {
+        ownerId: string;
+    }): Promise<{
+        checked: number;
+        updated: number;
+    }>;
+    /**
+     * Sends a message from the owner's own number.
+     *
+     * With `template`, any time. With `body`, only inside the 24-hour window the
+     * contact opened by messaging them — outside it this throws rather than
+     * letting Meta accept the send and deliver nothing.
+     *
+     * Pass `refKey` to make a retry safe: the same key never charges twice.
+     */
+    send(params: {
+        ownerId: string;
+        to: string;
+        template?: string;
+        language?: string;
+        components?: unknown[];
+        body?: string;
+        refKey?: string;
+    }): Promise<WaSendResult>;
+    messages(params: {
+        ownerId: string;
+        contact?: string;
+        limit?: number;
+        cursor?: string;
+    }): Promise<{
+        messages: WaMessage[];
+        nextCursor: string | null;
+    }>;
+    conversations(params: {
+        ownerId: string;
+        status?: string;
+        unread?: boolean;
+        limit?: number;
+        cursor?: string;
+    }): Promise<{
+        conversations: WaConversation[];
+        nextCursor: string | null;
+    }>;
+    conversation(params: {
+        ownerId: string;
+        conversationId: string;
+    }): Promise<{
+        conversation: WaConversation & {
+            messages: WaMessage[];
+        };
+    }>;
+    updateConversation(params: {
+        ownerId: string;
+        conversationId: string;
+        status?: "OPEN" | "SNOOZED" | "CLOSED";
+        assignedAgentId?: string | null;
+        optedOut?: boolean;
+    }): Promise<{
+        updated: boolean;
+    }>;
+    agents(params: {
+        ownerId: string;
+        includeInactive?: boolean;
+    }): Promise<{
+        agents: WaAgent[];
+    }>;
+    saveAgent(params: {
+        ownerId: string;
+        agentId: string;
+        name: string;
+        email?: string;
+        role?: "AGENT" | "ADMIN";
+        active?: boolean;
+    }): Promise<{
+        agent: WaAgent;
+    }>;
+    autoreplyRules(params: {
+        ownerId: string;
+    }): Promise<{
+        rules: unknown[];
+    }>;
+    createAutoreplyRule(params: {
+        ownerId: string;
+        name: string;
+        matchType: WaMatchType;
+        pattern?: string;
+        replyText: string;
+        priority?: number;
+    }): Promise<{
+        rule: unknown;
+    }>;
+    /**
+     * Adds balance for one of your owners, after you have collected the money on
+     * your own rails. We hold the ledger; we never hold your customer's funds.
+     */
+    credit(params: {
+        ownerId: string;
+        amountPaise: number;
+        refKey?: string;
+        note?: string;
+    }): Promise<WaBalance>;
+    balance(params?: {
+        ownerId?: string;
+    }): Promise<WaBalance>;
+    /**
+     * Mints a short-lived, owner-scoped session for the inbox UI.
+     *
+     * Call this from a server route and return the result to your page. It is
+     * what lets `<WhatsappInbox>` talk to us without your API key ever reaching
+     * the browser. The ticket lasts sixty seconds; the component refreshes it
+     * through the same route on reconnect.
+     */
+    createInboxSession(params: {
+        ownerId: string;
+    }): Promise<{
+        ownerId: string;
+        ticket: string;
+        expiresIn: number;
+        baseUrl: string;
+    }>;
+}
+declare function createWhatsappClient(options: WhatsappClientOptions): WhatsappClient;
+
+/**
+ * A ready-made proxy route for the inbox UI.
+ *
+ * The browser must never hold your platform API key, so `<WhatsappInbox>` talks
+ * to *your* server, and your server talks to us. This builds that middle layer
+ * so you do not have to hand-write five thin fetch wrappers.
+ *
+ * ```ts
+ * // app/api/whatsapp/[...action]/route.ts
+ * import { createWhatsappClient, createInboxHandler } from "@glitchgrab/whatsapp";
+ *
+ * const client = createWhatsappClient({ apiKey: process.env.GG_WA_KEY! });
+ *
+ * const handler = createInboxHandler({
+ *   client,
+ *   // The single most important line here: derive the owner from YOUR session,
+ *   // never from the request body. Returning a client-supplied id would let any
+ *   // signed-in user read any other library's WhatsApp.
+ *   resolveOwnerId: async () => (await auth()).user.libraryId,
+ * });
+ *
+ * export const GET = handler;
+ * export const POST = handler;
+ * ```
+ */
+interface InboxHandlerOptions {
+    client: WhatsappClient;
+    /**
+     * Returns the owner id for the current request, from your own auth. Return
+     * null to deny.
+     */
+    resolveOwnerId: (request: Request) => Promise<string | null> | string | null;
+    /** Set false to make the inbox read-only for this route. Default true. */
+    allowSend?: boolean;
+}
+declare function createInboxHandler(options: InboxHandlerOptions): (request: Request) => Promise<Response>;
+
+/**
+ * Opens Meta's Embedded Signup popup.
+ *
+ * Runs in the browser, holds no credentials, and returns the `code` your server
+ * exchanges via `client.completeConnect()`. Nothing is connected until that
+ * exchange happens.
+ *
+ * Meta's JS SDK must already be on the page — Embedded Signup only works
+ * through `FB.login` with a `config_id`; a plain OAuth redirect gets a token but
+ * skips the WABA creation the owner actually needs.
+ */
+interface FacebookSdk {
+    init(params: {
+        appId: string;
+        cookie?: boolean;
+        xfbml?: boolean;
+        version: string;
+    }): void;
+    login(callback: (response: {
+        authResponse?: {
+            code?: string;
+        };
+        status?: string;
+    }) => void, options: {
+        config_id: string;
+        response_type: string;
+        override_default_response_type: boolean;
+        extras?: Record<string, unknown>;
+    }): void;
+}
+declare global {
+    interface Window {
+        FB?: FacebookSdk;
+    }
+}
+interface SignupOutcome {
+    code: string;
+    state: string;
+}
+declare function launchSignup(config: WaSignupLaunch): Promise<SignupOutcome>;
+
+export { type InboxHandlerOptions, type SignupOutcome, WaAgent, WaBalance, WaConversation, WaMatchType, WaMessage, WaNumber, WaSendResult, WaSignupLaunch, WaTemplate, WaTemplateCategory, WhatsappClient, type WhatsappClientOptions, createInboxHandler, createWhatsappClient, launchSignup };

package/dist/index.d.ts

@@ -0,0 +1,280 @@
+import { k as WaSignupLaunch, i as WaNumber, l as WaTemplate, m as WaTemplateCategory, j as WaSendResult, f as WaMessage, b as WaConversation, W as WaAgent, e as WaMatchType, a as WaBalance } from './types-BKOEzRzb.js';
+export { c as WaConversationStatus, d as WaErrorCode, g as WaMessageDirection, h as WaMessageStatus, n as WaTemplateStatus, o as WhatsappError } from './types-BKOEzRzb.js';
+
+/**
+ * The server-side client.
+ *
+ * **This holds your platform API key. It must never run in a browser** — the key
+ * is scoped to your whole account, and every one of your customers' numbers is
+ * reachable with it. Call it from a route handler or a server action, and give
+ * the browser only what it needs. `createInboxSession()` exists precisely so the
+ * inbox UI can work without the key ever leaving your server.
+ *
+ * `ownerId` is *your* user id for the business owner. We map it to a tenant on
+ * our side, so you never handle a WABA id, a phone number id, or a Meta token.
+ */
+interface WhatsappClientOptions {
+    apiKey: string;
+    /** Override for local development against a tunnel. */
+    baseUrl?: string;
+    fetch?: typeof globalThis.fetch;
+}
+declare class WhatsappClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    constructor(options: WhatsappClientOptions);
+    private request;
+    /**
+     * Starts Embedded Signup for one of your business owners.
+     *
+     * Returns config for Meta's JS SDK, not a redirect URL — a plain OAuth
+     * redirect yields a token but skips WABA creation, which is the part the owner
+     * actually needs. Pass the result to `launchSignup()` in the browser.
+     */
+    connect(params: {
+        ownerId: string;
+        ownerName?: string;
+    }): Promise<WaSignupLaunch>;
+    /** Exchanges the code Meta's popup returns. Call this from your server. */
+    completeConnect(params: {
+        ownerId: string;
+        code: string;
+        state?: string;
+    }): Promise<{
+        wabaId: string;
+        numbers: WaNumber[];
+        creditLineShared: boolean;
+        warnings: string[];
+    }>;
+    numbers(params: {
+        ownerId: string;
+        refresh?: boolean;
+    }): Promise<{
+        numbers: WaNumber[];
+    }>;
+    templates(params: {
+        ownerId: string;
+        status?: string;
+    }): Promise<{
+        templates: WaTemplate[];
+    }>;
+    saveTemplate(params: {
+        ownerId: string;
+        name: string;
+        language: string;
+        category: WaTemplateCategory;
+        components: unknown[];
+    }): Promise<{
+        template: WaTemplate;
+    }>;
+    /** Sends a draft to Meta. The verdict arrives asynchronously — poll or wait. */
+    submitTemplate(params: {
+        ownerId: string;
+        templateId: string;
+    }): Promise<{
+        template: WaTemplate;
+    }>;
+    /** Reconciles against Meta now, rather than waiting for the hourly sweep. */
+    syncTemplates(params: {
+        ownerId: string;
+    }): Promise<{
+        checked: number;
+        updated: number;
+    }>;
+    /**
+     * Sends a message from the owner's own number.
+     *
+     * With `template`, any time. With `body`, only inside the 24-hour window the
+     * contact opened by messaging them — outside it this throws rather than
+     * letting Meta accept the send and deliver nothing.
+     *
+     * Pass `refKey` to make a retry safe: the same key never charges twice.
+     */
+    send(params: {
+        ownerId: string;
+        to: string;
+        template?: string;
+        language?: string;
+        components?: unknown[];
+        body?: string;
+        refKey?: string;
+    }): Promise<WaSendResult>;
+    messages(params: {
+        ownerId: string;
+        contact?: string;
+        limit?: number;
+        cursor?: string;
+    }): Promise<{
+        messages: WaMessage[];
+        nextCursor: string | null;
+    }>;
+    conversations(params: {
+        ownerId: string;
+        status?: string;
+        unread?: boolean;
+        limit?: number;
+        cursor?: string;
+    }): Promise<{
+        conversations: WaConversation[];
+        nextCursor: string | null;
+    }>;
+    conversation(params: {
+        ownerId: string;
+        conversationId: string;
+    }): Promise<{
+        conversation: WaConversation & {
+            messages: WaMessage[];
+        };
+    }>;
+    updateConversation(params: {
+        ownerId: string;
+        conversationId: string;
+        status?: "OPEN" | "SNOOZED" | "CLOSED";
+        assignedAgentId?: string | null;
+        optedOut?: boolean;
+    }): Promise<{
+        updated: boolean;
+    }>;
+    agents(params: {
+        ownerId: string;
+        includeInactive?: boolean;
+    }): Promise<{
+        agents: WaAgent[];
+    }>;
+    saveAgent(params: {
+        ownerId: string;
+        agentId: string;
+        name: string;
+        email?: string;
+        role?: "AGENT" | "ADMIN";
+        active?: boolean;
+    }): Promise<{
+        agent: WaAgent;
+    }>;
+    autoreplyRules(params: {
+        ownerId: string;
+    }): Promise<{
+        rules: unknown[];
+    }>;
+    createAutoreplyRule(params: {
+        ownerId: string;
+        name: string;
+        matchType: WaMatchType;
+        pattern?: string;
+        replyText: string;
+        priority?: number;
+    }): Promise<{
+        rule: unknown;
+    }>;
+    /**
+     * Adds balance for one of your owners, after you have collected the money on
+     * your own rails. We hold the ledger; we never hold your customer's funds.
+     */
+    credit(params: {
+        ownerId: string;
+        amountPaise: number;
+        refKey?: string;
+        note?: string;
+    }): Promise<WaBalance>;
+    balance(params?: {
+        ownerId?: string;
+    }): Promise<WaBalance>;
+    /**
+     * Mints a short-lived, owner-scoped session for the inbox UI.
+     *
+     * Call this from a server route and return the result to your page. It is
+     * what lets `<WhatsappInbox>` talk to us without your API key ever reaching
+     * the browser. The ticket lasts sixty seconds; the component refreshes it
+     * through the same route on reconnect.
+     */
+    createInboxSession(params: {
+        ownerId: string;
+    }): Promise<{
+        ownerId: string;
+        ticket: string;
+        expiresIn: number;
+        baseUrl: string;
+    }>;
+}
+declare function createWhatsappClient(options: WhatsappClientOptions): WhatsappClient;
+
+/**
+ * A ready-made proxy route for the inbox UI.
+ *
+ * The browser must never hold your platform API key, so `<WhatsappInbox>` talks
+ * to *your* server, and your server talks to us. This builds that middle layer
+ * so you do not have to hand-write five thin fetch wrappers.
+ *
+ * ```ts
+ * // app/api/whatsapp/[...action]/route.ts
+ * import { createWhatsappClient, createInboxHandler } from "@glitchgrab/whatsapp";
+ *
+ * const client = createWhatsappClient({ apiKey: process.env.GG_WA_KEY! });
+ *
+ * const handler = createInboxHandler({
+ *   client,
+ *   // The single most important line here: derive the owner from YOUR session,
+ *   // never from the request body. Returning a client-supplied id would let any
+ *   // signed-in user read any other library's WhatsApp.
+ *   resolveOwnerId: async () => (await auth()).user.libraryId,
+ * });
+ *
+ * export const GET = handler;
+ * export const POST = handler;
+ * ```
+ */
+interface InboxHandlerOptions {
+    client: WhatsappClient;
+    /**
+     * Returns the owner id for the current request, from your own auth. Return
+     * null to deny.
+     */
+    resolveOwnerId: (request: Request) => Promise<string | null> | string | null;
+    /** Set false to make the inbox read-only for this route. Default true. */
+    allowSend?: boolean;
+}
+declare function createInboxHandler(options: InboxHandlerOptions): (request: Request) => Promise<Response>;
+
+/**
+ * Opens Meta's Embedded Signup popup.
+ *
+ * Runs in the browser, holds no credentials, and returns the `code` your server
+ * exchanges via `client.completeConnect()`. Nothing is connected until that
+ * exchange happens.
+ *
+ * Meta's JS SDK must already be on the page — Embedded Signup only works
+ * through `FB.login` with a `config_id`; a plain OAuth redirect gets a token but
+ * skips the WABA creation the owner actually needs.
+ */
+interface FacebookSdk {
+    init(params: {
+        appId: string;
+        cookie?: boolean;
+        xfbml?: boolean;
+        version: string;
+    }): void;
+    login(callback: (response: {
+        authResponse?: {
+            code?: string;
+        };
+        status?: string;
+    }) => void, options: {
+        config_id: string;
+        response_type: string;
+        override_default_response_type: boolean;
+        extras?: Record<string, unknown>;
+    }): void;
+}
+declare global {
+    interface Window {
+        FB?: FacebookSdk;
+    }
+}
+interface SignupOutcome {
+    code: string;
+    state: string;
+}
+declare function launchSignup(config: WaSignupLaunch): Promise<SignupOutcome>;
+
+export { type InboxHandlerOptions, type SignupOutcome, WaAgent, WaBalance, WaConversation, WaMatchType, WaMessage, WaNumber, WaSendResult, WaSignupLaunch, WaTemplate, WaTemplateCategory, WhatsappClient, type WhatsappClientOptions, createInboxHandler, createWhatsappClient, launchSignup };