@wassist/sdk 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## 0.1.0 (Unreleased)
+
+Initial release.
+
+- Typed client for the public Wassist REST API: `agents`, `conversations` (+ `messages`), `phoneNumbers`, `whatsappAccounts`, `whatsappLinkSessions`, `whatsappTemplates`.
+- Auto-paginating list endpoints with `for await` support and `.firstPage()`.
+- Automatic retries on `429` and `5xx` with exponential backoff and `Retry-After` honoring.
+- Per-call idempotency keys for `POST` mutations (`Idempotency-Key` header).
+- Typed error hierarchy with `statusCode`, `code`, `requestId`, and raw response body.
+- Stripe-style webhook signature verification via `wassist.webhooks.constructEvent()` (sync) and `constructEventAsync()` (Web Crypto, for edge runtimes).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Wassist
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,282 @@
+# Wassist SDK
+
+The TypeScript client for the [Wassist API](https://docs.wassist.app/api-reference). Build WhatsApp agents, send messages, manage templates, and verify webhooks from any modern JavaScript runtime.
+
+[![npm version](https://img.shields.io/npm/v/@wassist/sdk.svg)](https://www.npmjs.com/package/@wassist/sdk)
+
+## Installation
+
+```bash
+npm install @wassist/sdk
+```
+
+Requires Node.js >= 18, or any runtime with a global `fetch` (Deno, Bun, Cloudflare Workers, Vercel Edge, modern browsers).
+
+## Quickstart
+
+```ts
+import { Wassist } from '@wassist/sdk';
+
+const wassist = new Wassist({ apiKey: process.env.WASSIST_API_KEY! });
+
+// Create an agent
+const agent = await wassist.agents.create({ name: 'Sales Assistant' });
+
+// Configure it
+await wassist.agents.update(agent.id, {
+  systemPrompt: 'You help customers pick the right product.',
+  firstMessage: 'Hi! How can I help today?',
+});
+
+// Start a conversation
+const conversation = await wassist.conversations.create({
+  toNumber: '+447700900100',
+  agentId: agent.id,
+});
+
+// Send a message
+await wassist.conversations.messages.send(conversation.id, {
+  type: 'text',
+  text: { body: 'Hello!' },
+});
+
+// Walk every conversation lazily
+for await (const c of wassist.conversations.list()) {
+  console.log(c.id, c.lastMessage?.body);
+}
+```
+
+Get your API key at [wassist.app/settings](https://wassist.app/settings).
+
+## Configuration
+
+```ts
+const wassist = new Wassist({
+  apiKey: process.env.WASSIST_API_KEY!,    // required
+  baseUrl: 'https://backend.wassist.app',  // default
+  timeout: 60_000,                         // ms; default 60s
+  maxRetries: 2,                           // default 2 (so 3 attempts total)
+  fetch: customFetch,                      // optional override
+});
+```
+
+## Resources
+
+| Namespace | Methods |
+|-----------|---------|
+| `wassist.agents` | `list`, `get`, `create`, `createBYOA`, `update`, `delete` |
+| `wassist.conversations` | `list`, `get`, `create`, `read`, `typing`, `prompt`, `subscribe`, `unsubscribe` |
+| `wassist.conversations.messages` | `list`, `send` |
+| `wassist.phoneNumbers` | `list`, `getBusinessProfile`, `subscribe`, `connectAgent`, `unsubscribe` |
+| `wassist.whatsappAccounts` | `list`, `get`, `addNumber`, `availableNumbers` |
+| `wassist.whatsappLinkSessions` | `list`, `get`, `create`, `expire` |
+| `wassist.whatsappTemplates` | `list`, `get`, `create`, `update`, `delete`, `publish`, `unpublish` |
+| `wassist.webhooks` | `constructEvent`, `constructEventAsync` |
+
+Every method is fully typed against the [public API reference](https://docs.wassist.app/api-reference) — your editor knows every field on every input and response.
+
+## Pagination
+
+List methods return a lazy `AutoPaginatedList<T>`. Use `for await` to walk all pages, or `.firstPage()` for a single page.
+
+```ts
+// Iterate every conversation (pages are fetched on demand)
+for await (const conv of wassist.conversations.list({ limit: 100 })) {
+  // ...
+}
+
+// One page at a time
+const { data, hasMore, nextOffset } = await wassist.conversations
+  .list({ limit: 20 })
+  .firstPage();
+
+// Eagerly collect everything (small lists only)
+const allAgents = await wassist.agents.list().all();
+```
+
+## Errors
+
+Every API failure throws a typed subclass of `WassistError`. Branch on `instanceof` to handle each case.
+
+```ts
+import {
+  WassistError,
+  WassistAuthenticationError,
+  WassistInvalidRequestError,
+  WassistNotFoundError,
+  WassistRateLimitError,
+  WassistTimeoutError,
+} from '@wassist/sdk';
+
+try {
+  await wassist.agents.get('not-a-real-id');
+} catch (err) {
+  if (err instanceof WassistAuthenticationError) {
+    // 401 — bad/missing API key
+  } else if (err instanceof WassistNotFoundError) {
+    // 404
+  } else if (err instanceof WassistRateLimitError) {
+    console.log('retry after', err.retryAfter, 'seconds');
+  } else if (err instanceof WassistInvalidRequestError) {
+    // 400 / 422
+  } else if (err instanceof WassistTimeoutError) {
+    // request didn't complete within `timeout` ms
+  } else if (err instanceof WassistError) {
+    console.log(err.statusCode, err.code, err.requestId, err.raw);
+  }
+}
+```
+
+Every error carries `statusCode`, `code`, and the `requestId` from the `X-Request-Id` response header — quote it when filing support tickets.
+
+## Retries and idempotency
+
+The SDK automatically retries `429`, `408`, `425`, `5xx`, and network failures with exponential backoff + jitter. `Retry-After` headers on `429` are honored.
+
+For mutations that need to be safe against retries, pass an `idempotencyKey`:
+
+```ts
+import { randomUUID } from 'node:crypto';
+
+const conv = await wassist.conversations.create(
+  { toNumber: '+447700900100', agentId },
+  { idempotencyKey: randomUUID() }
+);
+```
+
+The key is forwarded as the `Idempotency-Key` header; the server deduplicates within a 24-hour window.
+
+You can also tune retries and timeouts per call:
+
+```ts
+await wassist.agents.list({}, { timeout: 5_000, maxRetries: 0 });
+```
+
+And cancel any request:
+
+```ts
+const controller = new AbortController();
+setTimeout(() => controller.abort(), 1000);
+await wassist.agents.list({}, { signal: controller.signal });
+```
+
+## Webhook signature verification
+
+Wassist signs every webhook delivery with HMAC-SHA256 using the Stripe-style `t=<unix>,v1=<hex>` header format. The SDK gives you a one-liner to verify it.
+
+### Node.js / Express
+
+```ts
+import express from 'express';
+import { Wassist, WassistSignatureVerificationError, type WassistEvent } from '@wassist/sdk';
+
+const app = express();
+
+app.post(
+  '/webhooks/wassist',
+  express.raw({ type: 'application/json' }),
+  (req, res) => {
+    let event: WassistEvent;
+    try {
+      event = Wassist.webhooks.constructEvent(
+        req.body,                                      // raw Buffer — DON'T parse first
+        req.header('x-wassist-signature') ?? '',
+        process.env.WASSIST_WEBHOOK_SECRET!
+      );
+    } catch (err) {
+      if (err instanceof WassistSignatureVerificationError) {
+        return res.status(400).send(err.message);
+      }
+      throw err;
+    }
+
+    switch (event.event) {
+      case 'message.received':
+        // event.message, event.from, event.conversationId, ...
+        break;
+      case 'subscription.activated':
+      case 'subscription.revoked':
+        // event.webhookId, event.conversationId
+        break;
+      case 'test.ping':
+        // dashboard "Send test event" button
+        break;
+    }
+    res.status(200).send('ok');
+  }
+);
+```
+
+### Cloudflare Workers / Deno / Edge runtimes
+
+Use the async variant — it runs entirely on Web Crypto:
+
+```ts
+export default {
+  async fetch(request: Request, env: { WASSIST_WEBHOOK_SECRET: string }) {
+    const body = await request.text();
+    try {
+      const event = await Wassist.webhooks.constructEventAsync(
+        body,
+        request.headers.get('x-wassist-signature'),
+        env.WASSIST_WEBHOOK_SECRET
+      );
+      // ... handle event
+      return new Response('ok');
+    } catch {
+      return new Response('bad signature', { status: 400 });
+    }
+  },
+};
+```
+
+### Replay protection
+
+By default the SDK rejects events whose timestamp is more than **300 seconds** off from now. Tune or disable:
+
+```ts
+Wassist.webhooks.constructEvent(body, header, secret, { tolerance: 600 });
+Wassist.webhooks.constructEvent(body, header, secret, { tolerance: 0 }); // off (not recommended)
+```
+
+## Custom fetch / runtimes
+
+The SDK uses `globalThis.fetch` by default. Inject your own — for tests, retries, tracing, or older Node:
+
+```ts
+const wassist = new Wassist({
+  apiKey: '...',
+  fetch: async (url, init) => {
+    console.log('->', init?.method ?? 'GET', url);
+    return fetch(url, init);
+  },
+});
+```
+
+## TypeScript
+
+The package is published with full `.d.ts` types. Every response, input, and event is typed against the public Wassist API:
+
+```ts
+import type {
+  Agent,
+  Conversation,
+  Message,
+  PhoneNumber,
+  WhatsAppAccount,
+  WhatsAppTemplate,
+  WhatsAppLinkSession,
+  WassistEvent,
+  MessageReceivedEvent,
+} from '@wassist/sdk';
+```
+
+## Support
+
+- Documentation: [docs.wassist.app/api-reference](https://docs.wassist.app/api-reference)
+- Email: [contact@wassist.app](mailto:contact@wassist.app)
+- Issues: [github.com/wassist/sdk/issues](https://github.com/wassist/sdk/issues)
+
+## License
+
+MIT