@ecodrix/erix-api 1.1.4 → 1.1.6

package/src/resources/health.ts

@@ -36,7 +36,15 @@ export interface JobStatus {
 
 export class Health extends APIResource {
   /**
-   * Global platform health check.
+   * Perform a global platform health check.
+   * Verify that the API, database, and background workers are operational.
+   *
+   * @returns System health summary (status, version, uptime).
+   * @example
+   * ```typescript
+   * const health = await erixClient.health.system();
+   * console.log(`API Status: ${health.status}`);
+   * ```
    */
   async system(): Promise<SystemHealth> {
     const res = await this.get<{ data: SystemHealth }>("/api/saas/health", {
@@ -54,10 +62,22 @@ export class Health extends APIResource {
   }
 
   /**
-   * Job execution status lookup.
+   * Lookup the execution status of a background job.
+   *
+   * @param jobId - The unique ID of the background job.
+   * @returns Job status report (attempts, error trace, completion time).
+   * @example
+   * ```typescript
+   * const status = await erixClient.health.jobStatus("job_123");
+   * if (status.status === "completed") {
+   *   console.log("Job finished successfully!");
+   * }
+   * ```
    */
   async jobStatus(jobId: string): Promise<JobStatus> {
-    const res = await this.get<{ data: JobStatus }>(`/api/saas/jobs/status/${jobId}`);
+    const res = await this.get<{ data: JobStatus }>(
+      `/api/saas/jobs/status/${jobId}`,
+    );
     return res.data;
   }
 }

package/src/resources/marketing.ts

@@ -8,7 +8,18 @@ export interface SendCampaignParams {
 
 export class Emails extends APIResource {
   /**
-   * Dispatch a bulk email campaign.
+   * Dispatch a bulk email campaign to a list of recipients.
+   *
+   * @param params - The campaign details (recipients, subject, html).
+   * @returns The dispatch result.
+   * @example
+   * ```typescript
+   * await erixClient.marketing.emails.sendCampaign({
+   *   recipients: ["user@example.com"],
+   *   subject: "Special Offer",
+   *   html: "<p>Check out our deal!</p>"
+   * });
+   * ```
    */
   async sendCampaign<T = any>(params: SendCampaignParams) {
     return this.post<T>("/api/saas/marketing/emails/campaign", params);
@@ -23,14 +34,33 @@ export class Emails extends APIResource {
 }
 export class Campaigns extends APIResource {
   /**
-   * List email and SMS marketing campaigns.
+   * List all email and SMS marketing campaigns with optional status filtering.
+   *
+   * @param params - Optional filters (status, limit).
+   * @returns Paginated list of campaign objects.
+   * @example
+   * ```typescript
+   * const campaigns = await erixClient.marketing.campaigns.list({ status: "sent" });
+   * ```
    */
   async list<T = any>(params?: { status?: string; limit?: number }) {
     return this.get<T>("/api/saas/marketing/campaigns", { params } as any);
   }
 
   /**
-   * Create a new campaign.
+   * Create a new marketing campaign (Email or SMS).
+   *
+   * @param payload - Campaign details (name, type, content).
+   * @returns The created campaign record.
+   * @example
+   * ```typescript
+   * await erixClient.marketing.campaigns.create({
+   *   name: "Spring Sale",
+   *   type: "email",
+   *   subject: "Our Spring Sale is Here!",
+   *   html: "<h1>BIG DEALS!</h1>"
+   * });
+   * ```
    */
   async create<T = any>(payload: {
     name: string;
@@ -44,7 +74,13 @@ export class Campaigns extends APIResource {
   }
 
   /**
-   * Retrieve campaign details.
+   * Retrieve full details for a specific marketing campaign.
+   *
+   * @param campaignId - The unique ID of the campaign.
+   * @example
+   * ```typescript
+   * const campaign = await erixClient.marketing.campaigns.retrieve("camp_123");
+   * ```
    */
   async retrieve<T = any>(campaignId: string) {
     return this.get<T>(`/api/saas/marketing/campaigns/${campaignId}`);
@@ -65,14 +101,39 @@ export class Campaigns extends APIResource {
   }
 
   /**
-   * Send or schedule a campaign.
+   * Send a campaign immediately or schedule it for a later date.
+   *
+   * @param campaignId - The ID of the campaign to dispatch.
+   * @param payload - Optional scheduling information (ISO timestamp).
+   * @example
+   * ```typescript
+   * // Send immediately
+   * await erixClient.marketing.campaigns.send("camp_123");
+   *
+   * // Schedule for tomorrow
+   * await erixClient.marketing.campaigns.send("camp_123", {
+   *   scheduledAt: "2026-04-10T09:00:00Z"
+   * });
+   * ```
    */
   async send<T = any>(campaignId: string, payload?: { scheduledAt?: string }) {
-    return this.post<T>(`/api/saas/marketing/campaigns/${campaignId}/send`, payload || {});
+    return this.post<T>(
+      `/api/saas/marketing/campaigns/${campaignId}/send`,
+      payload || {},
+    );
   }
 
   /**
-   * Get campaign stats (opens, clicks, bounces).
+   * Get detailed delivery and engagement statistics for a campaign.
+   * Includes opens, clicks, bounces, and delivery failures.
+   *
+   * @param campaignId - The ID of the campaign.
+   * @returns Stats summary object.
+   * @example
+   * ```typescript
+   * const report = await erixClient.marketing.campaigns.stats("camp_123");
+   * console.log(`Open Rate: ${report.openRate}%`);
+   * ```
    */
   async stats<T = any>(campaignId: string) {
     return this.get<T>(`/api/saas/marketing/campaigns/${campaignId}/stats`);
@@ -83,8 +144,18 @@ export class WhatsAppMarketing extends APIResource {
   /**
    * Dispatch a template-based WhatsApp message with CRM-integrated variable resolution.
    *
-   * Unlike direct WhatsApp sending, this endpoint automatically pulls data from the CRM
+   * Unlike direct WhatsApp sending, this endpoint documentation automatically pulls data from the CRM
    * based on the provided variables mapping.
+   *
+   * @param params - Template details and recipient phone.
+   * @example
+   * ```typescript
+   * await erixClient.marketing.whatsapp.sendTemplate({
+   *   phone: "+919876543210",
+   *   templateName: "order_update",
+   *   variables: { "1": "Order #123" }
+   * });
+   * ```
    */
   async sendTemplate<T = any>(params: {
     phone: string;

package/src/resources/notifications.ts

@@ -125,24 +125,39 @@ export class Notifications extends APIResource {
   // Backend routes mounted at /api/crm — see crm.router.ts + notification.routes.ts
 
   /**
-   * List unread CRM notifications/alerts for the current tenant.
-   * Maps to: GET /api/crm/notifications
+   * List unread CRM notifications and alerts (e.g., lead assignments, system alerts).
+   *
+   * @param params - Optional filters (limit, unreadOnly).
+   * @returns Paginated list of notification objects.
+   * @example
+   * ```typescript
+   * const alerts = await erixClient.notifications.listAlerts({ unreadOnly: true });
+   * ```
    */
   async listAlerts<T = any>(params?: { limit?: number; unreadOnly?: boolean }) {
     return this.get<T>("/api/crm/notifications", { params } as any);
   }
 
   /**
-   * Dismiss a specific notification alert.
-   * Maps to: PATCH /api/crm/notifications/:id/dismiss
+   * Dismiss/mark a specific notification alert as read.
+   *
+   * @param notificationId - The unique ID of the notification.
+   * @example
+   * ```typescript
+   * await erixClient.notifications.dismissAlert("alert_123");
+   * ```
    */
   async dismissAlert<T = any>(notificationId: string) {
     return this.patch<T>(`/api/crm/notifications/${notificationId}/dismiss`);
   }
 
   /**
-   * Clear (dismiss) all notifications for the current tenant.
-   * Maps to: DELETE /api/crm/notifications/clear-all
+   * Clear all notifications for the current tenant immediately.
+   *
+   * @example
+   * ```typescript
+   * await erixClient.notifications.clearAllAlerts();
+   * ```
    */
   async clearAllAlerts<T = any>() {
     return this.deleteRequest<T>("/api/crm/notifications/clear-all");
@@ -150,7 +165,12 @@ export class Notifications extends APIResource {
 
   /**
    * Retry an action from a notification (e.g. failed automation send).
-   * Maps to: POST /api/crm/notifications/:id/retry
+   *
+   * @param notificationId - The unique ID of the notification.
+   * @example
+   * ```typescript
+   * await erixClient.notifications.retryAction("alert_123");
+   * ```
    */
   async retryAction<T = any>(notificationId: string) {
     return this.post<T>(`/api/crm/notifications/${notificationId}/retry`, {});

package/src/resources/queue.ts

@@ -10,21 +10,40 @@ export interface JobStats {
 
 export class Queue extends APIResource {
   /**
-   * List all failed jobs.
+   * List all background jobs that have failed execution.
+   *
+   * @returns Array of failed job objects.
+   * @example
+   * ```typescript
+   * const failed = await erixClient.queue.listFailed();
+   * ```
    */
   async listFailed<T = any>() {
     return this.get<T>("/api/saas/admin/queue/failed");
   }
 
   /**
-   * Get queue health statistics.
+   * Get real-time health statistics for the background job queue (waiting, active, failed).
+   *
+   * @returns Queue statistics summary.
+   * @example
+   * ```typescript
+   * const stats = await erixClient.queue.getStats();
+   * console.log(`Active Jobs: ${stats.active}`);
+   * ```
    */
   async getStats<T = JobStats>() {
     return this.get<T>("/api/saas/admin/queue/stats");
   }
 
   /**
-   * Retry a failed job.
+   * Manually retry a failed background job.
+   *
+   * @param jobId - The unique ID of the failed job.
+   * @example
+   * ```typescript
+   * await erixClient.queue.retryJob("job_123");
+   * ```
    */
   async retryJob<T = any>(jobId: string) {
     return this.post<T>(`/api/saas/admin/queue/${jobId}/retry`, {});
@@ -32,6 +51,12 @@ export class Queue extends APIResource {
 
   /**
    * Remove a job from the queue.
+   *
+   * @param jobId - The unique ID of the job to delete.
+   * @example
+   * ```typescript
+   * await erixClient.queue.deleteJob("job_123");
+   * ```
    */
   async deleteJob<T = any>(jobId: string) {
     return this.deleteRequest<T>(`/api/saas/admin/queue/${jobId}`);

package/src/resources/storage.ts

@@ -2,7 +2,13 @@ import { APIResource } from "../resource";
 
 export class Folders extends APIResource {
   /**
-   * Create a new folder.
+   * Create a new folder in the tenant's cloud storage.
+   *
+   * @param name - The name of the folder to create.
+   * @example
+   * ```typescript
+   * await erixClient.storage.folders.create("Invoices");
+   * ```
    */
   async create<T = any>(name: string) {
     return this.post<T>("/api/saas/storage/folders", { name });
@@ -18,16 +24,42 @@ export class Folders extends APIResource {
 
 export class Files extends APIResource {
   /**
-   * List files in a folder.
+   * List files within a specific folder.
+   *
+   * @param folder - The folder name or path.
+   * @param params - Optional year/month filters for organized storage.
+   * @example
+   * ```typescript
+   * const files = await erixClient.storage.files.list("Invoices", { year: "2026" });
+   * ```
    */
-  async list<T = any>(folder: string, params?: { year?: string; month?: string }) {
+  async list<T = any>(
+    folder: string,
+    params?: { year?: string; month?: string },
+  ) {
     return this.get<T>(`/api/saas/storage/files/${folder}`, { params } as any);
   }
 
   /**
    * Get a presigned upload URL for direct-to-cloud browser uploads.
+   * This allows the client to upload files directly to R2/S3 without hitting the backend.
+   *
+   * @param params - Upload parameters (folder, filename, contentType).
+   * @example
+   * ```typescript
+   * const { data } = await erixClient.storage.files.getUploadUrl({
+   *   folder: "Invoices",
+   *   filename: "inv_1.pdf",
+   *   contentType: "application/pdf"
+   * });
+   * // Now use data.url with a PUT request
+   * ```
    */
-  async getUploadUrl<T = any>(params: { folder: string; filename: string; contentType: string }) {
+  async getUploadUrl<T = any>(params: {
+    folder: string;
+    filename: string;
+    contentType: string;
+  }) {
     return this.post<T>("/api/saas/storage/upload-url", params);
   }
 

package/src/resources/whatsapp/broadcasts.ts

@@ -16,16 +16,79 @@ export interface CreateBroadcastParams {
 
 export class Broadcasts extends APIResource {
   /**
-   * List past and active broadcasts.
+   * List past and active WhatsApp broadcast campaigns.
+   *
+   * @param params - Optional filter parameters (page, limit, status).
+   * @returns Paginated list of broadcast records.
+   * @example
+   * ```typescript
+   * const broadcasts = await erixClient.whatsapp.broadcasts.list({ limit: 10 });
+   * ```
    */
   async list<T = any>(params?: Record<string, any>) {
     return this.get<T>("/api/saas/chat/broadcasts", { params } as any);
   }
 
   /**
-   * Create a new broadcast to send a template message to multiple recipients.
+   * Retrieve full details and real-time stats for a specific broadcast campaign.
+   *
+   * @param id - The unique identifier of the broadcast.
+   * @returns The broadcast record including sent/failed counts.
+   * @example
+   * ```typescript
+   * const stats = await erixClient.whatsapp.broadcasts.retrieve("bc_123");
+   * console.log(`Success Rate: ${(stats.sentCount / stats.totalRecipients) * 100}%`);
+   * ```
+   */
+  async retrieve<T = any>(id: string) {
+    return this.get<T>(`/api/saas/chat/broadcasts/${id}`);
+  }
+
+  /**
+   * Create a new broadcast campaign to send template messages to multiple recipients.
+   *
+   * @param params - Broadcast configuration (name, templateName, recipients).
+   * @returns The newly created broadcast record.
+   * @example
+   * ```typescript
+   * await erixClient.whatsapp.broadcasts.create({
+   *   name: "Spring Sale",
+   *   templateName: "promo_code",
+   *   recipients: [
+   *     { phone: "+919876543210", variables: ["SAVE10"] }
+   *   ]
+   * });
+   * ```
    */
   async create<T = any>(params: CreateBroadcastParams) {
     return this.post<T>("/api/saas/chat/broadcast", params);
   }
+
+  /**
+   * Update broadcast metadata, such as its name or administrative status.
+   *
+   * @param id - The unique ID of the broadcast.
+   * @param data - The fields to update (name, status).
+   * @example
+   * ```typescript
+   * await erixClient.whatsapp.broadcasts.update("bc_123", { name: "Revised Spring Sale" });
+   * ```
+   */
+  async update<T = any>(id: string, data: { name?: string; status?: string }) {
+    return this.patch<T>(`/api/saas/chat/broadcasts/${id}`, data);
+  }
+
+  /**
+   * Delete a broadcast campaign record.
+   * Note: This does not cancel messages already in flight but removes the record from the dashboard.
+   *
+   * @param id - The unique ID of the broadcast.
+   * @example
+   * ```typescript
+   * await erixClient.whatsapp.broadcasts.delete("bc_123");
+   * ```
+   */
+  async delete<T = any>(id: string) {
+    return this.deleteRequest<T>(`/api/saas/chat/broadcasts/${id}`);
+  }
 }

package/src/resources/whatsapp/conversations.ts

@@ -10,6 +10,15 @@ export interface ListParams {
 export class Conversations extends APIResource {
   /**
    * List conversations for the tenant.
+   * @deprecated Use `list` method from `ErixClient` instead.
+   * @param params - List parameters.
+   * @returns List of conversations.
+   * @example
+   * ```typescript
+   * import { ErixClient } from "erix-react";
+   * const erixClient = new ErixClient({ apiKey: "YOUR_API_KEY" });
+   * const conversations = await erixClient.whatsapp.conversations.list();
+   * ```
    */
   async list<T = any>(params?: ListParams) {
     return this.get<T>("/api/saas/chat/conversations", { params } as any);
@@ -19,6 +28,13 @@ export class Conversations extends APIResource {
    * Create a new conversation explicitly.
    *
    * @param params - Conversation details.
+   * @example
+   * ```typescript
+   * const conversation = await erixClient.whatsapp.conversations.create({
+   *   phone: "+919876543210",
+   *   name: "John Doe"
+   * });
+   * ```
    */
   async create<T = any>(params: { phone: string; name?: string }) {
     return this.post<T>("/api/saas/chat/conversations", params);
@@ -26,6 +42,12 @@ export class Conversations extends APIResource {
 
   /**
    * Retrieve details of a specific conversation.
+   *
+   * @param conversationId - The unique ID of the conversation.
+   * @example
+   * ```typescript
+   * const conversation = await erixClient.whatsapp.conversations.retrieve("conv_123");
+   * ```
    */
   async retrieve<T = any>(conversationId: string) {
     return this.get<T>(`/api/saas/chat/conversations/${conversationId}`);
@@ -33,32 +55,72 @@ export class Conversations extends APIResource {
 
   /**
    * Get messages for a specific conversation.
+   *
+   * @param conversationId - The unique ID of the conversation.
+   * @param params - Pagination and filter parameters.
+   * @example
+   * ```typescript
+   * const messages = await erixClient.whatsapp.conversations.messages("conv_123", { limit: 50 });
+   * ```
    */
   async messages<T = any>(conversationId: string, params?: ListParams) {
-    return this.get<T>(`/api/saas/chat/conversations/${conversationId}/messages`, {
-      params,
-    } as any);
+    return this.get<T>(
+      `/api/saas/chat/conversations/${conversationId}/messages`,
+      {
+        params,
+      } as any,
+    );
   }
 
   /**
-   * Link a conversation to a lead.
+   * Link a conversation to a lead in the CRM.
+   *
+   * @param conversationId - The unique ID of the conversation.
+   * @param leadId - The unique ID of the lead to link.
+   * @param leadData - Optional additional lead metadata.
+   * @example
+   * ```typescript
+   * await erixClient.whatsapp.conversations.linkLead("conv_123", "lead_456");
+   * ```
    */
-  async linkLead<T = any>(conversationId: string, leadId: string, leadData?: any) {
-    return this.post<T>(`/api/saas/chat/conversations/${conversationId}/link-lead`, {
-      leadId,
-      leadData,
-    });
+  async linkLead<T = any>(
+    conversationId: string,
+    leadId: string,
+    leadData?: any,
+  ) {
+    return this.post<T>(
+      `/api/saas/chat/conversations/${conversationId}/link-lead`,
+      {
+        leadId,
+        leadData,
+      },
+    );
   }
 
   /**
    * Mark a conversation as read (clear unread count).
+   *
+   * @param conversationId - The unique ID of the conversation.
+   * @example
+   * ```typescript
+   * await erixClient.whatsapp.conversations.markRead("conv_123");
+   * ```
    */
   async markRead<T = any>(conversationId: string) {
-    return this.post<T>(`/api/saas/chat/conversations/${conversationId}/read`, {});
+    return this.post<T>(
+      `/api/saas/chat/conversations/${conversationId}/read`,
+      {},
+    );
   }
 
   /**
    * Delete a conversation.
+   *
+   * @param conversationId - The unique ID of the conversation.
+   * @example
+   * ```typescript
+   * await erixClient.whatsapp.conversations.delete("conv_123");
+   * ```
    */
   async delete(conversationId: string) {
     return this.deleteRequest(`/api/saas/chat/conversations/${conversationId}`);
@@ -66,6 +128,12 @@ export class Conversations extends APIResource {
 
   /**
    * Bulk delete conversations.
+   *
+   * @param ids - Array of conversation IDs to delete.
+   * @example
+   * ```typescript
+   * await erixClient.whatsapp.conversations.bulkDelete(["conv_1", "conv_2"]);
+   * ```
    */
   async bulkDelete<T = any>(ids: string[]) {
     return this.post<T>("/api/saas/chat/conversations/bulk-delete", { ids });

package/src/resources/whatsapp/messages.ts

@@ -90,26 +90,26 @@ export class Messages extends APIResource {
    * Send a free-text or media message to a WhatsApp number.
    *
    * For text-only messages, supply `text`. For media, supply `mediaUrl`
-   * and `mediaType`. Both can be combined.
+   * and `mediaType`. Both can be combined in a single message.
    *
-   * @param params - Message parameters.
-   * @returns The created message record.
+   * @param params - Message parameters including recipient, text, and media.
+   * @returns The created message record from the database.
    *
-   * @example Text message
+   * @example Send a simple text message
    * ```typescript
-   * await ecod.whatsapp.messages.send({
+   * await erixClient.whatsapp.messages.send({
    *   to: "+919876543210",
-   *   text: "Hello!",
+   *   text: "Hello from Ecodrix!",
    * });
    * ```
    *
-   * @example Media message
+   * @example Send an image with a caption
    * ```typescript
-   * await ecod.whatsapp.messages.send({
+   * await erixClient.whatsapp.messages.send({
    *   to: "+919876543210",
-   *   mediaUrl: "https://cdn.ecodrix.com/invoice.pdf",
-   *   mediaType: "document",
-   *   filename: "invoice.pdf",
+   *   text: "Check out this flyer",
+   *   mediaUrl: "https://example.com/flyer.jpg",
+   *   mediaType: "image",
    * });
    * ```
    */
@@ -120,20 +120,20 @@ export class Messages extends APIResource {
   /**
    * Send a pre-approved WhatsApp Business template message.
    *
-   * Templates must be approved in Meta Business Manager before use.
-   * Variable placeholders in the template body are filled left-to-right
-   * from the `variables` array.
+   * Templates must be approved in Meta Business Manager before they can be sent.
+   * Variable placeholders (e.g., {{1}}, {{2}}) are replaced with values from the
+   * `variables` array in order.
    *
-   * @param params - Template message parameters.
+   * @param params - Template message configuration (name, language, variables).
    * @returns The created message record.
    *
    * @example
    * ```typescript
-   * await ecod.whatsapp.messages.sendTemplate({
+   * await erixClient.whatsapp.messages.sendTemplate({
    *   to: "+919876543210",
-   *   templateName: "appointment_reminder",
+   *   templateName: "welcome_user",
    *   language: "en_US",
-   *   variables: ["Alice", "10 April", "10:00 AM"],
+   *   variables: ["Alice"], // Replaces {{1}} in template
    * });
    * ```
    */