@alvera-ai/platform-sdk 0.13.0 → 0.14.0

package/dist/index.d.mts

@@ -361,6 +361,8 @@ type ManualToolInvocationResponse = {
   tool_call?: ({
     tool_call_type: 'sms_request';
   } & ManualToolInvocationSmsCallResponse) | ({
+    tool_call_type: 'mms_request';
+  } & ManualToolInvocationMmsCallResponse) | ({
     tool_call_type: 'email_request';
   } & ManualToolInvocationEmailCallResponse) | ({
     tool_call_type: 'restapi_request';
@@ -524,7 +526,7 @@ type S3CallResponse = {
  * Action Status Updater — automated polling for delivery status updates.
  */
 type ActionStatusUpdaterResponse = {
-  action_log_config?: SimpleTemplateConfigResponse | null;
+  action_log_config: SimpleTemplateConfigResponse | null;
   /**
    * SHA-256 drift fingerprint over authored fields (server-computed)
    */
@@ -538,7 +540,7 @@ type ActionStatusUpdaterResponse = {
    */
   datalake_id: string;
   /**
-   * JSON Schema the rendered events_template output is validated against on every poll (required for restapi updaters)
+   * JSON Schema the rendered events_template output is validated against on every poll (required for restapi updaters). FLOOR: it must describe an array whose items are objects listing "external_id" in "required" — every event has to name the message it reconciles, so the events_template maps the provider's own id (messageId / id / sid) into external_id. Add whatever else your provider guarantees on top; the platform only enforces the floor.
    */
   events_output_schema?: {
     [key: string]: unknown;
@@ -556,7 +558,7 @@ type ActionStatusUpdaterResponse = {
    */
   readonly last_run_at?: string | null;
   /**
-   * Why the last poll run failed; null when it succeeded
+   * Why the last poll run failed, or why a `partial` run was truncated; null when the run completed and read its whole window
    */
   readonly last_run_error?: string | null;
   /**
@@ -564,16 +566,16 @@ type ActionStatusUpdaterResponse = {
    */
   readonly last_run_events_found?: number | null;
   /**
-   * Outcome of the last poll run
+   * Outcome of the last poll run. `partial` means the run completed but its provider fetch was truncated, so the window was not fully read and the newest events may be missing — read `last_run_error` for detail.
    */
-  readonly last_run_status?: 'ok' | 'error';
+  readonly last_run_status?: 'ok' | 'partial' | 'error';
   message_config: SimpleTemplateConfigResponse;
   /**
    * Updater name
    */
   name: string;
   /**
-   * JSON Schema the rendered pagination_context_template output is validated against on every poll — requires has_next plus any provider cursor keys (required for restapi updaters)
+   * JSON Schema the rendered pagination_context_template output is validated against on every poll (required for restapi updaters). FLOOR: it must describe an object listing "has_next" in "required" — that key is what ends the page loop. Add the provider's cursor keys on top; the platform only enforces the floor.
    */
   pagination_context_output_schema?: {
     [key: string]: unknown;
@@ -582,6 +584,10 @@ type ActionStatusUpdaterResponse = {
    * IDs of sender tools whose messages this updater monitors
    */
   sender_tool_ids?: Array<string> | null;
+  /**
+   * Whether this updater may poll. The server sets cycle_detected when a run re-reads events it has already handled, and every later job then fails without calling the provider. Set it back to active to resume polling — nothing else clears it.
+   */
+  status?: 'active' | 'cycle_detected';
   /**
    * Tenant ID
    */
@@ -624,6 +630,7 @@ type IngestRequest = {
  */
 declare enum ToolIntent {
   SMS = "sms",
+  MMS = "mms",
   EMAIL = "email",
   EXPORT = "export",
   VOICE = "voice",
@@ -827,7 +834,7 @@ type ResolvePageResponse = {
     /**
      * Message channel
      */
-    channel: 'sms' | 'email' | 'voice' | 'web_form' | 'push';
+    channel: 'sms' | 'mms' | 'email' | 'voice' | 'web_form' | 'push';
     /**
      * When delivery was confirmed
      */
@@ -877,7 +884,11 @@ type ResolvePageResponse = {
     /**
      * Delivery status
      */
-    status: 'pending' | 'queued' | 'sent' | 'delivered' | 'failed' | 'received' | 'clicked';
+    status: 'pending' | 'queued' | 'sent' | 'delivered' | 'read' | 'opened' | 'clicked' | 'form_submitted' | 'failed' | 'invalidated' | 'customer_rejected' | 'dry_run' | 'received';
+    /**
+     * Human-readable detail behind the current status, rendered from the delivery provider's event (e.g. the mailgun event name, or a bounce reason on failure)
+     */
+    status_description?: string | null;
     /**
      * Raw email subject line (null for SMS)
      */
@@ -907,6 +918,7 @@ type ResolvePageResponse = {
  */
 declare enum ActionType {
   SMS = "sms",
+  MMS = "mms",
   EMAIL = "email",
   VOICE = "voice",
   DATA_EXCHANGE = "data_exchange",
@@ -1078,7 +1090,7 @@ type ActionResponse = {
    */
   action_window_start?: number | null;
   /**
-   * Optional connected app — only valid for :sms and :email action types
+   * Optional connected app — when set, the executor mints a per-recipient connected_app_form_url template variable; connected_app_route is required
    */
   connected_app_id?: string | null;
   /**
@@ -1113,6 +1125,8 @@ type ActionResponse = {
   tool_call: ({
     tool_call_type: 'sms_request';
   } & ActionSmsCallResponse) | ({
+    tool_call_type: 'mms_request';
+  } & ActionMmsCallResponse) | ({
     tool_call_type: 'email_request';
   } & ActionEmailCallResponse) | ({
     tool_call_type: 'sql_query';
@@ -1293,6 +1307,10 @@ type UpdatePageRequest = {
    * Puid token extracted from the short URL
    */
   short_path: string;
+  /**
+   * Engagement status reported by the connected app — typically "opened", "clicked", or "form_submitted". Applied through the monotonic status guard, so it only ever advances the message and never regresses it.
+   */
+  status?: string | null;
 };
 /**
  * InvitationResponse
@@ -1762,6 +1780,19 @@ type GenericTableListResponse = {
   data: Array<GenericTableResponse>;
   meta: PaginationMeta;
 };
+/**
+ * MMSCallResponse
+ *
+ * MMS tool-call config — Liquid-templated recipient and body, plain public media URL.
+ */
+type MmsCallResponse = {
+  body: SimpleTemplateConfigResponse;
+  /**
+   * Public http(s) URL of the media to attach — fetched and re-staged into the tool's S3 media bucket
+   */
+  media_url: string;
+  to: SimpleTemplateConfigResponse;
+};
 /**
  * ManualToolInvocationEmailCallResponse
  */
@@ -1796,6 +1827,10 @@ type UpdatePageResponse = {
      * When the page was opened by the recipient
      */
     opened_at?: string | null;
+    /**
+     * Message status after applying the update through the monotonic guard
+     */
+    status?: 'pending' | 'queued' | 'sent' | 'delivered' | 'read' | 'opened' | 'clicked' | 'form_submitted' | 'failed' | 'invalidated' | 'customer_rejected' | 'dry_run' | 'received';
   };
 };
 /**
@@ -1854,6 +1889,12 @@ type ManualToolInvocationSmsCallResponse = SmsCallResponse & {
 type ActionStatusUpdaterCloudWatchQueryResponse = CloudWatchQueryResponse & {
   updater_body_type: 'cloud_watch_request';
 };
+/**
+ * ActionMMSCallResponse
+ */
+type ActionMmsCallResponse = MmsCallResponse & {
+  tool_call_type: 'mms_request';
+};
 /**
  * ToolSQLDatabaseResponse
  */
@@ -2106,6 +2147,54 @@ type DatasetSearchResponse = {
 type ActionAwsLambdaCallResponse = AwsLambdaCallResponse & {
   tool_call_type: 'aws_lambda_request';
 };
+/**
+ * EndUserMessagingResponse
+ *
+ * AWS End User Messaging tool configuration for sending MMS via the SendMediaMessage API.
+ */
+type EndUserMessagingResponse = {
+  /**
+   * AWS access key ID (used when auth_method is access_key)
+   */
+  access_key_id?: string | null;
+  /**
+   * IAM role ARN to assume in the customer's AWS account (used when auth_method is assume_role)
+   */
+  assume_role_arn?: string | null;
+  /**
+   * External ID for the STS AssumeRole call, unique per customer (auto-generated when auth_method is assume_role)
+   */
+  assume_role_external_id?: string | null;
+  /**
+   * AWS authentication method
+   */
+  auth_method: 'access_key' | 'iam_role' | 'assume_role';
+  base_message?: ComplexTemplateConfigResponse | null;
+  /**
+   * AWS End User Messaging configuration set that routes delivery events to CloudWatch
+   */
+  configuration_set_name: string;
+  /**
+   * Custom sms-voice endpoint URL (e.g. http://localhost:8080 for the WireMock stub); leave blank for real AWS
+   */
+  endpoint_url?: string | null;
+  /**
+   * S3 bucket (same region as the sending number) where author media is re-staged for SendMediaMessage
+   */
+  media_bucket: string;
+  /**
+   * Custom S3 endpoint URL for media staging (e.g. http://localhost:4566 for LocalStack); leave blank for AWS S3 in the tool's region
+   */
+  media_endpoint_url?: string | null;
+  /**
+   * Origination phone number or identity in E.164 format (e.g., +15551234567); must be MMS-capable
+   */
+  phone_number: string;
+  /**
+   * AWS region (e.g., us-west-2)
+   */
+  region: string;
+};
 /**
  * ToolS3Response
  */
@@ -2721,6 +2810,8 @@ type ToolResponse = {
   } & ToolEmailResponse) | ({
     tool_body_type: 'sns';
   } & ToolSnsResponse) | ({
+    tool_body_type: 'end_user_messaging';
+  } & ToolEndUserMessagingResponse) | ({
     tool_body_type: 'rest_api';
   } & ToolRestapiResponse) | ({
     tool_body_type: 's3';
@@ -3154,6 +3245,12 @@ type EmailResponse = {
    */
   smtp_username?: string;
 };
+/**
+ * ManualToolInvocationMMSCallResponse
+ */
+type ManualToolInvocationMmsCallResponse = MmsCallResponse & {
+  tool_call_type: 'mms_request';
+};
 /**
  * WorkflowLogResponse
  *
@@ -3529,7 +3626,7 @@ type ToolCloudWatchLogGroupResponse = CloudWatchLogGroupResponse & {
  */
 type CloudWatchQueryRequest = {
   /**
-   * Liquid template for the poll window end time, rendered with `{{ now }}` in unix milliseconds (e.g., "{{ now }}")
+   * Liquid template for the poll window end time, rendered with `{{ now_msec }}` in unix milliseconds (e.g., "{{ now_msec }}")
    */
   end_time: string;
   /**
@@ -3537,7 +3634,7 @@ type CloudWatchQueryRequest = {
    */
   log_group_name: string;
   /**
-   * Liquid template for the poll window start time, rendered with `{{ now }}` in unix milliseconds (e.g., "{{ now | minutes_ago: 45 }}")
+   * Liquid template for the poll window start time, rendered with `{{ now }}` in unix milliseconds (e.g., "{{ now_msec | minutes_ago: 45 }}")
    */
   start_time: string;
 };
@@ -3612,6 +3709,12 @@ type InteroperabilityContractListResponse = {
   data: Array<InteroperabilityContractResponse>;
   meta: PaginationMeta;
 };
+/**
+ * ToolEndUserMessagingResponse
+ */
+type ToolEndUserMessagingResponse = EndUserMessagingResponse & {
+  tool_body_type: 'end_user_messaging';
+};
 /**
  * ActionStatusUpdaterListResponse
  *
@@ -3863,7 +3966,7 @@ type GenericTableColumnRequest = {
  */
 type CloudWatchQueryResponse = {
   /**
-   * Liquid template for the poll window end time, rendered with `{{ now }}` in unix milliseconds (e.g., "{{ now }}")
+   * Liquid template for the poll window end time, rendered with `{{ now_msec }}` in unix milliseconds (e.g., "{{ now_msec }}")
    */
   end_time: string;
   /**
@@ -3871,7 +3974,7 @@ type CloudWatchQueryResponse = {
    */
   log_group_name: string;
   /**
-   * Liquid template for the poll window start time, rendered with `{{ now }}` in unix milliseconds (e.g., "{{ now | minutes_ago: 45 }}")
+   * Liquid template for the poll window start time, rendered with `{{ now }}` in unix milliseconds (e.g., "{{ now_msec | minutes_ago: 45 }}")
    */
   start_time: string;
 };
@@ -4383,7 +4486,7 @@ type ActionResponseWritable = {
    */
   action_window_start?: number | null;
   /**
-   * Optional connected app — only valid for :sms and :email action types
+   * Optional connected app — when set, the executor mints a per-recipient connected_app_form_url template variable; connected_app_route is required
    */
   connected_app_id?: string | null;
   /**
@@ -4419,6 +4522,58 @@ type ActionResponseWritable = {
    */
   trigger_template: string;
 };
+/**
+ * EndUserMessagingRequest
+ *
+ * AWS End User Messaging tool configuration for sending MMS via the SendMediaMessage API. Request
+ */
+type EndUserMessagingRequestWritable = {
+  /**
+   * AWS access key ID (used when auth_method is access_key)
+   */
+  access_key_id?: string | null;
+  /**
+   * IAM role ARN to assume in the customer's AWS account (used when auth_method is assume_role)
+   */
+  assume_role_arn?: string | null;
+  /**
+   * External ID for the STS AssumeRole call, unique per customer (auto-generated when auth_method is assume_role)
+   */
+  assume_role_external_id?: string | null;
+  /**
+   * AWS authentication method
+   */
+  auth_method: 'access_key' | 'iam_role' | 'assume_role';
+  base_message?: ComplexTemplateConfigRequest;
+  /**
+   * AWS End User Messaging configuration set that routes delivery events to CloudWatch
+   */
+  configuration_set_name: string;
+  /**
+   * Custom sms-voice endpoint URL (e.g. http://localhost:8080 for the WireMock stub); leave blank for real AWS
+   */
+  endpoint_url?: string | null;
+  /**
+   * S3 bucket (same region as the sending number) where author media is re-staged for SendMediaMessage
+   */
+  media_bucket: string;
+  /**
+   * Custom S3 endpoint URL for media staging (e.g. http://localhost:4566 for LocalStack); leave blank for AWS S3 in the tool's region
+   */
+  media_endpoint_url?: string | null;
+  /**
+   * Origination phone number or identity in E.164 format (e.g., +15551234567); must be MMS-capable
+   */
+  phone_number: string;
+  /**
+   * AWS region (e.g., us-west-2)
+   */
+  region: string;
+  /**
+   * AWS secret access key (used when auth_method is access_key)
+   */
+  secret_access_key?: string | null;
+};
 /**
  * ToolSharePointRequest
  */
@@ -4436,6 +4591,8 @@ type ToolRequestWritable = {
   } & ToolEmailRequestWritable) | ({
     tool_body_type: 'sns';
   } & ToolSnsRequestWritable) | ({
+    tool_body_type: 'end_user_messaging';
+  } & ToolEndUserMessagingRequestWritable) | ({
     tool_body_type: 'rest_api';
   } & ToolRestapiRequestWritable) | ({
     tool_body_type: 's3';
@@ -5242,6 +5399,12 @@ type RunManuallyRequestWritable = {
     tool_call_type: 'DataActivationClientS3CallRequestWritable';
   } & DataActivationClientS3CallRequestWritable) | null;
 };
+/**
+ * ToolEndUserMessagingRequest
+ */
+type ToolEndUserMessagingRequestWritable = EndUserMessagingRequestWritable & {
+  tool_body_type: 'end_user_messaging';
+};
 /**
  * DatalakeCloudStorageAwsRequest
  */
@@ -6430,7 +6593,7 @@ interface CreateActionStatusUpdaterRequest {
   datalake_id: string;
   sender_tool_ids?: string[] | null;
   message_config: TemplateConfig;
-  action_log_config?: TemplateConfig | null;
+  action_log_config: TemplateConfig;
   events_output_schema?: Record<string, unknown> | null;
   pagination_context_output_schema?: Record<string, unknown> | null;
   updater_body: ActionStatusUpdaterCloudWatchQueryRequest | ActionStatusUpdaterRestCallRequest;
@@ -6565,15 +6728,22 @@ interface ApiDebugConfig {
   redactStrings?: readonly string[];
 }
 /**
- * `sessionToken` and `apiKey` travel together on every request — Firebase's
- * "API key + ID token" split, not an either/or. `apiKey` identifies the
- * publishable client (and is what a server-side CORS check matches the
+ * `sessionToken` and `apiKey` travel together on an authorized request —
+ * Firebase's "API key + ID token" split, not an either/or. `apiKey` identifies
+ * the publishable client (and is what a server-side CORS check matches the
  * request's `Origin` against); `sessionToken` (Bearer) is what actually
  * authorizes the call. Neither ever substitutes for the other.
+ *
+ * `sessionToken` is OPTIONAL: a key-only client — every deployed connected
+ * app authenticating machine-to-machine on its tenant's publishable key —
+ * constructs with just `{ baseUrl, apiKey }` and sends no `Authorization`
+ * header at all (never a fabricated `Bearer ` with an empty token). It
+ * reaches only the limited surface the publishable key permits; everything
+ * else 401s server-side, which is the intended ceiling.
  */
 interface ApiConfig {
   baseUrl: string;
-  sessionToken: string;
+  sessionToken?: string;
   apiKey: string;
   debug?: ApiDebugConfig;
 }