lua-cli 3.29.0 → 3.30.0

package/dist/api-exports.d.ts

@@ -934,6 +934,31 @@ export declare interface ChannelsApi {
          */
         send(input: EmailSendInput): Promise<ChannelSendOutput>;
     };
+    /**
+     * Read the delivery status of one outbound message.
+     *
+     * Pass the `deliveryId` any send returned. The record moves
+     * `queued -> accepted -> sent -> delivered -> read`, or terminates on
+     * `failed`, and a failure carries a canonical `error.category`, the vendor
+     * code and a remediation link.
+     *
+     * @example
+     * ```typescript
+     * const sent = await Channels.send({ channel: 'whatsapp', to: { phoneNumber: '+15551234567' }, text: 'Hi' });
+     * const delivery = await Channels.getStatus(sent.deliveryId);
+     * if (delivery.status === 'failed') console.error(delivery.error?.category, delivery.error?.title);
+     * ```
+     */
+    getStatus(deliveryId: string): Promise<DeliveryView>;
+    /**
+     * List the agent's recent deliveries, newest first.
+     *
+     * @example
+     * ```typescript
+     * const failures = await Channels.listDeliveries({ status: 'failed', since: '2026-09-01T00:00:00Z', limit: 50 });
+     * ```
+     */
+    listDeliveries(filter?: DeliveryListFilter): Promise<DeliveryView[]>;
 }
 
 export declare type ChannelSendChannel = (typeof CHANNEL_SEND_CHANNELS)[number];
@@ -971,6 +996,18 @@ export declare interface ChannelSendOptions {
  * `warning` — never an error status for a delivered message.
  */
 export declare interface ChannelSendOutput {
+    /** Delivery record id. Stable across the send's whole lifecycle; query it for status. */
+    deliveryId: string;
+    /**
+     * Where the delivery stands the moment the send returns. `queued` means the
+     * WhatsApp window was closed and the text flushes when the user replies.
+     * Receipts move it further (delivered, read, failed) after this call.
+     *
+     * A live send returns `queued`, `accepted` or `sent`. Replaying an
+     * `X-Idempotency-Key` returns wherever the first send's delivery has since
+     * got to, so any status is possible there.
+     */
+    status: DeliveryStatus;
     delivered: boolean;
     /** False for conversation-scoped sends: a shared conversation has no single
      * user to attribute the message to, so nothing is written to agent memory. */
@@ -1543,6 +1580,98 @@ declare interface DeleteProductResponse {
     deleted: boolean;
 }
 
+/** Canonical, cross-vendor failure reason. Vendor codes map onto these. */
+declare const DELIVERY_ERROR_CATEGORIES: readonly ["window_closed", "unreachable", "billing", "opted_out", "throttled", "auth", "template", "media", "invalid_request", "compliance", "experiment", "provider", "unknown"];
+
+declare const DELIVERY_ORIGINS: readonly ["agent_reply", "channels_send", "template", "system_template", "queued_flush", "admin_template", "notification", "unknown"];
+
+declare const DELIVERY_PROVIDERS: readonly ["meta", "vonage", "bird", "ses", "agentmail", "slack", "front", "teams", "pusher"];
+
+/**
+ * Outbound delivery record contracts.
+ *
+ * One outbound message is one delivery document moving through a monotone
+ * status rank with a single terminal failure. Vendor callbacks are normalised
+ * into `ProviderStatusUpdate` by a per-provider mapper, so vendor vocabulary
+ * stops at the mapper and everything downstream speaks these types.
+ */
+declare const DELIVERY_STATUSES: readonly ["queued", "accepted", "sent", "delivered", "read", "failed", "expired"];
+
+export declare interface DeliveryError {
+    category: DeliveryErrorCategory;
+    provider: DeliveryProvider;
+    /** Vendor code as a string. '131042', '1240', 'Permanent/General'. */
+    code: string;
+    title: string;
+    detail?: string;
+    href?: string;
+    retryable: boolean;
+    owner: DeliveryErrorOwner;
+}
+
+export declare type DeliveryErrorCategory = (typeof DELIVERY_ERROR_CATEGORIES)[number];
+
+/** Who has to act on a failure. Drives the operator surface, not retry logic. */
+declare type DeliveryErrorOwner = 'customer' | 'recipient' | 'lua' | 'vendor';
+
+declare type DeliveryEventSource = 'send' | 'callback' | 'sweep';
+
+declare interface DeliveryEventView {
+    status: DeliveryStatus;
+    at: string;
+    source: DeliveryEventSource;
+}
+
+/** Query filter accepted by the delivery list read APIs. */
+export declare interface DeliveryListFilter {
+    userId?: string;
+    status?: DeliveryStatus;
+    channel?: string;
+    /** Only deliveries created at or after this instant. */
+    since?: string | Date;
+    /** 1..200, defaults to 50. */
+    limit?: number;
+}
+
+declare type DeliveryOrigin = (typeof DELIVERY_ORIGINS)[number];
+
+/** Vendor-reported cost metadata. Meta only today. */
+declare interface DeliveryPricing {
+    billable: boolean;
+    category?: string;
+    model?: string;
+}
+
+declare type DeliveryProvider = (typeof DELIVERY_PROVIDERS)[number];
+
+export declare type DeliveryStatus = (typeof DELIVERY_STATUSES)[number];
+
+/** Wire shape of a delivery as returned by read APIs (dates as ISO strings). */
+export declare interface DeliveryView {
+    id: string;
+    agentId: string;
+    userId?: string;
+    /** `ChannelSendChannel | 'rcs' | 'messagebird' | 'slack' | 'front' | 'webchat' | 'sms'`. */
+    channel: string;
+    provider: DeliveryProvider;
+    channelIdentifier: string;
+    recipient: string;
+    providerMessageId?: string;
+    conversationMessageId?: string;
+    origin: DeliveryOrigin;
+    templateName?: string;
+    idempotencyKey?: string;
+    status: DeliveryStatus;
+    error?: DeliveryError;
+    events: DeliveryEventView[];
+    pricing?: DeliveryPricing;
+    createdAt: string;
+    updatedAt: string;
+    deliveredAt?: string;
+    readAt?: string;
+    failedAt?: string;
+}
+
 /** Configuration for a single device command (agent → device) */
 export declare interface DeviceCommandConfig {
     /** Description of what this command does */
@@ -1840,6 +1969,7 @@ declare abstract class HttpClient {
      * cannot be recovered after an ambiguous network or server failure.
      */
     protected httpPostOnce<T>(url: string, data?: any, headers?: Record<string, string>): Promise<ApiResponse<T>>;
+    protected httpPostCoreDrainRetry<T>(url: string, data?: any, headers?: Record<string, string>): Promise<ApiResponse<T>>;
     /**
      * Performs an HTTP PUT request
      * @param url - The relative URL path to request (will be appended to baseUrl)
@@ -3484,14 +3614,14 @@ declare const LuaVoiceConfigSchema: z.ZodEffects<z.ZodObject<{
          */
         options: z.ZodRecord<z.ZodString, z.ZodUnknown>;
     }, "strip", z.ZodTypeAny, {
+        provider?: "deepgram" | "elevenlabs";
         options?: Record<string, unknown>;
         kind?: "plugin";
-        provider?: "deepgram" | "elevenlabs";
         class?: "LLM" | "STT" | "STTv2" | "TTS";
     }, {
+        provider?: "deepgram" | "elevenlabs";
         options?: Record<string, unknown>;
         kind?: "plugin";
-        provider?: "deepgram" | "elevenlabs";
         class?: "LLM" | "STT" | "STTv2" | "TTS";
     }>, z.ZodObject<{
         kind: z.ZodLiteral<"realtime">;
@@ -3504,13 +3634,13 @@ declare const LuaVoiceConfigSchema: z.ZodEffects<z.ZodObject<{
          */
         options: z.ZodRecord<z.ZodString, z.ZodUnknown>;
     }, "strip", z.ZodTypeAny, {
+        provider?: "google" | "xai" | "openai";
         options?: Record<string, unknown>;
         kind?: "realtime";
-        provider?: "google" | "xai" | "openai";
     }, {
+        provider?: "google" | "xai" | "openai";
         options?: Record<string, unknown>;
         kind?: "realtime";
-        provider?: "google" | "xai" | "openai";
     }>]>;
     stt: z.ZodOptional<z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
         kind: z.ZodLiteral<"inference">;
@@ -3550,14 +3680,14 @@ declare const LuaVoiceConfigSchema: z.ZodEffects<z.ZodObject<{
          */
         options: z.ZodRecord<z.ZodString, z.ZodUnknown>;
     }, "strip", z.ZodTypeAny, {
+        provider?: "deepgram" | "elevenlabs";
         options?: Record<string, unknown>;
         kind?: "plugin";
-        provider?: "deepgram" | "elevenlabs";
         class?: "LLM" | "STT" | "STTv2" | "TTS";
     }, {
+        provider?: "deepgram" | "elevenlabs";
         options?: Record<string, unknown>;
         kind?: "plugin";
-        provider?: "deepgram" | "elevenlabs";
         class?: "LLM" | "STT" | "STTv2" | "TTS";
     }>, z.ZodObject<{
         kind: z.ZodLiteral<"realtime">;
@@ -3570,13 +3700,13 @@ declare const LuaVoiceConfigSchema: z.ZodEffects<z.ZodObject<{
          */
         options: z.ZodRecord<z.ZodString, z.ZodUnknown>;
     }, "strip", z.ZodTypeAny, {
+        provider?: "google" | "xai" | "openai";
         options?: Record<string, unknown>;
         kind?: "realtime";
-        provider?: "google" | "xai" | "openai";
     }, {
+        provider?: "google" | "xai" | "openai";
         options?: Record<string, unknown>;
         kind?: "realtime";
-        provider?: "google" | "xai" | "openai";
     }>]>>;
     tts: z.ZodOptional<z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
         kind: z.ZodLiteral<"inference">;
@@ -3616,14 +3746,14 @@ declare const LuaVoiceConfigSchema: z.ZodEffects<z.ZodObject<{
          */
         options: z.ZodRecord<z.ZodString, z.ZodUnknown>;
     }, "strip", z.ZodTypeAny, {
+        provider?: "deepgram" | "elevenlabs";
         options?: Record<string, unknown>;
         kind?: "plugin";
-        provider?: "deepgram" | "elevenlabs";
         class?: "LLM" | "STT" | "STTv2" | "TTS";
     }, {
+        provider?: "deepgram" | "elevenlabs";
         options?: Record<string, unknown>;
         kind?: "plugin";
-        provider?: "deepgram" | "elevenlabs";
         class?: "LLM" | "STT" | "STTv2" | "TTS";
     }>, z.ZodObject<{
         kind: z.ZodLiteral<"realtime">;
@@ -3636,13 +3766,13 @@ declare const LuaVoiceConfigSchema: z.ZodEffects<z.ZodObject<{
          */
         options: z.ZodRecord<z.ZodString, z.ZodUnknown>;
     }, "strip", z.ZodTypeAny, {
+        provider?: "google" | "xai" | "openai";
         options?: Record<string, unknown>;
         kind?: "realtime";
-        provider?: "google" | "xai" | "openai";
     }, {
+        provider?: "google" | "xai" | "openai";
         options?: Record<string, unknown>;
         kind?: "realtime";
-        provider?: "google" | "xai" | "openai";
     }>]>>;
     vad: z.ZodOptional<z.ZodString>;
     vadOptions: z.ZodOptional<z.ZodObject<{
@@ -3808,14 +3938,14 @@ declare const LuaVoiceConfigSchema: z.ZodEffects<z.ZodObject<{
         kind?: "inference";
         model?: string;
     } | {
+        provider?: "deepgram" | "elevenlabs";
         options?: Record<string, unknown>;
         kind?: "plugin";
-        provider?: "deepgram" | "elevenlabs";
         class?: "LLM" | "STT" | "STTv2" | "TTS";
     } | {
+        provider?: "google" | "xai" | "openai";
         options?: Record<string, unknown>;
         kind?: "realtime";
-        provider?: "google" | "xai" | "openai";
     };
     volume?: number;
     llm?: {
@@ -3824,14 +3954,14 @@ declare const LuaVoiceConfigSchema: z.ZodEffects<z.ZodObject<{
         kind?: "inference";
         model?: string;
     } | {
+        provider?: "deepgram" | "elevenlabs";
         options?: Record<string, unknown>;
         kind?: "plugin";
-        provider?: "deepgram" | "elevenlabs";
         class?: "LLM" | "STT" | "STTv2" | "TTS";
     } | {
+        provider?: "google" | "xai" | "openai";
         options?: Record<string, unknown>;
         kind?: "realtime";
-        provider?: "google" | "xai" | "openai";
     };
     tts?: {
         voice?: string;
@@ -3839,14 +3969,14 @@ declare const LuaVoiceConfigSchema: z.ZodEffects<z.ZodObject<{
         kind?: "inference";
         model?: string;
     } | {
+        provider?: "deepgram" | "elevenlabs";
         options?: Record<string, unknown>;
         kind?: "plugin";
-        provider?: "deepgram" | "elevenlabs";
         class?: "LLM" | "STT" | "STTv2" | "TTS";
     } | {
+        provider?: "google" | "xai" | "openai";
         options?: Record<string, unknown>;
         kind?: "realtime";
-        provider?: "google" | "xai" | "openai";
     };
     vadOptions?: {
         minSpeechDuration?: number;
@@ -3902,14 +4032,14 @@ declare const LuaVoiceConfigSchema: z.ZodEffects<z.ZodObject<{
         kind?: "inference";
         model?: string;
     } | {
+        provider?: "deepgram" | "elevenlabs";
         options?: Record<string, unknown>;
         kind?: "plugin";
-        provider?: "deepgram" | "elevenlabs";
         class?: "LLM" | "STT" | "STTv2" | "TTS";
     } | {
+        provider?: "google" | "xai" | "openai";
         options?: Record<string, unknown>;
         kind?: "realtime";
-        provider?: "google" | "xai" | "openai";
     };
     volume?: number;
     llm?: {
@@ -3918,14 +4048,14 @@ declare const LuaVoiceConfigSchema: z.ZodEffects<z.ZodObject<{
         kind?: "inference";
         model?: string;
     } | {
+        provider?: "deepgram" | "elevenlabs";
         options?: Record<string, unknown>;
         kind?: "plugin";
-        provider?: "deepgram" | "elevenlabs";
         class?: "LLM" | "STT" | "STTv2" | "TTS";
     } | {
+        provider?: "google" | "xai" | "openai";
         options?: Record<string, unknown>;
         kind?: "realtime";
-        provider?: "google" | "xai" | "openai";
     };
     tts?: {
         voice?: string;
@@ -3933,14 +4063,14 @@ declare const LuaVoiceConfigSchema: z.ZodEffects<z.ZodObject<{
         kind?: "inference";
         model?: string;
     } | {
+        provider?: "deepgram" | "elevenlabs";
         options?: Record<string, unknown>;
         kind?: "plugin";
-        provider?: "deepgram" | "elevenlabs";
         class?: "LLM" | "STT" | "STTv2" | "TTS";
     } | {
+        provider?: "google" | "xai" | "openai";
         options?: Record<string, unknown>;
         kind?: "realtime";
-        provider?: "google" | "xai" | "openai";
     };
     vadOptions?: {
         minSpeechDuration?: number;
@@ -3996,14 +4126,14 @@ declare const LuaVoiceConfigSchema: z.ZodEffects<z.ZodObject<{
         kind?: "inference";
         model?: string;
     } | {
+        provider?: "deepgram" | "elevenlabs";
         options?: Record<string, unknown>;
         kind?: "plugin";
-        provider?: "deepgram" | "elevenlabs";
         class?: "LLM" | "STT" | "STTv2" | "TTS";
     } | {
+        provider?: "google" | "xai" | "openai";
         options?: Record<string, unknown>;
         kind?: "realtime";
-        provider?: "google" | "xai" | "openai";
     };
     volume?: number;
     llm?: {
@@ -4012,14 +4142,14 @@ declare const LuaVoiceConfigSchema: z.ZodEffects<z.ZodObject<{
         kind?: "inference";
         model?: string;
     } | {
+        provider?: "deepgram" | "elevenlabs";
         options?: Record<string, unknown>;
         kind?: "plugin";
-        provider?: "deepgram" | "elevenlabs";
         class?: "LLM" | "STT" | "STTv2" | "TTS";
     } | {
+        provider?: "google" | "xai" | "openai";
         options?: Record<string, unknown>;
         kind?: "realtime";
-        provider?: "google" | "xai" | "openai";
     };
     tts?: {
         voice?: string;
@@ -4027,14 +4157,14 @@ declare const LuaVoiceConfigSchema: z.ZodEffects<z.ZodObject<{
         kind?: "inference";
         model?: string;
     } | {
+        provider?: "deepgram" | "elevenlabs";
         options?: Record<string, unknown>;
         kind?: "plugin";
-        provider?: "deepgram" | "elevenlabs";
         class?: "LLM" | "STT" | "STTv2" | "TTS";
     } | {
+        provider?: "google" | "xai" | "openai";
         options?: Record<string, unknown>;
         kind?: "realtime";
-        provider?: "google" | "xai" | "openai";
     };
     vadOptions?: {
         minSpeechDuration?: number;
@@ -4090,14 +4220,14 @@ declare const LuaVoiceConfigSchema: z.ZodEffects<z.ZodObject<{
         kind?: "inference";
         model?: string;
     } | {
+        provider?: "deepgram" | "elevenlabs";
         options?: Record<string, unknown>;
         kind?: "plugin";
-        provider?: "deepgram" | "elevenlabs";
         class?: "LLM" | "STT" | "STTv2" | "TTS";
     } | {
+        provider?: "google" | "xai" | "openai";
         options?: Record<string, unknown>;
         kind?: "realtime";
-        provider?: "google" | "xai" | "openai";
     };
     volume?: number;
     llm?: {
@@ -4106,14 +4236,14 @@ declare const LuaVoiceConfigSchema: z.ZodEffects<z.ZodObject<{
         kind?: "inference";
         model?: string;
     } | {
+        provider?: "deepgram" | "elevenlabs";
         options?: Record<string, unknown>;
         kind?: "plugin";
-        provider?: "deepgram" | "elevenlabs";
         class?: "LLM" | "STT" | "STTv2" | "TTS";
     } | {
+        provider?: "google" | "xai" | "openai";
         options?: Record<string, unknown>;
         kind?: "realtime";
-        provider?: "google" | "xai" | "openai";
     };
     tts?: {
         voice?: string;
@@ -4121,14 +4251,14 @@ declare const LuaVoiceConfigSchema: z.ZodEffects<z.ZodObject<{
         kind?: "inference";
         model?: string;
     } | {
+        provider?: "deepgram" | "elevenlabs";
         options?: Record<string, unknown>;
         kind?: "plugin";
-        provider?: "deepgram" | "elevenlabs";
         class?: "LLM" | "STT" | "STTv2" | "TTS";
     } | {
+        provider?: "google" | "xai" | "openai";
         options?: Record<string, unknown>;
         kind?: "realtime";
-        provider?: "google" | "xai" | "openai";
     };
     vadOptions?: {
         minSpeechDuration?: number;