@ecodrix/erix-api 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,1096 @@
+import { AxiosInstance, AxiosRequestConfig, Method } from 'axios';
+
+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;
+}
+declare abstract class APIResource {
+    protected readonly client: AxiosInstance;
+    constructor(client: AxiosInstance);
+    protected post<T>(url: string, data?: any, options?: RequestOptions): Promise<T>;
+    protected get<T>(url: string, options?: RequestOptions): Promise<T>;
+    protected deleteRequest<T>(url: string, options?: RequestOptions): Promise<T>;
+    private buildConfig;
+    private handleError;
+}
+
+/**
+ * Parameters for sending a free-form WhatsApp message.
+ */
+interface SendMessageParams {
+    /**
+     * Recipient's phone number in E.164 format.
+     * @example "+919876543210"
+     */
+    to: string;
+    /** Plain text body of the message. */
+    text?: string;
+    /** Public URL of the media asset to send. */
+    mediaUrl?: string;
+    /** MIME category of the media. */
+    mediaType?: "image" | "video" | "audio" | "document";
+    /** The `messageId` of the message to reply to (quoted replies). */
+    replyToId?: string;
+    /** Filename shown to the recipient (required for `document` type). */
+    filename?: string;
+    /** Arbitrary metadata stored with the message record. */
+    metadata?: Record<string, any>;
+}
+/**
+ * Parameters for sending a pre-approved WhatsApp Business template.
+ */
+interface SendTemplateParams {
+    /**
+     * Recipient's phone number in E.164 format.
+     * @example "+919876543210"
+     */
+    to: string;
+    /** The exact template name as approved in Meta Business Manager. */
+    templateName: string;
+    /**
+     * BCP-47 language code for the template.
+     * @default "en_US"
+     */
+    language?: string;
+    /**
+     * Ordered array of variable substitutions for template placeholders.
+     * @example ["Alice", "10 April 2026", "10:00 AM"]
+     */
+    variables?: string[];
+    /** Optional header media URL (for templates with media headers). */
+    mediaUrl?: string;
+    /** Media type for the header (e.g. "image", "document"). */
+    mediaType?: string;
+}
+/**
+ * WhatsApp outbound messaging resource.
+ *
+ * Access via `ecod.whatsapp.messages`.
+ *
+ * @example
+ * ```typescript
+ * await ecod.whatsapp.messages.send({
+ *   to: "+919876543210",
+ *   text: "Your appointment is confirmed!",
+ * });
+ * ```
+ */
+declare class Messages extends APIResource {
+    /**
+     * Send a free-text or media message to a WhatsApp number.
+     *
+     * For text-only messages, supply `text`. For media, supply `mediaUrl`
+     * and `mediaType`. Both can be combined.
+     *
+     * @param params - Message parameters.
+     * @returns The created message record.
+     *
+     * @example Text message
+     * ```typescript
+     * await ecod.whatsapp.messages.send({
+     *   to: "+919876543210",
+     *   text: "Hello!",
+     * });
+     * ```
+     *
+     * @example Media message
+     * ```typescript
+     * await ecod.whatsapp.messages.send({
+     *   to: "+919876543210",
+     *   mediaUrl: "https://cdn.ecodrix.com/invoice.pdf",
+     *   mediaType: "document",
+     *   filename: "invoice.pdf",
+     * });
+     * ```
+     */
+    send(params: SendMessageParams): Promise<unknown>;
+    /**
+     * Send a pre-approved WhatsApp Business template message.
+     *
+     * Templates must be approved in Meta Business Manager before use.
+     * Variable placeholders in the template body are filled left-to-right
+     * from the `variables` array.
+     *
+     * @param params - Template message parameters.
+     * @returns The created message record.
+     *
+     * @example
+     * ```typescript
+     * await ecod.whatsapp.messages.sendTemplate({
+     *   to: "+919876543210",
+     *   templateName: "appointment_reminder",
+     *   language: "en_US",
+     *   variables: ["Alice", "10 April", "10:00 AM"],
+     * });
+     * ```
+     */
+    sendTemplate(params: SendTemplateParams): Promise<unknown>;
+    /**
+     * Mark all messages in a conversation as read (double-tick).
+     *
+     * @param conversationId - The conversation to mark as read.
+     *
+     * @example
+     * ```typescript
+     * await ecod.whatsapp.messages.markRead("conv_64abc...");
+     * ```
+     */
+    markRead(conversationId: string): Promise<unknown>;
+}
+
+interface ListParams {
+    limit?: number;
+    before?: string;
+}
+declare class Conversations extends APIResource {
+    /**
+     * List conversations for the tenant.
+     */
+    list(params?: ListParams): Promise<any>;
+    /**
+     * Retrieve details of a specific conversation.
+     */
+    retrieve(conversationId: string): Promise<any>;
+    /**
+     * Get messages for a specific conversation.
+     */
+    messages(conversationId: string, params?: ListParams): Promise<any>;
+    /**
+     * Link a conversation to a lead.
+     */
+    linkLead(conversationId: string, leadId: string): Promise<unknown>;
+    /**
+     * Delete a conversation.
+     */
+    delete(conversationId: string): Promise<any>;
+}
+
+interface SendTemplatePayload {
+    /** Phone number in E.164 format. */
+    phone: string;
+    /** Name of the pre-approved WhatsApp template. */
+    templateName: string;
+    /** Language code (defaults to "en"). */
+    languageCode?: string;
+    /** Key-value pairs matching variables in your template (e.g., {{1}}, {{2}}). */
+    variables?: Record<string, string>;
+    /** Explicitly resolved variables if bypassing the internal resolution engine. */
+    resolvedVariables?: any[];
+}
+declare class WhatsApp extends APIResource {
+    messages: Messages;
+    conversations: Conversations;
+    constructor(client: AxiosInstance);
+    /**
+     * Dispatch a WhatsApp template message directly to a specific phone number.
+     * Bypasses the automation queue for immediate high-priority delivery.
+     *
+     * @param payload - The template dispatch payload.
+     * @returns Information about the dispatched message.
+     */
+    sendTemplate(payload: SendTemplatePayload): Promise<{
+        success: boolean;
+        messageId?: string;
+        templateName?: string;
+        resolvedVariables?: any[];
+    }>;
+}
+
+/**
+ * Parameters for creating a new CRM Lead.
+ */
+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",
+ * });
+ * ```
+ */
+declare 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",
+     * });
+     * ```
+     */
+    create<T = any>(params: CreateLeadParams): Promise<T>;
+    /**
+     * 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.
+     */
+    createMany(leads: CreateLeadParams[], chunkSize?: number): Promise<any[]>;
+    /**
+     * 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 });
+     * ```
+     */
+    list<T = any>(params?: Record<string, any>): Promise<T>;
+    /**
+     * 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);
+     * }
+     * ```
+     */
+    listAutoPaging(params?: Record<string, any>): AsyncGenerator<any, void, unknown>;
+    /**
+     * 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...");
+     * ```
+     */
+    retrieve(leadId: string): Promise<unknown>;
+    /**
+     * 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" });
+     * ```
+     */
+    update(leadId: string, params: Partial<CreateLeadParams>): Promise<unknown>;
+    /**
+     * 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...");
+     * ```
+     */
+    delete(leadId: string): Promise<unknown>;
+}
+
+declare class CRM {
+    leads: Leads;
+    constructor(client: AxiosInstance);
+}
+
+/**
+ * Options for the `upload()` elite helper.
+ */
+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
+ * ```
+ */
+declare 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`);
+     * ```
+     */
+    getUsage(): Promise<unknown>;
+    /**
+     * 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");
+     * ```
+     */
+    createFolder(name: string): Promise<unknown>;
+    /**
+     * 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" });
+     * ```
+     */
+    list(folder: string, params?: {
+        year?: string;
+        month?: string;
+    }): Promise<unknown>;
+    /**
+     * 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");
+     * ```
+     */
+    delete(key: string): Promise<unknown>;
+    /**
+     * 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=..." }
+     * ```
+     */
+    getDownloadUrl(key: string): Promise<unknown>;
+    /**
+     * **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,
+     * });
+     * ```
+     */
+    upload(file: any, options: UploadOptions): Promise<any>;
+}
+
+/**
+ * Parameters for scheduling a new Google Meet appointment.
+ */
+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.
+ */
+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
+ * ```
+ */
+declare 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",
+     * });
+     * ```
+     */
+    create(data: CreateMeetingParams): Promise<any>;
+    /**
+     * 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" });
+     * ```
+     */
+    list(params?: {
+        leadId?: string;
+        status?: string;
+    }): Promise<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");
+     * ```
+     */
+    retrieve(meetingId: string): Promise<any>;
+    /**
+     * 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",
+     * });
+     * ```
+     */
+    update(meetingId: string, data: UpdateMeetingParams): Promise<any>;
+    /**
+     * Cancel a meeting. This sets the meeting status to `"cancelled"`.
+     *
+     * @param meetingId - The meeting to cancel.
+     *
+     * @example
+     * ```typescript
+     * await ecod.meet.delete("meeting_id");
+     * ```
+     */
+    delete(meetingId: string): Promise<any>;
+}
+
+/**
+ * Filters for querying event and automation execution logs.
+ */
+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",
+ * });
+ * ```
+ */
+declare 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,
+     * });
+     * ```
+     */
+    listLogs(params?: LogFilter): Promise<unknown>;
+    /**
+     * 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"
+     * ```
+     */
+    retrieveLog(logId: string): Promise<unknown>;
+    /**
+     * 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}`);
+     * ```
+     */
+    getStats(params?: {
+        startDate?: string;
+        endDate?: string;
+    }): Promise<unknown>;
+    /**
+     * 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 });
+     * ```
+     */
+    listCallbacks(params?: Omit<LogFilter, "trigger" | "phone">): Promise<unknown>;
+}
+
+/**
+ * Payload to send a high-throughput email campaign.
+ */
+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.
+ */
+interface CampaignResult {
+    success: boolean;
+    message?: string;
+    [key: string]: any;
+}
+declare 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.
+     */
+    sendEmailCampaign(payload: SendCampaignPayload): Promise<CampaignResult>;
+    /**
+     * Send a system verification/test email to validate SMTP configuration.
+     *
+     * @param to - The recipient's email address.
+     * @returns The dispatch result.
+     */
+    sendTestEmail(to: string): Promise<CampaignResult>;
+}
+
+/**
+ * Event definition representing an entry point capable of triggering automations.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+interface TriggerResponse {
+    success: boolean;
+    data?: {
+        eventLogId: string;
+        trigger: string;
+        leadId: string;
+        rulesMatched: number;
+    };
+    message?: string;
+    code?: string;
+}
+declare class EventsResource extends APIResource {
+    /**
+     * Retrieve all valid events (system + custom) that can be used as Automation Rule triggers.
+     */
+    list(): Promise<{
+        success: boolean;
+        data: EventDefinition[];
+    }>;
+    /**
+     * Register a new custom event entry point into the CRM automation engine.
+     * Useful when introducing new granular triggers.
+     */
+    assign(payload: AssignEventPayload): Promise<{
+        success: boolean;
+        data: EventDefinition;
+    }>;
+    /**
+     * Deactivate a custom event assignment by name.
+     */
+    unassign(name: string): Promise<{
+        success: boolean;
+        data: any;
+    }>;
+    /**
+     * Deactivate multiple custom event assignments simultaneously.
+     */
+    unassignBulk(names: string[]): Promise<{
+        success: boolean;
+        message: string;
+    }>;
+    /**
+     * Programmatically fire an event into the CRM automation engine.
+     * Emits to the internal EventBus to match with active Workflow Automation Rules.
+     */
+    trigger(payload: TriggerPayload): Promise<TriggerResponse>;
+}
+
+/**
+ * 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. */
+declare class EcodrixError extends Error {
+    constructor(message: string);
+}
+/**
+ * Represents an error returned by the ECODrIx API.
+ * Carries the HTTP `status` code and an optional `code` string.
+ */
+declare class APIError extends EcodrixError {
+    /** HTTP status code returned by the API (e.g. 400, 404, 500). */
+    status?: number;
+    /** Machine-readable error code (e.g. `"NOT_FOUND"`, `"VALIDATION_ERROR"`). */
+    code?: string;
+    constructor(message: string, status?: number, code?: string);
+}
+/**
+ * Thrown when the API key or client code is missing, invalid, or expired.
+ * HTTP 401.
+ */
+declare class AuthenticationError extends APIError {
+    constructor(message?: string);
+}
+/**
+ * Thrown when the rate limit for the API key has been exceeded.
+ * HTTP 429. Implement exponential backoff before retrying.
+ */
+declare class RateLimitError extends APIError {
+    constructor(message?: string);
+}
+
+declare class WebhookSignatureError extends APIError {
+    constructor(message: string);
+}
+/**
+ * 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}`);
+ *   }
+ * });
+ * ```
+ */
+declare 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.
+     */
+    constructEvent(payload: string | Buffer, signature: string | string[] | undefined, secret: string): Promise<any>;
+}
+
+/**
+ * Configuration options for the Ecodrix client.
+ */
+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..." });
+ * ```
+ */
+declare class Ecodrix {
+    private readonly client;
+    private readonly socket;
+    /** WhatsApp messaging and conversation management. */
+    readonly whatsapp: WhatsApp;
+    /** CRM resources — Leads and related sub-resources. */
+    readonly crm: CRM;
+    /** Cloudflare R2-backed media storage. */
+    readonly media: MediaResource;
+    /** Google Meet appointment scheduling. */
+    readonly meet: Meetings;
+    /** Automation execution logs and provider webhook callbacks. */
+    readonly notifications: Notifications;
+    /** Outbound email marketing engine. */
+    readonly email: EmailResource;
+    /** Lead events and workflow automation triggers. */
+    readonly events: EventsResource;
+    /** Cryptographic webhook signature verification. */
+    readonly webhooks: Webhooks;
+    constructor(options: EcodrixOptions);
+    private setupSocket;
+    /**
+     * 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));
+     * ```
+     */
+    on(event: string, callback: (...args: any[]) => void): 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());
+     * ```
+     */
+    disconnect(): void;
+    /**
+     * 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);
+     * ```
+     */
+    request<T = any>(method: Method, path: string, data?: any, params?: any): Promise<T>;
+}
+
+export { APIError, type AssignEventPayload, AuthenticationError, type CampaignResult, Conversations, type CreateLeadParams, type CreateMeetingParams, Ecodrix, EcodrixError, type EcodrixOptions, EmailResource, type EventDefinition, EventsResource, Leads, type ListParams, type LogFilter, MediaResource, Meetings, Messages, Notifications, RateLimitError, type SendCampaignPayload, type SendMessageParams, type SendTemplateParams, type SendTemplatePayload, type TriggerPayload, type TriggerResponse, type UpdateMeetingParams, type UploadOptions, WebhookSignatureError, Webhooks, WhatsApp, Ecodrix as default };