@ecodrix/erix-api 1.0.0 → 1.0.3

package/src/cli.ts

@@ -0,0 +1,318 @@
+import { Command } from "commander";
+import dotenv from "dotenv";
+import pc from "picocolors";
+import repl from "node:repl";
+import { Ecodrix } from "./core";
+
+// Setup environment
+dotenv.config();
+
+// Build-time constants injected by tsup
+declare const process: any;
+const VERSION = process.env.SDK_VERSION || "1.0.2";
+const NAME = process.env.SDK_NAME || "@ecodrix/erix-api";
+const DESCRIPTION = process.env.SDK_DESCRIPTION || "Official ECODrIx SDK CLI";
+
+const program = new Command();
+
+program.name("erix").description(DESCRIPTION).version(VERSION);
+
+/**
+ * Helper to initialize the Ecodrix client from environment or flags.
+ */
+function getClient(options: any): Ecodrix {
+  const apiKey = options.key || process.env.ECOD_API_KEY;
+  const clientCode = options.client || process.env.ECOD_CLIENT_CODE;
+
+  if (!apiKey) {
+    console.error(pc.red("Error: API Key is missing."));
+    console.log(
+      pc.yellow("Set ECOD_API_KEY environment variable or use --key <key>"),
+    );
+    process.exit(1);
+  }
+
+  return new Ecodrix({
+    apiKey,
+    clientCode,
+    baseUrl: options.baseUrl || process.env.ECOD_BASE_URL,
+  });
+}
+
+program
+  .option("-k, --key <key>", "ECODrIx API Key")
+  .option("-c, --client <code...", "Tenant Client Code")
+  .option("--base-url <url>", "API Base URL override");
+
+// --- WHOAMI ---
+program
+  .command("whoami")
+  .description("Verify current authentication and tenant status")
+  .action(async (options, command) => {
+    const globalOptions = command.parent.opts();
+    const ecod = getClient(globalOptions);
+
+    console.log(pc.cyan("Checking connection to ECODrIx Platform..."));
+    try {
+      const me = (await ecod.request("GET", "/api/saas/me/profile")) as any;
+      console.log(pc.green("✔ Authenticated successfully!"));
+      console.log(`${pc.bold("User ID:")} ${me.id}`);
+      console.log(
+        `${pc.bold("Organisation:")} ${me.organisation?.name || "N/A"}`,
+      );
+      if (globalOptions.client) {
+        console.log(
+          `${pc.bold("Tenant Code:")} ${pc.magenta(globalOptions.client)}`,
+        );
+      }
+    } catch (error: any) {
+      console.error(pc.red("✖ Authentication failed"));
+      console.error(pc.dim(error.message));
+      process.exit(1);
+    }
+  });
+
+// --- WHATSAPP ---
+const whatsapp = program
+  .command("whatsapp")
+  .description("WhatsApp Business API operations");
+
+whatsapp
+  .command("send-template")
+  .description("Send a WhatsApp template message")
+  .argument("<phone>", "Recipient phone number")
+  .argument("<template>", "Template name")
+  .option("-v, --vars <json>", "Template variables as JSON string", "[]")
+  .action(async (phone, template, options, command) => {
+    const globalOptions = command.parent.parent.opts();
+    const ecod = getClient(globalOptions);
+
+    try {
+      const vars = JSON.parse(options.vars);
+      console.log(pc.cyan(`Sending template '${template}' to ${phone}...`));
+
+      const result = (await ecod.whatsapp.messages.sendTemplate({
+        to: phone,
+        templateName: template,
+        language: "en_US",
+        variables: vars,
+      })) as any;
+
+      console.log(pc.green("✔ Message sent successfully!"));
+      console.log(pc.dim(`ID: ${result?.id || "N/A"}`));
+    } catch (error: any) {
+      console.error(pc.red("✖ Failed to send message"));
+      console.error(pc.dim(error.message));
+    }
+  });
+
+// --- CRM ---
+const crm = program.command("crm").description("CRM and Lead management");
+
+crm
+  .command("leads")
+  .description("List recent leads")
+  .option("-l, --limit <number>", "Number of leads to fetch", "10")
+  .option("-s, --status <status>", "Filter by lead status")
+  .option("-p, --pipeline <id>", "Filter by pipeline ID")
+  .option("-q, --search <query>", "Search by name or email")
+  .action(async (options, command) => {
+    const globalOptions = command.parent.parent.opts();
+    const ecod = getClient(globalOptions);
+
+    try {
+      const limit = parseInt(options.limit);
+      console.log(pc.cyan(`Fetching last ${limit} leads...`));
+
+      const queryParams: any = { limit };
+      if (options.status) queryParams.status = options.status;
+      if (options.pipeline) queryParams.pipelineId = options.pipeline;
+      if (options.search) queryParams.search = options.search;
+
+      const response: any = await ecod.crm.leads.list(queryParams);
+      const leads = Array.isArray(response.data)
+        ? response.data
+        : Array.isArray(response)
+          ? response
+          : [];
+
+      if (leads.length === 0) {
+        console.log(pc.yellow("No leads found."));
+        return;
+      }
+
+      console.table(
+        leads.map((l: any) => ({
+          ID: l.id || l._id,
+          Name: `${l.firstName} ${l.lastName || ""}`.trim(),
+          Phone: l.phone,
+          Status: l.status,
+          Score: l.score || 0,
+          Created: new Date(l.createdAt).toLocaleDateString(),
+        })),
+      );
+    } catch (error: any) {
+      console.error(pc.red("✖ Failed to fetch leads"));
+      console.error(pc.dim(error.message));
+    }
+  });
+
+crm
+  .command("pipelines")
+  .description("List all CRM pipelines")
+  .action(async (options, command) => {
+    const globalOptions = command.parent.parent.opts();
+    const ecod = getClient(globalOptions);
+
+    try {
+      console.log(pc.cyan("Fetching pipelines..."));
+      const response: any = await ecod.crm.pipelines.list();
+      const pipelines = response.data || response || [];
+
+      if (pipelines.length === 0) {
+        console.log(pc.yellow("No pipelines found."));
+        return;
+      }
+
+      console.table(
+        pipelines.map((p: any) => ({
+          ID: p.id || p._id,
+          Name: p.name,
+          Default: p.isDefault ? "Yes" : "No",
+          Stages: p.stages?.length || 0
+        })),
+      );
+    } catch (error: any) {
+      console.error(pc.red("✖ Failed to fetch pipelines"));
+      console.error(pc.dim(error.message));
+    }
+  });
+
+// --- ANALYTICS ---
+const analytics = program.command("analytics").description("Business Intelligence Analytics");
+
+analytics
+  .command("overview")
+  .description("Get high-level CRM KPIs")
+  .option("-r, --range <range>", "Date range (e.g., 24h, 7d, 30d, 365d)", "30d")
+  .action(async (options, command) => {
+    const globalOptions = command.parent.parent.opts();
+    const ecod = getClient(globalOptions);
+
+    try {
+      console.log(pc.cyan(`Fetching overview metrics for last ${options.range}...`));
+      const response: any = await ecod.crm.analytics.overview({ range: options.range });
+      const data = response.data || response;
+
+      console.log("\n" + pc.bold("OVERVIEW KPIs:"));
+      console.log(`Total Leads:  ${pc.green(data.totalLeads || 0)}`);
+      console.log(`Open Value:   ${pc.yellow("$" + (data.openValue || 0).toLocaleString())}`);
+      console.log(`Won Revenue:  ${pc.green("$" + (data.wonRevenue || 0).toLocaleString())}`);
+      console.log(`Avg Score:    ${pc.blue(data.avgScore?.toFixed(1) || 0)}`);
+      console.log(`Conversion:   ${pc.magenta((data.conversionRate || 0).toFixed(2) + "%")}\n`);
+
+    } catch (error: any) {
+      console.error(pc.red("✖ Failed to fetch analytics overview"));
+      console.error(pc.dim(error.message));
+    }
+  });
+
+// --- WEBHOOKS ---
+const webhooks = program
+  .command("webhooks")
+  .description("Webhook utility tools");
+
+webhooks
+  .command("verify")
+  .description("Verify a cryptographic webhook signature")
+  .argument("<payload>", "The raw request body string")
+  .argument("<signature>", "The 'x-ecodrix-signature' header value")
+  .argument("<secret>", "Your webhook signing secret")
+  .action(async (payload, signature, secret, options, command) => {
+    const globalOptions = command.parent.parent.opts();
+    const ecod = getClient(globalOptions);
+
+    try {
+      await ecod.webhooks.constructEvent(payload, signature, secret);
+      console.log(pc.green("✔ Signature is VALID"));
+    } catch (error: any) {
+      console.error(pc.red("✖ Error during verification"));
+      console.error(pc.dim(error.message));
+    }
+  });
+
+// --- SHELL (REPL) ---
+program
+  .command("shell")
+  .alias("repl")
+  .description("Start an interactive SDK shell")
+  .action(async (options, command) => {
+    const globalOptions = command.parent.opts();
+    const ecod = getClient(globalOptions);
+
+    console.log(pc.magenta(pc.bold("\nWelcome to the Erix Interactive Shell")));
+    console.log(pc.dim(`SDK Version: ${VERSION}`));
+    console.log(pc.dim("The 'ecod' client is pre-initialized and ready.\n"));
+
+    const r = repl.start({
+      prompt: pc.cyan("erix > "),
+      useColors: true,
+    });
+
+    // Load resources into REPL context for immediate access
+    r.context.ecod = ecod;
+    r.context.whatsapp = ecod.whatsapp;
+    r.context.crm = ecod.crm;
+    r.context.meet = ecod.meet;
+    r.context.media = ecod.media;
+
+    r.on("exit", () => {
+      console.log(pc.yellow("\nGoodbye!"));
+      process.exit(0);
+    });
+  });
+
+// --- COMPLETION ---
+program
+  .command("completion")
+  .description("Generate Bash auto-completion script")
+  .action(() => {
+    const script = `
+# Erix Bash Completion
+_erix_completions() {
+    local cur opts
+    COMPREPLY=()
+    cur="\${COMP_WORDS[COMP_CWORD]}"
+    opts="whoami whatsapp crm analytics webhooks shell completion"
+
+    if [[ \${COMP_CWORD} -eq 1 ]] ; then
+        COMPREPLY=( \$(compgen -W "\${opts}" -- \${cur}) )
+        return 0
+    fi
+    
+    # Simple sub-command completion
+    case "\${COMP_WORDS[1]}" in
+        whatsapp)
+            COMPREPLY=( \$(compgen -W "send-template" -- \${cur}) )
+            ;;
+        crm)
+            COMPREPLY=( \$(compgen -W "leads pipelines" -- \${cur}) )
+            ;;
+        analytics)
+            COMPREPLY=( \$(compgen -W "overview" -- \${cur}) )
+            ;;
+        webhooks)
+            COMPREPLY=( \$(compgen -W "verify" -- \${cur}) )
+            ;;
+    esac
+}
+complete -F _erix_completions erix
+`;
+    console.log(script.trim());
+    console.error(pc.yellow('\n# To enable, run: eval "$(erix completion)"'));
+    console.error(
+      pc.dim("# Or add it to your ~/.bashrc: erix completion >> ~/.bashrc"),
+    );
+  });
+
+program.parse();

package/src/core.ts

@@ -9,6 +9,10 @@ import { Notifications } from "./resources/notifications";
 import { EmailResource } from "./resources/email";
 import { EventsResource } from "./resources/events";
 import { Webhooks } from "./resources/webhooks";
+import { Storage } from "./resources/storage";
+import { Marketing } from "./resources/marketing";
+import { Health } from "./resources/health";
+import { Queue } from "./resources/queue";
 import { io, type Socket } from "socket.io-client";
 
 declare const process: any;
@@ -94,6 +98,18 @@ export class Ecodrix {
   /** Cryptographic webhook signature verification. */
   public readonly webhooks: Webhooks;
 
+  /** Tenant Cloud Storage mapping. */
+  public readonly storage: Storage;
+
+  /** Email and SMS Marketing Campaigns. */
+  public readonly marketing: Marketing;
+
+  /** Platform and tenant health diagnostics. */
+  public readonly health: Health;
+
+  /** Background job queue management. */
+  public readonly queue: Queue;
+
   constructor(options: EcodrixOptions) {
     if (!options.apiKey) {
       throw new AuthenticationError("API Key is required");
@@ -151,6 +167,10 @@ export class Ecodrix {
     this.email = new EmailResource(this.client);
     this.events = new EventsResource(this.client);
     this.webhooks = new Webhooks();
+    this.storage = new Storage(this.client);
+    this.marketing = new Marketing(this.client);
+    this.health = new Health(this.client);
+    this.queue = new Queue(this.client);
 
     // Establish persistent Socket.io connection
     this.socket = io(socketUrl, {

package/src/index.ts

@@ -2,16 +2,32 @@ export { Ecodrix, type EcodrixOptions } from "./core";
 export * from "./error";
 
 // Resource Type Exports
+export * from "./resources/whatsapp/index";
 export * from "./resources/whatsapp/messages";
 export * from "./resources/whatsapp/conversations";
-export * from "./resources/whatsapp/index";
+export * from "./resources/whatsapp/templates";
+export * from "./resources/whatsapp/broadcasts";
+
+export * from "./resources/crm/index";
 export * from "./resources/crm/leads";
+export * from "./resources/crm/automations";
+export * from "./resources/crm/pipelines";
+export * from "./resources/crm/activities";
+export * from "./resources/crm/analytics";
+export * from "./resources/crm/sequences";
+export * from "./resources/crm/scoring";
+export * from "./resources/crm/payments";
+export * from "./resources/crm/automationDashboard";
 export * from "./resources/meet";
 export * from "./resources/media";
 export * from "./resources/notifications";
 export * from "./resources/email";
 export * from "./resources/events";
 export * from "./resources/webhooks";
+export * from "./resources/storage";
+export * from "./resources/marketing";
+export * from "./resources/health";
+export * from "./resources/queue";
 
 // Export the main client also as default for better ergonomics
 import { Ecodrix } from "./core";

package/src/resource.ts

@@ -17,7 +17,11 @@ export interface RequestOptions extends AxiosRequestConfig {
 export abstract class APIResource {
   public constructor(protected readonly client: AxiosInstance) {}
 
-  protected async post<T>(url: string, data?: any, options?: RequestOptions): Promise<T> {
+  protected async post<T>(
+    url: string,
+    data?: any,
+    options?: RequestOptions,
+  ): Promise<T> {
     try {
       const config = this.buildConfig(options);
       const response = await this.client.post(url, data, config);
@@ -37,7 +41,38 @@ export abstract class APIResource {
     }
   }
 
-  protected async deleteRequest<T>(url: string, options?: RequestOptions): Promise<T> {
+  protected async patch<T>(
+    url: string,
+    data?: any,
+    options?: RequestOptions,
+  ): Promise<T> {
+    try {
+      const config = this.buildConfig(options);
+      const response = await this.client.patch(url, data, config);
+      return response.data;
+    } catch (error: any) {
+      this.handleError(error);
+    }
+  }
+
+  protected async put<T>(
+    url: string,
+    data?: any,
+    options?: RequestOptions,
+  ): Promise<T> {
+    try {
+      const config = this.buildConfig(options);
+      const response = await this.client.put(url, data, config);
+      return response.data;
+    } catch (error: any) {
+      this.handleError(error);
+    }
+  }
+
+  protected async deleteRequest<T>(
+    url: string,
+    options?: RequestOptions,
+  ): Promise<T> {
     try {
       const config = this.buildConfig(options);
       const response = await this.client.delete(url, config);
@@ -47,7 +82,9 @@ export abstract class APIResource {
     }
   }
 
-  private buildConfig(options?: RequestOptions): AxiosRequestConfig | undefined {
+  private buildConfig(
+    options?: RequestOptions,
+  ): AxiosRequestConfig | undefined {
     if (!options) return undefined;
 
     const config: AxiosRequestConfig = { ...options };
@@ -63,9 +100,11 @@ export abstract class APIResource {
   private handleError(error: any): never {
     if (error.response) {
       throw new APIError(
-        error.response.data?.message || error.response.data?.error || "API Request Failed",
+        error.response.data?.message ||
+          error.response.data?.error ||
+          "API Request Failed",
         error.response.status,
-        error.response.data?.code
+        error.response.data?.code,
       );
     }
     throw new APIError(error.message || "Network Error");

package/src/resources/crm/activities.ts

@@ -0,0 +1,89 @@
+import { APIResource } from "../../resource";
+
+export interface LogActivityParams {
+  leadId: string;
+  type: "note" | "call" | "email" | "meeting" | "whatsapp" | "system";
+  title: string;
+  body?: string;
+  metadata?: Record<string, any>;
+}
+
+export interface LogCallParams {
+  durationMinutes: number;
+  summary: string;
+  outcome: "answered" | "no_answer" | "busy" | "voicemail" | "wrong_number";
+}
+
+export class Notes extends APIResource {
+  /**
+   * List all notes for a specific lead.
+   */
+  async list<T = any>(leadId: string) {
+    return this.get<T>(`/api/saas/crm/leads/${leadId}/notes`);
+  }
+
+  /**
+   * Add a note to a lead.
+   */
+  async create<T = any>(leadId: string, params: { content: string }) {
+    return this.post<T>(`/api/saas/crm/leads/${leadId}/notes`, params);
+  }
+
+  /**
+   * Update an existing note.
+   */
+  async update<T = any>(noteId: string, content: string) {
+    return this.patch<T>(`/api/saas/crm/notes/${noteId}`, { content });
+  }
+
+  /**
+   * Pin or unpin a note to the top of the feed.
+   */
+  async pin<T = any>(noteId: string, isPinned = true) {
+    return this.patch<T>(`/api/saas/crm/notes/${noteId}/pin`, { isPinned });
+  }
+
+  /**
+   * Delete a note.
+   */
+  async delete(noteId: string) {
+    return this.deleteRequest(`/api/saas/crm/notes/${noteId}`);
+  }
+}
+
+export class Activities extends APIResource {
+  public notes: Notes;
+
+  constructor(client: any) {
+    super(client);
+    this.notes = new Notes(client);
+  }
+
+  /**
+   * Retrieve the complete chronological timeline for a lead.
+   */
+  async timeline<T = any>(leadId: string, params?: { page?: number; limit?: number }) {
+    return this.get<T>(`/api/saas/crm/leads/${leadId}/timeline`, { params } as any);
+  }
+
+  /**
+   * List specific activities (filtered by type).
+   */
+  async list<T = any>(leadId: string, params?: { type?: string; page?: number; limit?: number }) {
+    return this.get<T>(`/api/saas/crm/activities`, { params: { leadId, ...params } } as any);
+  }
+
+  /**
+   * Generic method to log a business activity/event.
+   */
+  async log<T = any>(params: LogActivityParams) {
+    return this.post<T>("/api/saas/crm/activities", params);
+  }
+
+  /**
+   * Specific method to log communication outcomes.
+   */
+  async logCall<T = any>(leadId: string, params: LogCallParams) {
+    return this.post<T>(`/api/saas/crm/leads/${leadId}/calls`, params);
+  }
+}

package/src/resources/crm/analytics.ts

@@ -0,0 +1,89 @@
+import { APIResource } from "../../resource";
+
+export type AnalyticsRange = "24h" | "7d" | "30d" | "60d" | "90d" | "365d";
+
+export interface AnalyticsParams {
+  range?: AnalyticsRange;
+  from?: string;
+  to?: string;
+  pipelineId?: string;
+}
+
+export class Analytics extends APIResource {
+  /**
+   * KPIs: total leads, pipeline value, won revenue, avg score, conversion rate.
+   */
+  async overview<T = any>(params?: AnalyticsParams) {
+    return this.get<T>("/api/saas/crm/analytics/overview", { params } as any);
+  }
+
+  /**
+   * Stage-by-stage lead counts and conversion percentages.
+   */
+  async funnel<T = any>(pipelineId: string) {
+    return this.get<T>("/api/saas/crm/analytics/funnel", { params: { pipelineId } } as any);
+  }
+
+  /**
+   * Revenue forecast: deal value × stage probability.
+   */
+  async forecast<T = any>(pipelineId?: string) {
+    return this.get<T>("/api/saas/crm/analytics/forecast", { params: { pipelineId } } as any);
+  }
+
+  /**
+   * Lead source breakdown: count, conversion rate, total value per source.
+   */
+  async sources<T = any>(params?: AnalyticsParams) {
+    return this.get<T>("/api/saas/crm/analytics/sources", { params } as any);
+  }
+
+  /**
+   * Team leaderboard: won deals, revenue, activity count, conversion rate per member.
+   */
+  async team<T = any>(params?: AnalyticsParams) {
+    return this.get<T>("/api/saas/crm/analytics/team", { params } as any);
+  }
+
+  /**
+   * Daily activity counts by type. For activity calendar.
+   */
+  async heatmap<T = any>(params?: AnalyticsParams) {
+    return this.get<T>("/api/saas/crm/analytics/heatmap", { params } as any);
+  }
+
+  /**
+   * Score distribution: how many leads in each score bucket.
+   */
+  async scores<T = any>() {
+    return this.get<T>("/api/saas/crm/analytics/scores");
+  }
+
+  /**
+   * Avg time leads spend in each stage. Helps find bottlenecks.
+   */
+  async stageTime<T = any>(pipelineId: string) {
+    return this.get<T>("/api/saas/crm/analytics/stage-time", { params: { pipelineId } } as any);
+  }
+
+  /**
+   * Tiered Growth Report matching business sophistication.
+   */
+  async tiered<T = any>(params?: AnalyticsParams) {
+    return this.get<T>("/api/saas/crm/analytics/tiered", { params } as any);
+  }
+
+  /**
+   * Consolidated analytics including CRM overview and WhatsApp.
+   */
+  async summary<T = any>(params?: AnalyticsParams) {
+    return this.get<T>("/api/saas/crm/analytics/summary", { params } as any);
+  }
+
+  /**
+   * WhatsApp volume and delivery analytics.
+   */
+  async whatsapp<T = any>(params?: AnalyticsParams) {
+    return this.get<T>("/api/saas/crm/analytics/whatsapp", { params } as any);
+  }
+}

package/src/resources/crm/automationDashboard.ts

@@ -0,0 +1,24 @@
+import { APIResource } from "../../resource";
+
+export class AutomationDashboard extends APIResource {
+  /**
+   * Retrieve summary statistics for automation health.
+   */
+  async stats<T = any>() {
+    return this.get<T>("/api/saas/crm/automation/stats");
+  }
+
+  /**
+   * List recent EventLog entries (automation logs).
+   */
+  async logs<T = any>(params?: { limit?: number; status?: string }) {
+    return this.get<T>("/api/saas/crm/automation/logs", { params } as any);
+  }
+
+  /**
+   * Re-emit a failed event log to process its automations again.
+   */
+  async retryFailedEvent<T = any>(logId: string) {
+    return this.post<T>(`/api/saas/crm/automation/logs/${logId}/retry`, {});
+  }
+}