@alvera-ai/platform-sdk 0.17.2 → 0.17.4-next.g6daa781

package/.agent/tools.md

@@ -12,10 +12,11 @@ dimensions:
 - **body type** declares HOW the tool connects (S3, SFTP, SQL,
   REST, AWS Lambda, …) via a polymorphic discriminator
 
-A datalake can own many tools. Some tools nest under a data source
-(`data_source_id` populated — typical for ingestion-receiving
-tools like `manual_upload`); others are standalone and reachable
-to any workflow on the datalake.
+A datalake can own many tools, and every tool names the data source
+it belongs to (`data_source_id`, required on every intent — see §2).
+A tool stays reachable to any workflow on the datalake; the data
+source decides which `uri` the messages it sends carry, which is what
+action status updaters match on.
 
 ## 1. Wire shape
 
@@ -119,6 +120,7 @@ happened to it** — no delivery status, no reconciliation.
 await api.tools.create(tenantSlug, datalakeSlug, {
   name: 'Campaign Sender — Main Line',
   intent: 'sms',
+  data_source_id: dataSourceId,  // every tool names one; its messages carry this source's uri
   tool_body_type: 'twilio',
   variant_type: 'primary',
   account_sid: 'AC…',           // "AC" + 32 hex
@@ -182,14 +184,16 @@ What stays with the variant is the sender identity and its event routing:
 twilio              from_number XOR messaging_service_sid
 sns                 phone_number
 end_user_messaging  phone_number · configuration_set_name
-email :mailgun      from_email · from_name · reply_to · domain
-email :ses          from_email · from_name · reply_to
-email :sendgrid     from_email · from_name · reply_to
-email :smtp         from_email · from_name · reply_to
+email :mailgun      base_from_email · base_from_name · base_reply_to · domain
+email :ses          base_from_email · base_from_name · base_reply_to
+email :sendgrid     base_from_email · base_from_name · base_reply_to
+email :smtp         base_from_email · base_from_name · base_reply_to
 ```
 
 Everything else — auth, region, endpoints, the MMS staging bucket — comes
-from the primary. Two entries look arbitrary and are not: Mailgun's
+from the primary; an SES variant on `assume_role` uses its primary's
+role. `base_from_email` is required on every email tool, primary or
+variant. Two entries look arbitrary and are not: Mailgun's
 `domain` is also a path segment in the request URL
 (`/v3/{domain}/messages`), and End User Messaging's
 `configuration_set_name` is the *event-routing* address, of which AWS
@@ -227,16 +231,29 @@ create time:
 A misaligned pair (e.g. `intent: sms` + `tool_body_type: sftp`)
 returns a `422` with `body.tool_body_type` in `errors`.
 
-### `data_source_id` is optional but discriminator-aware
+### `data_source_id` is required on every tool
 
-When set, the tool is **embedded under a data source** — its
-lifecycle is tied to the parent data source, and ingestion paths
-expect it at that scope. When omitted, the tool is **standalone**
-on the datalake — available to any workflow that names it.
+Every tool names the data source it belongs to, whatever its intent
+or body type. A create without `data_source_id` is a `422` at
+`/data_source_id` (`can't be blank`); `update()` is a full
+replacement, so send it on every PUT too. The generated type still
+marks the field optional and nullable — the server's rule is the one
+that holds.
 
-The body type itself signals the typical pattern: `manual_upload`
-is almost always embedded (the data source IS the upload sink);
-`sns`, `rest_api`, `sql_database` are typically standalone.
+What it drives:
+
+- **The messages a tool sends carry its data source's `uri`.** An
+  action status updater names one data source and matches polled
+  events to messages and action logs by that `uri` plus the vendor's
+  id (`action_status_updaters.md` §2). One data source may hold SMS,
+  MMS and voice tools; nothing checks what else is on it.
+- **A data source cannot be deleted while it still has tools.** The
+  delete answers `409` (`still has tools`); delete or move its tools
+  first. The foreign key restricts, so nothing cascades.
+
+The body type still signals the typical pattern: a `manual_upload`
+tool's data source IS the upload sink; a sender's data source is the
+one its messages, and its status updater, belong to.
 
 ### Body-type sub-fields are validated against the matching discriminator branch (server-side)
 
@@ -325,15 +342,53 @@ tool body. Nothing you can put in `endpoint_url` changes it.
 
 ### `assume_role` needs the platform's ARN — read it from `GET /api/ping`
 
-The `assume_role` auth method (on `sns` and `end_user_messaging`
-bodies) is configured from two values that come from opposite
-sides of the trust relationship:
+The `assume_role` auth method (on `sns`, `end_user_messaging` and
+SES `email` bodies) is configured from two values that come from
+opposite sides of the trust relationship:
 
 ```
    assume_role_arn          the role YOU create in YOUR AWS
                               account, for the platform to assume
-   assume_role_external_id  the platform-generated external ID
-                              that role must require
+                              (arn:aws:iam::<12 digits>:role/<name>)
+   assume_role_external_id  the external ID that role must require
+                              — kept as sent, generated by the
+                              platform when sent blank
+```
+
+Because the customer writes the external ID into the role's trust
+policy before the tool exists, send it on create rather than letting
+the platform generate one — a generated value is one the policy does
+not know yet.
+
+**SES email tools on `assume_role`.** The email body's `auth_method`
+(`access_key | iam_role | assume_role`, SES only) defaults to
+`access_key` when an SES tool is saved without it; a non-SES email
+tool has all three auth fields cleared on save. Saving an SES tool on
+`assume_role` checks the role, the SES account and the sending address
+(the rendered `base_from_email`) against AWS. A failure is a `422` in
+the standard envelope (`errors.md`) pointing at `/body/auth_method`,
+`/body/region`, `/body/base_from_email` or `/body/primary_tool_id`,
+and it carries what AWS said. A variant (`variant_type: 'variant'`,
+`primary_tool_id`) uses its primary's role.
+
+```typescript
+const { data: sesTool } = await api.tools.create(tenantSlug, datalakeSlug, {
+  name: 'Campaign Email',
+  intent: ToolIntent.EMAIL,
+  status: 'active',
+  datalake_id: datalakeId,
+  data_source_id: dataSourceId,
+  body: {
+    tool_body_type: 'email',
+    provider: 'ses',
+    region: 'us-east-1',
+    auth_method: 'assume_role',
+    assume_role_arn: 'arn:aws:iam::123456789012:role/alvera-ses-sender',
+    assume_role_external_id: externalId,   // the value already in the role's trust policy
+    base_from_email: { type: 'custom', body: 'campaigns@example.com' },
+    base_from_name: { type: 'custom', body: 'Example Salon' },
+  },
+})
 ```
 
 Creating that role means naming a principal in its trust policy,
@@ -507,8 +562,8 @@ silent OIDC-provider outage can fail an otherwise-cosmetic
 
    scoping
      datalake_id          parent datalake (UUID)
-     data_source_id       (optional) parent data source for embedded
-                          tools; omit for standalone
+     data_source_id       required — the data source the tool belongs
+                          to (every intent; send it on every PUT)
 
    body (polymorphic — required keys depend on tool_body_type)
      tool_body_type       discriminator — names which branch shape
@@ -542,8 +597,8 @@ Capture both `id` and `slug` from the create response; never
 pre-compute either client-side. The **UUID `id`** is the CRUD path
 key (`.get` / `.update` / `.delete`) AND the cross-resource
 reference — workflows and data-activation clients bind a tool by
-`id` (`tool_id`), and action status updaters by `updater_tool_id` /
-`sender_tool_ids` (see §7). The `slug` is the human handle; it does
+`id` (`tool_id`), and action status updaters by `updater_tool_id`
+(see §7; an updater names a data source, not its sender tools). The `slug` is the human handle; it does
 NOT key a CRUD `.get` (passing it 422s `Expected :uuid`). See
 `type_naming.md` for the id/slug/name convention.
 
@@ -805,9 +860,9 @@ downstream resource that names a tool must apply AFTER it.
    `status: "error"` + non-empty `error_message`. If you see a
    5xx, file a platform bug, do not retry.
 
-5. **Standalone vs embedded tool routing differs at list time**
+5. **Tools list per datalake, not per data source**
    — `tools.list(tenant, datalake, query?)` returns ALL tools on
-   the datalake (standalone + embedded). The Flop query
+   the datalake, across every data source. The Flop query
    (type_naming.md) filters on `intent`, `status`, `name`, etc. —
    but `data_source_id` is NOT in the filterable set, so tools
    owned by a specific data source must still be filtered

package/.agent/type_naming.md

@@ -63,7 +63,7 @@ they are **not** interchangeable as call arguments:
    id      UUID — the API path key for CRUD. `.get` / `.update` /
              `.delete` on every datalake-scoped resource take the
              `id`, and cross-resource references (`tool_id`,
-             `updater_tool_id`, `sender_tool_ids`, …) are `id`s too.
+             `updater_tool_id`, `data_source_id`, …) are `id`s too.
    slug    the human handle — the path key for runtime / operations
              verbs (workflows `execute` / `run` / logs, datalakes
              `migrate`, data-activation-client ingest / run, interop
@@ -105,6 +105,7 @@ await api.tools.get(tenantSlug, datalakeSlug, toolId)
 // 2b. downstream resources reference the tool by id
 await api.actionStatusUpdaters.create(tenantSlug, datalakeSlug, {
   updater_tool_id: toolId,
+  data_source_id: dataSourceId,   // a data source's id, the same way
   action_log_config: {
     type: 'custom',
     body: '{"external_id": "{{ notification.messageId }}", "status": "delivered"}',

package/dist/index.d.mts

@@ -567,6 +567,10 @@ type ActionStatusUpdaterResponse = {
    * Cron schedule expression (e.g. "*30 * * * *")
    */
   cron_expression: string;
+  /**
+   * The data source whose messages and action logs this updater updates, found by the data source's uri and the vendor's id. An updater without one skips its runs.
+   */
+  data_source_id: string | null;
   /**
    * Datalake ID
    */
@@ -612,10 +616,6 @@ type ActionStatusUpdaterResponse = {
   pagination_context_output_schema?: {
     [key: string]: unknown;
   } | null;
-  /**
-   * 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.
    */
@@ -1446,7 +1446,7 @@ type InvitationResponse = {
  */
 type ToolRequest = {
   /**
-   * Data Source ID
+   * Data Source ID. Required for SMS, MMS, email and voice tools: the messages they send carry this data source's uri, which status updaters match on.
    */
   data_source_id?: string | null;
   /**
@@ -1784,10 +1784,13 @@ type ConnectedAppListResponse = {
 /**
  * EmailCallResponse
  *
- * Email tool-call config — Liquid-templated recipient, subject, and body.
+ * Email tool-call config — Liquid-templated recipient, subject, and body. The optional from_name, from_email, and reply_to override the email tool's own sender, field by field.
  */
 type EmailCallResponse = {
   body: SimpleTemplateConfigResponse;
+  from_email?: SimpleTemplateConfigResponse;
+  from_name?: SimpleTemplateConfigResponse;
+  reply_to?: SimpleTemplateConfigResponse;
   subject: SimpleTemplateConfigResponse;
   to: SimpleTemplateConfigResponse;
 };
@@ -3022,7 +3025,7 @@ type ToolResponse = {
    */
   readonly checksum?: string;
   /**
-   * Data Source ID
+   * Data Source ID. Required for SMS, MMS, email and voice tools: the messages they send carry this data source's uri, which status updaters match on.
    */
   data_source_id?: string | null;
   /**
@@ -3408,25 +3411,53 @@ type DataActivationClientSharePointExcelCallResponse = SharePointExcelCallRespon
  */
 type EmailResponse = {
   /**
-   * AWS access key ID (SES)
+   * AWS access key ID (SES, auth_method access_key)
    */
   access_key_id?: string;
   /**
-   * Sending domain (Mailgun)
+   * SES only. The IAM role to assume in the customer's AWS account (auth_method assume_role)
    */
-  domain?: string;
+  assume_role_arn?: string;
   /**
-   * Custom provider endpoint. Mailgun: the API base URL, which the sending domain is appended to (e.g., https://api.eu.mailgun.net/v3 for EU domains, or a WireMock endpoint for integration tests). SES: the whole request URL (e.g., https://email.us-west-2.amazonaws.com, or http://localhost:4566 for LocalStack). Leave blank for the provider's own endpoint.
+   * SES only. The external id the customer's role requires (auth_method assume_role). Kept as sent; generated when blank.
    */
-  endpoint_url?: string | null;
+  assume_role_external_id?: string;
+  /**
+   * SES only. How the tool reaches its AWS account: its own key, the platform's role, or a role in the customer's account. An SES tool saved without one uses its key.
+   */
+  auth_method?: 'access_key' | 'iam_role' | 'assume_role';
+  /**
+   * Liquid template for the body, with the tool's own variables only; used when a workflow action's body renders blank
+   */
+  base_body?: SimpleTemplateConfigResponse | null;
+  /**
+   * Liquid template for the sender address, with the tool's own variables only (tool.name and the tool's settings other than credentials, such as tool.provider, tool.domain, tool.region); rendered and checked when the tool is saved. A workflow action's from_email wins when it renders non-blank.
+   */
+  base_from_email: SimpleTemplateConfigResponse;
+  /**
+   * Liquid template for the sender display name, with the tool's own variables only. A workflow action's from_name wins when it renders non-blank.
+   */
+  base_from_name?: SimpleTemplateConfigResponse | null;
+  /**
+   * Liquid template for the reply-to address, with the tool's own variables only. A workflow action's reply_to wins when it renders non-blank.
+   */
+  base_reply_to?: SimpleTemplateConfigResponse | null;
+  /**
+   * Liquid template for the subject, with the tool's own variables only; used when a workflow action's subject renders blank
+   */
+  base_subject?: SimpleTemplateConfigResponse | null;
+  /**
+   * Liquid template for the recipient address, with the tool's own variables only; used when a workflow action's to renders blank
+   */
+  base_to?: SimpleTemplateConfigResponse | null;
   /**
-   * Default sender email address
+   * Sending domain (Mailgun)
    */
-  from_email: string;
+  domain?: string;
   /**
-   * Default sender display name
+   * Custom provider endpoint. Mailgun: the API base URL, which the sending domain is appended to (e.g., https://api.eu.mailgun.net/v3 for EU domains, or a WireMock endpoint for integration tests). SES: the whole request URL (e.g., https://email.us-west-2.amazonaws.com, or http://localhost:4566 for LocalStack). Leave blank for the provider's own endpoint.
    */
-  from_name?: string | null;
+  endpoint_url?: string | null;
   /**
    * ID of the primary Email tool supplying credentials; required when variant_type is variant
    */
@@ -3439,10 +3470,6 @@ type EmailResponse = {
    * AWS region (SES)
    */
   region?: string;
-  /**
-   * Default reply-to address
-   */
-  reply_to?: string | null;
   /**
    * SMTP server hostname
    */
@@ -4707,10 +4734,13 @@ type ToolRestapiRequestWritable = RestapiRequestWritable & {
 /**
  * EmailCallRequest
  *
- * Email tool-call config — Liquid-templated recipient, subject, and body. Request
+ * Email tool-call config — Liquid-templated recipient, subject, and body. The optional from_name, from_email, and reply_to override the email tool's own sender, field by field. Request
  */
 type EmailCallRequestWritable = {
   body: SimpleTemplateConfigRequest;
+  from_email?: SimpleTemplateConfigRequest;
+  from_name?: SimpleTemplateConfigRequest;
+  reply_to?: SimpleTemplateConfigRequest;
   subject: SimpleTemplateConfigRequest;
   to: SimpleTemplateConfigRequest;
 };
@@ -4918,7 +4948,7 @@ type ToolRequestWritable = {
     tool_body_type: 'manual_upload';
   } & ToolManualUploadRequest);
   /**
-   * Data Source ID
+   * Data Source ID. Required for SMS, MMS, email and voice tools: the messages they send carry this data source's uri, which status updaters match on.
    */
   data_source_id?: string | null;
   /**
@@ -5164,7 +5194,7 @@ type AiAgentRequestWritable = {
  */
 type EmailRequestWritable = {
   /**
-   * AWS access key ID (SES)
+   * AWS access key ID (SES, auth_method access_key)
    */
   access_key_id?: string;
   /**
@@ -5172,21 +5202,31 @@ type EmailRequestWritable = {
    */
   api_key?: string;
   /**
-   * Sending domain (Mailgun)
+   * SES only. The IAM role to assume in the customer's AWS account (auth_method assume_role)
    */
-  domain?: string;
+  assume_role_arn?: string;
   /**
-   * Custom provider endpoint. Mailgun: the API base URL, which the sending domain is appended to (e.g., https://api.eu.mailgun.net/v3 for EU domains, or a WireMock endpoint for integration tests). SES: the whole request URL (e.g., https://email.us-west-2.amazonaws.com, or http://localhost:4566 for LocalStack). Leave blank for the provider's own endpoint.
+   * SES only. The external id the customer's role requires (auth_method assume_role). Kept as sent; generated when blank.
    */
-  endpoint_url?: string | null;
+  assume_role_external_id?: string;
   /**
-   * Default sender email address
+   * SES only. How the tool reaches its AWS account: its own key, the platform's role, or a role in the customer's account. An SES tool saved without one uses its key.
    */
-  from_email: string;
+  auth_method?: 'access_key' | 'iam_role' | 'assume_role';
+  base_body?: SimpleTemplateConfigRequest;
+  base_from_email: SimpleTemplateConfigRequest;
+  base_from_name?: SimpleTemplateConfigRequest;
+  base_reply_to?: SimpleTemplateConfigRequest;
+  base_subject?: SimpleTemplateConfigRequest;
+  base_to?: SimpleTemplateConfigRequest;
   /**
-   * Default sender display name
+   * Sending domain (Mailgun)
    */
-  from_name?: string | null;
+  domain?: string;
+  /**
+   * Custom provider endpoint. Mailgun: the API base URL, which the sending domain is appended to (e.g., https://api.eu.mailgun.net/v3 for EU domains, or a WireMock endpoint for integration tests). SES: the whole request URL (e.g., https://email.us-west-2.amazonaws.com, or http://localhost:4566 for LocalStack). Leave blank for the provider's own endpoint.
+   */
+  endpoint_url?: string | null;
   /**
    * ID of the primary Email tool supplying credentials; required when variant_type is variant
    */
@@ -5200,11 +5240,7 @@ type EmailRequestWritable = {
    */
   region?: string;
   /**
-   * Default reply-to address
-   */
-  reply_to?: string | null;
-  /**
-   * AWS secret access key (SES)
+   * AWS secret access key (SES, auth_method access_key)
    */
   secret_access_key?: string;
   /**
@@ -6150,6 +6186,10 @@ type ActionStatusUpdaterRequestWritable = {
    * Cron schedule expression (e.g. "*30 * * * *")
    */
   cron_expression: string;
+  /**
+   * The data source whose messages and action logs this updater updates, found by the data source's uri and the vendor's id. An updater without one skips its runs.
+   */
+  data_source_id: string | null;
   /**
    * Datalake ID
    */
@@ -6171,10 +6211,6 @@ type ActionStatusUpdaterRequestWritable = {
   pagination_context_output_schema?: {
     [key: string]: unknown;
   } | null;
-  /**
-   * 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.
    */
@@ -7417,7 +7453,7 @@ interface CreateActionStatusUpdaterRequest {
   updater_type: 'cloud_watch' | 'restapi';
   updater_tool_id: string;
   datalake_id: string;
-  sender_tool_ids?: string[] | null;
+  data_source_id: string;
   message_config: TemplateConfig;
   action_log_config: TemplateConfig;
   events_output_schema?: Record<string, unknown> | null;