@ecodrix/erix-api 1.0.4 → 1.0.6

package/README.md

@@ -6,10 +6,11 @@
 [![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, file storage, and Google Meet appointments — all from a single, type-safe library.
+Manage WhatsApp conversations, CRM leads, pipelines, automations, marketing campaigns, file storage, and Google Meet — all from a single, type-safe library.
 
 </div>
 
@@ -22,12 +23,30 @@ Manage WhatsApp conversations, CRM leads, file storage, and Google Meet appointm
 - [Configuration](#configuration)
 - [Resources](#resources)
   - [WhatsApp](#whatsapp)
-  - [CRM — Leads](#crm--leads)
+    - [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)
-  - [Media (Storage)](#media-storage)
+  - [Storage](#storage)
+  - [Media](#media)
   - [Email](#email)
-  - [Events & Workflows](#events--workflows)
   - [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)
@@ -48,9 +67,6 @@ pnpm add @ecodrix/erix-api
 
 # npm
 npm install @ecodrix/erix-api
-
-# yarn
-yarn add @ecodrix/erix-api
 ```
 
 > **Requires**: Node.js >= 18
@@ -63,8 +79,8 @@ yarn add @ecodrix/erix-api
 import { Ecodrix } from "@ecodrix/erix-api";
 
 const ecod = new Ecodrix({
-  apiKey: "your_api_key",
-  clientCode: "YOUR_CLIENT_CODE", // Your tenant ID
+  apiKey: process.env.ECOD_API_KEY!,
+  clientCode: process.env.ECOD_CLIENT_CODE,
 });
 
 // Send a WhatsApp message
@@ -75,12 +91,17 @@ await ecod.whatsapp.messages.send({
 
 // Create a CRM lead
 const lead = await ecod.crm.leads.create({
-  firstName: "Jhon",
+  firstName: "Priya",
   phone: "+919876543210",
   source: "website",
 });
 
-console.log(lead.data.id);
+// Fire an automation trigger
+await ecod.events.trigger({
+  trigger: "trial_started",
+  phone: "+919876543210",
+  createLeadIfMissing: true,
+});
 ```
 
 ---
@@ -92,7 +113,7 @@ 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)           |
+| `clientCode` | `string` | Recommended | —                         | Your tenant ID — scopes all requests           |
 | `baseUrl`    | `string` | No          | `https://api.ecodrix.com` | Override the API base URL (e.g. for local dev) |
 | `socketUrl`  | `string` | No          | Same as `baseUrl`         | Override the Socket.io server URL              |
 
@@ -108,22 +129,12 @@ const ecod = new Ecodrix({
 
 ## Resources
 
-Every resource follows the same predictable CRUD interface:
-
-| Method                | Description                        |
-| --------------------- | ---------------------------------- |
-| `.create(params)`     | Create a new record                |
-| `.list(params?)`      | List records with optional filters |
-| `.retrieve(id)`       | Get a single record by ID          |
-| `.update(id, params)` | Update a record                    |
-| `.delete(id)`         | Delete or cancel a record          |
-
----
-
 ### WhatsApp
 
 Access via `ecod.whatsapp`.
 
+---
+
 #### `ecod.whatsapp.messages`
 
 **Send a text message**
@@ -146,355 +157,651 @@ await ecod.whatsapp.messages.send({
 });
 ```
 
-**Send a pre-approved template message**
+**Send a template message via queue**
 
 ```typescript
 await ecod.whatsapp.messages.sendTemplate({
   to: "+919876543210",
   templateName: "appointment_reminder",
   language: "en_US",
-  variables: ["Dhanesh", "Tomorrow 10AM"],
+  variables: ["Priya", "Tomorrow 10AM"],
 });
 ```
 
-**Send a Meta-approved direct template (Bypass queues)**
-
-Use this specifically to dispatch high-priority utility templates containing dynamic variable maps.
+**Mark messages as read**
 
 ```typescript
-const { messageId } = await ecod.whatsapp.sendTemplate({
-  phone: "+919876543210",
-  templateName: "payment_confirmation",
-  variables: {
-    name: "Dhanesh",
-    amount: "₹1,500",
-  },
-});
+await ecod.whatsapp.messages.markRead("message_id");
 ```
 
-**Mark a conversation as read**
-
-```typescript
-await ecod.whatsapp.messages.markRead("conversation_id");
-```
+---
 
 #### `ecod.whatsapp.conversations`
 
 ```typescript
 // List conversations (cursor-based pagination)
-const { data } = await ecod.whatsapp.conversations.list({ limit: 20 });
+const { data } = await ecod.whatsapp.conversations.list({
+  limit: 20,
+  status: "open",
+  after: "cursor_token",
+});
 
 // Get a specific conversation
 const conv = await ecod.whatsapp.conversations.retrieve("conversation_id");
 
-// Archive a conversation
+// Get messages in a conversation
+const { data: msgs } = await ecod.whatsapp.conversations.messages("conversation_id", {
+  limit: 50,
+});
+
+// Create a conversation explicitly
+await ecod.whatsapp.conversations.create({ phone: "+919876543210", name: "Priya" });
+
+// Link a conversation to a CRM lead
+await ecod.whatsapp.conversations.linkLead("conversation_id", "lead_id");
+
+// Mark a conversation as read (clears unread badge)
+await ecod.whatsapp.conversations.markRead("conversation_id");
+
+// Delete / archive a conversation
 await ecod.whatsapp.conversations.delete("conversation_id");
+
+// Bulk delete conversations
+await ecod.whatsapp.conversations.bulkDelete(["conv_1", "conv_2"]);
 ```
 
 ---
 
-### CRM — Leads
+#### `ecod.whatsapp.templates`
 
-Access via `ecod.crm.leads`.
+```typescript
+// List pre-approved Meta templates
+const { data } = await ecod.whatsapp.templates.list();
 
-**Create a Lead**
+// Sync templates from the Meta Business Account
+await ecod.whatsapp.templates.sync();
+```
+
+---
+
+#### `ecod.whatsapp.broadcasts`
+
+Send a personalised WhatsApp template message to multiple recipients at once.
 
 ```typescript
-const { data: lead } = await ecod.crm.leads.create({
-  firstName: "Dhanesh",
-  lastName: "Kumar",
+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%"] },
+  ],
+});
+
+// List past broadcasts
+const { data } = await ecod.whatsapp.broadcasts.list({ status: "completed" });
+```
+
+---
+
+#### `ecod.whatsapp.sendTemplate` — Direct Template (Bypass Queue)
+
+Use this for high-priority utility templates that must deliver immediately outside the automation queue.
+
+```typescript
+const result = await ecod.whatsapp.sendTemplate({
   phone: "+919876543210",
-  email: "dhanesh@example.com",
-  source: "website", // 'website' | 'whatsapp' | 'direct' | ...
-  metadata: {
-    utmSource: "google",
+  templateName: "payment_confirmation",
+  variables: {
+    name: "Priya",
+    amount: "₹1,500",
   },
 });
+// result.messageId → WA message ID
+```
+
+---
+
+### CRM
+
+Access via `ecod.crm`.
+
+---
+
+#### `ecod.crm.leads`
+
+**Create**
+
+```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" },
+});
+```
+
+**Upsert by phone** — Creates if absent, updates if exists
+
+```typescript
+await ecod.crm.leads.upsert({
+  leadData: { phone: "+919876543210", firstName: "Priya" },
+  trigger: "webinar_joined",
+});
 ```
 
-**List Leads (with filters)**
+**List with filters**
 
 ```typescript
-const { data: leads } = await ecod.crm.leads.list({
-  status: "new", // filter by status
+const { data } = await ecod.crm.leads.list({
+  status: "new",
   source: "whatsapp",
+  pipelineId: "pipeline_id",
   page: 1,
   limit: 25,
 });
 ```
 
-_(See [Enterprise Capabilities](#enterprise-capabilities) for efficient auto-pagination or bulk-creation tricks like `listAutoPaging` and `createMany`)._
-
-**Retrieve a Lead by ID**
+**Retrieve**
 
 ```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");
 ```
 
-**Update a Lead**
+**Update**
 
 ```typescript
-await ecod.crm.leads.update("lead_id", {
-  email: "new@email.com",
-  metadata: { score: 95 },
+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" },
 });
 ```
 
-**Delete / Archive a Lead**
+**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"] });
+```
+
+**Score**
+
+```typescript
+await ecod.crm.leads.recalculateScore("lead_id");
+```
+
+**Bulk**
+
+```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"]);
 ```
 
 ---
 
-### Meetings
+#### `ecod.crm.pipelines`
 
-Access via `ecod.meet`. Backed by **Google Meet**.
+```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");
+```
 
-**Schedule a Meeting**
+---
+
+#### `ecod.crm.automations`
+
+```typescript
+// CRUD
+const { data } = await ecod.crm.automations.list();
+await ecod.crm.automations.create({ name: "Follow-up", trigger: "lead_created", nodes: [], edges: [] });
+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
-const { data: meeting } = await ecod.meet.create({
+await ecod.crm.sequences.enroll({
   leadId: "lead_id",
-  participantName: "Dhanesh Kumar",
-  participantPhone: "+919876543210",
-  startTime: "2026-04-10T10:00:00.000Z",
-  endTime: "2026-04-10T10:30:00.000Z",
+  ruleId: "rule_id",
+  variables: { discount: "20%" },
 });
-
-console.log(meeting.meetLink); // → https://meet.google.com/abc-defg-hij
+await ecod.crm.sequences.unenroll("enrollment_id");
+const { data } = await ecod.crm.sequences.listForLead("lead_id");
 ```
 
-**List Meetings**
+---
+
+#### `ecod.crm.activities`
 
 ```typescript
-const { data: meetings } = await ecod.meet.list({ status: "scheduled" });
+// 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" });
+
+// Log a call outcome
+await ecod.crm.activities.logCall("lead_id", {
+  outcome: "answered",
+  duration: 120,
+  notes: "Interested in Pro plan",
+});
+
+// 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" });
+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
 ```
 
-**Retrieve a Meeting**
+---
+
+#### `ecod.crm.analytics`
 
 ```typescript
-const { data } = await ecod.meet.retrieve("meeting_id");
+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");
 ```
 
-**Reschedule a Meeting**
+---
+
+#### `ecod.crm.scoring`
 
 ```typescript
-await ecod.meet.update("meeting_id", {
-  startTime: "2026-04-11T11:00:00.000Z",
-  endTime: "2026-04-11T11:30:00.000Z",
-});
+const { data } = await ecod.crm.scoring.getConfig();
+await ecod.crm.scoring.updateConfig({ rules: [...] });
 ```
 
-**Cancel a Meeting**
+---
+
+#### `ecod.crm.payments`
 
 ```typescript
-await ecod.meet.delete("meeting_id");
+const { data } = await ecod.crm.payments.list("lead_id");
 ```
 
 ---
 
-### Storage
+#### `ecod.crm.automationDashboard`
 
-Access via `ecod.storage`. Powered by **Cloudflare R2**.
+```typescript
+const { data: stats } = await ecod.crm.automationDashboard.stats();
+const { data: logs } = await ecod.crm.automationDashboard.logs({ limit: 10, status: "failed" });
+await ecod.crm.automationDashboard.retryFailedEvent("log_id");
+```
 
-**Upload a File (Elite Helper)**
+---
 
-This single call handles the entire R2 presigned-URL orchestration for you:
+### Events & Workflows
 
-1. Requests a presigned PUT URL from the backend.
-2. Uploads the file directly to R2 (no proxy overhead).
-3. Confirms the upload with the backend.
+Access via `ecod.events`. Connect your external applications to the CRM automation engine.
 
-```typescript
-// Node.js: from a Buffer
-import { readFileSync } from "fs";
+**List all available triggers**
 
-const fileBuffer = readFileSync("./contract.pdf");
-const { data } = await ecod.storage.upload(fileBuffer, {
-  folder: "customer_documents",
-  filename: "contract.pdf",
-  contentType: "application/pdf",
-});
+```typescript
+const { data: triggers } = await ecod.events.list();
+```
 
-console.log(data.url); // → https://cdn.ecodrix.com/customer_documents/contract.pdf
+**Register a custom event**
 
-// Browser: from an <input> file
-const file = document.getElementById("file-input").files[0];
-const { data } = await ecod.storage.upload(file, {
-  folder: "avatars",
-  filename: file.name,
-  contentType: file.type,
-});
-  filename: "dhanesh.png",
-  contentType: "image/png"
+```typescript
+await ecod.events.assign({
+  name: "cart_abandoned",
+  displayName: "Shopping Cart Abandoned",
+  pipelineId: "pipeline_123",
 });
 
-console.log(data.url);
-// -> https://cdn.ecodrix.com/avatars/dhanesh.png
+// Deactivate
+await ecod.events.unassign("cart_abandoned");
+await ecod.events.unassignBulk(["event_a", "event_b"]);
 ```
 
-**Get a Presigned URL for Private Assets**
+**Fire an event / trigger workflows**
 
-```javascript
-const { data } = await ecod.media.getDownloadUrl("confidential/contract.pdf");
+```typescript
+await ecod.events.trigger({
+  trigger: "cart_abandoned",
+  phone: "+919876543210",
+  variables: { items: "T-Shirt, Mug", total: "₹850" },
+  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",
+  },
+});
 ```
 
-**Monitor Quota & Usage**
+**Custom event definitions (CRM-managed)**
 
-```javascript
-const { data: usage } = await ecod.media.getUsage();
-console.log(`${usage.usedMB} MB used of ${usage.limitMB} MB`);
+```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" });
 ```
 
 ---
 
-### Email
+### Marketing
+
+Access via `ecod.marketing`.
 
-Access via `ecod.email`.
+**Email campaigns**
 
-**Send an Email Campaign**
+```typescript
+await ecod.marketing.emails.sendCampaign({
+  recipients: ["user@example.com"],
+  subject: "Summer Sale!",
+  html: "<h1>Get 20% off!</h1>",
+});
+await ecod.marketing.emails.sendTest("dev@example.com");
+```
 
-Dispatch an HTML email campaign to a given array of recipients. Powered by Ecodrix or AWS SES depending on tenant configuration.
+**Campaigns (Email + SMS)**
 
 ```typescript
-const { success } = await ecod.email.sendEmailCampaign({
-  subject: "Summer Subscription Discount!",
-  recipients: ["user@example.com", "lead@example.com"],
-  html: "<h1>Get 20% off all plans today!</h1>",
+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");
+```
+
+**WhatsApp marketing (CRM-integrated template dispatch)**
+
+Unlike the direct `ecod.whatsapp.sendTemplate`, this endpoint resolves CRM field variables automatically.
+
+```typescript
+await ecod.marketing.whatsapp.sendTemplate({
+  phone: "+919876543210",
+  templateName: "seasonal_offer",
+  variables: { discount: "40%" },
 });
 ```
 
-**Send a Test Email**
+---
 
-Send a system verification email to validate SMTP configuration for your tenant.
+### Meetings
+
+Access via `ecod.meet`. Backed by **Google Meet**.
 
 ```typescript
-const { success } = await ecod.email.sendTestEmail("admin@example.com");
+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",
+});
+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");
 ```
 
 ---
 
-### Events & Workflows
+### Storage
 
-Access via `ecod.events`. Programmatically integrate the CRM's automation engine with your external apps.
+Access via `ecod.storage`. Powered by **Cloudflare R2**.
 
-**Retrieve Global Triggers**
+This handles the full presigned-URL orchestration transparently:
 
-Fetch all active automation triggers belonging to the current tenant.
+1. Requests a presigned PUT URL from the backend.
+2. Uploads directly to R2 (no proxy overhead).
+3. Confirms the upload.
 
 ```typescript
-const { data: triggers } = await ecod.events.list();
+// Node.js: from a Buffer
+import { readFileSync } from "fs";
+
+const fileBuffer = readFileSync("./contract.pdf");
+const { data } = await ecod.storage.upload(fileBuffer, {
+  folder: "customer_documents",
+  filename: "contract.pdf",
+  contentType: "application/pdf",
+});
+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,
+});
 ```
 
-**Register a Custom Event Definition**
+---
+
+### Media
 
-Register a new entry point that you want to show up in the CRM Automation Builder.
+Access via `ecod.media`. Manage files stored in R2.
 
 ```typescript
-await ecod.events.assign({
-  name: "cart_abandoned",
-  displayName: "Shopping Cart Abandoned",
-  pipelineId: "pipeline_123" /* Auto map leads to this pipeline */,
-});
+// 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`);
+
+// List files in a folder
+await ecod.media.list({ folder: "invoices" });
+
+// Delete a file
+await ecod.media.delete("invoices/old_invoice.pdf");
 ```
 
-**Emit a Payload / Trigger Workflow**
+---
+
+### Email
 
-Inject generic data into the `EventBus` to fire customized automation rules.
+Access via `ecod.email`. Backed by SMTP or AWS SES depending on tenant configuration.
 
 ```typescript
-await ecod.events.trigger({
-  trigger: "cart_abandoned",
-  phone: "+919876543210", // Primary matching key
-  variables: { items: "T-Shirt, Mug", total: "₹850" },
-  createLeadIfMissing: true, // Upsert lead if it's a new customer
+await ecod.email.sendEmailCampaign({
+  subject: "Summer Discount!",
+  recipients: ["user@example.com"],
+  html: "<h1>Get 20% off all plans!</h1>",
 });
+
+// Verify SMTP configuration
+await ecod.email.sendTestEmail("admin@example.com");
 ```
 
 ---
 
 ### Notifications & Logs
 
-Access via `ecod.notifications`. View automation and webhook audit logs.
-
-**List Automation Execution Logs**
+Access via `ecod.notifications`.
 
 ```typescript
+// Automation execution logs
 const { data: logs } = await ecod.notifications.listLogs({
   trigger: "lead_created",
-  status: "failed", // filter to only failed automations
+  status: "failed",
   startDate: "2026-04-01",
   endDate: "2026-04-30",
-  limit: 50,
 });
-```
-
-**Retrieve a Specific Log**
-
-```typescript
-const { data: log } = await ecod.notifications.retrieveLog("log_id");
-```
 
-**Get Automation Stats Summary**
+await ecod.notifications.retrieveLog("log_id");
 
-```typescript
+// Aggregate stats
 const { data: stats } = await ecod.notifications.getStats({
   startDate: "2026-04-01",
   endDate: "2026-04-30",
 });
+
+// Provider webhook callback logs
+const { data } = await ecod.notifications.listCallbacks({ limit: 20 });
+```
+
+---
+
+### Queue Management
+
+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");
+
+// Remove a job permanently
+await ecod.queue.deleteJob("job_id");
 ```
 
-**List Provider Callback Logs (Webhooks)**
+---
+
+### Health & Diagnostics
+
+Access via `ecod.health`.
 
 ```typescript
-const { data: callbacks } = await ecod.notifications.listCallbacks({
-  limit: 20,
-});
+// Global platform status
+const health = await ecod.health.system();
+// { status: "ok", version: "...", env: "production", uptime: 3600, db: "connected", queueDepth: 5 }
+
+// Tenant-scoped service readiness
+const clientHealth = await ecod.health.clientHealth();
+// { clientCode: "...", services: { whatsapp: "connected", email: "configured", googleMeet: "configured" }, ... }
+
+// Background job status lookup
+const job = await ecod.health.jobStatus("job_id");
 ```
 
 ---
 
-## Enterprise Capabilities
+### Webhooks
 
-The SDK is equipped with state-of-the-art native patterns for robust execution, zero-downtime performance, and unparalleled developer experience. All network requests automatically utilize an exponential-backoff retry engine to gracefully handle temporary network errors.
+Access via `ecod.webhooks`.
+
+> ⚠️ **Node.js only** — Requires `node:crypto`. Not available in browser bundles.
+
+---
+
+## Enterprise Capabilities
 
 ### Auto-Paginating Iterators
 
-To rapidly ingest records without manually iterating pages, use standard Node.js `for await` loops. The SDK controls memory buffers and page fetching dynamically.
+Stream all records without manual page management:
 
 ```typescript
-// Look how beautiful this developer experience is:
-for await (const lead of ecod.crm.leads.listAutoPaging({ status: "won" })) {
+// With optional type parameter for full type safety
+for await (const lead of ecod.crm.leads.listAutoPaging<Lead>({ status: "won" })) {
   await syncToMyDatabase(lead);
 }
 ```
 
 ### Bulk Data Chunking
 
-Need to insert 5,000 leads at once but worried about network congestion or rate limits? `createMany` automatically chunks arrays into concurrent streams.
+Insert thousands of leads without hitting rate limits. `createMany` automatically chunks and concurrently streams batches:
 
 ```typescript
-// The users array chunked into safe parallel batched requests
 const results = await ecod.crm.leads.createMany(massiveArrayOfLeads, 100);
-console.log(`Successfully ingested ${results.length} leads.`);
+console.log(`Ingested ${results.length} leads.`);
 ```
 
 ### Idempotency Keys
 
-Because the SDK provides an automatic network retry engine (`axios-retry`), temporary blips could duplicate events. Passing an `idempotencyKey` strictly tells the backend: "Only execute this once, even if I accidentally retry the same payload."
+Prevent duplicate requests caused by automatic retries:
 
 ```typescript
 await ecod.email.sendEmailCampaign(
-  { subject: "Promo", recipients: ["user@example.com"] },
-  { idempotencyKey: "promo_campaign_uuid_123_abc" },
+  { subject: "Promo", recipients: ["user@example.com"], html: "..." },
+  { idempotencyKey: "promo_campaign_uuid_2026_q2" },
 );
 ```
 
 ### Webhook Signature Verification
 
-Verify cryptographic webhook payloads issued by the ECODrIx platform reliably in Node environments, mitigating spoofing attacks seamlessly.
+Cryptographically verify that webhook payloads originated from ECODrIx:
 
 ```typescript
 app.post(
@@ -505,9 +812,10 @@ app.post(
       const event = await ecod.webhooks.constructEvent(
         req.body.toString(),
         req.headers["x-ecodrix-signature"],
-        "whsec_your_secret_key",
+        "whsec_your_webhook_secret",
       );
-      console.log("Verified event received:", event);
+      console.log("Verified event:", event);
+      res.json({ received: true });
     } catch (err) {
       return res.status(400).send(`Invalid signature: ${err.message}`);
     }
@@ -517,11 +825,10 @@ app.post(
 
 ### Raw Execution Engine
 
-Need to execute an experimental, undocumented, or beta endpoint but still want full authentication mapping, global headers, and intelligent retries?
+Access any API endpoint — including experimental or custom ones — with full authentication and retry benefits:
 
 ```typescript
-// Bypass strictly typed resources with full network resiliency
-const customData = await ecod.request("POST", "/api/saas/beta-feature-route", {
+const { data } = await ecod.request("POST", "/api/saas/beta-feature", {
   experimentalFlag: true,
 });
 ```
@@ -530,46 +837,41 @@ const customData = await ecod.request("POST", "/api/saas/beta-feature-route", {
 
 ## Real-time Events
 
-The SDK maintains a persistent **Socket.io** connection. Subscribe to live platform events using `ecod.on(event, handler)`.
-
-```typescript
-const ecod = new Ecodrix({ apiKey: "...", clientCode: "..." });
-
-// New incoming WhatsApp message
-ecod.on("whatsapp.message_received", (data) => {
-  console.log(`New message from ${data.from}: ${data.body}`);
-});
-
-// Lead stage changed in CRM
-ecod.on("crm.lead_updated", (data) => {
-  console.log(`Lead ${data.leadId} moved to stage: ${data.stageName}`);
-});
-
-// Automation or event failed — for alert pipelines
-ecod.on("automation.failed", (data) => {
-  console.error(`Automation failed: ${data.trigger} — ${data.reason}`);
-});
-
-// Storage upload completed
-ecod.on("storage.upload_confirmed", (data) => {
-  console.log(`File available at: ${data.url}`);
-});
+The SDK maintains a persistent Socket.io connection, scoped to your `clientCode` tenant. Use `ecod.on()` to subscribe:
+
+```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}`);
+  });
 
-// Disconnect when done (e.g. server shutdown)
-ecod.disconnect();
+// Graceful shutdown
+process.on("SIGTERM", () => ecod.disconnect());
 ```
 
-### Standard Event Names
+### 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 field changed |
-| `meet.scheduled`            | `{ meetingId, meetLink }`        | New Google Meet booked      |
-| `storage.upload_confirmed`  | `{ key, url, sizeBytes }`        | File upload confirmed       |
-| `automation.failed`         | `{ trigger, reason, leadId }`    | Automation execution failed |
+| 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    |
 
 ---
 
@@ -578,12 +880,7 @@ ecod.disconnect();
 All methods throw typed errors you can catch and inspect:
 
 ```typescript
-import {
-  Ecodrix,
-  APIError,
-  AuthenticationError,
-  RateLimitError,
-} from "@ecodrix/erix-api";
+import { APIError, AuthenticationError, RateLimitError, Ecodrix } from "@ecodrix/erix-api";
 
 try {
   const { data } = await ecod.crm.leads.retrieve("non_existent_id");
@@ -592,31 +889,30 @@ try {
     // 401 — invalid API key or client code
     console.error("Check your credentials.");
   } else if (err instanceof RateLimitError) {
-    // 429 — slow down requests
-    console.warn("Rate limit hit. Retrying after delay...");
+    // 429 — too many requests (SDK auto-retries up to 3×)
+    console.warn("Rate limit hit.");
   } else if (err instanceof APIError) {
-    // Other HTTP errors from the API
     console.error(`API Error [${err.status}]: ${err.message}`);
   } else {
-    throw err; // re-throw unknown errors
+    throw err;
   }
 }
 ```
 
 ### Error Classes
 
-| Class                 | Status | Code                  | Description                                |
-| --------------------- | ------ | --------------------- | ------------------------------------------ |
-| `EcodrixError`        | —      | —                     | Base error class                           |
-| `APIError`            | varies | varies                | Generic API error with `status` and `code` |
-| `AuthenticationError` | 401    | `AUTH_FAILED`         | Invalid API key or client code             |
-| `RateLimitError`      | 429    | `RATE_LIMIT_EXCEEDED` | Too many requests                          |
+| 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                          |
 
 ---
 
 ## Browser / CDN Usage
 
-For usage without a bundler (plain HTML, marketing pages):
+For usage without a bundler:
 
 ```html
 <!-- Via CDN (jsDelivr) -->
@@ -634,14 +930,17 @@ For usage without a bundler (plain HTML, marketing pages):
 </script>
 ```
 
+> ⚠️ **Note**: `ecod.webhooks.constructEvent` and `ecod.storage.upload` (from `Buffer`) are Node.js only and will not function in browser environments.
+
 ---
 
 ## Contributing
 
 1. Fork the repository.
 2. Create a feature branch: `git checkout -b feat/my-feature`
-3. Make changes, then run `pnpm check` to validate.
-4. Submit a Pull Request.
+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.
 
 ---