@ecodrix/erix-api 1.0.0

package/src/core.ts

@@ -0,0 +1,262 @@
+import axios, { type AxiosInstance, type Method } from "axios";
+import axiosRetry from "axios-retry";
+import { AuthenticationError, APIError } from "./error";
+import { WhatsApp } from "./resources/whatsapp";
+import { CRM } from "./resources/crm";
+import { MediaResource } from "./resources/media";
+import { Meetings } from "./resources/meet";
+import { Notifications } from "./resources/notifications";
+import { EmailResource } from "./resources/email";
+import { EventsResource } from "./resources/events";
+import { Webhooks } from "./resources/webhooks";
+import { io, type Socket } from "socket.io-client";
+
+declare const process: any;
+
+/**
+ * Configuration options for the Ecodrix client.
+ */
+export interface EcodrixOptions {
+  /**
+   * Your ECODrIx Platform API key.
+   * Obtain this from the ECODrIx dashboard under Settings → API Keys.
+   * @example "ecod_live_sk_..."
+   */
+  apiKey: string;
+
+  /**
+   * 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"
+   */
+  baseUrl?: string;
+
+  /**
+   * Override the Socket.io server URL for real-time events.
+   * Defaults to the same value as `baseUrl`.
+   * @default "https://api.ecodrix.com"
+   */
+  socketUrl?: string;
+}
+
+/**
+ * The primary entry point for the ECODrIx SDK.
+ *
+ * Initialise once with your credentials and use the namespaced resources
+ * to interact with every part of the platform.
+ *
+ * @example
+ * ```typescript
+ * import { Ecodrix } from "@ecodrix/erix-api";
+ *
+ * const ecod = new Ecodrix({
+ *   apiKey: process.env.ECOD_API_KEY!,
+ *   clientCode: "ERIX_CLNT_JHBJHF",
+ * });
+ *
+ * await ecod.whatsapp.messages.send({ to: "+91...", text: "Hello!" });
+ * const lead = await ecod.crm.leads.create({ firstName: "Alice", phone: "+91..." });
+ * ```
+ */
+export class Ecodrix {
+  private readonly client: AxiosInstance;
+  private readonly socket: Socket;
+
+  /** WhatsApp messaging and conversation management. */
+  public readonly whatsapp: WhatsApp;
+
+  /** CRM resources — Leads and related sub-resources. */
+  public readonly crm: CRM;
+
+  /** Cloudflare R2-backed media storage. */
+  public readonly media: MediaResource;
+
+  /** Google Meet appointment scheduling. */
+  public readonly meet: Meetings;
+
+  /** Automation execution logs and provider webhook callbacks. */
+  public readonly notifications: Notifications;
+
+  /** Outbound email marketing engine. */
+  public readonly email: EmailResource;
+
+  /** Lead events and workflow automation triggers. */
+  public readonly events: EventsResource;
+
+  /** Cryptographic webhook signature verification. */
+  public readonly webhooks: Webhooks;
+
+  constructor(options: EcodrixOptions) {
+    if (!options.apiKey) {
+      throw new AuthenticationError("API Key is required");
+    }
+
+    const baseUrl = options.baseUrl || "https://api.ecodrix.com";
+    const socketUrl = options.socketUrl || baseUrl;
+
+    const isBrowser =
+      typeof window !== "undefined" && typeof window.document !== "undefined";
+    const runtime = isBrowser
+      ? "browser"
+      : typeof process !== "undefined"
+        ? `node ${process.version}`
+        : "unknown";
+    const os = isBrowser
+      ? globalThis.navigator?.userAgent || "browser"
+      : typeof process !== "undefined"
+        ? process.platform
+        : "unknown";
+
+    this.client = axios.create({
+      baseURL: baseUrl,
+      headers: {
+        "x-api-key": options.apiKey,
+        "x-client-code": options.clientCode?.toUpperCase(),
+        "Content-Type": "application/json",
+        "x-ecodrix-client-agent": JSON.stringify({
+          sdk_version: "1.0.0", // Can be auto-injected during build in future
+          runtime,
+          os,
+        }),
+      },
+    });
+
+    // Make the client completely bulletproof for execution from external projects.
+    // It will automatically handle network blips, 502 Bad Gateways, and 429 Rate Limits.
+    axiosRetry(this.client, {
+      retries: 3,
+      retryDelay: axiosRetry.exponentialDelay,
+      retryCondition: (error) => {
+        return (
+          axiosRetry.isNetworkOrIdempotentRequestError(error) ||
+          error.response?.status === 429
+        );
+      },
+    });
+
+    // Initialise resources
+    this.whatsapp = new WhatsApp(this.client);
+    this.crm = new CRM(this.client);
+    this.media = new MediaResource(this.client);
+    this.meet = new Meetings(this.client);
+    this.notifications = new Notifications(this.client);
+    this.email = new EmailResource(this.client);
+    this.events = new EventsResource(this.client);
+    this.webhooks = new Webhooks();
+
+    // Establish persistent Socket.io connection
+    this.socket = io(socketUrl, {
+      extraHeaders: {
+        "x-api-key": options.apiKey,
+        "x-client-code": options.clientCode?.toUpperCase() || "",
+      },
+    });
+
+    this.setupSocket(options.clientCode);
+  }
+
+  private setupSocket(clientCode?: string) {
+    this.socket.on("connect", () => {
+      if (clientCode) {
+        // Join the tenant-scoped room to receive only relevant events.
+        this.socket.emit("join-room", clientCode.toUpperCase());
+      }
+    });
+  }
+
+  /**
+   * Subscribe to a real-time event emitted by the ECODrIx platform.
+   *
+   * The SDK maintains a persistent Socket.io connection. Events are
+   * scoped to your `clientCode` — you will only receive events for
+   * your own tenant.
+   *
+   * **Standard events:**
+   * - `whatsapp.message_received` — inbound WhatsApp message
+   * - `whatsapp.message_sent` — outbound message delivered
+   * - `crm.lead_created` — new CRM lead ingested
+   * - `crm.lead_updated` — lead details or stage changed
+   * - `meet.scheduled` — Google Meet appointment booked
+   * - `storage.upload_confirmed` — file upload completed
+   * - `automation.failed` — automation execution error
+   *
+   * @param event - The event name to subscribe to.
+   * @param callback - The handler function invoked when the event fires.
+   * @returns `this` for method chaining.
+   *
+   * @example
+   * ```typescript
+   * ecod
+   *   .on("whatsapp.message_received", (msg) => console.log(msg.body))
+   *   .on("automation.failed", (err) => alertTeam(err));
+   * ```
+   */
+  public on(event: string, callback: (...args: any[]) => void): this {
+    this.socket.on(event, callback);
+    return this;
+  }
+
+  /**
+   * Gracefully disconnect the real-time Socket.io connection.
+   * Call this when shutting down your server or when the client is
+   * no longer needed to free up resources.
+   *
+   * @example
+   * ```typescript
+   * process.on("SIGTERM", () => ecod.disconnect());
+   * ```
+   */
+  public disconnect() {
+    this.socket.disconnect();
+  }
+
+  /**
+   * Raw Execution Escape-Hatch.
+   * Send an authenticated HTTP request directly to the ECODrIx backend from ANY external project.
+   *
+   * This is extremely powerful giving you full unrestricted access to make calls
+   * against new, experimental, or completely custom backend APIs while still benefitting
+   * from the SDK's built-in authentication and automatic `axios-retry` logic.
+   *
+   * @example
+   * ```typescript
+   * const { data } = await ecod.request("POST", "/api/saas/experimental-feature", { flag: true });
+   * console.log(data);
+   * ```
+   */
+  public async request<T = any>(
+    method: Method,
+    path: string,
+    data?: any,
+    params?: any,
+  ): Promise<T> {
+    try {
+      const response = await this.client.request<T>({
+        method,
+        url: path,
+        data,
+        params,
+      });
+      return response.data;
+    } catch (error: any) {
+      if (error.response) {
+        throw new APIError(
+          error.response.data?.message ||
+            error.response.data?.error ||
+            "Raw Execution Failed",
+          error.response.status,
+          error.response.data?.code,
+        );
+      }
+      throw new APIError(error.message || "Network Error");
+    }
+  }
+}

package/src/error.ts

@@ -0,0 +1,72 @@
+/**
+ * Typed error hierarchy for the @ecodrix/erix-api SDK.
+ *
+ * All errors thrown by the SDK extend `EcodrixError`, so a single
+ * `catch` block can handle them all, while still allowing granular
+ * differentiation between auth failures, rate limits, and generic API errors.
+ *
+ * @example
+ * ```typescript
+ * import { APIError, AuthenticationError, RateLimitError } from "@ecodrix/erix-api";
+ *
+ * try {
+ *   await ecod.crm.leads.retrieve("invalid_id");
+ * } catch (err) {
+ *   if (err instanceof AuthenticationError) {
+ *     console.error("Invalid API key or client code.");
+ *   } else if (err instanceof RateLimitError) {
+ *     console.warn("Slow down — rate limit hit.");
+ *   } else if (err instanceof APIError) {
+ *     console.error(`API error ${err.status}: ${err.message}`);
+ *   }
+ * }
+ * ```
+ */
+
+/** Base class for all ECODrIx SDK errors. */
+export class EcodrixError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "EcodrixError";
+  }
+}
+
+/**
+ * Represents an error returned by the ECODrIx API.
+ * Carries the HTTP `status` code and an optional `code` string.
+ */
+export class APIError extends EcodrixError {
+  /** HTTP status code returned by the API (e.g. 400, 404, 500). */
+  public status?: number;
+  /** Machine-readable error code (e.g. `"NOT_FOUND"`, `"VALIDATION_ERROR"`). */
+  public code?: string;
+
+  constructor(message: string, status?: number, code?: string) {
+    super(message);
+    this.name = "APIError";
+    this.status = status;
+    this.code = code;
+  }
+}
+
+/**
+ * Thrown when the API key or client code is missing, invalid, or expired.
+ * HTTP 401.
+ */
+export class AuthenticationError extends APIError {
+  constructor(message = "Invalid API Key or Client Code") {
+    super(message, 401, "AUTH_FAILED");
+    this.name = "AuthenticationError";
+  }
+}
+
+/**
+ * Thrown when the rate limit for the API key has been exceeded.
+ * HTTP 429. Implement exponential backoff before retrying.
+ */
+export class RateLimitError extends APIError {
+  constructor(message = "Too many requests. Please slow down.") {
+    super(message, 429, "RATE_LIMIT_EXCEEDED");
+    this.name = "RateLimitError";
+  }
+}

package/src/index.ts

@@ -0,0 +1,18 @@
+export { Ecodrix, type EcodrixOptions } from "./core";
+export * from "./error";
+
+// Resource Type Exports
+export * from "./resources/whatsapp/messages";
+export * from "./resources/whatsapp/conversations";
+export * from "./resources/whatsapp/index";
+export * from "./resources/crm/leads";
+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 the main client also as default for better ergonomics
+import { Ecodrix } from "./core";
+export default Ecodrix;

package/src/resource.ts

@@ -0,0 +1,73 @@
+import type { AxiosInstance, AxiosRequestConfig } from "axios";
+import { APIError } from "./error";
+
+export interface RequestOptions extends AxiosRequestConfig {
+  /**
+   * If true, will not add the x-client-code header.
+   */
+  ignoreClientCode?: boolean;
+
+  /**
+   * Safe execution idempotency key.
+   * If provided, the backend will safely ignore duplicate requests retried with the same key.
+   */
+  idempotencyKey?: string;
+}
+
+export abstract class APIResource {
+  public constructor(protected readonly client: AxiosInstance) {}
+
+  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);
+      return response.data;
+    } catch (error: any) {
+      this.handleError(error);
+    }
+  }
+
+  protected async get<T>(url: string, options?: RequestOptions): Promise<T> {
+    try {
+      const config = this.buildConfig(options);
+      const response = await this.client.get(url, 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);
+      return response.data;
+    } catch (error: any) {
+      this.handleError(error);
+    }
+  }
+
+  private buildConfig(options?: RequestOptions): AxiosRequestConfig | undefined {
+    if (!options) return undefined;
+
+    const config: AxiosRequestConfig = { ...options };
+    if (options.idempotencyKey) {
+      config.headers = {
+        ...config.headers,
+        "Idempotency-Key": options.idempotencyKey,
+      };
+    }
+    return config;
+  }
+
+  private handleError(error: any): never {
+    if (error.response) {
+      throw new APIError(
+        error.response.data?.message || error.response.data?.error || "API Request Failed",
+        error.response.status,
+        error.response.data?.code
+      );
+    }
+    throw new APIError(error.message || "Network Error");
+  }
+}

package/src/resources/crm/index.ts

@@ -0,0 +1,10 @@
+import { Leads } from "./leads";
+import type { AxiosInstance } from "axios";
+
+export class CRM {
+  public leads: Leads;
+
+  constructor(client: AxiosInstance) {
+    this.leads = new Leads(client);
+  }
+}

package/src/resources/crm/leads.ts

@@ -0,0 +1,186 @@
+import { APIResource } from "../../resource";
+
+/**
+ * Parameters for creating a new CRM Lead.
+ */
+export interface CreateLeadParams {
+  /** Lead's first name. Required. */
+  firstName: string;
+  /** Lead's last name. */
+  lastName?: string;
+  /** Lead's email address. */
+  email?: string;
+  /** Lead's phone number in E.164 format (e.g. "+919876543210"). */
+  phone?: string;
+  /**
+   * Acquisition channel.
+   * @example "website" | "whatsapp" | "direct" | "referral"
+   */
+  source?: string;
+  /** Arbitrary key-value metadata (UTM params, order IDs, etc.). */
+  metadata?: Record<string, any>;
+}
+
+/**
+ * CRM Lead resource — full lifecycle management.
+ *
+ * Access via `ecod.crm.leads`.
+ *
+ * @example
+ * ```typescript
+ * const { data: lead } = await ecod.crm.leads.create({
+ *   firstName: "Alice",
+ *   phone: "+919876543210",
+ *   source: "website",
+ * });
+ * ```
+ */
+export class Leads extends APIResource {
+  /**
+   * Create a new lead in the CRM pipeline.
+   *
+   * @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);
+  }
+
+  /**
+   * Bulk ingest leads efficiently in parallel using automatic chunking.
+   * Prevents rate limit exhaustion by executing `chunkSize` requests at a time.
+   *
+   * @param leads - Array of leads to create.
+   * @param chunkSize - Number of leads to send concurrently (default: 50)
+   * @returns Array of created lead results.
+   */
+  async createMany(leads: CreateLeadParams[], chunkSize = 50): Promise<any[]> {
+    const results: any[] = [];
+    
+    for (let i = 0; i < leads.length; i += chunkSize) {
+      const chunk = leads.slice(i, i + chunkSize);
+      
+      const chunkPromises = chunk.map((lead) => this.create(lead));
+      const chunkResults = await Promise.allSettled(chunkPromises);
+      
+      for (const res of chunkResults) {
+        if (res.status === "fulfilled") {
+          results.push(res.value);
+        } else {
+          throw res.reason;
+        }
+      }
+    }
+
+    return results;
+  }
+
+  /**
+   * 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);
+  }
+
+  /**
+   * 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" })) {
+   *   console.log(lead.firstName);
+   * }
+   * ```
+   */
+  async *listAutoPaging(params?: Record<string, any>): AsyncGenerator<any, void, unknown> {
+    let currentPage = params?.page || 1;
+    let hasMore = true;
+
+    while (hasMore) {
+      const response: any = await this.list({ ...params, page: currentPage });
+      
+      const items = Array.isArray(response.data) ? response.data : response || [];
+      
+      if (items.length === 0) {
+        hasMore = false;
+        break;
+      }
+
+      for (const item of items) {
+        yield item;
+      }
+
+      if (response.pagination && currentPage < response.pagination.pages) {
+        currentPage++;
+      } else if (!response.pagination && items.length > 0) {
+        // Fallback: If no explicit pagination struct, assume simple array and just keep pulling until empty
+        currentPage++;
+      } else {
+        hasMore = false;
+      }
+    }
+  }
+
+  /**
+   * Retrieve a single lead by its unique ID.
+   *
+   * @param leadId - The MongoDB ObjectId of the lead.
+   * @returns The Lead document, or a 404 error if not found.
+   *
+   * @example
+   * ```typescript
+   * const { data } = await ecod.crm.leads.retrieve("64abc...");
+   * ```
+   */
+  async retrieve(leadId: string) {
+    return this.get(`/api/services/leads/${leadId}`);
+  }
+
+  /**
+   * Update the fields of an existing lead.
+   *
+   * @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);
+  }
+
+  /**
+   * Archive (soft-delete) a lead. The record is retained in the database
+   * for audit purposes but is excluded from all standard list views.
+   *
+   * @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}`);
+  }
+}

package/src/resources/email.ts

@@ -0,0 +1,51 @@
+import type { AxiosInstance } from "axios";
+import { APIResource } from "../resource";
+import { APIError } from "../error";
+
+/**
+ * Payload to send a high-throughput email campaign.
+ */
+export interface SendCampaignPayload {
+  /** Array of recipient email addresses. */
+  recipients: string[];
+  /** Subject line of the email. */
+  subject: string;
+  /** HTML body of the email. */
+  html: string;
+}
+
+
+/**
+ * Interface representing the result of a campaign dispatch.
+ */
+export interface CampaignResult {
+  success: boolean;
+  message?: string;
+  [key: string]: any;
+}
+
+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.
+   */
+  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.
+   *
+   * @param to - The recipient's email address.
+   * @returns The dispatch result.
+   */
+  async sendTestEmail(to: string): Promise<CampaignResult> {
+    return this.post<CampaignResult>("/api/saas/emails/test", { to });
+  }
+
+  // WhatsApp moved to native wrapper
+}