@ecodrix/erix-api 1.1.5 → 1.1.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecodrix/erix-api",
-  "version": "1.1.5",
+  "version": "1.1.7",
   "author": "ECODrIx Team <contact@ecodrix.com>",
   "license": "MIT",
   "description": "Official Isomorphic SDK for the ECODrIx platform. Native support for WhatsApp, CRM, Storage, and Meetings across TS, JS, Python, and Java.",

package/src/core.ts

@@ -17,8 +17,14 @@ import { WhatsApp } from "./resources/whatsapp";
 
 declare const process: any;
 
+/** @internal The canonical ECODrIx backend URL — not exposed to SDK consumers. */
+const ECOD_API_BASE = "https://api.ecodrix.com";
+
 /**
  * Configuration options for the Ecodrix client.
+ *
+ * Minimum required: `apiKey` and `clientCode`.
+ * The backend URL is managed internally and should not need to be changed.
  */
 export interface EcodrixOptions {
   /**
@@ -31,24 +37,21 @@ export interface EcodrixOptions {
   /**
    * Your tenant ID (Client Code).
    * This scopes all API requests to your specific organisation.
-   * Required for most operations.
    * @example "ERIX_CLNT_JHBJHF"
    */
   clientCode?: string;
 
   /**
-   * Override the base URL of the ECODrIx API.
-   * Useful for pointing to a local development or staging server.
-   * @default "https://api.ecodrix.com"
+   * @internal Override Socket.io URL for testing/staging.
+   * Not documented — internal use only.
    */
-  baseUrl?: string;
+  socketUrl?: string;
 
   /**
-   * Override the Socket.io server URL for real-time events.
-   * Defaults to the same value as `baseUrl`.
-   * @default "https://api.ecodrix.com"
+   * @internal Override the backend API URL. Used by the CLI and internal tests only.
+   * Host projects must never set this — the production URL is hardcoded internally.
    */
-  socketUrl?: string;
+  baseUrl?: string;
 }
 
 /**
@@ -115,7 +118,9 @@ export class Ecodrix {
       throw new AuthenticationError("API Key is required");
     }
 
-    const baseUrl = options.baseUrl || "https://api.ecodrix.com";
+    // @internal: options.baseUrl is available for CLI/test use only.
+    // Host projects hardcode to prod — they never set baseUrl.
+    const baseUrl = options.baseUrl ?? ECOD_API_BASE;
     const socketUrl = options.socketUrl || baseUrl;
 
     const isBrowser = typeof window !== "undefined" && typeof window.document !== "undefined";
@@ -183,7 +188,7 @@ export class Ecodrix {
 
   /**
    * Join a specific real-time room (e.g., a conversation or a lead).
-   * 
+   *
    * @param roomId - The unique identifier for the room.
    */
   public joinRoom(roomId: string) {
@@ -192,7 +197,7 @@ export class Ecodrix {
 
   /**
    * Leave a previously joined real-time room.
-   * 
+   *
    * @param roomId - The unique identifier for the room.
    */
   public leaveRoom(roomId: string) {

package/src/resources/crm/activities.ts

@@ -84,10 +84,7 @@ export class Activities extends APIResource {
    * const timeline = await erixClient.crm.activities.timeline("lead_123", { limit: 10 });
    * ```
    */
-  async timeline<T = any>(
-    leadId: string,
-    params?: { page?: number; limit?: number },
-  ) {
+  async timeline<T = any>(leadId: string, params?: { page?: number; limit?: number }) {
     return this.get<T>(`/api/crm/leads/${leadId}/timeline`, { params } as any);
   }
 
@@ -123,4 +120,3 @@ export class Activities extends APIResource {
     return this.post<T>(`/api/crm/leads/${leadId}/calls`, params);
   }
 }
-

package/src/resources/crm/analytics.ts

@@ -14,11 +14,12 @@ export class Analytics extends APIResource {
    * Retrieve high-level CRM performance KPIs.
    * Includes total leads, pipeline value, won revenue, and conversion rates.
    *
-   * @param params - Optional filters (time range, pipelineId).
-   * @returns KPI summary object.
+   * @param params - Optional filters including time range (24h, 7d, 30d, etc.) and custom date bounds.
+   * @returns {Promise<any>} KPI summary object containing core business metrics.
    * @example
    * ```typescript
    * const stats = await erixClient.crm.analytics.overview({ range: "30d" });
+   * console.log(stats.avgScore);
    * ```
    */
   async overview<T = any>(params?: AnalyticsParams) {
@@ -27,9 +28,10 @@ export class Analytics extends APIResource {
 
   /**
    * Get stage-by-stage lead counts and conversion percentages for a pipeline.
-   * Useful for identifying funnel bottlenecks.
+   * Useful for identifying funnel bottlenecks and drop-off points.
    *
    * @param pipelineId - The unique ID of the pipeline to analyze.
+   * @returns {Promise<any>} Array of funnel stages with count and conversion data.
    * @example
    * ```typescript
    * const funnel = await erixClient.crm.analytics.funnel("pipe_123");
@@ -42,56 +44,88 @@ export class Analytics extends APIResource {
   }
 
   /**
-   * Revenue forecast: deal value × stage probability.
+   * Revenue forecast: Calculates expected revenue based on deal value × stage probability.
+   * Helps in sales planning and goal setting.
+   *
+   * @param pipelineId - Optional pipeline ID to filter the forecast.
+   * @returns {Promise<any>} Forecast data including weighted expected revenue.
+   * @example
+   * ```typescript
+   * const prognosis = await erixClient.crm.analytics.forecast("pipe_123");
+   * ```
    */
   async forecast<T = any>(pipelineId?: string) {
-    return this.get<T>("/api/crm/analytics/forecast", { params: { pipelineId } } as any);
+    return this.get<T>("/api/crm/analytics/forecast", {
+      params: { pipelineId },
+    } as any);
   }
 
   /**
-   * Lead source breakdown: count, conversion rate, total value per source.
+   * Lead source breakdown: count, conversion rate, and total value per source.
+   *
+   * @param params - Time range filters.
+   * @returns {Promise<any>} Breakdown of how different marketing channels are performing.
    */
   async sources<T = any>(params?: AnalyticsParams) {
     return this.get<T>("/api/crm/analytics/sources", { params } as any);
   }
 
   /**
-   * Team leaderboard: won deals, revenue, activity count, conversion rate per member.
+   * Team leaderboard: Evaluates agent performance across won deals, revenue, and activity.
+   *
+   * @param params - Time range filters.
+   * @returns {Promise<any>} Ranked list of team members by performance.
    */
   async team<T = any>(params?: AnalyticsParams) {
     return this.get<T>("/api/crm/analytics/team", { params } as any);
   }
 
   /**
-   * Daily activity counts by type. For activity calendar.
+   * Activity heatmap: Daily activity counts by type.
+   * Ideal for visualizing engagement patterns on a calendar view.
+   *
+   * @param params - Time range filters.
+   * @returns {Promise<any>} Time-series data of team activities.
    */
   async heatmap<T = any>(params?: AnalyticsParams) {
     return this.get<T>("/api/crm/analytics/heatmap", { params } as any);
   }
 
   /**
-   * Score distribution: how many leads in each score bucket.
+   * Score distribution: Groups leads into buckets based on their calculated score (0-100).
+   *
+   * @returns {Promise<any>} Volume of leads in different readiness tiers.
    */
   async scores<T = any>() {
     return this.get<T>("/api/crm/analytics/scores");
   }
 
   /**
-   * Avg time leads spend in each stage. Helps find bottlenecks.
+   * Avg time in stage: Measures the velocity of leads through the sales pipeline.
+   *
+   * @param pipelineId - Target pipeline ID.
+   * @returns {Promise<any>} Velocity metrics per stage.
    */
   async stageTime<T = any>(pipelineId: string) {
-    return this.get<T>("/api/crm/analytics/stage-time", { params: { pipelineId } } as any);
+    return this.get<T>("/api/crm/analytics/stage-time", {
+      params: { pipelineId },
+    } as any);
   }
 
   /**
-   * Tiered Growth Report matching business sophistication.
+   * Tiered Growth Report matching business sophistication (Pulse, Growth, Weapon).
+   * Provides deep tactical and strategic insights.
+   *
+   * @param params - Filtering and range parameters.
    */
   async tiered<T = any>(params?: AnalyticsParams) {
     return this.get<T>("/api/crm/analytics/tiered", { params } as any);
   }
 
   /**
-   * Consolidated analytics including CRM overview and WhatsApp.
+   * Consolidated analytics including CRM overview and WhatsApp messaging metrics.
+   *
+   * @param params - Time range filters.
    */
   async summary<T = any>(params?: AnalyticsParams) {
     return this.get<T>("/api/crm/analytics/summary", { params } as any);
@@ -99,15 +133,16 @@ export class Analytics extends APIResource {
 
   /**
    * Retrieve WhatsApp messaging volume and delivery performance analytics.
+   * Includes total sent, delivered, read, and daily volume trends.
    *
    * @param params - Optional filters (time range).
    * @example
    * ```typescript
    * const waStats = await erixClient.crm.analytics.whatsapp({ range: "7d" });
+   * console.log(waStats.totalSent);
    * ```
    */
   async whatsapp<T = any>(params?: AnalyticsParams) {
     return this.get<T>("/api/crm/analytics/whatsapp", { params } as any);
   }
-
 }

package/src/resources/crm/automationDashboard.ts

@@ -39,5 +39,4 @@ export class AutomationDashboard extends APIResource {
   async retryFailedEvent<T = any>(logId: string) {
     return this.post<T>(`/api/crm/automation/logs/${logId}/retry`, {});
   }
-
 }

package/src/resources/crm/automations.ts

@@ -62,7 +62,6 @@ export class Automations extends APIResource {
     return this.deleteRequest(`/api/crm/automations/${ruleId}`);
   }
 
-
   /**
    * Bulk delete rules.
    */
@@ -118,20 +117,14 @@ export class Automations extends APIResource {
    * Pause an enrollment.
    */
   async pauseEnrollment<T = any>(ruleId: string, enrollmentId: string) {
-    return this.post<T>(
-      `/api/crm/automations/${ruleId}/enrollments/${enrollmentId}/pause`,
-      {},
-    );
+    return this.post<T>(`/api/crm/automations/${ruleId}/enrollments/${enrollmentId}/pause`, {});
   }
 
   /**
    * Resume an enrollment.
    */
   async resumeEnrollment<T = any>(ruleId: string, enrollmentId: string) {
-    return this.post<T>(
-      `/api/crm/automations/${ruleId}/enrollments/${enrollmentId}/resume`,
-      {},
-    );
+    return this.post<T>(`/api/crm/automations/${ruleId}/enrollments/${enrollmentId}/resume`, {});
   }
 
   /**
@@ -174,5 +167,4 @@ export class Automations extends APIResource {
   async webhookEvent<T = any>(ruleId: string, eventName: string, payload?: any) {
     return this.post<T>("/api/crm/webhook-event", { ruleId, eventName, payload });
   }
-
 }

package/src/resources/crm/leads.ts

@@ -3,23 +3,12 @@ import { APIResource } from "../../resource";
 /**
  * Valid statuses for a CRM Lead.
  */
-export type LeadStatus =
-  | "new"
-  | "contacted"
-  | "qualified"
-  | "won"
-  | "lost"
-  | "archived";
+export type LeadStatus = "new" | "contacted" | "qualified" | "won" | "lost" | "archived";
 
 /**
  * Common lead acquisition sources. Additional string values are allowed.
  */
-export type LeadSource =
-  | "website"
-  | "whatsapp"
-  | "direct"
-  | "referral"
-  | string;
+export type LeadSource = "website" | "whatsapp" | "direct" | "referral" | string;
 
 /**
  * Parameters for creating a new CRM Lead.
@@ -201,9 +190,7 @@ export class Leads extends APIResource {
    * }
    * ```
    */
-  async *listAutoPaging<T = any>(
-    params?: ListLeadsParams,
-  ): AsyncGenerator<T, void, unknown> {
+  async *listAutoPaging<T = any>(params?: ListLeadsParams): AsyncGenerator<T, void, unknown> {
     let currentPage = params?.page || 1;
     let hasMore = true;
 
@@ -213,9 +200,7 @@ export class Leads extends APIResource {
         page: currentPage,
       });
 
-      const items = Array.isArray(response.data)
-        ? response.data
-        : response || [];
+      const items = Array.isArray(response.data) ? response.data : response || [];
 
       if (items.length === 0) {
         hasMore = false;
@@ -308,11 +293,7 @@ export class Leads extends APIResource {
    * @param outcome - "won" | "lost"
    * @param reason - Reason for the outcome.
    */
-  async convert<T = any>(
-    leadId: string,
-    outcome: "won" | "lost",
-    reason?: string,
-  ) {
+  async convert<T = any>(leadId: string, outcome: "won" | "lost", reason?: string) {
     return this.post<T>(`/api/crm/leads/${leadId}/convert`, {
       outcome,
       reason,
@@ -325,10 +306,7 @@ export class Leads extends APIResource {
    * @param leadId - ID of the lead.
    * @param options - Tags to add or remove.
    */
-  async tags<T = any>(
-    leadId: string,
-    options: { add?: string[]; remove?: string[] },
-  ) {
+  async tags<T = any>(leadId: string, options: { add?: string[]; remove?: string[] }) {
     return this.patch<T>(`/api/crm/leads/${leadId}/tags`, options);
   }
 
@@ -371,10 +349,7 @@ export class Leads extends APIResource {
   /**
    * Retrieve the complete chronological timeline for a lead.
    */
-  async activities<T = any>(
-    leadId: string,
-    params?: { page?: number; limit?: number },
-  ) {
+  async activities<T = any>(leadId: string, params?: { page?: number; limit?: number }) {
     return this.get<T>(`/api/crm/leads/${leadId}/timeline`, { params } as any);
   }
 
@@ -388,11 +363,7 @@ export class Leads extends APIResource {
   /**
    * Update an existing note.
    */
-  async updateNote<T = any>(
-    leadId: string,
-    noteId: string,
-    params: { content: string },
-  ) {
+  async updateNote<T = any>(leadId: string, noteId: string, params: { content: string }) {
     return this.patch<T>(`/api/crm/notes/${noteId}`, params);
   }
 

package/src/resources/crm/payments.ts

@@ -24,5 +24,4 @@ export class Payments extends APIResource {
   }) {
     return this.post<T>("/api/crm/payments/capture", payload);
   }
-
 }

package/src/resources/crm/scoring.ts

@@ -43,5 +43,4 @@ export class Scoring extends APIResource {
   async recalculate<T = any>(leadId: string) {
     return this.post<T>(`/api/crm/scoring/${leadId}/recalculate`, {});
   }
-
 }

package/src/resources/email.ts

@@ -38,9 +38,7 @@ export class EmailResource extends APIResource {
    * });
    * ```
    */
-  async sendEmailCampaign(
-    payload: SendCampaignPayload,
-  ): Promise<CampaignResult> {
+  async sendEmailCampaign(payload: SendCampaignPayload): Promise<CampaignResult> {
     return this.post<CampaignResult>("/api/saas/emails/campaign", payload);
   }
 

package/src/resources/events.ts

@@ -103,9 +103,7 @@ export class EventsResource extends APIResource {
    * ```
    */
   async list(): Promise<{ success: boolean; data: EventDefinition[] }> {
-    return this.get<{ success: boolean; data: EventDefinition[] }>(
-      "/api/saas/events",
-    );
+    return this.get<{ success: boolean; data: EventDefinition[] }>("/api/saas/events");
   }
 
   /**

package/src/resources/health.ts

@@ -75,9 +75,7 @@ export class Health extends APIResource {
    * ```
    */
   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

@@ -117,10 +117,7 @@ export class Campaigns extends APIResource {
    * ```
    */
   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 || {});
   }
 
   /**

package/src/resources/storage.ts

@@ -33,10 +33,7 @@ export class Files extends APIResource {
    * 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);
   }
 

package/src/resources/whatsapp/conversations.ts

@@ -64,12 +64,9 @@ export class Conversations extends APIResource {
    * ```
    */
   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);
   }
 
   /**
@@ -83,18 +80,11 @@ export class Conversations extends APIResource {
    * 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,
+    });
   }
 
   /**
@@ -107,10 +97,7 @@ export class Conversations extends APIResource {
    * ```
    */
   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`, {});
   }
 
   /**

package/src/resources/whatsapp/messages.ts

@@ -85,6 +85,32 @@ export interface SendTemplateParams {
  * });
  * ```
  */
+/**
+ * Resolved media metadata returned by any upload endpoint.
+ * `variants` is only present for raster images (JPEG, PNG, WebP, AVIF, GIF).
+ */
+export interface ChatMediaMeta {
+  /** Raw CDN URL — always present, all media types */
+  url: string;
+  /** Categorical type — "image" | "video" | "audio" | "document" */
+  type: "image" | "video" | "audio" | "document";
+  /** Cloudflare-optimised variant URLs. Only present for raster images. */
+  variants?: {
+    /** 150px WebP — use for list thumbnails and chat bubbles */
+    thumb: string;
+    /** 600px WebP — use for modal previews */
+    medium: string;
+    /** 1200px WebP — use for hero or full-screen views */
+    full: string;
+    /** Original CDN URL, no transformation */
+    raw: string;
+  };
+  /** Storage key within the tenant bucket */
+  key?: string;
+  /** Original filename */
+  fileName?: string;
+}
+
 export class Messages extends APIResource {
   /**
    * Send a free-text or media message to a WhatsApp number.
@@ -185,25 +211,26 @@ export class Messages extends APIResource {
   /**
    * Upload a media file for WhatsApp chat.
    *
-   * This is the recommended way to upload media for WhatsApp chatting as it
-   * allows the backend to perform WhatsApp-specific optimizations (resizing,
-   * format conversion, and thumbnail generation).
+   * Works with any file type — image, video, audio, or document.
+   * For raster images the response includes Cloudflare-optimised `variants`
+   * (thumb 150px, medium 600px, full 1200px). Non-image types return only `url`.
    *
    * @param file - The file to upload (File, Blob, or Buffer).
-   * @returns The uploaded media details `{ url, type }`.
+   * @returns Full media metadata `{ url, type, variants?, key, fileName }`.
    *
    * @example
    * ```typescript
    * const file = input.files[0];
    * const { data } = await ecod.whatsapp.messages.upload(file);
-   * console.log(data.url); // -> https://cdn.ecodrix.com/tenants/ABC/chat/chat_123.jpg
+   * // For images: data.variants.thumb → 150px WebP from Cloudflare
+   * // For video/audio: use data.url directly in <video> or <audio>
    * ```
    */
-  async upload<T = { url: string; type: string }>(file: any): Promise<{ success: boolean; data: T }> {
+  async upload(file: any): Promise<{ success: boolean; data: ChatMediaMeta }> {
     const formData = new FormData();
     formData.append("file", file);
 
-    return this.post<{ success: boolean; data: T }>("/api/saas/chat/upload", formData, {
+    return this.post<{ success: boolean; data: ChatMediaMeta }>("/api/saas/chat/upload", formData, {
       headers: {
         "Content-Type": "multipart/form-data",
       },

package/src/resources/whatsapp/templates.ts

@@ -49,9 +49,7 @@ export class Templates extends APIResource {
    * ```
    */
   async retrieve<T = any>(templateIdentifier: string) {
-    return this.get<T>(
-      `/api/saas/chat/templates/${encodeURIComponent(templateIdentifier)}`,
-    );
+    return this.get<T>(`/api/saas/chat/templates/${encodeURIComponent(templateIdentifier)}`);
   }
 
   /**
@@ -145,9 +143,7 @@ export class Templates extends APIResource {
    * Validate if a template is ready for automated sending based on its mappings.
    */
   async validate<T = any>(templateName: string) {
-    return this.get<T>(
-      `/api/saas/chat/templates/${encodeURIComponent(templateName)}/validate`,
-    );
+    return this.get<T>(`/api/saas/chat/templates/${encodeURIComponent(templateName)}/validate`);
   }
 
   /**
@@ -162,22 +158,16 @@ export class Templates extends APIResource {
    * });
    * ```
    */
-  async preview<T = any>(
-    templateName: string,
-    context: { lead?: any; vars?: any },
-  ) {
-    return this.post<T>(
-      `/api/saas/chat/templates/${encodeURIComponent(templateName)}/preview`,
-      { context },
-    );
+  async preview<T = any>(templateName: string, context: { lead?: any; vars?: any }) {
+    return this.post<T>(`/api/saas/chat/templates/${encodeURIComponent(templateName)}/preview`, {
+      context,
+    });
   }
 
   /**
    * Check which automations or sequences are currently using this template.
    */
   async checkUsage<T = any>(templateName: string) {
-    return this.get<T>(
-      `/api/saas/chat/templates/${encodeURIComponent(templateName)}/usage`,
-    );
+    return this.get<T>(`/api/saas/chat/templates/${encodeURIComponent(templateName)}/usage`);
   }
 }