@ecodrix/erix-api 1.0.1 → 1.0.3

package/src/resources/crm/automations.ts

@@ -0,0 +1,145 @@
+import { APIResource } from "../../resource";
+
+export interface AutomationRulePayload {
+  name: string;
+  trigger: string;
+  isActive?: boolean;
+  nodes: any[];
+  edges: any[];
+}
+
+export class Automations extends APIResource {
+  /**
+   * List all automation rules for the tenant.
+   */
+  async list<T = any>() {
+    return this.get<T>("/api/saas/crm/automations");
+  }
+
+  /**
+   * Create a new automation rule.
+   */
+  async create<T = any>(payload: AutomationRulePayload) {
+    return this.post<T>("/api/saas/crm/automations", payload);
+  }
+
+  /**
+   * Update an existing automation rule.
+   */
+  async update<T = any>(ruleId: string, payload: Partial<AutomationRulePayload>) {
+    return this.patch<T>(`/api/saas/crm/automations/${ruleId}`, payload as any);
+  }
+
+  /**
+   * Enable or disable an automation rule.
+   */
+  async toggle<T = any>(ruleId: string) {
+    return this.patch<T>(`/api/saas/crm/automations/${ruleId}/toggle`);
+  }
+
+  /**
+   * Delete an automation rule.
+   */
+  async deleteRule<T = any>(ruleId: string) {
+    return this.deleteRequest<T>(`/api/saas/crm/automations/${ruleId}`);
+  }
+
+  /**
+   * Bulk delete rules.
+   */
+  async bulkDelete<T = any>(ruleIds: string[]) {
+    return this.post<T>("/api/saas/crm/automations/bulk-delete", { ids: ruleIds });
+  }
+
+  /**
+   * Dry-run test an automation rule against a specific lead.
+   */
+  async test<T = any>(ruleId: string, leadId: string) {
+    return this.post<T>(`/api/saas/crm/automations/${ruleId}/test`, { leadId });
+  }
+
+  /**
+   * Get available event triggers for automations.
+   */
+  async getAvailableEvents<T = any>() {
+    return this.post<T>("/api/saas/crm/automations/events", {});
+  }
+
+  /**
+   * List enrollments for a rule.
+   */
+  async enrollments<T = any>(
+    ruleId: string,
+    params?: {
+      status?: string;
+      page?: number;
+      limit?: number;
+      startDate?: string;
+      endDate?: string;
+    }
+  ) {
+    return this.get<T>(`/api/saas/crm/automations/${ruleId}/enrollments`, { params });
+  }
+
+  /**
+   * Get an enrollment detail.
+   */
+  async getEnrollment<T = any>(enrollmentId: string) {
+    return this.get<T>(`/api/saas/crm/automations/enrollments/${enrollmentId}`);
+  }
+
+  /**
+   * Pause an enrollment.
+   */
+  async pauseEnrollment<T = any>(ruleId: string, enrollmentId: string) {
+    return this.post<T>(`/api/saas/crm/automations/${ruleId}/enrollments/${enrollmentId}/pause`, {});
+  }
+
+  /**
+   * Resume an enrollment.
+   */
+  async resumeEnrollment<T = any>(ruleId: string, enrollmentId: string) {
+    return this.post<T>(`/api/saas/crm/automations/${ruleId}/enrollments/${enrollmentId}/resume`, {});
+  }
+
+  /**
+   * List workflow runs.
+   */
+  async runs<T = any>(ruleId: string) {
+    return this.get<T>(`/api/saas/crm/automations/${ruleId}/runs`);
+  }
+
+  /**
+   * Get run details.
+   */
+  async getRun<T = any>(runId: string) {
+    return this.get<T>(`/api/saas/crm/automations/runs/${runId}`);
+  }
+
+  /**
+   * Resume a paused run.
+   */
+  async resumeRun<T = any>(runId: string) {
+    return this.post<T>(`/api/saas/crm/automations/runs/${runId}/resume`, {});
+  }
+
+  /**
+   * Abort a running workflow.
+   */
+  async abortRun<T = any>(runId: string) {
+    return this.post<T>(`/api/saas/crm/automations/runs/${runId}/abort`, {});
+  }
+
+  /**
+   * Emit an external webhook event to unlock a `wait_event` node inside a
+   * paused workflow run. Required when integrating third-party tools that
+   * need to resume a suspended automation.
+   *
+   * @param ruleId - The automation rule that contains the wait_event node.
+   * @param eventName - The event name that should match the node's condition.
+   * @param payload - Arbitrary data forwarded to the node context.
+   */
+  async webhookEvent<T = any>(ruleId: string, eventName: string, payload?: any) {
+    return this.post<T>("/api/saas/crm/webhook-event", { ruleId, eventName, payload });
+  }
+}

package/src/resources/crm/index.ts

@@ -1,10 +1,34 @@
 import { Leads } from "./leads";
+import { Pipelines } from "./pipelines";
+import { Activities } from "./activities";
+import { Analytics } from "./analytics";
+import { Automations } from "./automations";
+import { Sequences } from "./sequences";
+import { Scoring } from "./scoring";
+import { Payments } from "./payments";
+import { AutomationDashboard } from "./automationDashboard";
 import type { AxiosInstance } from "axios";
 
 export class CRM {
   public leads: Leads;
+  public pipelines: Pipelines;
+  public activities: Activities;
+  public analytics: Analytics;
+  public automations: Automations;
+  public sequences: Sequences;
+  public scoring: Scoring;
+  public payments: Payments;
+  public automationDashboard: AutomationDashboard;
 
   constructor(client: AxiosInstance) {
     this.leads = new Leads(client);
+    this.pipelines = new Pipelines(client);
+    this.activities = new Activities(client);
+    this.analytics = new Analytics(client);
+    this.automations = new Automations(client);
+    this.sequences = new Sequences(client);
+    this.scoring = new Scoring(client);
+    this.payments = new Payments(client);
+    this.automationDashboard = new AutomationDashboard(client);
   }
 }

package/src/resources/crm/leads.ts

@@ -1,5 +1,15 @@
 import { APIResource } from "../../resource";
 
+/**
+ * Valid statuses for a CRM Lead.
+ */
+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;
+
 /**
  * Parameters for creating a new CRM Lead.
  */
@@ -14,11 +24,49 @@ export interface CreateLeadParams {
   phone?: string;
   /**
    * Acquisition channel.
-   * @example "website" | "whatsapp" | "direct" | "referral"
    */
-  source?: string;
+  source?: LeadSource;
   /** Arbitrary key-value metadata (UTM params, order IDs, etc.). */
   metadata?: Record<string, any>;
+  /** Pipeline ID to assign the lead */
+  pipelineId?: string;
+  /** Stage ID to assign the lead */
+  stageId?: string;
+}
+
+/**
+ * Options for listing leads.
+ */
+export interface ListLeadsParams {
+  status?: LeadStatus;
+  pipelineId?: string;
+  stageId?: string;
+  source?: LeadSource;
+  assignedTo?: string;
+  tags?: string[] | string;
+  minScore?: number;
+  search?: string;
+  startDate?: string;
+  endDate?: string;
+  appointmentId?: string;
+  bookingId?: string;
+  orderId?: string;
+  meetingId?: string;
+  page?: number;
+  limit?: number;
+  sortBy?: string;
+  sortDir?: "asc" | "desc";
+}
+
+/**
+ * Options for upserting a lead.
+ */
+export interface UpsertLeadParams {
+  leadData: Partial<CreateLeadParams> & { phone: string; name?: string };
+  moduleInfo?: any;
+  trigger?: string;
+  pipelineId?: string;
+  stageId?: string;
 }
 
 /**
@@ -41,19 +89,21 @@ export class Leads extends APIResource {
    *
    * @param params - Lead creation parameters. `firstName` is required.
    * @returns The newly created Lead document.
-   *
-   * @example
-   * ```typescript
-   * const { data } = await ecod.crm.leads.create({
-   *   firstName: "Alice",
-   *   phone: "+919876543210",
-   * });
-   * ```
    */
   async create<T = any>(params: CreateLeadParams) {
     return this.post<T>("/api/services/leads", params);
   }
 
+  /**
+   * Upsert a lead by phone number. Creates if not exists, updates if exists.
+   *
+   * @param params - Upsert parameters containing leadData with a phone number.
+   * @returns The newly created or updated Lead document.
+   */
+  async upsert<T = any>(params: UpsertLeadParams) {
+    return this.post<T>("/api/services/leads/upsert", params);
+  }
+
   /**
    * Bulk ingest leads efficiently in parallel using automatic chunking.
    * Prevents rate limit exhaustion by executing `chunkSize` requests at a time.
@@ -83,38 +133,46 @@ export class Leads extends APIResource {
     return results;
   }
 
+  /**
+   * Bulk upsert (import) leads.
+   *
+   * @param leads - Array of leads to import.
+   */
+  async import<T = any>(leads: Partial<CreateLeadParams>[]) {
+    return this.post<T>("/api/services/leads/import", { leads });
+  }
+
   /**
    * List 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 { data } = await ecod.crm.leads.list({ status: "new", limit: 25 });
-   * ```
    */
-  async list<T = any>(params?: Record<string, any>) {
-    return this.get<T>("/api/services/leads", { params } as any);
+  async list<T = any>(params?: ListLeadsParams) {
+    let queryParams = { ...params } as any;
+    if (Array.isArray(queryParams.tags)) {
+      queryParams.tags = queryParams.tags.join(",");
+    }
+    return this.get<T>("/api/services/leads", { params: queryParams } as any);
   }
 
   /**
    * Auto-paginating iterator for leads.
    * Seamlessly fetches leads page by page as you iterate.
-   *
+   * 
    * @example
    * ```typescript
-   * for await (const lead of ecod.crm.leads.listAutoPaging({ status: "won" })) {
+   * for await (const lead of ecod.crm.leads.listAutoPaging<Lead>()) {
    *   console.log(lead.firstName);
    * }
    * ```
    */
-  async *listAutoPaging(params?: Record<string, any>): AsyncGenerator<any, void, unknown> {
+  async *listAutoPaging<T = any>(params?: ListLeadsParams): AsyncGenerator<T, void, unknown> {
     let currentPage = params?.page || 1;
     let hasMore = true;
 
     while (hasMore) {
-      const response: any = await this.list({ ...params, page: currentPage });
+      const response: any = await this.list<any>({ ...params, page: currentPage });
       
       const items = Array.isArray(response.data) ? response.data : response || [];
       
@@ -124,7 +182,7 @@ export class Leads extends APIResource {
       }
 
       for (const item of items) {
-        yield item;
+        yield item as T;
       }
 
       if (response.pagination && currentPage < response.pagination.pages) {
@@ -143,14 +201,29 @@ export class Leads extends APIResource {
    *
    * @param leadId - The MongoDB ObjectId of the lead.
    * @returns The Lead document, or a 404 error if not found.
+   */
+  async retrieve<T = any>(leadId: string) {
+    return this.get<T>(`/api/services/leads/${leadId}`);
+  }
+
+  /**
+   * Retrieve a single lead by its phone number.
    *
-   * @example
-   * ```typescript
-   * const { data } = await ecod.crm.leads.retrieve("64abc...");
-   * ```
+   * @param phone - Lead's phone number.
    */
-  async retrieve(leadId: string) {
-    return this.get(`/api/services/leads/${leadId}`);
+  async retrieveByPhone<T = any>(phone: string) {
+    // URL-encode the phone to handle '+' safe
+    return this.get<T>(`/api/services/leads/phone/${encodeURIComponent(phone)}`);
+  }
+
+  /**
+   * Retrieve a single lead by a reference key and value.
+   *
+   * @param refKey - Reference key metadata.
+   * @param refValue - Reference value.
+   */
+  async retrieveByRef<T = any>(refKey: string, refValue: string) {
+    return this.get<T>(`/api/services/leads/ref/${encodeURIComponent(refKey)}/${encodeURIComponent(refValue)}`);
   }
 
   /**
@@ -159,28 +232,83 @@ 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 ecod.crm.leads.update("64abc...", { email: "new@email.com" });
-   * ```
    */
-  async update(leadId: string, params: Partial<CreateLeadParams>) {
-    return this.post(`/api/services/leads/${leadId}`, params);
+  async update<T = any>(leadId: string, params: Partial<CreateLeadParams>) {
+    return this.post<T>(`/api/services/leads/${leadId}`, params);
+  }
+
+  /**
+   * Move a lead to a new stage in a pipeline.
+   * 
+   * @param leadId - ID of the lead.
+   * @param stageId - Target stage ID.
+   */
+  async move<T = any>(leadId: string, stageId: string) {
+    return this.patch<T>(`/api/services/leads/${leadId}/move`, { stageId });
+  }
+
+  /**
+   * Convert a lead (mark as won or lost with reason).
+   * 
+   * @param leadId - ID of the lead.
+   * @param outcome - "won" | "lost"
+   * @param reason - Reason for the outcome.
+   */
+  async convert<T = any>(leadId: string, outcome: "won" | "lost", reason?: string) {
+    return this.post<T>(`/api/services/leads/${leadId}/convert`, { outcome, reason });
+  }
+
+  /**
+   * Update the tags of a lead.
+   * 
+   * @param leadId - ID of the lead.
+   * @param options - Tags to add or remove.
+   */
+  async tags<T = any>(leadId: string, options: { add?: string[]; remove?: string[] }) {
+    return this.patch<T>(`/api/services/leads/${leadId}/tags`, options);
   }
 
   /**
-   * Archive (soft-delete) a lead. The record is retained in the database
-   * for audit purposes but is excluded from all standard list views.
+   * Recalculate lead score based on activities and interactions.
+   * 
+   * @param leadId - ID of the lead.
+   */
+  async recalculateScore<T = any>(leadId: string) {
+    return this.post<T>(`/api/services/leads/${leadId}/score`, {});
+  }
+
+  /**
+   * Update embedded metadata/references of a lead without touching core fields.
+   * 
+   * @param leadId - ID of the lead.
+   * @param metadata - Metadata object indicating { refs, extra }
+   */
+  async updateMetadata<T = any>(leadId: string, metadata: { refs?: Record<string, any>; extra?: Record<string, any> }) {
+    return this.patch<T>(`/api/services/leads/${leadId}/metadata`, metadata);
+  }
+
+  /**
+   * Introspect available custom fields configured by the tenant limit.
+   */
+  async fields<T = any>() {
+    return this.get<T>("/api/services/leads/fields");
+  }
+
+  /**
+   * Archive (soft-delete) a single lead.
    *
    * @param leadId - The ID of the lead to archive.
-   *
-   * @example
-   * ```typescript
-   * await ecod.crm.leads.delete("64abc...");
-   * ```
    */
   async delete(leadId: string) {
     return this.deleteRequest(`/api/services/leads/${leadId}`);
   }
+
+  /**
+   * Bulk archive multiple leads.
+   * 
+   * @param ids - Array of lead IDs to archive.
+   */
+  async bulkDelete(ids: string[]) {
+    return this.deleteRequest("/api/services/leads", { data: { ids } });
+  }
 }

package/src/resources/crm/payments.ts

@@ -0,0 +1,10 @@
+import { APIResource } from "../../resource";
+
+export class Payments extends APIResource {
+  /**
+   * Record an inbound payment against a lead or appointment.
+   */
+  async capture<T = any>(payload: { leadId: string; amount: number; currency?: string; description?: string; appointmentId?: string }) {
+    return this.post<T>("/api/saas/crm/payments/capture", payload);
+  }
+}

package/src/resources/crm/pipelines.ts

@@ -0,0 +1,117 @@
+import { APIResource } from "../../resource";
+
+export interface CreatePipelineParams {
+  name: string;
+  isDefault?: boolean;
+  stages?: any[]; // Typically an array of stage objects
+}
+
+export interface PipelineStageParams {
+  name: string;
+  color?: string;
+  probability?: number;
+}
+
+export class Pipelines extends APIResource {
+  /**
+   * List all pipelines matching the optional query parameters.
+   */
+  async list<T = any>(params?: Record<string, any>) {
+    return this.get<T>("/api/saas/crm/pipelines", { params } as any);
+  }
+
+  /**
+   * Create a new pipeline.
+   */
+  async create<T = any>(params: CreatePipelineParams) {
+    return this.post<T>("/api/saas/crm/pipelines", params);
+  }
+
+  /**
+   * Retrieve a single pipeline.
+   */
+  async retrieve<T = any>(pipelineId: string) {
+    return this.get<T>(`/api/saas/crm/pipelines/${pipelineId}`);
+  }
+
+  /**
+   * Update a pipeline's details.
+   */
+  async update<T = any>(pipelineId: string, params: { name?: string; description?: string }) {
+    return this.patch<T>(`/api/saas/crm/pipelines/${pipelineId}`, params);
+  }
+
+  /**
+   * Set pipeline as the tenant's default.
+   */
+  async setDefault<T = any>(pipelineId: string) {
+    return this.post<T>(`/api/saas/crm/pipelines/${pipelineId}/default`, {});
+  }
+
+  /**
+   * Duplicate a pipeline with a new name.
+   */
+  async duplicate<T = any>(pipelineId: string, newName: string) {
+    return this.post<T>(`/api/saas/crm/pipelines/${pipelineId}/duplicate`, { newName });
+  }
+
+  /**
+   * Archive a pipeline.
+   */
+  async archive<T = any>(pipelineId: string) {
+    return this.post<T>(`/api/saas/crm/pipelines/${pipelineId}/archive`, {});
+  }
+
+  /**
+   * Delete a pipeline permanently.
+   */
+  async delete(pipelineId: string) {
+    return this.deleteRequest(`/api/saas/crm/pipelines/${pipelineId}`);
+  }
+
+  /**
+   * Retrieve a Kanban-style board representation of the pipeline with leads nested.
+   */
+  async board<T = any>(pipelineId: string) {
+    return this.get<T>(`/api/saas/crm/pipelines/${pipelineId}/board`);
+  }
+
+  /**
+   * Retrieve a revenue forecast based on stage probabilities for a pipeline.
+   */
+  async forecast<T = any>(pipelineId: string) {
+    return this.get<T>(`/api/saas/crm/pipelines/${pipelineId}/forecast`);
+  }
+
+  // --- Stage Management ---
+
+  /**
+   * Add a new stage to the pipeline.
+   */
+  async addStage<T = any>(pipelineId: string, params: PipelineStageParams) {
+    return this.post<T>(`/api/saas/crm/pipelines/${pipelineId}/stages`, params);
+  }
+
+  /**
+   * Change the order of stages inside the pipeline.
+   */
+  async reorderStages<T = any>(pipelineId: string, orderArray: string[]) {
+    return this.put<T>(`/api/saas/crm/pipelines/${pipelineId}/stages/reorder`, { order: orderArray });
+  }
+
+  /**
+   * Update a specific stage.
+   */
+  async updateStage<T = any>(stageId: string, params: Partial<PipelineStageParams>) {
+    return this.patch<T>(`/api/saas/crm/stages/${stageId}`, params);
+  }
+
+  /**
+   * Delete a stage. Optionally provide a fallback stageId to move active leads to.
+   */
+  async deleteStage(stageId: string, moveLeadsToStageId?: string) {
+    return this.deleteRequest(`/api/saas/crm/stages/${stageId}`, {
+      data: moveLeadsToStageId ? { moveLeadsToStageId } : undefined,
+    });
+  }
+}

package/src/resources/crm/scoring.ts

@@ -0,0 +1,33 @@
+import { APIResource } from "../../resource";
+
+export interface ScoringConfig {
+  decayDays: number;
+  thresholds: {
+    hot: number;
+    warm: number;
+  };
+  rules: any[]; // Specific rule shapes
+}
+
+export class Scoring extends APIResource {
+  /**
+   * Retrieve the tenant's global lead scoring configuration.
+   */
+  async getConfig<T = any>() {
+    return this.get<T>("/api/saas/crm/scoring");
+  }
+
+  /**
+   * Update scoring configuration.
+   */
+  async updateConfig<T = any>(payload: Partial<ScoringConfig>) {
+    return this.patch<T>("/api/saas/crm/scoring", payload as any);
+  }
+
+  /**
+   * Force recalculate the score for a specific lead.
+   */
+  async recalculate<T = any>(leadId: string) {
+    return this.post<T>(`/api/saas/crm/scoring/${leadId}/recalculate`, {});
+  }
+}

package/src/resources/crm/sequences.ts

@@ -0,0 +1,24 @@
+import { APIResource } from "../../resource";
+
+export class Sequences extends APIResource {
+  /**
+   * Manually enroll a lead in a drip sequence (automation rule).
+   */
+  async enroll<T = any>(payload: { leadId: string; ruleId: string; variables?: Record<string, any> }) {
+    return this.post<T>("/api/saas/crm/sequences/enroll", payload);
+  }
+
+  /**
+   * Unenroll a lead from a running sequence.
+   */
+  async unenroll<T = any>(enrollmentId: string) {
+    return this.deleteRequest<T>(`/api/saas/crm/sequences/unenroll/${enrollmentId}`);
+  }
+
+  /**
+   * List active sequence enrollments for a specific lead.
+   */
+  async listForLead<T = any>(leadId: string) {
+    return this.get<T>(`/api/saas/crm/sequences/lead/${leadId}`);
+  }
+}