@ecodrix/erix-api 1.1.4 → 1.1.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecodrix/erix-api",
-  "version": "1.1.4",
+  "version": "1.1.5",
   "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/resources/crm/activities.ts

@@ -17,13 +17,28 @@ export interface LogCallParams {
 export class Notes extends APIResource {
   /**
    * List all notes for a specific lead.
+   *
+   * @param leadId - The unique ID of the lead.
+   * @example
+   * ```typescript
+   * const notes = await erixClient.crm.activities.notes.list("lead_123");
+   * ```
    */
   async list<T = any>(leadId: string) {
     return this.get<T>(`/api/crm/leads/${leadId}/notes`);
   }
 
   /**
-   * Add a note to a lead.
+   * Add a new descriptive note to a lead's profile.
+   *
+   * @param leadId - The unique ID of the lead.
+   * @param params - The note content.
+   * @example
+   * ```typescript
+   * await erixClient.crm.activities.notes.create("lead_123", {
+   *   content: "Customer is interested in the enterprise plan."
+   * });
+   * ```
    */
   async create<T = any>(leadId: string, params: { content: string }) {
     return this.post<T>(`/api/crm/leads/${leadId}/notes`, params);
@@ -60,9 +75,19 @@ export class Activities extends APIResource {
   }
 
   /**
-   * Retrieve the complete chronological timeline for a lead.
+   * Retrieve the complete chronological timeline of all activities for a lead.
+   *
+   * @param leadId - The unique ID of the lead.
+   * @param params - Optional pagination parameters.
+   * @example
+   * ```typescript
+   * 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);
   }
 
@@ -74,7 +99,18 @@ export class Activities extends APIResource {
   }
 
   /**
-   * Generic method to log a business activity/event.
+   * Generic method to log a business activity/event (e.g., system events, manual tasks).
+   *
+   * @param params - Activity details (leadId, type, title, body).
+   * @example
+   * ```typescript
+   * await erixClient.crm.activities.log({
+   *   leadId: "lead_123",
+   *   type: "system",
+   *   title: "Meeting Scheduled",
+   *   body: "Initial consultation booked for Friday."
+   * });
+   * ```
    */
   async log<T = any>(params: LogActivityParams) {
     return this.post<T>(`/api/crm/leads/${params.leadId}/activities`, params);

package/src/resources/crm/analytics.ts

@@ -11,17 +11,34 @@ export interface AnalyticsParams {
 
 export class Analytics extends APIResource {
   /**
-   * KPIs: total leads, pipeline value, won revenue, avg score, conversion rate.
+   * 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.
+   * @example
+   * ```typescript
+   * const stats = await erixClient.crm.analytics.overview({ range: "30d" });
+   * ```
    */
   async overview<T = any>(params?: AnalyticsParams) {
     return this.get<T>("/api/crm/analytics/overview", { params } as any);
   }
 
   /**
-   * Stage-by-stage lead counts and conversion percentages.
+   * Get stage-by-stage lead counts and conversion percentages for a pipeline.
+   * Useful for identifying funnel bottlenecks.
+   *
+   * @param pipelineId - The unique ID of the pipeline to analyze.
+   * @example
+   * ```typescript
+   * const funnel = await erixClient.crm.analytics.funnel("pipe_123");
+   * ```
    */
   async funnel<T = any>(pipelineId: string) {
-    return this.get<T>("/api/crm/analytics/funnel", { params: { pipelineId } } as any);
+    return this.get<T>("/api/crm/analytics/funnel", {
+      params: { pipelineId },
+    } as any);
   }
 
   /**
@@ -81,7 +98,13 @@ export class Analytics extends APIResource {
   }
 
   /**
-   * WhatsApp volume and delivery analytics.
+   * Retrieve WhatsApp messaging volume and delivery performance analytics.
+   *
+   * @param params - Optional filters (time range).
+   * @example
+   * ```typescript
+   * const waStats = await erixClient.crm.analytics.whatsapp({ range: "7d" });
+   * ```
    */
   async whatsapp<T = any>(params?: AnalyticsParams) {
     return this.get<T>("/api/crm/analytics/whatsapp", { params } as any);

package/src/resources/crm/automationDashboard.ts

@@ -2,21 +2,39 @@ import { APIResource } from "../../resource";
 
 export class AutomationDashboard extends APIResource {
   /**
-   * Retrieve summary statistics for automation health.
+   * Retrieve summary statistics for automation health (total, success, failed).
+   *
+   * @returns Stats object.
+   * @example
+   * ```typescript
+   * const stats = await erixClient.crm.automationDashboard.stats();
+   * ```
    */
   async stats<T = any>() {
     return this.get<T>("/api/crm/automation/stats");
   }
 
   /**
-   * List recent EventLog entries (automation logs).
+   * List recent EventLog entries representing automation executions.
+   *
+   * @param params - Optional filters (limit, status).
+   * @example
+   * ```typescript
+   * const logs = await erixClient.crm.automationDashboard.logs({ status: "failed" });
+   * ```
    */
   async logs<T = any>(params?: { limit?: number; status?: string }) {
     return this.get<T>("/api/crm/automation/logs", { params } as any);
   }
 
   /**
-   * Re-emit a failed event log to process its automations again.
+   * Re-emit a failed event log to re-trigger its associated automation rules.
+   *
+   * @param logId - The unique ID of the failed event log.
+   * @example
+   * ```typescript
+   * await erixClient.crm.automationDashboard.retryFailedEvent("log_123");
+   * ```
    */
   async retryFailedEvent<T = any>(logId: string) {
     return this.post<T>(`/api/crm/automation/logs/${logId}/retry`, {});

package/src/resources/crm/automations.ts

@@ -10,14 +10,32 @@ export interface AutomationRulePayload {
 
 export class Automations extends APIResource {
   /**
-   * List all automation rules for the tenant.
+   * List all automation rules (workflows) configured for the tenant.
+   *
+   * @returns Array of automation rule objects.
+   * @example
+   * ```typescript
+   * const rules = await erixClient.crm.automations.list();
+   * ```
    */
   async list<T = any>() {
     return this.get<T>("/api/crm/automations");
   }
 
   /**
-   * Create a new automation rule.
+   * Create a new automation rule with triggers and workflow nodes.
+   *
+   * @param payload - The automation rule definition (trigger, nodes, edges).
+   * @returns The created automation rule.
+   * @example
+   * ```typescript
+   * await erixClient.crm.automations.create({
+   *   name: "Welcome Email Workflow",
+   *   trigger: "contact_created",
+   *   nodes: [...],
+   *   edges: [...]
+   * });
+   * ```
    */
   async create<T = any>(payload: AutomationRulePayload) {
     return this.post<T>("/api/crm/automations", payload);
@@ -53,7 +71,14 @@ export class Automations extends APIResource {
   }
 
   /**
-   * Dry-run test an automation rule against a specific lead.
+   * Dry-run test an automation rule against a specific lead to verify logic.
+   *
+   * @param ruleId - The ID of the rule to test.
+   * @param leadId - The ID of the lead to run the test against.
+   * @example
+   * ```typescript
+   * await erixClient.crm.automations.test("rule_123", "lead_456");
+   * ```
    */
   async test<T = any>(ruleId: string, leadId: string) {
     return this.post<T>(`/api/crm/automations/${ruleId}/test`, { leadId });

package/src/resources/crm/leads.ts

@@ -100,16 +100,31 @@ export class Leads extends APIResource {
    *
    * @param params - Lead creation parameters. `firstName` is required.
    * @returns The newly created Lead document.
+   * @example
+   * ```typescript
+   * const lead = await erixClient.crm.leads.create({
+   *   firstName: "Alice",
+   *   phone: "+919876543210",
+   *   source: "website"
+   * });
+   * ```
    */
   async create<T = any>(params: CreateLeadParams) {
     return this.post<T>("/api/crm/leads", params);
   }
 
   /**
-   * Upsert a lead by phone number. Creates if not exists, updates if exists.
+   * Upsert a lead by phone number. If a lead with the same phone exists,
+   * it will be updated; otherwise, a new lead is created.
    *
    * @param params - Upsert parameters containing leadData with a phone number.
    * @returns The newly created or updated Lead document.
+   * @example
+   * ```typescript
+   * await erixClient.crm.leads.upsert({
+   *   leadData: { phone: "+919876543210", firstName: "Alice" }
+   * });
+   * ```
    */
   async upsert<T = any>(params: UpsertLeadParams) {
     return this.post<T>("/api/crm/leads/upsert", params);
@@ -154,10 +169,18 @@ export class Leads extends APIResource {
   }
 
   /**
-   * List leads with optional filtering and pagination.
+   * List CRM leads with optional filtering and pagination.
    *
    * @param params - Filter options (status, source, pipelineId, page, limit, etc.)
    * @returns Paginated list of Lead documents.
+   * @example
+   * ```typescript
+   * const leads = await erixClient.crm.leads.list({
+   *   status: "new",
+   *   source: "website",
+   *   limit: 20
+   * });
+   * ```
    */
   async list<T = any>(params?: ListLeadsParams) {
     const queryParams = { ...params } as any;
@@ -219,6 +242,10 @@ export class Leads extends APIResource {
    *
    * @param leadId - The MongoDB ObjectId of the lead.
    * @returns The Lead document, or a 404 error if not found.
+   * @example
+   * ```typescript
+   * const lead = await erixClient.crm.leads.retrieve("64abc...");
+   * ```
    */
   async retrieve<T = any>(leadId: string) {
     return this.get<T>(`/api/crm/leads/${leadId}`);
@@ -252,6 +279,13 @@ export class Leads extends APIResource {
    * @param leadId - The ID of the lead to update.
    * @param params - Partial lead fields to update.
    * @returns The updated Lead document.
+   * @example
+   * ```typescript
+   * await erixClient.crm.leads.update("64abc...", {
+   *   lastName: "Smith",
+   *   status: "qualified"
+   * });
+   * ```
    */
   async update<T = any>(leadId: string, params: Partial<CreateLeadParams>) {
     return this.patch<T>(`/api/crm/leads/${leadId}`, params);

package/src/resources/crm/payments.ts

@@ -2,7 +2,18 @@ import { APIResource } from "../../resource";
 
 export class Payments extends APIResource {
   /**
-   * Record an inbound payment against a lead or appointment.
+   * Record an inbound payment/transaction against a lead or specific appointment.
+   *
+   * @param payload - Payment details (leadId, amount, currency, description).
+   * @example
+   * ```typescript
+   * await erixClient.crm.payments.capture({
+   *   leadId: "lead_123",
+   *   amount: 5000,
+   *   currency: "INR",
+   *   description: "Consultation Fee"
+   * });
+   * ```
    */
   async capture<T = any>(payload: {
     leadId: string;

package/src/resources/crm/pipelines.ts

@@ -14,21 +14,43 @@ export interface PipelineStageParams {
 
 export class Pipelines extends APIResource {
   /**
-   * List all pipelines and their stages.
+   * List all CRM pipelines and their configured stages.
+   *
+   * @returns Array of pipeline objects with nested stages.
+   * @example
+   * ```typescript
+   * const pipelines = await erixClient.crm.pipelines.list();
+   * ```
    */
   async list<T = any>() {
     return this.get<T>("/api/crm/pipelines");
   }
 
   /**
-   * Create a new pipeline.
+   * Create a new CRM sales or support pipeline.
+   *
+   * @param payload - Pipeline details (name and array of stage names).
+   * @returns The created pipeline record.
+   * @example
+   * ```typescript
+   * await erixClient.crm.pipelines.create({
+   *   name: "Sales Pipeline",
+   *   stages: ["Lead", "Contacted", "Proposal", "Negotiation", "Closed"]
+   * });
+   * ```
    */
   async create<T = any>(payload: { name: string; stages: string[] }) {
     return this.post<T>("/api/crm/pipelines", payload);
   }
 
   /**
-   * Retrieve a single pipeline by ID.
+   * Retrieve a single pipeline configuration by ID.
+   *
+   * @param pipelineId - The unique ID of the pipeline.
+   * @example
+   * ```typescript
+   * const pipeline = await erixClient.crm.pipelines.retrieve("pipe_123");
+   * ```
    */
   async retrieve<T = any>(pipelineId: string) {
     return this.get<T>(`/api/crm/pipelines/${pipelineId}`);
@@ -71,6 +93,12 @@ export class Pipelines extends APIResource {
 
   /**
    * Retrieve a Kanban-style board representation of the pipeline with leads nested.
+   *
+   * @param pipelineId - The unique ID of the pipeline.
+   * @example
+   * ```typescript
+   * const board = await erixClient.crm.pipelines.board("pipe_123");
+   * ```
    */
   async board<T = any>(pipelineId: string) {
     return this.get<T>(`/api/crm/pipelines/${pipelineId}/board`);
@@ -87,6 +115,17 @@ export class Pipelines extends APIResource {
 
   /**
    * Add a new stage to the pipeline.
+   *
+   * @param pipelineId - The unique ID of the pipeline.
+   * @param params - Stage details (name, color, probability).
+   * @example
+   * ```typescript
+   * await erixClient.crm.pipelines.addStage("pipe_123", {
+   *   name: "Decision Maker Bought In",
+   *   color: "#FF5733",
+   *   probability: 80
+   * });
+   * ```
    */
   async addStage<T = any>(pipelineId: string, params: PipelineStageParams) {
     return this.post<T>(`/api/crm/pipelines/${pipelineId}/stages`, params);
@@ -109,7 +148,10 @@ export class Pipelines extends APIResource {
   }
 
   /**
-   * Delete a stage. Optionally provide a fallback stageId to move active leads to.
+   * Delete a stage permanently.
+   *
+   * @param stageId - The unique ID of the stage to delete.
+   * @param moveLeadsToStageId - Optional fallback stageId to move active leads to before deletion.
    */
   async deleteStage(stageId: string, moveLeadsToStageId?: string) {
     return this.deleteRequest(`/api/crm/stages/${stageId}`, {

package/src/resources/crm/scoring.ts

@@ -11,7 +11,13 @@ export interface ScoringConfig {
 
 export class Scoring extends APIResource {
   /**
-   * Retrieve the tenant's global lead scoring configuration.
+   * Retrieve the tenant's global lead scoring configuration (rules, decay, thresholds).
+   *
+   * @returns The scoring configuration object.
+   * @example
+   * ```typescript
+   * const config = await erixClient.crm.scoring.getConfig();
+   * ```
    */
   async getConfig<T = any>() {
     return this.get<T>("/api/crm/scoring");
@@ -25,7 +31,14 @@ export class Scoring extends APIResource {
   }
 
   /**
-   * Force recalculate the score for a specific lead.
+   * Force an immediate score recalculation for a specific lead.
+   * Useful when profile data changes significantly.
+   *
+   * @param leadId - The unique ID of the lead.
+   * @example
+   * ```typescript
+   * await erixClient.crm.scoring.recalculate("lead_123");
+   * ```
    */
   async recalculate<T = any>(leadId: string) {
     return this.post<T>(`/api/crm/scoring/${leadId}/recalculate`, {});

package/src/resources/crm/sequences.ts

@@ -2,7 +2,17 @@ import { APIResource } from "../../resource";
 
 export class Sequences extends APIResource {
   /**
-   * Manually enroll a lead in a drip sequence (automation rule).
+   * Manually enroll a lead into a specific automation drip sequence (Workflow).
+   *
+   * @param payload - Enrollment details (leadId, ruleId, and custom variables).
+   * @example
+   * ```typescript
+   * await erixClient.crm.sequences.enroll({
+   *   leadId: "lead_123",
+   *   ruleId: "rule_456",
+   *   variables: { start_date: "2026-05-01" }
+   * });
+   * ```
    */
   async enroll<T = any>(payload: {
     leadId: string;
@@ -13,17 +23,29 @@ export class Sequences extends APIResource {
   }
 
   /**
-   * Unenroll a lead from a running sequence.
+   * Unenroll a lead from a currently running automation sequence.
+   *
+   * @param enrollmentId - The unique ID of the sequence enrollment.
+   * @example
+   * ```typescript
+   * await erixClient.crm.sequences.unenroll("enroll_123");
+   * ```
    */
   async unenroll<T = any>(enrollmentId: string) {
     return this.deleteRequest(`/api/crm/sequences/unenroll/${enrollmentId}`);
   }
 
   /**
-   * List active sequence enrollments for a specific lead.
+   * List all active and completed sequence enrollments for a specific lead.
+   *
+   * @param leadId - The unique ID of the lead.
+   * @returns Array of enrollment records.
+   * @example
+   * ```typescript
+   * const enrollments = await erixClient.crm.sequences.listForLead("lead_123");
+   * ```
    */
   async listForLead<T = any>(leadId: string) {
     return this.get<T>(`/api/crm/sequences/lead/${leadId}`);
   }
-
 }

package/src/resources/email.ts

@@ -28,17 +28,31 @@ export class EmailResource extends APIResource {
    * Send an HTML email campaign to a list of recipients.
    *
    * @param payload - The campaign details (recipients, subject, html).
-   * @returns The dispatch result.
+   * @returns The dispatch result indicating success or failure.
+   * @example
+   * ```typescript
+   * await erixClient.email.sendEmailCampaign({
+   *   recipients: ["user1@example.com", "user2@example.com"],
+   *   subject: "Monthly Newsletter",
+   *   html: "<h1>Hello!</h1><p>Check out our latest updates...</p>"
+   * });
+   * ```
    */
-  async sendEmailCampaign(payload: SendCampaignPayload): Promise<CampaignResult> {
+  async sendEmailCampaign(
+    payload: SendCampaignPayload,
+  ): Promise<CampaignResult> {
     return this.post<CampaignResult>("/api/saas/emails/campaign", payload);
   }
 
   /**
-   * Send a system verification/test email to validate SMTP configuration.
+   * Send a system test email to validate your current SMTP configuration.
    *
    * @param to - The recipient's email address.
    * @returns The dispatch result.
+   * @example
+   * ```typescript
+   * await erixClient.email.sendTestEmail("admin@company.com");
+   * ```
    */
   async sendTestEmail(to: string): Promise<CampaignResult> {
     return this.post<CampaignResult>("/api/saas/emails/test", { to });

package/src/resources/events.ts

@@ -94,10 +94,18 @@ export interface TriggerResponse {
 
 export class EventsResource extends APIResource {
   /**
-   * Retrieve all valid events (system + custom) that can be used as Automation Rule triggers.
+   * List all available event definitions (both system and custom) that can trigger automations.
+   *
+   * @returns Array of event definitions.
+   * @example
+   * ```typescript
+   * const events = await erixClient.events.list();
+   * ```
    */
   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",
+    );
   }
 
   /**
@@ -128,8 +136,20 @@ export class EventsResource extends APIResource {
   }
 
   /**
-   * Programmatically fire an event into the CRM automation engine.
-   * Emits to the internal EventBus to match with active Workflow Automation Rules.
+   * Programmatically trigger an automation workflow by firing a specific event.
+   * This matches the event against active Automation Rules and executes linked actions.
+   *
+   * @param payload - The trigger details (event name, lead phone/email, variables).
+   * @returns Trigger response with diagnostic info (eventLogId, matched rules).
+   * @example
+   * ```typescript
+   * await erixClient.events.trigger({
+   *   trigger: "webinar_joined",
+   *   phone: "+919876543210",
+   *   variables: { webinar_name: "AI Masterclass" },
+   *   createLeadIfMissing: true
+   * });
+   * ```
    */
   async trigger(payload: TriggerPayload): Promise<TriggerResponse> {
     return this.post<TriggerResponse>("/api/saas/workflows/trigger", payload);

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;
   }
 }