@ecodrix/erix-api 1.2.0 → 1.2.1

package/dist/ts/cjs/index.d.cts

@@ -378,6 +378,67 @@ declare class Automations extends APIResource {
     webhookEvent<T = any>(ruleId: string, eventName: string, payload?: any): Promise<T>;
 }
 
+/**
+ * The specific UI control type suggested for a field.
+ */
+type FieldType = "string" | "number" | "boolean" | "date" | "datetime" | "select" | "multi-select" | "phone" | "email" | "currency" | "json" | "textarea" | "richtext" | "file" | "image";
+/**
+ * Metadata defining a single field within a resource.
+ * Used by UI kits to automatically generate forms and validation logic.
+ */
+interface FieldManifest {
+    /** The technical key name used in API requests. */
+    key: string;
+    /** Human-readable label (localized if possible). */
+    label: string;
+    /** Suggested UI type. */
+    type: FieldType;
+    /** Short hint/placeholder text. */
+    description?: string;
+    /** Whether the field is required for creation. */
+    required: boolean;
+    /** Whether the field should be hidden from standard create/edit forms. */
+    hidden?: boolean;
+    /** If type is 'select', the available options. */
+    options?: Array<{
+        label: string;
+        value: string | number;
+    }>;
+    /** Validation constraints. */
+    validation?: {
+        regex?: string;
+        min?: number;
+        max?: number;
+        message?: string;
+    };
+    /** Whether the field is read-only. */
+    readOnly?: boolean;
+    /** UI grouping/category name. */
+    group?: string;
+}
+/**
+ * A logical grouping of fields and UI hints for a top-level resource.
+ * Provides a 'blueprint' for erix-react components.
+ */
+interface ResourceManifest {
+    /** The unique name of the resource (e.g., 'Lead', 'Template'). */
+    name: string;
+    /** All available fields for this resource. */
+    fields: FieldManifest[];
+    /** Suggested UI configurations. */
+    uiHints?: {
+        icon?: string;
+        primaryColor?: string;
+        /** Default sort order. */
+        defaultSort?: {
+            field: string;
+            direction: "asc" | "desc";
+        };
+        /** Fields to show in a compact table view. */
+        summaryFields?: string[];
+    };
+}
+
 /**
  * Valid statuses for a CRM Lead.
  */
@@ -475,6 +536,14 @@ declare class Leads extends APIResource {
      * ```
      */
     create<T = any>(params: CreateLeadParams): Promise<T>;
+    /**
+     * 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.
+     */
+    describe(): Promise<ResourceManifest>;
     /**
      * Upsert a lead by phone number. If a lead with the same phone exists,
      * it will be updated; otherwise, a new lead is created.
@@ -701,6 +770,15 @@ declare class Pipelines extends APIResource {
      * ```
      */
     list<T = any>(): Promise<T>;
+    /**
+     * 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.
+     */
+    getStageManifest(pipelineId: string): Promise<ResourceManifest>;
     /**
      * Create a new CRM sales or support pipeline.
      *
@@ -907,33 +985,98 @@ interface CampaignResult {
     message?: string;
     [key: string]: any;
 }
-declare class EmailResource extends APIResource {
+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;
+}
+interface CreateTemplateDTO {
+    name: string;
+    subject: string;
+    htmlBody: string;
+    description?: string;
+    category?: "marketing" | "transactional" | "sequence";
+    status?: "draft" | "published" | "archived";
+    variableMapping?: any[];
+}
+interface TemplatePreviewResponse {
+    success: boolean;
+    data: {
+        subject: string;
+        html: string;
+        text?: string;
+    };
+}
+/**
+ * Outbound email marketing engine and template management.
+ *
+ * Access via `ecod.email`.
+ */
+declare 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>"
-     * });
-     * ```
      */
-    sendEmailCampaign(payload: SendCampaignPayload): Promise<CampaignResult>;
+    sendCampaign(payload: SendCampaignPayload): Promise<CampaignResult>;
     /**
      * 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");
-     * ```
      */
-    sendTestEmail(to: string): Promise<CampaignResult>;
+    sendTest(to: string): Promise<CampaignResult>;
+    /**
+     * List all email templates.
+     */
+    listTemplates(query?: any): Promise<{
+        success: boolean;
+        data: EmailTemplate[];
+    }>;
+    /**
+     * Get a single email template by ID.
+     */
+    getTemplate(id: string): Promise<{
+        success: boolean;
+        data: EmailTemplate;
+    }>;
+    /**
+     * Create a new email template.
+     */
+    createTemplate(data: CreateTemplateDTO): Promise<{
+        success: boolean;
+        data: EmailTemplate;
+    }>;
+    /**
+     * Update an existing email template.
+     */
+    updateTemplate(id: string, data: Partial<CreateTemplateDTO>): Promise<{
+        success: boolean;
+        data: EmailTemplate;
+    }>;
+    /**
+     * Delete an email template.
+     */
+    deleteTemplate(id: string, force?: boolean): Promise<{
+        success: boolean;
+    }>;
+    /**
+     * Preview a template with dynamic variable resolution.
+     */
+    previewTemplate(id: string, params: {
+        leadId?: string;
+        variables?: Record<string, any>;
+    }): Promise<TemplatePreviewResponse>;
+}
+/** @deprecated Use Email instead */
+declare class EmailResource extends Email {
 }
 
 /**
@@ -1133,39 +1276,122 @@ interface JobStatus {
     failedAt: string | null;
     createdAt: string;
 }
+/**
+ * Platform and tenant-specific health diagnostics.
+ *
+ * Access via `ecod.health`.
+ */
 declare 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.
      */
     system(): Promise<SystemHealth>;
     /**
-     * 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.
      */
     clientHealth(): Promise<ClientHealth>;
+    /**
+     * Alias for clientHealth to match diagnostic terminology.
+     */
+    getDiagnosticReport(): Promise<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!");
-     * }
-     * ```
      */
     jobStatus(jobId: string): Promise<JobStatus>;
 }
 
+interface LogPaginationQuery {
+    page?: number;
+    limit?: number;
+    trigger?: string;
+    status?: "received" | "processing" | "completed" | "partial" | "failed";
+    from?: string;
+    to?: string;
+}
+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;
+}
+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;
+}
+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`.
+ */
+declare class Logs extends APIResource {
+    /**
+     * List event execution logs with optional filtering.
+     *
+     * Use this to audit automation triggers and debug workflow execution.
+     */
+    listEventLogs(query?: LogPaginationQuery): Promise<LogResponse<EventLog>>;
+    /**
+     * Get detailed information for a single event execution.
+     */
+    getEventLog(id: string): Promise<{
+        success: boolean;
+        data: EventLog;
+    }>;
+    /**
+     * List webhook callback logs (outbound responses from ECODrIx to your system).
+     */
+    listCallbackLogs(query?: LogPaginationQuery): Promise<LogResponse<CallbackLog>>;
+    /**
+     * Get high-level execution statistics for the tenant.
+     */
+    getStats(): Promise<{
+        success: boolean;
+        data: any;
+    }>;
+}
+
 interface SendCampaignParams {
     recipients: string[];
     subject: string;
@@ -1352,7 +1578,7 @@ interface UploadOptions {
  * console.log(data.url); // → https://cdn.ecodrix.com/invoices/invoice-001.pdf
  * ```
  */
-declare class MediaResource extends APIResource {
+declare class Media extends APIResource {
     /**
      * Get current storage usage metrics for the tenant.
      *
@@ -1455,6 +1681,9 @@ declare class MediaResource extends APIResource {
      */
     upload(file: any, options: UploadOptions): Promise<any>;
 }
+/** @deprecated Use Media instead */
+declare class MediaResource extends Media {
+}
 
 /**
  * Parameters for scheduling a new Google Meet appointment.
@@ -2491,6 +2720,15 @@ declare class Templates extends APIResource {
         lead?: any;
         vars?: any;
     }): Promise<T>;
+    /**
+     * 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.
+     */
+    getVariableManifest(templateIdentifier: string): Promise<ResourceManifest>;
     /**
      * Check which automations or sequences are currently using this template.
      */
@@ -2597,13 +2835,15 @@ declare class Ecodrix {
     /** CRM resources — Leads and related sub-resources. */
     readonly crm: CRM;
     /** Cloudflare R2-backed media storage. */
-    readonly media: MediaResource;
+    readonly media: Media;
     /** Google Meet appointment scheduling. */
     readonly meet: Meetings;
     /** Automation execution logs and provider webhook callbacks. */
     readonly notifications: Notifications;
-    /** Outbound email marketing engine. */
-    readonly email: EmailResource;
+    /** Outbound email marketing engine and template management. */
+    readonly email: Email;
+    /** Platform-wide execution logs and audit trails. */
+    readonly logs: Logs;
     /** Lead events and workflow automation triggers. */
     readonly events: EventsResource;
     /** Cryptographic webhook signature verification. */
@@ -2697,4 +2937,4 @@ declare class Ecodrix {
     request<T = any>(method: Method, path: string, data?: any, params?: any): Promise<T>;
 }
 
-export { APIError, Activities, Analytics, type AnalyticsParams, type AnalyticsRange, type AssignEventPayload, AuthenticationError, AutomationDashboard, type AutomationRulePayload, Automations, Broadcasts, CRM, type CampaignResult, Campaigns, type ChatMediaMeta, type ClientHealth, Conversations, type CreateBroadcastParams, type CreateLeadParams, type CreateMeetingParams, type CreatePipelineParams, Ecodrix, EcodrixError, type EcodrixOptions, EmailResource, Emails, type EventDefinition, EventsResource, Files, Folders, Health, type JobStats, type JobStatus, type LeadSource, type LeadStatus, Leads, type ListLeadsParams, type ListParams, type LogActivityParams, type LogCallParams, type LogFilter, Marketing, MediaResource, Meetings, Messages, Notes, Notifications, Payments, type PipelineStageParams, Pipelines, Queue, RateLimitError, Scoring, type ScoringConfig, type SendCampaignParams, type SendCampaignPayload, type SendMessageParams, type SendTemplateParams, type SendTemplatePayload, Sequences, Storage, type SystemHealth, type TemplateMapping, Templates, type TriggerPayload, type TriggerResponse, type UpdateMeetingParams, type UploadOptions, type UpsertLeadParams, WebhookSignatureError, Webhooks, WhatsApp, WhatsAppMarketing, Ecodrix as default };
+export { APIError, Activities, Analytics, type AnalyticsParams, type AnalyticsRange, type AssignEventPayload, AuthenticationError, AutomationDashboard, type AutomationRulePayload, Automations, Broadcasts, CRM, type CallbackLog, type CampaignResult, Campaigns, type ChatMediaMeta, type ClientHealth, Conversations, type CreateBroadcastParams, type CreateLeadParams, type CreateMeetingParams, type CreatePipelineParams, type CreateTemplateDTO, Ecodrix, EcodrixError, type EcodrixOptions, Email, EmailResource, type EmailTemplate, Emails, type EventDefinition, type EventLog, EventsResource, type FieldManifest, type FieldType, Files, Folders, Health, type JobStats, type JobStatus, type LeadSource, type LeadStatus, Leads, type ListLeadsParams, type ListParams, type LogActivityParams, type LogCallParams, type LogFilter, type LogPaginationQuery, type LogResponse, Logs, Marketing, Media, MediaResource, Meetings, Messages, Notes, Notifications, Payments, type PipelineStageParams, Pipelines, Queue, RateLimitError, type ResourceManifest, Scoring, type ScoringConfig, type SendCampaignParams, type SendCampaignPayload, type SendMessageParams, type SendTemplateParams, type SendTemplatePayload, Sequences, Storage, type SystemHealth, type TemplateMapping, type TemplatePreviewResponse, Templates, type TriggerPayload, type TriggerResponse, type UpdateMeetingParams, type UploadOptions, type UpsertLeadParams, WebhookSignatureError, Webhooks, WhatsApp, WhatsAppMarketing, Ecodrix as default };