@letsbot/sdk 0.0.0-stage → 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LetsBot
+
+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

@@ -1,3 +1,304 @@
-# Temporary Holding Version
+# LetsBot TypeScript SDK (`@letsbot/sdk`)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Official TypeScript/Node client for the LetsBot developer API (`https://letsbot.net/api/v1`).
+
+- Zero runtime dependencies — global `fetch` (Node 18+), `node:crypto`.
+- ESM and CommonJS builds, full types generated from the OpenAPI spec.
+- Retries with exponential backoff and full jitter, honouring `Retry-After`.
+- An `Idempotency-Key` on every send, so a retried send is delivered at most once.
+- A client-side token bucket (default 1000 requests/minute, the API's per-channel limit).
+- One error type, `LetsBotApiError`, for every refusal — including the ones the API sends with HTTP 200/202.
+
+## Install
+
+```bash
+npm install @letsbot/sdk
+```
+
+License: MIT.
+
+## Quick start
+
+```ts
+import { LetsBot } from '@letsbot/sdk';
+
+const letsbot = new LetsBot({ apiKey: process.env.LETSBOT_API_KEY! }); // the channel's lb_api_key
+
+const sent = await letsbot.messages.send({ phone: '966501234567', body: 'Your order has shipped.' });
+console.log(sent.success);
+```
+
+The API key is the channel's `lb_api_key` (panel → API → Authentication data). It is **not** the Zapier key
+(`lbz_…`). The workspace needs an active subscription with the API Access add-on, or an active trial.
+
+### Resources
+
+Every endpoint in the spec is available, grouped like the API:
+
+| Resource | Examples |
+|---|---|
+| `messages` | `send`, `reply`, `react`, `forward`, `sendList`, `sendDisappearing`, `get`, `fetch`, `delete` |
+| `media` | `sendImage`, `sendFile`, `sendVideo`, `sendAudio`, `sendVoiceNote`, `sendLocation`, `sendContact`, `shareCatalog` |
+| `interactive` | `sendButtons`, `sendButtonsWithImage`, `sendButtonsTemplate…`, `sendCarousel` |
+| `templates` | `send`, `sendSimple`, `sendWithImage`, `sendWithDocument`, `sendWithVideo` (official channels only) |
+| `chats` | `list`, `conversation`, `read`, `archive`, `mute`, `pin`, `typing`, `checkPhone`, … |
+| `contacts` | `list`, `get`, `listLabels`, `addLabel`, `listModerators`, `assignModerator` |
+| `groups`, `invites` | `create`, `list`, `addParticipants`, `rename`, `getCode`, `sendLink`, … |
+| `user`, `instance`, `session`, `products` | profile, presence, status, QR, catalog |
+| `archive` | `list` (one page), `iterate` (every page) |
+
+### CRM (`LetsBotCrm`)
+
+The CRM API lives on the workspace's own domain (`https://{workspace}/api/v1/crm`) and takes a workspace API key
+(`lbz_…`, Panel → Zapier → API keys) with the **crm** scope ticked. The key acts as the workspace owner.
+
+```ts
+import { LetsBotCrm, verifyCrmWebhookSignature } from '@letsbot/sdk';
+
+const crm = new LetsBotCrm({ apiKey: process.env.LETSBOT_CRM_KEY!, workspace: 'mystore.letsbot.net' });
+
+const { data: contact } = await crm.contacts.create({ phone: '966501234567', name: 'Laila' });
+const { data: deal } = await crm.deals.create({ title: 'Gift boxes', amount: 8750, contact_id: contact.id });
+await crm.deals.moveStage({ id: deal.id, stage_id: 4 });
+await crm.deals.addNote({ id: deal.id, body: 'Asked for a discount.' });
+
+for await (const won of crm.iterate('crmListDeals', { status: 'won', sort: 'updated_at', dir: 'desc' })) {
+  console.log(won.title, won.amount);
+}
+```
+
+| Resource | Methods |
+|---|---|
+| `contacts` | `list`, `schema`, `search`, `get`, `create`, `update`, `addNote` |
+| `companies` | `list`, `schema`, `search`, `get`, `create`, `update`, `delete`, `linkContact`, `unlinkContact`, `addNote` |
+| `deals` | `list`, `pipelines`, `lostReasons`, `search`, `get`, `create`, `update`, `delete`, `moveStage`, `markWon`, `markLost`, `addNote` |
+| `tasks` | `list`, `get`, `create`, `update`, `delete`, `complete` |
+| `activities`, `quotes`, `products` | `list`, `get`, `create` (+ `update`, `delete`, `schema` for quotes and products) |
+| `customObjects` | `list`, `schema` (custom objects — 404 until the workspace switches them on) |
+| `customRecords` | `list`, `search`, `get`, `create`, `update`, `delete` — pass the object `key`, e.g. `co_projects`; values by field key |
+| `hooks` | `list`, `events`, `sample`, `subscribe`, `unsubscribe` (`CRM_WEBHOOK_EVENTS` lists all 24 events) |
+
+Every method takes one object: path parameters (`id`, `contactId`) plus the query (reads) or the JSON body (writes).
+Lists take `q`, `filters` (lists-engine JSON — see `…schema()`), `view`, `sort`, `dir`, `page`, `per_page` and answer
+`{success, data, meta}`. Errors are `LetsBotApiError` with the envelope's `code` (`missing_scope`, `not_found`,
+`validation_failed`, `already_exists` — a duplicate phone, with the existing contact in `error.body.data`,
+`possible_duplicate` — a likely duplicate, read it with `crmPossibleDuplicate(error)` or repeat with
+`allow_duplicate: true`, …). Reads
+are retried on network errors and 5xx; writes are not. The client-side limit defaults to 120 requests/minute, the
+API's per-key limit.
+
+Webhook deliveries (panel → CRM → Settings → API & webhooks, or `crm.hooks.subscribe`) carry
+`X-LetsBot-Signature: t=<unix>,v1=<hex HMAC-SHA256 of "t.<raw body>">`:
+
+```ts
+const valid = verifyCrmWebhookSignature(rawBody, req.headers['x-letsbot-signature'], subscriptionSecret);
+```
+
+`invoice.created`, `form.submitted`, `deal.assigned` and `health.at_risk` deliveries carry an extra block next to `data`:
+`invoice`, `form` (source, form, submission, answers), `assignment` (new / previous owner) and `health` (score,
+previous, reasons; `object` says contact or company).
+
+```ts
+const record = await crm.customRecords.create({ key: 'co_projects', values: { name: 'Riyadh fit-out', budget: 120000 } });
+
+try {
+  await crm.contacts.create({ phone: '966501234567', email: 'laila@example.com' });
+} catch (error) {
+  const dup = crmPossibleDuplicate(error);
+  if (!dup) throw error;
+  await crm.contacts.update({ id: dup.existingId, name: 'Laila' });
+}
+```
+
+Any operation can also be called by its `operationId` from the spec:
+
+```ts
+await letsbot.call('sendButtonsAlias', { phone: '966501234567', body: 'Confirm?', title: 'Order', footer: 'LetsBot', buttons: [{ id: 'yes', title: 'Yes' }] });
+const { data, status, headers, replayed } = await letsbot.callWithResponse('getChatList');
+```
+
+### Business / ERP (`LetsBotErp`)
+
+The Business API lives on the workspace domain like the CRM API and needs a workspace key with the **erp** scope
+ticked. Each area (inventory, sales, purchasing, expenses, accounting) answers 404 until the workspace switches it on.
+Creates return drafts (or take the one step you call); nothing messages a customer.
+
+```ts
+import { LetsBotErp, verifyErpWebhookSignature } from '@letsbot/sdk';
+
+const erp = new LetsBotErp({ apiKey: process.env.LETSBOT_KEY!, workspace: 'mystore.letsbot.net' });
+
+const { data: order } = await erp.salesOrders.create({ customer_id: 42, lines: [{ sku: 'RY-OUD-50', qty: 2 }] });
+await erp.salesOrders.confirm({ id: order!.id! });
+
+const { data: invoice } = await erp.invoices.create({ order_id: order!.id! });
+await erp.invoices.issue({ id: invoice!.id! });
+const { data: link } = await erp.invoices.pdfLink({ id: invoice!.id! }); // link.pdf_url once shareable
+
+await erp.payments.record({ customer_id: 42, amount: 1150, method: 'bank_transfer', reference: 'TRX-1' });
+
+for await (const level of erp.iterate('erpListStockLevels', { warehouse_id: 1 })) console.log(level.sku, level.available);
+
+// Webhooks: invoice.issued, invoice.paid, invoice.cleared, invoice.rejected, credit_note.issued, payment.received,
+// order.confirmed, stock.low, po.confirmed_by_supplier, expense.posted
+const { data: hook } = await erp.hooks.subscribe({ url: 'https://example.com/letsbot', events: ['invoice.paid'] });
+// on receipt: verifyErpWebhookSignature(rawBody, req.headers['x-letsbot-signature'], hook.secret)
+```
+
+Every create (`salesOrders.create`, `invoices.create`, `invoices.createCreditNote`, `payments.record`,
+`purchaseOrders.create`, `expenses.create`) sends an `Idempotency-Key` — pass `{ idempotencyKey: 'order-123' }` to
+tie it to your own id — so a retry after a timeout never makes a second document.
+
+### Templates
+
+```ts
+await letsbot.templates.send({
+  phone: '966501234567',
+  template_name: 'order_confirmation',
+  template_language: 'ar',
+  components: { body: ['Ahmed', 'ORD-12345', '150 SAR'] },
+});
+```
+
+### Message archive
+
+```ts
+for await (const message of letsbot.archive.iterate({ date_from: '2026-09-01', date_to: '2026-09-07', timezone: 'Asia/Riyadh' })) {
+  console.log(message.message_date, message.from_me, message.body);
+}
+```
+
+## Errors
+
+```ts
+import { LetsBotApiError, LetsBotConnectionError } from '@letsbot/sdk';
+
+try {
+  await letsbot.messages.send({ phone: '966501234567', body: 'Hi' });
+} catch (error) {
+  if (error instanceof LetsBotApiError) {
+    error.status;    // HTTP status — can be 200 or 202, see below
+    error.body;      // parsed JSON body
+    error.code;      // error_code / code / error from the body, e.g. API_ADDON_REQUIRED
+    error.requestId; // the support reference on a 500 (API-XXXXXXXXXX), else undefined
+  } else if (error instanceof LetsBotConnectionError) {
+    // no HTTP response at all (DNS, reset, timeout), after retries
+  }
+}
+```
+
+**The HTTP status alone does not tell you whether a request worked.** Most endpoints answer a validation failure
+with **HTTP 202** and `{"Status": 0, "Message": "..."}`, and pass the connection gateway's answer through with
+HTTP 200 even when it says `{"success": false}`. The SDK treats both as failures and throws `LetsBotApiError`
+(same rule the server uses to decide whether a send counted). Pass `throwOnLogicalFailure: false` to get those
+bodies back instead.
+
+The API has no request-id header; `requestId` is only filled from the `reference` of a 500.
+
+## Retries
+
+- Exponential backoff with full jitter: base 500 ms, at most 3 retries (`retry: { maxRetries, baseDelayMs, maxDelayMs }`).
+- `Retry-After` is honoured. A `Retry-After` longer than `retry.maxRetryAfterMs` (default 60 s — the workspace's daily
+  send limit can say hours) is not waited out: the error is thrown with `error.retryAfter` set.
+- **429** is retried on every endpoint — it means nothing was done.
+- **Network errors and 5xx** are retried only when repeating is safe: on GET requests, and on **send** endpoints
+  that carry an `Idempotency-Key`. Any other POST/DELETE (archive a chat, block a user, create a group, …) is never
+  repeated after it may have reached the server.
+- **409 `idempotency_request_in_progress`** is retried with the same key.
+- **409 `idempotency_outcome_unknown`** is never retried (`error.isOutcomeUnknown === true`): an earlier attempt with
+  that key died before its result was known. Check the message before sending again with a new key.
+  Expect this after a 5xx on a send: the server marks the key "outcome unknown" on any 5xx, so the retry under the
+  same key comes back as this 409 rather than risking a duplicate.
+
+## Idempotency
+
+Every **send** endpoint (the 35 operations marked `x-letsbot-send` in the spec — `messages.send`, `templates.*`,
+`media.send*`, `interactive.*`, `messages.forward`, `media.shareCatalog`, `invites.sendLink`, …) gets an
+`Idempotency-Key` header: a fresh UUID per call by default, reused on every retry of that call. The server
+keeps the result for 24 hours and replays it for the same key (`callWithResponse(...).replayed === true`).
+
+- Pass your own key to stay idempotent across process restarts: `{ idempotencyKey: 'order-12345' }`.
+- Pass `{ idempotencyKey: false }` to send without one — the SDK will then not retry that send after a network
+  error or 5xx.
+- The server honours the header on send endpoints only, so the SDK does not send it anywhere else; a key given on
+  another endpoint is ignored and does not enable retries.
+
+## Rate limit
+
+The client waits for a token before every attempt (default 1000 per minute, the API's per-channel limit). Use
+one client per API key so the bucket sees all of that key's traffic. `rateLimit: { requestsPerMinute: 300 }` to
+go slower, `rateLimit: false` to turn it off.
+
+## Webhooks (experimental — read this)
+
+API webhooks (configured in the panel, API → Webhooks) are POSTed as `{"event": "<type>", "data": {...}}` with a
+`Signature` header: the hex HMAC-SHA256 of the raw body. **The key is the literal string `Letsbot`, the same for
+every LetsBot workspace**, and it is printed in this SDK. Anyone can therefore produce a valid signature:
+
+```ts
+import { experimental_verifyWebhookSignature } from '@letsbot/sdk';
+
+experimental_verifyWebhookSignature(rawBody, req.headers['signature']); // integrity only — NOT authentication
+```
+
+A `true` does **not** prove the request came from LetsBot. To authenticate webhooks, add a header with a secret of
+your own to the webhook in the panel and compare it on receipt (see `examples/webhook-receiver.ts`). Verify the
+raw bytes you received, before `JSON.parse`: the server's JSON escapes `/` and non-ASCII characters, so a
+re-serialised body will not match.
+
+## In-App Chat identity
+
+LetsBot In-App Chat (the mobile SDKs) links a conversation to your signed-in user when the app calls
+`identify(identityToken)`. The identity token is a short-lived JWT (HS256) that **your backend** signs with the app's
+**Identity Secret** (panel → In-App Chat → your app). Never put the secret in the mobile app.
+
+```ts
+import { createIdentityToken } from '@letsbot/sdk';
+
+// e.g. GET /api/letsbot/identity-token — behind your own authentication
+app.get('/api/letsbot/identity-token', requireUser, (req, res) => {
+  const token = createIdentityToken({
+    userId: req.user.id,                          // sub: stable id, ≤ 191 characters
+    secret: process.env.LETSBOT_IDENTITY_SECRET!,
+    expiresIn: '24h',                             // default; seconds or '90s' | '15m' | '24h' | '7d', max 7 days
+    name: req.user.name,                          // optional; claims win over fields the app sends
+    email: req.user.email,                        // optional
+    phone: req.user.phone,                        // optional, international format
+  });
+  res.set('Cache-Control', 'no-store').json({ token });
+});
+```
+
+Claims: `sub`, `iat`, `exp` (+ optional `name`, `email`, `phone`). LetsBot allows 60 s of clock skew and rejects a
+token whose `exp` is more than 7 days after `iat`. An expired token makes `identify` fail with `identity_expired` —
+the app should fetch a fresh one from this endpoint and retry; a bad signature gives `identity_invalid`.
+`createIdentityToken` throws `TypeError` / `RangeError` on an empty secret, an empty or over-long `userId`, or a
+lifetime over 7 days. Do not log the token or the secret. Examples for PHP, Python, Go, Ruby and .NET:
+`https://github.com/Lets-Bot/letsbot-identity-examples`.
+
+## Development
+
+```bash
+npm install
+npm run build                          # tsup → dist/ (ESM + CJS + .d.ts)
+npx tsc --noEmit -p .                  # typecheck src, test, examples
+npx vitest run test/retry.test.ts      # one spec file at a time
+npm run check:drift                    # fails when anything generated is stale
+```
+
+The spec lives in the LetsBot workspace at `packages/api/openapi/openapi.yaml`; this repository keeps a copy in
+`openapi/openapi.yaml` so it builds on its own. Inside the workspace:
+
+- `npm run spec:sync` — copy the workspace spec here and regenerate `src/generated/` (types via
+  `openapi-typescript`, the operation table via `scripts/gen-operations.mjs`).
+- `npm run spec:json` — regenerate `packages/api/openapi/openapi.json` from the YAML (letsbot's
+  `OpenApiRouteParityTest` reads the JSON twin).
+- `npm run check:drift` — vendored copy == workspace spec, generated types and operation table are fresh, and the
+  JSON twin matches the YAML. Outside the workspace the two workspace checks are skipped. Point
+  `LETSBOT_API_SPEC` at another copy of the spec to check against it.
+
+## Publishing
+
+Published to npm as `@letsbot/sdk` (public, MIT). Bump `version` in `package.json` and `SDK_VERSION` in
+`src/client.ts` together, move the changelog entries under the new version, then `npm publish --access public`
+(`prepublishOnly` builds and runs the tests).