@ecodrix/erix-api 1.2.0 → 1.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecodrix/erix-api",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "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

@@ -3,11 +3,12 @@ import axiosRetry from "axios-retry";
 import { type Socket, io } from "socket.io-client";
 import { APIError, AuthenticationError } from "./error";
 import { CRM } from "./resources/crm";
-import { EmailResource } from "./resources/email";
+import { Email } from "./resources/email";
 import { EventsResource } from "./resources/events";
 import { Health } from "./resources/health";
+import { Logs } from "./resources/logs";
 import { Marketing } from "./resources/marketing";
-import { MediaResource } from "./resources/media";
+import { Media } from "./resources/media";
 import { Meetings } from "./resources/meet";
 import { Notifications } from "./resources/notifications";
 import { Queue } from "./resources/queue";
@@ -90,7 +91,7 @@ export class Ecodrix {
   public readonly crm: CRM;
 
   /** Cloudflare R2-backed media storage. */
-  public readonly media: MediaResource;
+  public readonly media: Media;
 
   /** Google Meet appointment scheduling. */
   public readonly meet: Meetings;
@@ -98,8 +99,11 @@ export class Ecodrix {
   /** Automation execution logs and provider webhook callbacks. */
   public readonly notifications: Notifications;
 
-  /** Outbound email marketing engine. */
-  public readonly email: EmailResource;
+  /** Outbound email marketing engine and template management. */
+  public readonly email: Email;
+
+  /** Platform-wide execution logs and audit trails. */
+  public readonly logs: Logs;
 
   /** Lead events and workflow automation triggers. */
   public readonly events: EventsResource;
@@ -129,8 +133,7 @@ export class Ecodrix {
     const baseUrl = options.baseUrl ?? ECOD_API_BASE;
     const socketUrl = options.socketUrl || baseUrl;
 
-    const isBrowser =
-      typeof window !== "undefined" && typeof window.document !== "undefined";
+    const isBrowser = typeof window !== "undefined" && typeof window.document !== "undefined";
     const runtime = isBrowser
       ? "browser"
       : typeof process !== "undefined"
@@ -163,14 +166,11 @@ export class Ecodrix {
       retryDelay: axiosRetry.exponentialDelay,
       retryCondition: (error) => {
         return (
-          axiosRetry.isNetworkOrIdempotentRequestError(error) ||
-          error.response?.status === 429
+          axiosRetry.isNetworkOrIdempotentRequestError(error) || error.response?.status === 429
         );
       },
       onRetry: (retryCount, error, requestConfig) => {
-        const isDev =
-          typeof process !== "undefined" &&
-          process.env?.NODE_ENV === "development";
+        const isDev = typeof process !== "undefined" && process.env?.NODE_ENV === "development";
         if (isDev) {
           console.warn(
             `[ECODrIx SDK] Retrying request (${retryCount}/3): ${requestConfig.method?.toUpperCase()} ${requestConfig.url}. Reason: ${error.message}`,
@@ -182,10 +182,11 @@ export class Ecodrix {
     // Initialise resources
     this.whatsapp = new WhatsApp(this.client);
     this.crm = new CRM(this.client);
-    this.media = new MediaResource(this.client);
+    this.media = new Media(this.client);
     this.meet = new Meetings(this.client);
     this.notifications = new Notifications(this.client);
-    this.email = new EmailResource(this.client);
+    this.email = new Email(this.client);
+    this.logs = new Logs(this.client);
     this.events = new EventsResource(this.client);
     this.webhooks = new Webhooks();
     this.storage = new Storage(this.client);
@@ -323,9 +324,7 @@ export class Ecodrix {
     } catch (error: any) {
       if (error.response) {
         throw new APIError(
-          error.response.data?.message ||
-            error.response.data?.error ||
-            "Raw Execution Failed",
+          error.response.data?.message || error.response.data?.error || "Raw Execution Failed",
           error.response.status,
           error.response.data?.code,
         );

package/src/index.ts

@@ -1,4 +1,5 @@
 export { Ecodrix, type EcodrixOptions } from "./core";
+export * from "./types/metadata";
 export * from "./error";
 export * from "./resources/crm/activities";
 export * from "./resources/crm/analytics";
@@ -13,6 +14,7 @@ export * from "./resources/crm/sequences";
 export * from "./resources/email";
 export * from "./resources/events";
 export * from "./resources/health";
+export * from "./resources/logs";
 export * from "./resources/marketing";
 export * from "./resources/media";
 export * from "./resources/meet";

package/src/resources/crm/leads.ts

@@ -1,4 +1,5 @@
 import { APIResource } from "../../resource";
+import type { ResourceManifest } from "../../types/metadata";
 
 /**
  * Valid statuses for a CRM Lead.
@@ -102,6 +103,69 @@ export class Leads extends APIResource {
     return this.post<T>("/api/crm/leads", params);
   }
 
+  /**
+   * Introspect the Leads resource and provide a "Blueprint" for UI generation.
+   *
+   * This method returns a list of all fields (standard + custom), their types,
+   * labels, and suggested UI controls. Erix React uses this to render SmartForms
+   * and tables dynamically.
+   */
+  async describe(): Promise<ResourceManifest> {
+    // 1. Fetch custom fields from the tenant configuration
+    const customFieldsRes: any = await this.fields();
+    const customFields = Array.isArray(customFieldsRes.data) ? customFieldsRes.data : [];
+
+    // 2. Define the core system fields
+    const systemFields: any[] = [
+      {
+        key: "firstName",
+        label: "First Name",
+        type: "string",
+        required: true,
+        group: "Basic Info",
+      },
+      { key: "lastName", label: "Last Name", type: "string", required: false, group: "Basic Info" },
+      { key: "phone", label: "Phone Number", type: "phone", required: true, group: "Contact" },
+      { key: "email", label: "Email Address", type: "email", required: false, group: "Contact" },
+      {
+        key: "status",
+        label: "Status",
+        type: "select",
+        required: true,
+        options: [
+          { label: "New", value: "new" },
+          { label: "Contacted", value: "contacted" },
+          { label: "Qualified", value: "qualified" },
+          { label: "Won", value: "won" },
+          { label: "Lost", value: "lost" },
+        ],
+      },
+      { key: "value", label: "Lead Value", type: "currency", required: false },
+      { key: "source", label: "Source", type: "string", required: false },
+    ];
+
+    // 3. Map custom fields to FieldManifest shape
+    const mappedCustom = customFields.map((f: any) => ({
+      key: `metadata.extra.${f.name}`,
+      label: f.label || f.name,
+      type: f.type || "string",
+      required: !!f.required,
+      options: f.options,
+      group: "Custom Fields",
+    }));
+
+    return {
+      name: "Lead",
+      fields: [...systemFields, ...mappedCustom],
+      uiHints: {
+        icon: "User",
+        primaryColor: "#3b82f6",
+        defaultSort: { field: "createdAt", direction: "desc" },
+        summaryFields: ["firstName", "lastName", "phone", "status"],
+      },
+    };
+  }
+
   /**
    * Upsert a lead by phone number. If a lead with the same phone exists,
    * it will be updated; otherwise, a new lead is created.

package/src/resources/crm/pipelines.ts

@@ -1,4 +1,5 @@
 import { APIResource } from "../../resource";
+import type { ResourceManifest } from "../../types/metadata";
 
 export interface CreatePipelineParams {
   name: string;
@@ -26,6 +27,39 @@ export class Pipelines extends APIResource {
     return this.get<T>("/api/crm/pipelines");
   }
 
+  /**
+   * Introspect a pipeline and provide a manifest of its stages.
+   *
+   * Returns metadata about stage colors, probabilities, and order.
+   * Erix React uses this to build kanban boards and stage pickers.
+   *
+   * @param pipelineId - The unique ID of the pipeline.
+   */
+  async getStageManifest(pipelineId: string): Promise<ResourceManifest> {
+    const pipeline: any = await this.retrieve(pipelineId);
+    const stages = Array.isArray(pipeline.data?.stages) ? pipeline.data.stages : [];
+
+    return {
+      name: `Pipeline: ${pipeline.data?.name || pipelineId}`,
+      fields: stages.map((s: any) => ({
+        key: s._id,
+        label: s.name,
+        type: "string", // Labels are strings
+        required: true,
+        options: [{ label: s.name, value: s._id }],
+        group: "Stages",
+        uiHints: {
+          color: s.color || "#cbd5e1",
+          probability: s.probability,
+        },
+      })) as any,
+      uiHints: {
+        icon: "Columns",
+        primaryColor: "#6366f1",
+      },
+    };
+  }
+
   /**
    * Create a new CRM sales or support pipeline.
    *
@@ -74,7 +108,9 @@ export class Pipelines extends APIResource {
    * Duplicate a pipeline with a new name.
    */
   async duplicate<T = any>(pipelineId: string, newName: string) {
-    return this.post<T>(`/api/crm/pipelines/${pipelineId}/duplicate`, { newName });
+    return this.post<T>(`/api/crm/pipelines/${pipelineId}/duplicate`, {
+      newName,
+    });
   }
 
   /**

package/src/resources/email.ts

@@ -1,5 +1,3 @@
-import type { AxiosInstance } from "axios";
-import { APIError } from "../error";
 import { APIResource } from "../resource";
 
 /**
@@ -23,38 +21,122 @@ export interface CampaignResult {
   [key: string]: any;
 }
 
-export class EmailResource extends APIResource {
+export interface EmailTemplate {
+  id: string;
+  name: string;
+  description?: string;
+  subject: string;
+  preheader?: string;
+  htmlBody: string;
+  textBody?: string;
+  category: "marketing" | "transactional" | "sequence";
+  status: "draft" | "published" | "archived";
+  type: "standard" | "layout";
+  layoutId?: string;
+  thumbnail?: string;
+  variableMapping?: any[];
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface CreateTemplateDTO {
+  name: string;
+  subject: string;
+  htmlBody: string;
+  description?: string;
+  category?: "marketing" | "transactional" | "sequence";
+  status?: "draft" | "published" | "archived";
+  variableMapping?: any[];
+}
+
+export interface TemplatePreviewResponse {
+  success: boolean;
+  data: {
+    subject: string;
+    html: string;
+    text?: string;
+  };
+}
+
+/**
+ * Outbound email marketing engine and template management.
+ *
+ * Access via `ecod.email`.
+ */
+export class Email extends APIResource {
   /**
    * Send an HTML email campaign to a list of recipients.
-   *
-   * @param payload - The campaign details (recipients, subject, html).
-   * @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 sendCampaign(payload: SendCampaignPayload): Promise<CampaignResult> {
     return this.post<CampaignResult>("/api/saas/emails/campaign", payload);
   }
 
   /**
    * 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> {
+   */
+  async sendTest(to: string): Promise<CampaignResult> {
     return this.post<CampaignResult>("/api/saas/emails/test", { to });
   }
 
-  // WhatsApp moved to native wrapper
+  // --- Template Management ---
+
+  /**
+   * List all email templates.
+   */
+  async listTemplates(query?: any): Promise<{ success: boolean; data: EmailTemplate[] }> {
+    return this.get<{ success: boolean; data: EmailTemplate[] }>("/api/saas/mail/templates", {
+      params: query,
+    });
+  }
+
+  /**
+   * Get a single email template by ID.
+   */
+  async getTemplate(id: string): Promise<{ success: boolean; data: EmailTemplate }> {
+    return this.get<{ success: boolean; data: EmailTemplate }>(`/api/saas/mail/templates/${id}`);
+  }
+
+  /**
+   * Create a new email template.
+   */
+  async createTemplate(
+    data: CreateTemplateDTO,
+  ): Promise<{ success: boolean; data: EmailTemplate }> {
+    return this.post<{ success: boolean; data: EmailTemplate }>("/api/saas/mail/templates", data);
+  }
+
+  /**
+   * Update an existing email template.
+   */
+  async updateTemplate(
+    id: string,
+    data: Partial<CreateTemplateDTO>,
+  ): Promise<{ success: boolean; data: EmailTemplate }> {
+    return this.put<{ success: boolean; data: EmailTemplate }>(
+      `/api/saas/mail/templates/${id}`,
+      data,
+    );
+  }
+
+  /**
+   * Delete an email template.
+   */
+  async deleteTemplate(id: string, force = false): Promise<{ success: boolean }> {
+    return this.deleteRequest<{ success: boolean }>(`/api/saas/mail/templates/${id}`, {
+      params: { force },
+    });
+  }
+
+  /**
+   * Preview a template with dynamic variable resolution.
+   */
+  async previewTemplate(
+    id: string,
+    params: { leadId?: string; variables?: Record<string, any> },
+  ): Promise<TemplatePreviewResponse> {
+    return this.post<TemplatePreviewResponse>(`/api/saas/mail/templates/${id}/preview`, params);
+  }
 }
+
+/** @deprecated Use Email instead */
+export class EmailResource extends Email {}

package/src/resources/health.ts

@@ -34,48 +34,51 @@ export interface JobStatus {
   createdAt: string;
 }
 
+/**
+ * Platform and tenant-specific health diagnostics.
+ *
+ * Access via `ecod.health`.
+ */
 export class Health extends APIResource {
   /**
    * 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}`);
-   * ```
+   * Verify that the core API, database, and background workers are operational.
    */
   async system(): Promise<SystemHealth> {
-    const res = await this.get<{ data: SystemHealth }>("/api/saas/health", {
-      headers: { accept: "application/json" },
-    });
+    const res = await this.get<{ success: boolean; data: SystemHealth }>("/api/saas/health");
     return res.data;
   }
 
   /**
-   * Tenant-specific health check. Identifies configured services.
+   * Tenant-specific health check.
+   *
+   * Identifies correctly configured third-party integrations (WhatsApp, SMTP, Google Meet)
+   * and reports active automation counts.
    */
   async clientHealth(): Promise<ClientHealth> {
-    const res = await this.get<{ data: ClientHealth }>("/api/saas/health/client");
+    const res = await this.get<{ success: boolean; data: ClientHealth }>("/api/saas/health/client");
     return res.data;
   }
 
+  /**
+   * Alias for clientHealth to match diagnostic terminology.
+   */
+  async getDiagnosticReport(): Promise<ClientHealth> {
+    return this.clientHealth();
+  }
+
   /**
    * Lookup the execution status of a background job.
    *
+   * Use this to poll for completion of long-running tasks like bulk exports
+   * or campaign dispatches.
+   *
    * @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<{ success: boolean; data: JobStatus }>(
+      `/api/saas/jobs/status/${jobId}`,
+    );
     return res.data;
   }
 }

package/src/resources/logs.ts

@@ -0,0 +1,97 @@
+import { APIResource } from "../resource";
+
+export interface LogPaginationQuery {
+  page?: number;
+  limit?: number;
+  trigger?: string;
+  status?: "received" | "processing" | "completed" | "partial" | "failed";
+  from?: string;
+  to?: string;
+}
+
+export interface EventLog {
+  id: string;
+  trigger: string;
+  phone?: string;
+  email?: string;
+  status: "received" | "processing" | "completed" | "partial" | "failed";
+  rulesMatched: number;
+  jobsCreated: number;
+  meetLink?: string;
+  callbackUrl?: string;
+  callbackStatus: "not_required" | "sent" | "failed";
+  payload: any;
+  error?: string;
+  idempotencyKey?: string;
+  processedAt?: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface CallbackLog {
+  id: string;
+  callbackUrl: string;
+  method: string;
+  payload: any;
+  jobId?: string;
+  enrollmentId?: string;
+  responseStatus: number;
+  responseBody: string;
+  status: "sent" | "failed" | "pending_retry";
+  attempts: number;
+  lastAttemptAt?: string;
+  signature?: string;
+  createdAt: string;
+}
+
+export interface LogResponse<T> {
+  success: boolean;
+  data: T[];
+  pagination: {
+    total: number;
+    page: number;
+    limit: number;
+    pages: number;
+  };
+}
+
+/**
+ * Audit and execution logs for platform events and webhooks.
+ *
+ * Access via `ecod.logs`.
+ */
+export class Logs extends APIResource {
+  /**
+   * List event execution logs with optional filtering.
+   *
+   * Use this to audit automation triggers and debug workflow execution.
+   */
+  async listEventLogs(query?: LogPaginationQuery): Promise<LogResponse<EventLog>> {
+    return this.get<LogResponse<EventLog>>("/api/saas/events/logs", {
+      params: query,
+    });
+  }
+
+  /**
+   * Get detailed information for a single event execution.
+   */
+  async getEventLog(id: string): Promise<{ success: boolean; data: EventLog }> {
+    return this.get<{ success: boolean; data: EventLog }>(`/api/saas/events/logs/${id}`);
+  }
+
+  /**
+   * List webhook callback logs (outbound responses from ECODrIx to your system).
+   */
+  async listCallbackLogs(query?: LogPaginationQuery): Promise<LogResponse<CallbackLog>> {
+    return this.get<LogResponse<CallbackLog>>("/api/saas/callbacks/logs", {
+      params: query,
+    });
+  }
+
+  /**
+   * Get high-level execution statistics for the tenant.
+   */
+  async getStats(): Promise<{ success: boolean; data: any }> {
+    return this.get<{ success: boolean; data: any }>("/api/saas/events/stats");
+  }
+}

package/src/resources/media.ts

@@ -41,7 +41,7 @@ export interface UploadOptions {
  * console.log(data.url); // → https://cdn.ecodrix.com/invoices/invoice-001.pdf
  * ```
  */
-export class MediaResource extends APIResource {
+export class Media extends APIResource {
   /**
    * Get current storage usage metrics for the tenant.
    *
@@ -83,10 +83,7 @@ export class MediaResource extends APIResource {
    * const { data: files } = await ecod.media.list("invoices", { q: "contract" });
    * ```
    */
-  async list(
-    folder: string,
-    params?: { year?: string; month?: string; q?: string },
-  ) {
+  async list(folder: string, params?: { year?: string; month?: string; q?: string }) {
     return this.get(`/api/saas/storage/files/${folder}`, { params } as any);
   }
 
@@ -158,10 +155,7 @@ export class MediaResource extends APIResource {
    */
   async upload(file: any, options: UploadOptions): Promise<any> {
     // Step 1: Get presigned URL
-    const response = await this.post<any>(
-      "/api/saas/storage/upload-url",
-      options,
-    );
+    const response = await this.post<any>("/api/saas/storage/upload-url", options);
     const { uploadUrl, key } = response.data;
 
     // Step 2: Upload directly to R2 (bypasses the API server for performance)
@@ -175,3 +169,6 @@ export class MediaResource extends APIResource {
     return this.post("/api/saas/storage/confirm-upload", { key, sizeBytes });
   }
 }
+
+/** @deprecated Use Media instead */
+export class MediaResource extends Media {}

package/src/resources/whatsapp/templates.ts

@@ -1,4 +1,5 @@
 import { APIResource } from "../../resource";
+import type { ResourceManifest } from "../../types/metadata";
 
 export interface TemplateMapping {
   mappings: any[];
@@ -164,6 +165,50 @@ export class Templates extends APIResource {
     });
   }
 
+  /**
+   * Introspect a template and provide a manifest of its required variables.
+   *
+   * This is used by Erix React to build dynamic "Mapping Forms" where users
+   * can connect CRM fields to WhatsApp variables.
+   *
+   * @param templateIdentifier - The name or ID of the template.
+   */
+  async getVariableManifest(templateIdentifier: string): Promise<ResourceManifest> {
+    const template: any = await this.retrieve(templateIdentifier);
+    const components = Array.isArray(template.data?.components) ? template.data.components : [];
+
+    const fields: any[] = [];
+
+    for (const comp of components) {
+      // Look for {{n}} pattern in text components
+      if (comp.text) {
+        const vars = comp.text.match(/{{(\d+)}}/g);
+        if (vars) {
+          for (const v of vars) {
+            const index = v.replace(/{{|}}/g, "");
+            fields.push({
+              key: `var_${index}`,
+              label: `${comp.type} Var {{${index}}}`,
+              type: "string",
+              required: true,
+              group: comp.type,
+              description: `Variable placeholder in template ${comp.type}`,
+            });
+          }
+        }
+      }
+    }
+
+    return {
+      name: `Template variables: ${template.data?.name || templateIdentifier}`,
+      fields,
+      uiHints: {
+        icon: "Variables",
+        primaryColor: "#059669",
+      },
+    };
+  }
+
   /**
    * Check which automations or sequences are currently using this template.
    */