@ecodrix/erix-api 1.0.0

package/src/resources/events.ts

@@ -0,0 +1,121 @@
+import type { AxiosInstance } from "axios";
+import { APIResource } from "../resource";
+
+/**
+ * Event definition representing an entry point capable of triggering automations.
+ */
+export interface EventDefinition {
+  name: string;
+  displayName: string;
+  description?: string;
+  pipelineId?: string;
+  stageId?: string;
+  defaultSource?: string;
+  [key: string]: any;
+}
+
+/**
+ * Payload to register/assign a new custom event definition.
+ */
+export interface AssignEventPayload {
+  /** The internal machine-readable name of the event (e.g. "webinar_joined") */
+  name: string;
+  /** Human-readable display name */
+  displayName: string;
+  /** Event description */
+  description?: string;
+  /** ID of the pipeline to associate with matching leads */
+  pipelineId?: string;
+  /** ID of the stage within the pipeline */
+  stageId?: string;
+  /** Default source tag for leads created via this event */
+  defaultSource?: string;
+}
+
+/**
+ * Payload to programmatically trigger an event/workflow.
+ */
+export interface TriggerPayload {
+  /** The name of the event to fire (e.g., "webinar_joined") */
+  trigger: string;
+  /** Phone number of the lead (E.164 format) */
+  phone: string;
+  /** Email of the lead */
+  email?: string;
+  /** Key-value pairs for string templates */
+  variables?: Record<string, string>;
+  /** Deep payload data mapping to the event */
+  data?: any;
+  /** URL to receive an acknowledgment callback when processing completes */
+  callbackUrl?: string;
+  /** Secret metadata passed back to the callback URL */
+  callbackMetadata?: any;
+  /** Auto-create lead if phone does not exist in CRM */
+  createLeadIfMissing?: boolean;
+  /** Pre-fill data if creating a new lead */
+  leadData?: {
+    firstName?: string;
+    lastName?: string;
+    source?: string;
+  };
+  /** Delay execution of matched workflows (in seconds) */
+  delaySeconds?: number;
+  /** Delay execution of matched workflows (in minutes) */
+  delayMinutes?: number;
+  /** Explicit ISO timestamp to trigger the workflow run */
+  runAt?: string;
+}
+
+/**
+ * Response returned when triggering an event.
+ */
+export interface TriggerResponse {
+  success: boolean;
+  data?: {
+    eventLogId: string;
+    trigger: string;
+    leadId: string;
+    rulesMatched: number;
+  };
+  message?: string;
+  code?: string;
+}
+
+export class EventsResource extends APIResource {
+  /**
+   * Retrieve all valid events (system + custom) that can be used as Automation Rule triggers.
+   */
+  async list(): Promise<{ success: boolean; data: EventDefinition[] }> {
+    return this.get<{ success: boolean; data: EventDefinition[] }>("/api/saas/events");
+  }
+
+  /**
+   * Register a new custom event entry point into the CRM automation engine.
+   * Useful when introducing new granular triggers.
+   */
+  async assign(payload: AssignEventPayload): Promise<{ success: boolean; data: EventDefinition }> {
+    return this.post<{ success: boolean; data: EventDefinition }>("/api/saas/events/assign", payload);
+  }
+
+  /**
+   * Deactivate a custom event assignment by name.
+   */
+  async unassign(name: string): Promise<{ success: boolean; data: any }> {
+    return this.post<{ success: boolean; data: any }>("/api/saas/events/unassign", { name });
+  }
+
+  /**
+   * Deactivate multiple custom event assignments simultaneously.
+   */
+  async unassignBulk(names: string[]): Promise<{ success: boolean; message: string }> {
+    return this.post<{ success: boolean; message: string }>("/api/saas/events/unassign/bulk", { names });
+  }
+
+  /**
+   * Programmatically fire an event into the CRM automation engine.
+   * Emits to the internal EventBus to match with active Workflow Automation Rules.
+   */
+  async trigger(payload: TriggerPayload): Promise<TriggerResponse> {
+    return this.post<TriggerResponse>("/api/saas/workflows/trigger", payload);
+  }
+}

package/src/resources/media.ts

@@ -0,0 +1,174 @@
+import axios from "axios";
+import { APIResource } from "../resource";
+
+/**
+ * Options for the `upload()` elite helper.
+ */
+export interface UploadOptions {
+  /**
+   * The destination folder key in R2.
+   * @example "customer_documents" | "avatars" | "invoices"
+   */
+  folder: string;
+  /**
+   * The desired filename, including extension.
+   * @example "contract.pdf" | "profile.jpg"
+   */
+  filename: string;
+  /**
+   * The MIME type of the file.
+   * @example "application/pdf" | "image/jpeg" | "video/mp4"
+   */
+  contentType: string;
+}
+
+/**
+ * Cloudflare R2-backed media resource.
+ *
+ * Access via `ecod.media`.
+ *
+ * The `upload()` method is the recommended approach. It acts as a client-side
+ * orchestrator: it fetches a presigned URL from the backend, uploads directly
+ * to R2 (bypassing the API server), then confirms the upload — all in one call.
+ *
+ * @example
+ * ```typescript
+ * const { data } = await ecod.media.upload(fileBuffer, {
+ *   folder: "invoices",
+ *   filename: "invoice-001.pdf",
+ *   contentType: "application/pdf",
+ * });
+ * console.log(data.url); // → https://cdn.ecodrix.com/invoices/invoice-001.pdf
+ * ```
+ */
+export class MediaResource extends APIResource {
+  /**
+   * Get current storage usage metrics for the tenant.
+   *
+   * @returns `{ usedMB, limitMB, fileCount }`
+   *
+   * @example
+   * ```typescript
+   * const { data } = await ecod.media.getUsage();
+   * console.log(`${data.usedMB} / ${data.limitMB} MB used`);
+   * ```
+   */
+  async getUsage() {
+    return this.get("/api/saas/storage/usage");
+  }
+
+  /**
+   * Create a new top-level folder in the tenant's R2 bucket.
+   *
+   * @param name - Folder name (alphanumeric, hyphens, underscores).
+   *
+   * @example
+   * ```typescript
+   * await ecod.media.createFolder("patient_records");
+   * ```
+   */
+  async createFolder(name: string) {
+    return this.post("/api/saas/storage/folders", { name });
+  }
+
+  /**
+   * List files within a specific folder, with optional date filtering.
+   *
+   * @param folder - The folder key to list.
+   * @param params - Optional `year` and `month` filters (e.g. `{ year: "2026", month: "04" }`).
+   * @returns Array of file metadata objects.
+   *
+   * @example
+   * ```typescript
+   * const { data: files } = await ecod.media.list("invoices", { year: "2026" });
+   * ```
+   */
+  async list(folder: string, params?: { year?: string; month?: string }) {
+    return this.get(`/api/saas/storage/files/${folder}`, { params } as any);
+  }
+
+  /**
+   * Delete a file from R2 by its storage key.
+   *
+   * @param key - The full storage key of the file (e.g. `"invoices/contract.pdf"`).
+   *
+   * @example
+   * ```typescript
+   * await ecod.media.delete("invoices/old-contract.pdf");
+   * ```
+   */
+  async delete(key: string) {
+    return this.deleteRequest("/api/saas/storage/files", { params: { key } });
+  }
+
+  /**
+   * Request a temporary presigned download URL for a private file.
+   *
+   * @param key - The full storage key of the file.
+   * @returns `{ url }` — a time-limited download URL.
+   *
+   * @example
+   * ```typescript
+   * const { data } = await ecod.media.getDownloadUrl("invoices/contract.pdf");
+   * // → { url: "https://cdn.ecodrix.com/...?token=..." }
+   * ```
+   */
+  async getDownloadUrl(key: string) {
+    return this.post("/api/saas/storage/download-url", { key });
+  }
+
+  /**
+   * **Elite Upload Helper** — uploads a file to Cloudflare R2 in a single call.
+   *
+   * This orchestrates 3 steps transparently:
+   * 1. Fetch a presigned `PUT` URL from the ECODrIx backend.
+   * 2. Upload the file _directly_ to R2 (no API proxy, maximum throughput).
+   * 3. Confirm the upload with the backend so it is indexed and tracked.
+   *
+   * Works with Node.js `Buffer`, browser `File`/`Blob`, or any stream-like
+   * object that Axios can PUT.
+   *
+   * @param file - The file data to upload.
+   * @param options - Folder, filename, and content type.
+   * @returns Confirmed file metadata including `key` and `url`.
+   *
+   * @example Node.js
+   * ```typescript
+   * import { readFileSync } from "fs";
+   * const buf = readFileSync("./invoice.pdf");
+   * const { data } = await ecod.media.upload(buf, {
+   *   folder: "invoices",
+   *   filename: "invoice-001.pdf",
+   *   contentType: "application/pdf",
+   * });
+   * ```
+   *
+   * @example Browser
+   * ```typescript
+   * const file = inputElement.files[0];
+   * const { data } = await ecod.media.upload(file, {
+   *   folder: "avatars",
+   *   filename: file.name,
+   *   contentType: file.type,
+   * });
+   * ```
+   */
+  async upload(file: any, options: UploadOptions): Promise<any> {
+    // Step 1: Get presigned URL
+    const { data: presignedData } = await this.client.post(
+      "/api/saas/storage/upload-url",
+      options,
+    );
+    const { uploadUrl, key } = presignedData;
+
+    // Step 2: Upload directly to R2 (bypasses the API server for performance)
+    await axios.put(uploadUrl, file, {
+      headers: { "Content-Type": options.contentType },
+    });
+
+    const sizeBytes = file.size || file.byteLength || 0;
+
+    // Step 3: Confirm with backend
+    return this.post("/api/saas/storage/confirm-upload", { key, sizeBytes });
+  }
+}

package/src/resources/meet.ts

@@ -0,0 +1,153 @@
+import { APIResource } from "../resource";
+
+/**
+ * Parameters for scheduling a new Google Meet appointment.
+ */
+export interface CreateMeetingParams {
+  /** The CRM Lead ID this meeting belongs to. */
+  leadId: string;
+  /** Full name of the external participant. */
+  participantName: string;
+  /** Phone number of the participant in E.164 format. */
+  participantPhone: string;
+  /**
+   * Meeting start time.
+   * @example new Date("2026-04-10T10:00:00.000Z")
+   */
+  startTime: Date | string;
+  /**
+   * Meeting end time.
+   * @example new Date("2026-04-10T10:30:00.000Z")
+   */
+  endTime: Date | string;
+  /** Arbitrary metadata to attach to the meeting record. */
+  metadata?: Record<string, any>;
+}
+
+/**
+ * Parameters for updating an existing meeting.
+ */
+export interface UpdateMeetingParams {
+  /**
+   * Update the meeting status.
+   * @example "scheduled" | "completed" | "cancelled"
+   */
+  status?: string;
+  /** Update the payment status for paid consultations. */
+  paymentStatus?: string;
+  /** New start time for rescheduling. */
+  startTime?: Date | string;
+  /** New end time for rescheduling. */
+  endTime?: Date | string;
+  /** Duration in minutes. */
+  duration?: number;
+}
+
+/**
+ * Google Meet appointment scheduling resource.
+ *
+ * Access via `ecod.meet`.
+ *
+ * @example
+ * ```typescript
+ * const { data } = await ecod.meet.create({
+ *   leadId: "64abc...",
+ *   participantName: "Alice",
+ *   participantPhone: "+919876543210",
+ *   startTime: "2026-04-10T10:00:00Z",
+ *   endTime: "2026-04-10T10:30:00Z",
+ * });
+ * console.log(data.meetLink); // → https://meet.google.com/abc-defg-hij
+ * ```
+ */
+export class Meetings extends APIResource {
+  /**
+   * Schedule a new Google Meet with a lead.
+   *
+   * The backend automatically creates a Google Calendar event and generates
+   * a Meet link, then sends confirmation notifications via WhatsApp.
+   *
+   * @param data - Meeting details.
+   * @returns The created Meeting document including `meetLink`.
+   *
+   * @example
+   * ```typescript
+   * const { data } = await ecod.meet.create({
+   *   leadId: "64abc...",
+   *   participantName: "Alice",
+   *   participantPhone: "+91...",
+   *   startTime: "2026-04-10T10:00:00Z",
+   *   endTime: "2026-04-10T10:30:00Z",
+   * });
+   * ```
+   */
+  async create(data: CreateMeetingParams): Promise<any> {
+    return this.post("/api/saas/meet", data);
+  }
+
+  /**
+   * List all meetings for the tenant, with optional filters.
+   *
+   * @param params - `leadId` to filter by lead; `status` to filter by state.
+   * @returns Array of Meeting documents.
+   *
+   * @example
+   * ```typescript
+   * const { data } = await ecod.meet.list({ status: "scheduled" });
+   * ```
+   */
+  async list(params?: { leadId?: string; status?: string }): Promise<any> {
+    return this.get("/api/saas/meet", { params } as any);
+  }
+
+  /**
+   * Retrieve the full details for a specific meeting.
+   *
+   * @param meetingId - The unique meeting ID.
+   * @returns The Meeting document.
+   *
+   * @example
+   * ```typescript
+   * const { data } = await ecod.meet.retrieve("meeting_id");
+   * ```
+   */
+  async retrieve(meetingId: string): Promise<any> {
+    return this.get(`/api/saas/meet/${meetingId}`);
+  }
+
+  /**
+   * Update or reschedule an existing meeting.
+   *
+   * Partial updates are supported — only supply the fields you wish to change.
+   *
+   * @param meetingId - The meeting to update.
+   * @param data - Fields to update.
+   * @returns The updated Meeting document.
+   *
+   * @example
+   * ```typescript
+   * // Reschedule
+   * await ecod.meet.update("meeting_id", {
+   *   startTime: "2026-04-11T11:00:00Z",
+   *   endTime: "2026-04-11T11:30:00Z",
+   * });
+   * ```
+   */
+  async update(meetingId: string, data: UpdateMeetingParams): Promise<any> {
+    return this.client.patch(`/api/saas/meet/${meetingId}`, data).then((res) => res.data);
+  }
+
+  /**
+   * Cancel a meeting. This sets the meeting status to `"cancelled"`.
+   *
+   * @param meetingId - The meeting to cancel.
+   *
+   * @example
+   * ```typescript
+   * await ecod.meet.delete("meeting_id");
+   * ```
+   */
+  async delete(meetingId: string): Promise<any> {
+    return this.update(meetingId, { status: "cancelled" });
+  }
+}

package/src/resources/notifications.ts

@@ -0,0 +1,123 @@
+import { APIResource } from "../resource";
+
+/**
+ * Filters for querying event and automation execution logs.
+ */
+export interface LogFilter {
+  /** Page number for pagination (1-indexed). */
+  page?: number;
+  /** Maximum number of records to return per page. */
+  limit?: number;
+  /**
+   * Filter by automation trigger name.
+   * @example "lead_created" | "appointment_booked"
+   */
+  trigger?: string;
+  /**
+   * Filter by execution status.
+   * @example "success" | "failed" | "pending"
+   */
+  status?: string;
+  /** Filter logs associated with a specific phone number. */
+  phone?: string;
+  /** Start of the date range (inclusive). ISO 8601 or Date object. */
+  startDate?: string | Date;
+  /** End of the date range (inclusive). ISO 8601 or Date object. */
+  endDate?: string | Date;
+}
+
+/**
+ * Automation event log and provider callback resource.
+ *
+ * Access via `ecod.notifications`.
+ *
+ * This resource is **read-only**. It exposes platform audit trails — useful
+ * for debugging automation failures, monitoring webhook callbacks, and
+ * building internal ops dashboards.
+ *
+ * @example
+ * ```typescript
+ * // Find failed automations in April
+ * const { data } = await ecod.notifications.listLogs({
+ *   status: "failed",
+ *   startDate: "2026-04-01",
+ *   endDate: "2026-04-30",
+ * });
+ * ```
+ */
+export class Notifications extends APIResource {
+  /**
+   * List automation execution logs with optional filtering.
+   *
+   * Each log entry represents one automation run triggered by a platform event.
+   * Filter by `status: "failed"` to build a failure alerting pipeline.
+   *
+   * @param params - Optional filter criteria.
+   * @returns Paginated list of event log objects.
+   *
+   * @example
+   * ```typescript
+   * const { data: failed } = await ecod.notifications.listLogs({
+   *   status: "failed",
+   *   trigger: "lead_created",
+   *   limit: 50,
+   * });
+   * ```
+   */
+  async listLogs(params?: LogFilter) {
+    return this.get("/api/saas/events/logs", { params } as any);
+  }
+
+  /**
+   * Retrieve the full details for a single automation event log entry.
+   *
+   * @param logId - The unique log ID.
+   * @returns A single event log document including the payload and error trace.
+   *
+   * @example
+   * ```typescript
+   * const { data } = await ecod.notifications.retrieveLog("log_64abc...");
+   * console.log(data.error);  // → "Provider timeout after 30s"
+   * ```
+   */
+  async retrieveLog(logId: string) {
+    return this.get(`/api/saas/events/logs/${logId}`);
+  }
+
+  /**
+   * Get a summary statistics object for automation event execution.
+   *
+   * @param params - Optional date range for the summary window.
+   * @returns `{ total, success, failed, pending }` counts.
+   *
+   * @example
+   * ```typescript
+   * const { data: stats } = await ecod.notifications.getStats({
+   *   startDate: "2026-04-01",
+   *   endDate: "2026-04-30",
+   * });
+   * console.log(`Failed: ${stats.failed} / ${stats.total}`);
+   * ```
+   */
+  async getStats(params?: { startDate?: string; endDate?: string }) {
+    return this.get("/api/saas/events/stats", { params } as any);
+  }
+
+  /**
+   * List external provider webhook callback logs.
+   *
+   * These are inbound HTTP callbacks from third-party providers
+   * (payment gateways, email services, etc.) stored for audit purposes.
+   *
+   * @param params - Pagination and date filter options.
+   * @returns Paginated list of callback log records.
+   *
+   * @example
+   * ```typescript
+   * const { data } = await ecod.notifications.listCallbacks({ limit: 20 });
+   * ```
+   */
+  async listCallbacks(params?: Omit<LogFilter, "trigger" | "phone">) {
+    return this.get("/api/saas/callbacks/logs", { params } as any);
+  }
+}

package/src/resources/webhooks.ts

@@ -0,0 +1,85 @@
+import { APIError } from "../error";
+
+export class WebhookSignatureError extends APIError {
+  constructor(message: string) {
+    super(message, 400, "invalid_signature");
+    this.name = "WebhookSignatureError";
+  }
+}
+
+/**
+ * Validates and constructs webhook events sent by the ECODrIx platform.
+ * Ensures the payload has not been tampered with.
+ *
+ * @example
+ * ```typescript
+ * import { ecod } from "./services/ecodrix";
+ *
+ * app.post("/api/webhooks", async (req, res) => {
+ *   try {
+ *     const event = await ecod.webhooks.constructEvent(
+ *       req.rawBody,
+ *       req.headers["x-ecodrix-signature"],
+ *       process.env.ECOD_WEBHOOK_SECRET
+ *     );
+ *     console.log("Verified event:", event.type);
+ *     res.send({ received: true });
+ *   } catch (err) {
+ *     res.status(400).send(`Webhook Error: ${err.message}`);
+ *   }
+ * });
+ * ```
+ */
+export class Webhooks {
+  /**
+   * Cryptographically validates a webhook payload.
+   * Note: This method dynamically imports Node's `crypto` module, meaning it will only execute gracefully in a Server environment.
+   *
+   * @param payload - The raw request body as a string or Buffer.
+   * @param signature - The `x-ecodrix-signature` header value.
+   * @param secret - The webhook signing secret for your tenant.
+   * @returns The parsed JSON object of the event if the signature is valid.
+   * @throws WebhookSignatureError if the validation fails.
+   */
+  public async constructEvent(
+    payload: string | Buffer,
+    signature: string | string[] | undefined,
+    secret: string
+  ): Promise<any> {
+    if (!signature) {
+      throw new WebhookSignatureError("No webhook signature provided");
+    }
+
+    let sig = Array.isArray(signature) ? signature[0] : signature;
+    if (sig.startsWith("sha256=")) {
+      sig = sig.slice(7);
+    }
+
+    try {
+      // Dynamic import ensures Isomorphic bundles (like Vite UI) don't crash on import,
+      // and only throw if someone incorrectly tries to verify a webhook in the browser.
+      const crypto = await import("node:crypto");
+
+      const hmac = crypto.createHmac("sha256", secret);
+      const digest = hmac.update(payload).digest("hex");
+
+      const isValid = crypto.timingSafeEqual(
+        Buffer.from(digest),
+        Buffer.from(sig)
+      );
+
+      if (!isValid) {
+        throw new WebhookSignatureError("Invalid webhook signature provided");
+      }
+
+      return JSON.parse(payload.toString("utf8"));
+    } catch (error: any) {
+      if (error instanceof WebhookSignatureError) {
+        throw error;
+      }
+      throw new WebhookSignatureError(
+        `Webhook payload parsing failed: ${error.message}`
+      );
+    }
+  }
+}

package/src/resources/whatsapp/conversations.ts

@@ -0,0 +1,43 @@
+import { APIResource } from "../../resource";
+
+export interface ListParams {
+  limit?: number;
+  before?: string;
+}
+
+export class Conversations extends APIResource {
+  /**
+   * List conversations for the tenant.
+   */
+  async list(params?: ListParams): Promise<any> {
+    return this.get("/api/saas/chat/conversations", { params } as any);
+  }
+
+  /**
+   * Retrieve details of a specific conversation.
+   */
+  async retrieve(conversationId: string): Promise<any> {
+    return this.get(`/api/saas/chat/conversations/${conversationId}`);
+  }
+
+  /**
+   * Get messages for a specific conversation.
+   */
+  async messages(conversationId: string, params?: ListParams): Promise<any> {
+    return this.get(`/api/saas/chat/conversations/${conversationId}/messages`, { params } as any);
+  }
+
+  /**
+   * Link a conversation to a lead.
+   */
+  async linkLead(conversationId: string, leadId: string) {
+    return this.post(`/api/saas/chat/conversations/${conversationId}/link-lead`, { leadId });
+  }
+
+  /**
+   * Delete a conversation.
+   */
+  async delete(conversationId: string): Promise<any> {
+    return this.deleteRequest(`/api/saas/chat/conversations/${conversationId}`);
+  }
+}