@ecodrix/erix-api 3.1.1 → 3.2.0

package/README.md

@@ -1,1006 +1,659 @@
 # @ecodrix/erix-api
 
-<div align="center">
-
-[![NPM Version](https://img.shields.io/npm/v/@ecodrix/erix-api.svg?style=for-the-badge)](https://www.npmjs.com/package/@ecodrix/erix-api)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge)](https://opensource.org/licenses/MIT)
-[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue?style=for-the-badge&logo=typescript)](https://www.typescriptlang.org/)
-[![OpenAPI](https://img.shields.io/badge/OpenAPI-3.0-green?style=for-the-badge&logo=openapiinitiative)](./schema/openapi.yaml)
-[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18-brightgreen?style=for-the-badge&logo=nodedotjs)](https://nodejs.org/)
-
-**The official, isomorphic SDK for the [ECODrIx](https://ecodrix.com) platform.**
-
-Manage WhatsApp conversations, CRM leads, pipelines, automations, marketing campaigns, file storage, and Google Meet — all from a single, type-safe library.
-
-</div>
-
----
-
-## Table of Contents
-
-- [Installation](#installation)
-- [Quick Start](#quick-start)
-- [Configuration](#configuration)
-- [Resources](#resources)
-  - [WhatsApp](#whatsapp)
-    - [Messages](#ecod-whatsapp-messages)
-    - [Conversations](#ecod-whatsapp-conversations)
-    - [Templates](#ecod-whatsapp-templates)
-    - [Broadcasts](#ecod-whatsapp-broadcasts)
-  - [CRM](#crm)
-    - [Leads](#ecod-crm-leads)
-    - [Pipelines & Stages](#ecod-crm-pipelines)
-    - [Automations](#ecod-crm-automations)
-    - [Sequences](#ecod-crm-sequences)
-    - [Activities & Timeline](#ecod-crm-activities)
-    - [Analytics](#ecod-crm-analytics)
-    - [Scoring](#ecod-crm-scoring)
-    - [Payments](#ecod-crm-payments)
-    - [Automation Dashboard](#ecod-crm-automationdashboard)
-  - [Events & Workflows](#events--workflows)
-  - [Marketing](#marketing)
-  - [Meetings](#meetings)
-  - [Storage](#storage)
-  - [Media](#media)
-  - [Email](#email)
-  - [Notifications & Logs](#notifications--logs)
-  - [Queue Management](#queue-management)
-  - [Health & Diagnostics](#health--diagnostics)
-  - [Webhooks](#webhooks)
-- [Enterprise Capabilities](#enterprise-capabilities)
-  - [Auto-Paginating Iterators](#auto-paginating-iterators)
-  - [Bulk Data Chunking](#bulk-data-chunking)
-  - [Idempotency Keys](#idempotency-keys)
-  - [Webhook Signature Verification](#webhook-signature-verification)
-  - [Raw Execution Engine](#raw-execution-engine)
-- [Real-time Events](#real-time-events)
-- [Error Handling](#error-handling)
-- [Browser / CDN Usage](#browser--cdn-usage)
-
----
-
-## Installation
+[![npm](https://img.shields.io/npm/v/@ecodrix/erix-api.svg)](https://www.npmjs.com/package/@ecodrix/erix-api)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+The official TypeScript SDK for the [ECODrIx](https://ecodrix.com) platform.
+Use it from your own backend to work with your workspace: CRM leads and
+pipelines, Flow automations, the unified inbox (WhatsApp, Instagram, Facebook,
+Telegram, email, webchat), invoices and payment links, file storage, and live
+events. Every call is scoped to the workspace your key belongs to.
+
+- Developer guide: https://api.ecodrix.com/docs
+- API reference: https://api.ecodrix.com/reference
+
+## Install
 
 ```bash
-# pnpm (recommended)
 pnpm add @ecodrix/erix-api
-
-# npm
-npm install @ecodrix/erix-api
+# or: npm install @ecodrix/erix-api
 ```
 
-> **Requires**: Node.js >= 18
+- **Node.js 18+** (uses the global `fetch` and `Blob`). Ships ESM and CommonJS
+  builds with bundled type definitions.
+- **Browsers**: supported through a bundler (Vite, Next.js, webpack) in
+  [proxy mode](#browser-use-proxy-mode) only, plus the keyless
+  [website chat visitor client](#website-chat-visitor-client). There is no
+  CDN build.
 
----
+## Quick start
 
-## Quick Start
+Run this on your server. Keep the key in a server-only environment variable.
 
-```typescript
+```ts
 import { ECODrIxAPI } from "@ecodrix/erix-api";
 
 const ecod = new ECODrIxAPI({
   apiKey: process.env.ECOD_API_KEY!,
-  clientCode: "ERIX_CLNT_JHBJHF",
-  // Optional — pick the API version. Defaults to "v1".
-  version: "v1",
-});
-
-// The SDK surface mirrors the server's domain ownership 1:1:
-//   ecod.platform.*        control plane (auth-scoped tenant/admin)
-//   ecod.product.erix.*    ERIX product  (CRM, chat, commerce, events)
-//   ecod.infra.connect.*   channel transport (email, whatsapp, meet)
-//   ecod.infra.storage.*   file storage
-
-// Send a WhatsApp/chat message
-await ecod.product.erix.chat.messages.send({
-  to: "+919876543210",
-  text: "Hello from ECODrIx!",
+  clientCode: "ERIX_CLNT_XXXXXX", // Settings → Developer in the dashboard
 });
 
-// Create a CRM lead
-const lead = await ecod.product.erix.leads.create({
-  firstName: "Priya",
-  phone: "+919876543210",
+const { data: lead } = await ecod.product.erix.leads.create({
+  firstName: "Test",
+  lastName: "Customer",
+  phone: "+91XXXXXXXXXX",
   source: "website",
 });
 
-// Fire an automation trigger
 await ecod.product.erix.events.trigger({
-  trigger: "trial_started",
-  phone: "+919876543210",
-  createLeadIfMissing: true,
-});
-```
-
-> **Note:** host projects never pass a URL. The domain is managed by the SDK;
-> you only choose an API `version`. Moving the whole SDK to `v2` later is a
-> single flag — `new ECODrIxAPI({ ..., version: "v2" })` — because every
-> endpoint is issued relative to `<host>/<version>/api`.
-
----
-
-## Configuration
-
-Pass an options object to `new Ecodrix(options)`:
-
-| Option       | Type                   | Required    | Default | Description                                                        |
-| ------------ | ---------------------- | ----------- | ------- | ------------------------------------------------------------------ |
-| `apiKey`     | `string`               | ✅ Yes      | —       | Your ECOD Platform API key                                         |
-| `clientCode` | `string`               | Recommended | —       | Your tenant ID — scopes all requests                               |
-| `version`    | `"v1" \| "v2" \| "v3"` | No          | `"v1"`  | API route version. The single knob to target a new server version. |
-| `coreApiKey` | `string`               | No          | —       | Elevated key for platform-admin surfaces (`ecod.platform.admin.*`) |
-
-```typescript
-const ecod = new ECODrIxAPI({
-  apiKey: process.env.ECOD_API_KEY!,
-  clientCode: "ERIX_CLNT_JHBJHF",
-  version: "v1",
-});
-```
-
----
-
-## Resources
-
-### WhatsApp
-
-Access via `ecod.whatsapp`.
-
----
-
-#### `ecod.whatsapp.messages`
-
-**Send a text message**
-
-```typescript
-await ecod.whatsapp.messages.send({
-  to: "+919876543210",
-  text: "Your appointment is confirmed!",
-});
-```
-
-**Send a media message (image, video, document, audio)**
-
-```typescript
-await ecod.whatsapp.messages.send({
-  to: "+919876543210",
-  mediaUrl: "https://cdn.ecodrix.com/invoice.pdf",
-  mediaType: "document",
-  filename: "invoice.pdf",
+  trigger: "enquiry_received",
+  phone: "+91XXXXXXXXXX",
 });
-```
-
-**Send a template message via queue**
 
-```typescript
-await ecod.whatsapp.messages.sendTemplate({
-  to: "+919876543210",
-  templateName: "appointment_reminder",
-  language: "en_US",
-  variables: ["Priya", "Tomorrow 10AM"],
-});
+// The client keeps a realtime socket open. Close it when your process stops.
+process.on("SIGTERM", () => ecod.disconnect());
 ```
 
-**Mark messages as read**
+| Option       | Type                         | Default  | Notes                                                    |
+| ------------ | ---------------------------- | -------- | -------------------------------------------------------- |
+| `apiKey`     | `string`                     | none     | Workspace key or a [scoped key](#scoped-keys). Server only. |
+| `clientCode` | `string`                     | none     | Your workspace code, e.g. `ERIX_CLNT_XXXXXX`.            |
+| `version`    | `"v1"`                       | `"v1"`   | API route version.                                       |
+| `timeout`    | `number` (ms)                | `30000`  | Per request. `0` disables.                               |
+| `proxy`      | `{ url, ticket? }`           | none     | Browser mode. Replaces `apiKey`.                         |
 
-```typescript
-await ecod.whatsapp.messages.markRead("message_id");
-```
+## How the client is laid out
 
----
+The client follows the API's route tree:
 
-#### `ecod.whatsapp.conversations`
+| Namespace                    | What it covers                                                      |
+| ---------------------------- | ------------------------------------------------------------------- |
+| `ecod.product.erix.*`        | CRM (`leads`, `pipelines`, `activities`, `analytics`), `events` (Flow triggers), `chat` (inbox), `invoices`, `payments`, `ai` |
+| `ecod.infra.connect.*`       | Channels: `whatsapp.templates`, `email`, `meet`, `connections`       |
+| `ecod.infra.storage.*`       | Files: `media`, `files`, `folders`                                   |
+| `ecod.platform.*`            | Workspace: `knowledge` (AI knowledge base), `users.notifications`    |
+| `ecod.webhooks`              | Webhook signature verification                                      |
+| `ecod.on()` / `ecod.off()`   | Realtime events                                                     |
+| `ecod.request()`             | Authenticated call to any endpoint without a typed method yet       |
 
-```typescript
-// List conversations (cursor-based pagination)
-const { data } = await ecod.whatsapp.conversations.list({
-  limit: 20,
-  status: "open",
-  after: "cursor_token",
-});
+## Browser use (proxy mode)
 
-// Get a specific conversation
-const conv = await ecod.whatsapp.conversations.retrieve("conversation_id");
+Never put a workspace key in the browser. That includes `NEXT_PUBLIC_*`,
+`VITE_*` or any other variable that ends up in a client bundle. Anyone who
+opens dev tools can read it, and a workspace key has full access.
 
-// Get messages in a conversation
-const { data: msgs } = await ecod.whatsapp.conversations.messages(
-  "conversation_id",
-  {
-    limit: 50,
-  },
-);
+In the browser, run the SDK in proxy mode:
 
-// Create a conversation explicitly
-await ecod.whatsapp.conversations.create({
-  phone: "+919876543210",
-  name: "Priya",
-});
+1. Your server exposes `/api/erix/*`. It checks your signed-in user, adds the
+   key, and forwards the request to ECODrIx.
+2. For realtime, your server mints a 5-minute socket ticket. The browser gets
+   the ticket, never the key.
 
-// Link a conversation to a CRM lead
-await ecod.whatsapp.conversations.linkLead("conversation_id", "lead_id");
+Proxy route (Next.js App Router, `app/api/erix/[...path]/route.ts`):
 
-// Mark a conversation as read (clears unread badge)
-await ecod.whatsapp.conversations.markRead("conversation_id");
+```ts
+const API = "https://api.ecodrix.com";
+const PASS_HEADERS = ["content-type", "accept", "idempotency-key"];
+const DROP_HEADERS = ["content-encoding", "content-length", "transfer-encoding", "connection"];
 
-// Delete / archive a conversation
-await ecod.whatsapp.conversations.delete("conversation_id");
+async function proxy(req: Request, ctx: { params: Promise<{ path: string[] }> }) {
+  const user = await requireUser(req); // your own session check
+  if (!user) {
+    return Response.json({ success: false, error: "Unauthorized" }, { status: 401 });
+  }
 
-// Bulk delete conversations
-await ecod.whatsapp.conversations.bulkDelete(["conv_1", "conv_2"]);
-```
+  const { path } = await ctx.params;
+  const rel = `/${path.map(encodeURIComponent).join("/")}`;
+  if (!/^\/v\d+\/api\//.test(rel)) {
+    return Response.json({ success: false, error: "Not found" }, { status: 404 });
+  }
 
----
+  const headers = new Headers({
+    "x-api-key": process.env.ECOD_API_KEY!,
+    "x-client-code": "ERIX_CLNT_XXXXXX",
+  });
+  for (const name of PASS_HEADERS) {
+    const value = req.headers.get(name);
+    if (value) headers.set(name, value);
+  }
 
-#### `ecod.whatsapp.templates`
+  const hasBody = req.method !== "GET" && req.method !== "HEAD";
+  const upstream = await fetch(`${API}${rel}${new URL(req.url).search}`, {
+    method: req.method,
+    headers,
+    body: hasBody ? await req.arrayBuffer() : undefined,
+    redirect: "manual",
+  });
 
-```typescript
-// List pre-approved Meta templates
-const { data } = await ecod.whatsapp.templates.list();
+  const out = new Headers(upstream.headers);
+  for (const name of DROP_HEADERS) out.delete(name);
+  return new Response(upstream.body, { status: upstream.status, headers: out });
+}
 
-// Sync templates from the Meta Business Account
-await ecod.whatsapp.templates.sync();
+export { proxy as GET, proxy as POST, proxy as PUT, proxy as PATCH, proxy as DELETE };
 ```
 
----
-
-#### `ecod.whatsapp.broadcasts`
+Ticket route (`app/api/erix/ticket/route.ts`):
 
-Send a personalised WhatsApp template message to multiple recipients at once.
+```ts
+export async function POST(req: Request) {
+  const user = await requireUser(req); // your own session check
+  if (!user) return new Response("Unauthorized", { status: 401 });
 
-```typescript
-await ecod.whatsapp.broadcasts.create({
-  name: "April Promo",
-  templateName: "discount_offer",
-  templateLanguage: "en_US",
-  recipients: [
-    { phone: "+919876543210", variables: ["Priya", "20%"] },
-    { phone: "+919123456789", variables: ["Ravi", "30%"] },
-  ],
-});
+  const res = await fetch("https://api.ecodrix.com/v1/api/platform/realtime/ticket", {
+    method: "POST",
+    headers: {
+      "x-api-key": process.env.ECOD_API_KEY!,
+      "x-client-code": "ERIX_CLNT_XXXXXX",
+    },
+    cache: "no-store",
+  });
+  const body = (await res.json().catch(() => null)) as { data?: { ticket?: string } } | null;
+  const ticket = body?.data?.ticket;
+  if (!res.ok || !ticket) return new Response("Ticket unavailable", { status: 502 });
 
-// List past broadcasts
-const { data } = await ecod.whatsapp.broadcasts.list({ status: "completed" });
+  return new Response(ticket, {
+    headers: { "content-type": "text/plain", "cache-control": "no-store" },
+  });
+}
 ```
 
----
-
-#### `ecod.whatsapp.sendTemplate` — Direct Template (Bypass Queue)
+Browser client:
 
-Use this for high-priority utility templates that must deliver immediately outside the automation queue.
+```ts
+import { ECODrIxAPI } from "@ecodrix/erix-api";
 
-```typescript
-const result = await ecod.whatsapp.sendTemplate({
-  phone: "+919876543210",
-  templateName: "payment_confirmation",
-  variables: {
-    name: "Priya",
-    amount: "₹1,500",
+export const ecod = new ECODrIxAPI({
+  proxy: {
+    url: "/api/erix",
+    ticket: () =>
+      fetch("/api/erix/ticket", { method: "POST" }).then((r) =>
+        r.ok ? r.text() : Promise.reject(new Error("No realtime ticket")),
+      ),
   },
 });
-// result.messageId → WA message ID
 ```
 
----
-
-### CRM
-
-Access via `ecod.crm`.
-
----
+The SDK fetches a fresh ticket on every reconnect. Without `ticket`, REST
+calls work and no socket opens.
 
-#### `ecod.crm.leads`
+Anyone signed in to your app can now do whatever the workspace key can.
+If your users shouldn't have all of that, allow-list the paths they need in the
+proxy route.
 
-**Create**
+## Website chat visitor client
 
-```typescript
-const { data: lead } = await ecod.crm.leads.create({
-  firstName: "Priya",
-  lastName: "Sharma",
-  phone: "+919876543210",
-  email: "priya@example.com",
-  source: "website",
-  pipelineId: "pipeline_id",
-  stageId: "stage_id",
-  metadata: { utmSource: "google" },
-});
-```
+`@ecodrix/erix-api/visitor` is a separate entry for an anonymous website
+visitor chatting with a workspace. It takes no key and reaches only that
+visitor's own thread. It uses `fetch` and loads `socket.io-client` only when
+you go live, so a chat widget doesn't ship the full SDK. The ERIX chat widget
+runs on it.
 
-**Upsert by phone** — Creates if absent, updates if exists
+```ts
+import { WebchatVisitor, WebchatVisitorError } from "@ecodrix/erix-api/visitor";
 
-```typescript
-await ecod.crm.leads.upsert({
-  leadData: { phone: "+919876543210", firstName: "Priya" },
-  trigger: "webinar_joined",
+const chat = new WebchatVisitor({
+  clientCode: "ERIX_CLNT_XXXXXX",
+  // The visitor's only secret: random, 20–80 characters of A-Z a-z 0-9 _ -.
+  // Keep it (e.g. in localStorage) to continue the same thread next visit.
+  sessionId,
+  // The site the chat runs on. It must be on the workspace's allowed domains.
+  parent: "https://www.example.in",
 });
-```
-
-**List with filters**
 
-```typescript
-const { data } = await ecod.crm.leads.list({
-  status: "new",
-  source: "whatsapp",
-  pipelineId: "pipeline_id",
-  page: 1,
-  limit: 25,
-});
-```
+const { data: messages, widget, consentNotice } = await chat.messages();
 
-**Retrieve**
+try {
+  await chat.send("Do you open on Sunday?", {
+    messageId: crypto.randomUUID(), // resend with the same id: stored once
+    page: { path: location.pathname, title: document.title },
+  });
+} catch (err) {
+  if (err instanceof WebchatVisitorError) {
+    console.warn(err.code, err.status, err.field, err.message);
+  }
+}
 
-```typescript
-const { data: lead } = await ecod.crm.leads.retrieve("lead_id");
-const { data } = await ecod.crm.leads.retrieveByPhone("+919876543210");
-const { data } = await ecod.crm.leads.retrieveByRef("orderId", "ORD-123");
+await chat.contact({ name: "Ravi", phone: "98765 43210" });
 ```
 
-**Update**
+Live replies and typing (`/visitor` socket):
 
-```typescript
-await ecod.crm.leads.update("lead_id", { email: "new@email.com" });
-await ecod.crm.leads.updateMetadata("lead_id", {
-  refs: { orderId: "ORD-456" },
-  extra: { plan: "pro" },
+```ts
+chat.connect({
+  onMessage: (message) => upsert(message), // `from`: visitor | ai | team | system
+  onTyping: ({ on, waiting }) => showTyping(on, waiting), // waiting: the team will reply
+  onError: () => startPolling(), // live is down: poll messages()
+  onReconnect: () => {
+    stopPolling();
+    chat.messages().then(redraw); // nothing missed is replayed
+  },
 });
-```
-
-**Move & Convert**
-
-```typescript
-await ecod.crm.leads.move("lead_id", "target_stage_id");
-await ecod.crm.leads.convert("lead_id", "won", "Signed contract");
-```
 
-**Tags**
-
-```typescript
-await ecod.crm.leads.tags("lead_id", { add: ["vip", "hot"], remove: ["cold"] });
+chat.disconnect();
 ```
 
-**Score**
+| `err.code`           | Meaning                                                           |
+| -------------------- | ----------------------------------------------------------------- |
+| `VALIDATION_ERROR`   | Bad input. `err.field` names it, `err.message` is visitor copy    |
+| `ORIGIN_NOT_ALLOWED` | The site isn't on the workspace's allowed domains                 |
+| `NOT_FOUND`          | Unknown client code                                               |
+| `RATE_LIMITED`       | Too many messages or connects. Wait a minute                      |
+| `MALICIOUS_INPUT`    | The text was refused as a script or injection                     |
+| `INTERNAL_ERROR`     | Server error. Try again                                           |
+| `NETWORK_ERROR`      | No answer (offline, 30 s timeout). Try again                      |
 
-```typescript
-await ecod.crm.leads.recalculateScore("lead_id");
-```
+The live socket only accepts the ERIX widget frame's origin. A chat UI on your
+own page works over HTTP when that site is the workspace's website (browser
+CORS), and polls `messages()` for replies.
 
-**Bulk**
+## Scoped keys
 
-```typescript
-await ecod.crm.leads.import(leadArray); // Bulk import
-await ecod.crm.leads.delete("lead_id");
-await ecod.crm.leads.bulkDelete(["id_1", "id_2"]);
-```
+For an integration that does one job (a booking form that fires a Flow event,
+say), create a scoped key under **Settings → Developer → Scoped API keys**.
+Scoped keys can be revoked, can expire and have usage tracking. Each one
+carries a single grant:
 
----
-
-#### `ecod.crm.pipelines`
-
-```typescript
-// CRUD
-const { data } = await ecod.crm.pipelines.list();
-await ecod.crm.pipelines.create({ name: "Sales", isDefault: true });
-await ecod.crm.pipelines.retrieve("pipeline_id");
-await ecod.crm.pipelines.update("pipeline_id", { name: "Deals" });
-await ecod.crm.pipelines.delete("pipeline_id");
-
-// Advanced
-await ecod.crm.pipelines.setDefault("pipeline_id");
-await ecod.crm.pipelines.duplicate("pipeline_id", "Sales Copy");
-await ecod.crm.pipelines.archive("pipeline_id");
-const { data: board } = await ecod.crm.pipelines.board("pipeline_id");
-const { data: forecast } = await ecod.crm.pipelines.forecast("pipeline_id");
-
-// Stage management
-await ecod.crm.pipelines.addStage("pipeline_id", {
-  name: "Negotiation",
-  color: "#f59e0b",
-});
-await ecod.crm.pipelines.reorderStages("pipeline_id", [
-  "stage_1",
-  "stage_3",
-  "stage_2",
-]);
-await ecod.crm.pipelines.updateStage("stage_id", { probability: 80 });
-await ecod.crm.pipelines.deleteStage("stage_id", "fallback_stage_id");
-```
+| Purpose          | Grant              | Works for                                     |
+| ---------------- | ------------------ | --------------------------------------------- |
+| Trigger events   | `flow:events`      | `product.erix.events.trigger()`               |
+| Send WhatsApp    | `connect:whatsapp` | `chat.messages.send({ to })`, `sendTemplate()`|
+| Send email       | `connect:email`    | `POST /infra/connect/send/email`              |
+| Send Telegram    | `connect:telegram` | `POST /infra/connect/send/telegram`           |
 
----
+Keys look like `erix_<scope>_<secret>`. Pass one as `apiKey`. The server
+enforces its grant, so any call outside the grant fails with
+`AuthenticationError` (HTTP 403). Over plain HTTP you can also send it as
+`Authorization: Bearer erix_<scope>_…`.
 
-#### `ecod.crm.automations`
+```ts
+import { ECODrIxAPI } from "@ecodrix/erix-api";
 
-```typescript
-// CRUD
-const { data } = await ecod.crm.automations.list();
-await ecod.crm.automations.create({
-  name: "Follow-up",
-  trigger: "lead_created",
-  nodes: [],
-  edges: [],
+const events = new ECODrIxAPI({
+  apiKey: process.env.ECOD_EVENTS_KEY!, // erix_flow_… with flow:events
+  clientCode: "ERIX_CLNT_XXXXXX",
 });
-await ecod.crm.automations.update("rule_id", { isActive: false });
-await ecod.crm.automations.toggle("rule_id");
-await ecod.crm.automations.deleteRule("rule_id");
-await ecod.crm.automations.bulkDelete(["rule_1", "rule_2"]);
-
-// Testing & events
-await ecod.crm.automations.test("rule_id", "lead_id");
-const { data: events } = await ecod.crm.automations.getAvailableEvents();
-
-// Enrollment management
-const { data } = await ecod.crm.automations.enrollments("rule_id", {
-  status: "active",
-  page: 1,
-});
-await ecod.crm.automations.getEnrollment("enrollment_id");
-await ecod.crm.automations.pauseEnrollment("rule_id", "enrollment_id");
-await ecod.crm.automations.resumeEnrollment("rule_id", "enrollment_id");
-
-// Run inspection
-const { data: runs } = await ecod.crm.automations.runs("rule_id");
-await ecod.crm.automations.getRun("run_id");
-await ecod.crm.automations.resumeRun("run_id");
-await ecod.crm.automations.abortRun("run_id");
-
-// Unlock a wait_event node from external tool (e.g. Zapier, payment gateway callback)
-await ecod.crm.automations.webhookEvent("rule_id", "payment_received", {
-  amount: 1500,
-  currency: "INR",
-});
-```
-
----
-
-#### `ecod.crm.sequences`
-
-Manually enroll / unenroll leads in drip automation sequences.
 
-```typescript
-await ecod.crm.sequences.enroll({
-  leadId: "lead_id",
-  ruleId: "rule_id",
-  variables: { discount: "20%" },
-});
-await ecod.crm.sequences.unenroll("enrollment_id");
-const { data } = await ecod.crm.sequences.listForLead("lead_id");
+await events.product.erix.events.trigger({ trigger: "booking_created", phone: "+91XXXXXXXXXX" });
 ```
 
----
-
-#### `ecod.crm.activities`
-
-```typescript
-// Lead timeline (all CRM events in order)
-const { data } = await ecod.crm.activities.timeline("lead_id", {
-  page: 1,
-  limit: 50,
-});
-
-// Filtered activity list
-const { data } = await ecod.crm.activities.list("lead_id", { type: "call" });
+## CRM: leads and pipelines
 
-// Log a call outcome
-await ecod.crm.activities.logCall("lead_id", {
-  outcome: "answered",
-  duration: 120,
-  notes: "Interested in Pro plan",
+```ts
+// Create or update by phone. `refs` are your own IDs, kept on the lead.
+await ecod.product.erix.leads.upsert({
+  leadData: { phone: "+91XXXXXXXXXX", firstName: "Test", source: "website" },
+  refs: { orderId: "ORD-1042" },
 });
 
-// Log a generic activity
-await ecod.crm.activities.log({
-  leadId: "lead_id",
-  type: "email_opened",
-  title: "Campaign Email Opened",
-});
-
-// --- Notes ---
-const { data: notes } = await ecod.crm.activities.notes.list("lead_id");
-await ecod.crm.activities.notes.create("lead_id", {
-  content: "Call scheduled for Monday",
+const { data: leads, pagination } = await ecod.product.erix.leads.list({
+  status: "open", // open | won | lost | archived
+  search: "test",
+  limit: 25,
 });
-await ecod.crm.activities.notes.update("note_id", "Updated note text");
-await ecod.crm.activities.notes.pin("note_id"); // pin to top
-await ecod.crm.activities.notes.pin("note_id", false); // unpin
-```
 
----
-
-#### `ecod.crm.analytics`
-
-```typescript
-const { data: overview } = await ecod.crm.analytics.overview("pipeline_id");
-const { data: conversion } =
-  await ecod.crm.analytics.conversionRate("pipeline_id");
-const { data: velocity } = await ecod.crm.analytics.dealVelocity("pipeline_id");
-const { data: stageTime } = await ecod.crm.analytics.stageTime("pipeline_id");
+await ecod.product.erix.leads.move("LEAD_ID", "STAGE_ID"); // pipeline column
+await ecod.product.erix.leads.setFollowUp("LEAD_ID", "2026-10-20T15:00:00+05:30", "Share the quote");
+await ecod.product.erix.leads.tags("LEAD_ID", { add: ["hot"], remove: ["cold"] });
+await ecod.product.erix.leads.convert("LEAD_ID", "won", "Advance received");
+await ecod.product.erix.leads.delete("LEAD_ID"); // archives; history stays
 ```
 
----
-
-#### `ecod.crm.scoring`
+Other lookups: `retrieve(id)`, `retrieveByPhone(phone)`,
+`retrieveByRef(key, value)`, `update(id, patch)`, `notes(id)`,
+`createNote(id, { content })`, `activities(id)`, `profile(id)`,
+`import(leads)` and `merge(primaryId, secondaryId)`.
 
-```typescript
-const { data } = await ecod.crm.scoring.getConfig();
-await ecod.crm.scoring.updateConfig({ rules: [...] });
-```
-
----
+Data protection (DPDP). Only owners and admins can do this:
 
-#### `ecod.crm.payments`
+```ts
+const { data: everything } = await ecod.product.erix.leads.export("LEAD_ID"); // (3.2.0)
 
-```typescript
-const { data } = await ecod.crm.payments.list("lead_id");
+// Irreversible. Wipes personal data across CRM, inbox and automations.
+// Invoices are kept for GST records.
+const { data: result } = await ecod.product.erix.leads.erase("LEAD_ID"); // (3.2.0)
+console.log(result.invoicesKept);
 ```
 
----
-
-#### `ecod.crm.automationDashboard`
+Pipelines:
 
-```typescript
-const { data: stats } = await ecod.crm.automationDashboard.stats();
-const { data: logs } = await ecod.crm.automationDashboard.logs({
-  limit: 10,
-  status: "failed",
+```ts
+const { data: pipeline } = await ecod.product.erix.pipelines.create({
+  name: "Admissions",
+  stages: ["Enquiry", "Visit booked", "Fee paid", "Admitted"],
 });
-await ecod.crm.automationDashboard.retryFailedEvent("log_id");
-```
-
----
-
-### Events & Workflows
 
-Access via `ecod.events`. Connect your external applications to the CRM automation engine.
+const { data: pipelines } = await ecod.product.erix.pipelines.list();
+const { data: board } = await ecod.product.erix.pipelines.board("PIPELINE_ID");
 
-**List all available triggers**
-
-```typescript
-const { data: triggers } = await ecod.events.list();
+await ecod.product.erix.pipelines.addStage("PIPELINE_ID", { name: "Follow-up", color: "#f59e0b" });
+// Moves the stage's leads to another stage of the same pipeline, then deletes it.
+await ecod.product.erix.pipelines.deleteStage("STAGE_ID", "TARGET_STAGE_ID");
 ```
 
-**Register a custom event**
-
-```typescript
-await ecod.events.assign({
-  name: "cart_abandoned",
-  displayName: "Shopping Cart Abandoned",
-  pipelineId: "pipeline_123",
-});
-
-// Deactivate
-await ecod.events.unassign("cart_abandoned");
-await ecod.events.unassignBulk(["event_a", "event_b"]);
-```
+## Flow: events and custom triggers
 
-**Fire an event / trigger workflows**
+`events.trigger()` fires an event. Every active flow with a matching trigger
+starts a run for that contact. You need `phone` or `email`.
 
-```typescript
-await ecod.events.trigger({
-  trigger: "cart_abandoned",
-  phone: "+919876543210",
-  variables: { items: "T-Shirt, Mug", total: "₹850" },
+```ts
+const res = await ecod.product.erix.events.trigger({
+  trigger: "appointment_booked",
+  phone: "+91XXXXXXXXXX",
+  variables: { slot: "Mon 11:00", branch: "Indore" },
   createLeadIfMissing: true,
-  delayMinutes: 30,
-  // Optional: auto-book a Google Meet during the workflow
-  requiresMeet: true,
-  meetConfig: {
-    summary: "Follow-up call",
-    duration: 30,
-    timezone: "Asia/Kolkata",
-  },
+  leadData: { firstName: "Test", source: "website" },
+  delayMinutes: 30, // or delaySeconds, or runAt (ISO with offset). Use one.
+  idempotencyKey: "booking-8812", // a retry with the same key won't start flows twice
 });
+console.log(res.data?.idempotencyKey, res.data?.leadId);
 ```
 
-**Custom event definitions (CRM-managed)**
-
-```typescript
-const { data } = await ecod.events.listCustomEvents();
-await ecod.events.createCustomEvent({
-  name: "webinar_attended",
-  displayName: "Webinar Attended",
-});
-await ecod.events.deleteCustomEvent("event_id");
-await ecod.events.emit({ eventName: "webinar_attended", leadId: "lead_id" });
-```
-
----
-
-### Marketing
-
-Access via `ecod.marketing`.
+`createLeadIfMissing`, the delays and `runAt` are released per workspace.
+Without the release the server ignores them and says so in the response.
 
-**Email campaigns**
+Define your own triggers so flows can start on them:
 
-```typescript
-await ecod.marketing.emails.sendCampaign({
-  recipients: ["user@example.com"],
-  subject: "Summer Sale!",
-  html: "<h1>Get 20% off!</h1>",
+```ts
+await ecod.product.erix.events.createCustomEvent({
+  name: "appointment_confirm", // lowercase letters, digits, _ . -
+  displayName: "Appointment confirmed",
 });
-await ecod.marketing.emails.sendTest("dev@example.com");
-```
-
-**Campaigns (Email + SMS)**
 
-```typescript
-await ecod.marketing.campaigns.create({ name: "Q2 Push", type: "email" });
-await ecod.marketing.campaigns.list({ status: "active" });
-await ecod.marketing.campaigns.retrieve("campaign_id");
-await ecod.marketing.campaigns.update("campaign_id", {
-  subject: "New subject",
-});
-await ecod.marketing.campaigns.send("campaign_id", {
-  scheduledAt: "2026-05-01T09:00:00Z",
-});
-await ecod.marketing.campaigns.stats("campaign_id");
-await ecod.marketing.campaigns.delete("campaign_id");
+const { data } = await ecod.product.erix.events.listCustomEvents(); // data.triggers
+await ecod.product.erix.events.deleteCustomEvent("TRIGGER_ID");
 ```
 
-**WhatsApp marketing (CRM-integrated template dispatch)**
-
-Unlike the direct `ecod.whatsapp.sendTemplate`, this endpoint resolves CRM field variables automatically.
+Some runs stop at an approval step and wait for a person. You can list those
+and decide on them:
 
-```typescript
-await ecod.marketing.whatsapp.sendTemplate({
-  phone: "+919876543210",
-  templateName: "seasonal_offer",
-  variables: { discount: "40%" },
-});
+```ts
+const { data } = await ecod.product.erix.ai.approvals(); // { drafts, runs }
+for (const run of data.runs) {
+  // Pass run.nodeId (3.2.0) so a stale view can't decide a different step.
+  await ecod.product.erix.ai.decideRun(run.id, "approve", run.nodeId);
+}
 ```
 
----
-
-### Meetings
+## Channels: inbox and direct send
 
-Access via `ecod.meet`. Backed by **Google Meet**.
+All channels share one inbox. Any thread can be answered with
+`chat.messages.send({ conversationId })`.
 
-```typescript
-const { data: meeting } = await ecod.meet.create({
-  leadId: "lead_id",
-  participantName: "Priya Sharma",
-  participantPhone: "+919876543210",
-  startTime: "2026-04-10T10:00:00.000Z",
-  endTime: "2026-04-10T10:30:00.000Z",
+```ts
+const { data: threads } = await ecod.product.erix.chat.conversations.list({
+  channel: "whatsapp",
+  limit: 20,
 });
-console.log(meeting.meetLink); // → https://meet.google.com/abc-defg-hij
-
-const { data: meetings } = await ecod.meet.list({ status: "scheduled" });
-const { data } = await ecod.meet.retrieve("meeting_id");
-await ecod.meet.update("meeting_id", { startTime: "2026-04-11T11:00:00.000Z" });
-await ecod.meet.delete("meeting_id");
-```
-
----
 
-### Storage
-
-Access via `ecod.storage`. Powered by **Cloudflare R2**.
-
-This handles the full presigned-URL orchestration transparently:
-
-1. Requests a presigned PUT URL from the backend.
-2. Uploads directly to R2 (no proxy overhead).
-3. Confirms the upload.
-
-```typescript
-// Node.js: from a Buffer
-import { readFileSync } from "fs";
+const { data: messages, hasMore } = await ecod.product.erix.chat.conversations.messages(
+  "CONVERSATION_ID",
+  { limit: 50 }, // page back with { before: oldestMessage.createdAt }
+);
 
-const fileBuffer = readFileSync("./contract.pdf");
-const { data } = await ecod.storage.upload(fileBuffer, {
-  folder: "customer_documents",
-  filename: "contract.pdf",
-  contentType: "application/pdf",
+await ecod.product.erix.chat.messages.send({
+  conversationId: "CONVERSATION_ID",
+  text: "Your order is packed and ships today.",
 });
-console.log(data.url); // → https://cdn.ecodrix.com/customer_documents/contract.pdf
-
-// Browser: from an <input> element
-const file = document.getElementById("file-input").files[0];
-const { data } = await ecod.storage.upload(file, {
-  folder: "avatars",
-  filename: file.name,
-  contentType: file.type,
+await ecod.product.erix.chat.conversations.markRead("CONVERSATION_ID");
+
+// Open (or find) a thread for a number and link it to a lead.
+const { data: thread } = await ecod.product.erix.chat.conversations.create({
+  phone: "+91XXXXXXXXXX",
+  channel: "whatsapp",
 });
+await ecod.product.erix.chat.conversations.linkLead(thread.id, "LEAD_ID");
 ```
 
----
-
-### Media
-
-Access via `ecod.media`. Manage files stored in R2.
-
-```typescript
-// Get a presigned download URL for a private file
-const { data } = await ecod.media.getDownloadUrl("confidential/contract.pdf");
-
-// Monitor storage quota
-const { data: usage } = await ecod.media.getUsage();
-console.log(`${usage.usedMB} MB of ${usage.limitMB} MB used`);
+Send a file. Upload it to your storage first, then attach it:
 
-// List files in a folder
-await ecod.media.list({ folder: "invoices" });
+```ts
+const input = document.querySelector<HTMLInputElement>("#attachment")!;
+const media = await ecod.product.erix.chat.messages.upload(input.files![0]);
 
-// Delete a file
-await ecod.media.delete("invoices/old_invoice.pdf");
+await ecod.product.erix.chat.messages.send({
+  conversationId: "CONVERSATION_ID",
+  media,
+  text: "Invoice attached",
+});
 ```
 
----
-
-### Email
+Direct WhatsApp send, without an inbox thread ID:
 
-Access via `ecod.email`. Backed by SMTP or AWS SES depending on tenant configuration.
-
-```typescript
-await ecod.email.sendEmailCampaign({
-  subject: "Summer Discount!",
-  recipients: ["user@example.com"],
-  html: "<h1>Get 20% off all plans!</h1>",
+```ts
+// An approved template. Use this to start a conversation.
+await ecod.product.erix.chat.messages.sendTemplate({
+  to: "+91XXXXXXXXXX",
+  templateName: "order_update",
+  language: "en",
+  variables: ["ORD-1042", "₹1,499"],
 });
 
-// Verify SMTP configuration
-await ecod.email.sendTestEmail("admin@example.com");
+// Free text. Only works inside WhatsApp's 24-hour customer service window.
+await ecod.product.erix.chat.messages.send({ to: "+91XXXXXXXXXX", text: "Thanks, we got your enquiry." });
 ```
 
----
+Manage templates with `ecod.infra.connect.whatsapp.templates`: `list()`,
+`sync()` and `retrieve(name)`.
 
-### Notifications & Logs
+## Invoices and payment links
 
-Access via `ecod.notifications`.
+Amounts are in rupees. This invoice comes to ₹25,000 + 18% GST = ₹29,500:
 
-```typescript
-// Automation execution logs
-const { data: logs } = await ecod.notifications.listLogs({
-  trigger: "lead_created",
-  status: "failed",
-  startDate: "2026-04-01",
-  endDate: "2026-04-30",
+```ts
+const { data: invoice } = await ecod.product.erix.invoices.create({
+  clientName: "Test Customer",
+  clientPhone: "+91XXXXXXXXXX",
+  leadId: "LEAD_ID",
+  items: [{ description: "Website design", quantity: 1, rate: 25000, hsnSac: "998314" }],
+  taxRate: 18,
+  dueDate: "2026-11-15",
 });
 
-await ecod.notifications.retrieveLog("log_id");
-
-// Aggregate stats
-const { data: stats } = await ecod.notifications.getStats({
-  startDate: "2026-04-01",
-  endDate: "2026-04-30",
-});
+// A link on your connected gateway (Razorpay or Stripe). Calling again returns the same link.
+const { data: link } = await ecod.product.erix.invoices.paymentLink(invoice.id); // (3.2.0)
+console.log(link.paymentLinkUrl);
 
-// Provider webhook callback logs
-const { data } = await ecod.notifications.listCallbacks({ limit: 20 });
+await ecod.product.erix.invoices.sendWhatsApp(invoice.id); // (3.2.0) with the payment link
+await ecod.product.erix.invoices.sendEmail(invoice.id); // (3.2.0) PDF + payment link
 ```
 
----
+Invoices can't be deleted, only voided (`invoices.void(id)`), so GST records
+stay intact. Other calls: `list({ status })`, `getInvoice(id)` and
+`update(id, patch)`. Accounting exports live under
+`product.erix.invoiceExport`: `csv()`, `tally()` and `zoho()`.
 
-### Queue Management
+A one-off payment link that isn't tied to an invoice, or a payment you took
+offline:
 
-Access via `ecod.queue`. Inspect and manage background automation jobs.
-
-```typescript
-// View failed jobs
-const { data: failed } = await ecod.queue.listFailed();
-
-// Get queue health by status
-const stats = await ecod.queue.getStats();
-// stats → { waiting: 12, active: 3, completed: 482, failed: 7, delayed: 0 }
-
-// Retry a failed job
-await ecod.queue.retryJob("job_id");
+```ts
+await ecod.infra.connect.connections.createPaymentLink({
+  amount: 1499, // ₹1,499
+  description: "Consultation fee",
+  customer: { phone: "+91XXXXXXXXXX" },
+});
 
-// Remove a job permanently
-await ecod.queue.deleteJob("job_id");
+// Cash, UPI or bank transfer. With orderId, a retry is counted once.
+await ecod.product.erix.payments.capture({ leadId: "LEAD_ID", amount: 5000, orderId: "UPI-2026-0042" });
 ```
 
----
-
-### Health & Diagnostics
+## Storage uploads
 
-Access via `ecod.health`.
+`media.upload()` gets a presigned URL, uploads straight to storage and then
+confirms the upload, all in one call. The file bytes never pass through the
+API, and your key never goes to the storage host.
 
-```typescript
-// Global platform status
-const health = await ecod.health.system();
-// { status: "ok", version: "...", env: "production", uptime: 3600, db: "connected", queueDepth: 5 }
+```ts
+import { readFile } from "node:fs/promises";
 
-// Tenant-scoped service readiness
-const clientHealth = await ecod.health.clientHealth();
-// { clientCode: "...", services: { whatsapp: "connected", email: "configured", googleMeet: "configured" }, ... }
+const buffer = await readFile("./brochure.pdf");
+const { data: file } = await ecod.infra.storage.media.upload(buffer, {
+  folder: "documents",
+  filename: "brochure.pdf",
+  contentType: "application/pdf",
+});
 
-// Background job status lookup
-const job = await ecod.health.jobStatus("job_id");
+const { data: download } = await ecod.infra.storage.files.getDownloadUrl<{
+  data: { downloadUrl: string };
+}>(file.key);
+console.log(download.downloadUrl); // short-lived URL
 ```
 
----
-
-### Webhooks
-
-Access via `ecod.webhooks`.
+The same call takes a browser `File`. Other calls: `files.list(folder)` and
+`files.delete(key)`.
 
-> ⚠️ **Node.js only** — Requires `node:crypto`. Not available in browser bundles.
+## Realtime events
 
----
+Events stream over a socket that's scoped to your workspace. You only receive
+your own workspace's events.
 
-## Enterprise Capabilities
+```ts
+import type { Message } from "@ecodrix/erix-api";
 
-### Auto-Paginating Iterators
+const onMessage = ({ conversationId, message }: { conversationId: string; message: Message }) => {
+  console.log(conversationId, message.direction, message.text);
+};
 
-Stream all records without manual page management:
+ecod
+  .on("inbox.message", onMessage)
+  .on("message_status_update", ({ messageId, status }) => console.log(messageId, status))
+  .on("resync", () => {
+    // Reconnected after a gap too large to replay. Refetch your data.
+  });
 
-```typescript
-// With optional type parameter for full type safety
-for await (const lead of ecod.crm.leads.listAutoPaging<Lead>({
-  status: "won",
-})) {
-  await syncToMyDatabase(lead);
+// Later, e.g. in a React effect cleanup:
+ecod.off("inbox.message", onMessage);
+```
+
+| Event                                         | Payload / meaning                                                       |
+| --------------------------------------------- | ----------------------------------------------------------------------- |
+| `inbox.message`                               | `{ conversationId, message }`. Every stored message: any channel, inbound or outbound |
+| `message_status_update`                       | `{ messageId, conversationId, status }`. Sent, delivered, read or failed |
+| `ai_suggestion` / `ai_handoff`                | An AI draft is waiting / the AI handed a chat to a person               |
+| `workflow-run-update`                         | Flow run progress                                                       |
+| `platform:notification`                       | A new in-app notification                                               |
+| `knowledge.source_updated`                    | A knowledge base source changed status                                  |
+| `resync`                                      | Missed events couldn't be replayed. Refetch                             |
+
+Each event's last argument is `{ seq }`. After a reconnect the SDK sends back
+the last `seq` it saw and the server replays what was missed. A replay can
+repeat an event, so write handlers that are safe to run twice (upsert by ID).
+
+## Webhook signature verification
+
+Flow's webhook step sends JSON to your URL. If you set a secret on the
+Webhook connection, the request is signed with it in
+`x-ecodrix-signature: sha256=<hex>`. Verify the signature against the **raw**
+body, before you parse it. Node only.
+
+```ts
+import { APIError } from "@ecodrix/erix-api";
+import { ecod } from "./ecodrix"; // your server-side client from Quick start
+
+export async function POST(req: Request) {
+  const raw = await req.text();
+  try {
+    const event = await ecod.webhooks.constructEvent(
+      raw,
+      req.headers.get("x-ecodrix-signature") ?? undefined,
+      process.env.ECOD_WEBHOOK_SECRET!,
+    );
+    console.log("verified", event);
+    return Response.json({ received: true });
+  } catch (err) {
+    // WebhookSignatureError: APIError with code "invalid_signature"
+    const message = err instanceof APIError ? err.message : "Bad request";
+    return new Response(message, { status: 400 });
+  }
 }
 ```
 
-### Bulk Data Chunking
+## Raw requests
 
-Insert thousands of leads without hitting rate limits. `createMany` automatically chunks and concurrently streams batches:
+Use `ecod.request()` for an endpoint that has no typed method yet. You still
+get auth, retries and the timeout. Paths are relative to `/v1/api`:
 
-```typescript
-const results = await ecod.crm.leads.createMany(massiveArrayOfLeads, 100);
-console.log(`Ingested ${results.length} leads.`);
-```
-
-### Idempotency Keys
-
-Prevent duplicate requests caused by automatic retries:
-
-```typescript
-await ecod.email.sendEmailCampaign(
-  { subject: "Promo", recipients: ["user@example.com"], html: "..." },
-  { idempotencyKey: "promo_campaign_uuid_2026_q2" },
-);
-```
-
-### Webhook Signature Verification
-
-Cryptographically verify that webhook payloads originated from ECODrIx:
-
-```typescript
-app.post(
-  "/api/webhooks",
-  express.raw({ type: "application/json" }),
-  async (req, res) => {
-    try {
-      const event = await ecod.webhooks.constructEvent(
-        req.body.toString(),
-        req.headers["x-ecodrix-signature"],
-        "whsec_your_webhook_secret",
-      );
-      console.log("Verified event:", event);
-      res.json({ received: true });
-    } catch (err) {
-      return res.status(400).send(`Invalid signature: ${err.message}`);
-    }
-  },
-);
-```
-
-### Raw Execution Engine
-
-Access any API endpoint — including experimental or custom ones — with full authentication and retry benefits:
-
-```typescript
-const { data } = await ecod.request("POST", "/api/saas/beta-feature", {
-  experimentalFlag: true,
+```ts
+await ecod.request("POST", "/infra/connect/send/email", {
+  to: "customer@example.com",
+  subject: "Your booking is confirmed",
+  html: "<p>See you on Monday at 11:00.</p>",
 });
 ```
 
----
-
-## Real-time Events
+## Errors
 
-The SDK maintains a persistent Socket.io connection, scoped to your `clientCode` tenant. Use `ecod.on()` to subscribe:
+Failed calls throw. The API answers with an envelope like
+`{ success: false, error, message, code? }`, and the SDK turns it into one of
+these classes:
 
-```typescript
-ecod
-  .on("whatsapp.message_received", (msg) => {
-    console.log(`New message from ${msg.from}: ${msg.body}`);
-  })
-  .on("crm.lead_created", ({ leadId }) => {
-    console.log(`New lead: ${leadId}`);
-  })
-  .on("crm.lead_updated", ({ leadId, stageName }) => {
-    console.log(`${leadId} moved to ${stageName}`);
-  })
-  .on("meet.scheduled", ({ meetLink }) => {
-    console.log(`Meeting booked: ${meetLink}`);
-  })
-  .on("automation.failed", ({ trigger, reason }) => {
-    alertTeam(`Automation ${trigger} failed: ${reason}`);
-  });
+| Class                 | When                                                                 |
+| --------------------- | -------------------------------------------------------------------- |
+| `EcodrixError`        | Base class of everything below                                       |
+| `APIError`            | Any other failure. Has `.status`, `.code` (when sent) and `.message` |
+| `AuthenticationError` | HTTP 401 or 403: bad key or client code, missing scope, or a role that isn't allowed |
+| `RateLimitError`      | HTTP 429, after the SDK's own retries run out                       |
 
-// Graceful shutdown
-process.on("SIGTERM", () => ecod.disconnect());
-```
-
-### Standard Event Reference
-
-| Event                       | Payload                          | Description                    |
-| --------------------------- | -------------------------------- | ------------------------------ |
-| `whatsapp.message_received` | `{ from, body, conversationId }` | Inbound WhatsApp message       |
-| `whatsapp.message_sent`     | `{ to, messageId }`              | Outbound message delivered     |
-| `crm.lead_created`          | `{ leadId, phone }`              | New CRM lead created           |
-| `crm.lead_updated`          | `{ leadId, stageName }`          | Lead stage or fields updated   |
-| `meet.scheduled`            | `{ meetingId, meetLink }`        | Google Meet appointment booked |
-| `storage.upload_confirmed`  | `{ key, url, sizeBytes }`        | File upload confirmed          |
-| `automation.failed`         | `{ trigger, reason, leadId }`    | Automation execution failed    |
-
----
-
-## Error Handling
-
-All methods throw typed errors you can catch and inspect:
-
-```typescript
-import {
-  APIError,
-  AuthenticationError,
-  RateLimitError,
-  Ecodrix,
-} from "@ecodrix/erix-api";
+```ts
+import { APIError, AuthenticationError, RateLimitError } from "@ecodrix/erix-api";
 
 try {
-  const { data } = await ecod.crm.leads.retrieve("non_existent_id");
+  await ecod.product.erix.leads.retrieve("LEAD_ID");
 } catch (err) {
   if (err instanceof AuthenticationError) {
-    // 401 — invalid API key or client code
-    console.error("Check your credentials.");
+    console.error("Check the key, client code, scope or role:", err.message);
   } else if (err instanceof RateLimitError) {
-    // 429 — too many requests (SDK auto-retries up to 3×)
-    console.warn("Rate limit hit.");
+    console.warn("Rate limited, back off and retry later");
   } else if (err instanceof APIError) {
-    console.error(`API Error [${err.status}]: ${err.message}`);
+    console.error(`API error ${err.status ?? "network"}: ${err.message}`, err.code);
   } else {
     throw err;
   }
 }
 ```
 
-### Error Classes
+`ecod.request()` throws a plain `APIError` for every status.
 
-| Class                 | HTTP Status | Description                                  |
-| --------------------- | ----------- | -------------------------------------------- |
-| `EcodrixError`        | —           | Base error class                             |
-| `APIError`            | varies      | Generic API error with `.status` and `.code` |
-| `AuthenticationError` | 401         | Invalid API key or client code               |
-| `RateLimitError`      | 429         | Too many requests                            |
+**Retries and timeouts.** The SDK retries up to 3 times with exponential
+backoff. It retries network errors (any method), 5xx responses on idempotent
+methods (GET, PUT, DELETE) and 429 responses. Each request times out after
+30 s; change that with the `timeout` option. A timed-out request isn't retried.
+A network error can also hit a POST whose response was lost, and the retry
+then sends it a second time. Pass your own reference where a method takes one
+(`refs`, `orderId`) so a duplicate is safe.
 
----
+## TypeScript
 
-## Browser / CDN Usage
+Methods return the response body, so pass a type argument to get it typed.
+The SDK exports the main entity and parameter types (`Lead`,
+`CreateLeadParams`, `ListLeadsParams`, `Pipeline`, `PipelineStage`,
+`Conversation`, `Message`, `SendMessageParams`, `PausedRun`, `AiSuggestion`,
+`KnowledgeSource`, `PaginatedResponse` and more).
 
-For usage without a bundler:
+```ts
+import type { Lead, PaginatedResponse } from "@ecodrix/erix-api";
 
-```html
-<!-- Via CDN (jsDelivr) -->
-<script src="https://cdn.jsdelivr.net/npm/@ecodrix/erix-api/dist/ts/browser/index.global.js"></script>
-<script>
-  const ecod = new Ecodrix.Ecodrix({
-    apiKey: "your_api_key",
-    clientCode: "YOUR_CLIENT_CODE",
-  });
+const page = await ecod.product.erix.leads.list<PaginatedResponse<Lead>>({ limit: 50 });
+console.log(page.pagination.total, page.data[0]?.firstName);
 
-  ecod.whatsapp.messages.send({
-    to: "+919876543210",
-    text: "Hello from the browser!",
-  });
-</script>
+// Page through every lead without handling pages yourself.
+for await (const lead of ecod.product.erix.leads.listAutoPaging<Lead>({ status: "open" })) {
+  console.log(lead.phone);
+}
 ```
 
-> ⚠️ **Note**: `ecod.webhooks.constructEvent` and `ecod.storage.upload` (from `Buffer`) are Node.js only and will not function in browser environments.
-
----
-
-## Contributing
+## Versioning
 
-1. Fork the repository.
-2. Create a feature branch: `git checkout -b feat/my-feature`
-3. Make changes, then run `pnpm check` to validate formatting and lint.
-4. Run `pnpm build` to verify the output compiles cleanly.
-5. Submit a Pull Request.
+- The SDK follows [semver](https://semver.org) on its own line (3.x). Breaking
+  changes only land in a major release. See [CHANGELOG.md](CHANGELOG.md).
+- The API server has its own version numbers: platform v1.0 is server 1.0.0.
+  The SDK calls the `/v1` routes, and the `version` option chooses the route
+  version.
+- A method marked **(3.2.0)** needs SDK 3.2.0 or later.
 
----
+Guides: https://api.ecodrix.com/docs. Endpoint reference:
+https://api.ecodrix.com/reference.
 
 ## License
 
-[MIT](LICENSE) © 2026 [ECODrIx Team](https://ecodrix.com)
+[MIT](LICENSE)