@alvera-ai/platform-sdk 0.21.0 → 0.21.1-next.g7fffc89

package/.agent/AGENTS.md

@@ -327,7 +327,10 @@ from the filesystem at
 is no SDK function and no CLI verb that returns cookbook bytes
 at runtime.
 
-Each cookbook structure:
+Each cookbook structure — front matter, then these top-level `#`
+sections, each exactly once and in this order. The validator refuses a
+cookbook that is missing one, repeats one, reorders them, leaves one
+empty, or adds a top-level section that is not on this list:
 
 - **Front matter** — `title`, `summary`, `use_case`, `slug`,
   `vitest_source` (list of integration-test files the snippets
@@ -349,14 +352,17 @@ Each cookbook structure:
   carrying one fenced TypeScript block lifted from the anchor or
   ancillary vitest. State threads forward across subsections via
   plain JavaScript variables in the validator's generated
-  `describe` closure.
-- **Branches** — alternate paths the anchor vitest covers (a
-  filter rejection, a transport failure, an agent-classification
-  fallback).
-- **Rollback** — teardown order for the resources the cookbook
-  provisioned.
+  `describe` closure. A numbered step anywhere else in the file
+  is refused.
 - **Outcome** — author's prose summary of what the scenario
   produces.
+- **Gotchas** — one numbered list of the mistakes the walk exists
+  to keep you from making. Each item opens with a bold one-sentence
+  rule, says why it bites, and names the step that proves it as
+  `§NNN`. The validator refuses an item that names no step, or a
+  step the cookbook does not have — and every step runs against a
+  live platform — so a gotcha cannot outlive the behaviour it warns
+  about.
 - **See also** — links to relevant per-resource reference MDs
   and to the anchor + ancillary vitest files.
 

package/.agent/cookbook/organic-marketing.md

@@ -3077,12 +3077,66 @@ if (afterSubjects.size !== 1 || !afterSubjects.has(twoIdSubject)) {
 
 # Outcome
 
-The marketing tenant exists with one raw datalake, an SMS tool, an LLM
-tool, a lead-submissions table, and an agent-driven workflow that bands
-every inbound lead and fans out to exactly one of four SMS actions.
+After all forty-seven steps run green, on one tenant and **one raw
+datalake**:
+
+- **Every inbound lead is banded.** Three leads land in the Lead Submissions
+  table through the client the platform provisioned with it, and the Score
+  Lead agent's band steers each one to exactly one of four SMS actions
+  (§014–§018).
+- **A birthday greeting is scheduled a year out.** Two contacts arrive through
+  the lead-form client; the Happy Birthday workflow's pure-Liquid trigger
+  schedules a greeting for the one with a birthday and filters the one
+  without. Fast-forwarded, the greeting carries an authenticated link whose
+  exchange names that contact, and the tap, the page and the form are tracked
+  on the message (§020–§030).
+- **A campaign goes out A/B on two channels.** One business and four
+  recipients land in the roster and audience tables through contract pairs on
+  separate clients, identities first. The campaign workflow's gates decide who
+  is contacted at all, and its split sends each of them one variant on both
+  SMS and email, every message carrying its own link to the booking page
+  (§031–§040).
+- **A reply attaches to whoever sent it.** It ingests into the system inbound
+  table and resolves back to the recipient's subject without creating a new
+  one (§041).
+- **Delivery is reconciled, not assumed.** An action status updater turns
+  provider delivery events into updates on a schedule, its stored body is
+  read back against its checksum, and a poller whose request could never move
+  to the next page is refused at create (§042–§044).
+- **The lake answers in plain language.** Text-to-SQL proposes a query
+  without running it; the read-only executor runs one and returns the same
+  page as CSV (§045–§046).
+- **One person carries two identifiers.** A second ingest that names only the
+  email leaves the phone slot untouched on the same subject (§047).
 
 Running this walk again reuses all of it.
 
+# Gotchas
+
+1. **`link_prefix` is required on every SMS and email call, even one whose
+   body carries no link of its own.** Any URL in the body — including one a
+   lead typed into the form — goes out as `<link_prefix>/<token>`. Leave the
+   prefix off and the workflow is refused at create with a 422 on
+   `/actions/<n>/tool_call/link_prefix` — §012, §038.
+2. **`workflows.run` only schedules a run.** The ids a scenario needs are
+   written later, when the run fires, so poll until `workflow_run_log_id` is
+   a string, not until `status` leaves `'scheduled'`. And a run whose action
+   is scheduled for a future date never reaches a terminal status at all:
+   wait for every row's execution log instead — §007, §025.
+3. **Gate on `dataset_updated`, never on `rows_ingested`.** They answer
+   different questions — received versus written — and a batch whose row is
+   refused reports `rows_ingested: 1, dataset_updated: 0, status: 'partial'`.
+   A gate on `rows_ingested` calls that green, and the failure surfaces three
+   steps later as a workflow that seems broken — §007, §015.
+4. **On a repeat run every action is skipped, and that is correct.** The
+   idempotency key that already fired will not fire again, so read the
+   `message` row the lake keeps, not the execution log of the run you just
+   made — on run two that log carries no body at all — §017, §029.
+5. **`skip_mdm_resolution: false` is set explicitly, and must be.** A
+   generic-table row is never its own subject. With resolution on, the
+   message and every link minted with it name the stamped subject as their
+   `legal_entity_id`; skip it and the subject is nil — §038.
+
 # See also
 
 - `datalakes.md` — the create body, and what a derived pair would add

package/.agent/cookbook/payments-compliance.md

@@ -2131,7 +2131,7 @@ truncate a table with an inbound foreign key, regardless of whether the
 referencing tables hold any rows, so repairing a parent empties its whole
 dependent closure, transitively, in a single statement — and all of them are
 re-copied by the same run. `legal_entities` is the target here on purpose:
-§029's contract pair resolved every screened subject through it, and
+§019's contract pair resolved every screened subject through it, and
 `legal_entity_identifications` points at it, so `emptied` genuinely names more
 than one table. Any surface offering this button should read `resync_empties`
 and say the count before it is pressed.
@@ -2208,15 +2208,34 @@ pairs split across four Data Activation Clients, and two agentic workflows
 that between them screen, decide, notify and track — plus the copy's own
 arrival state, read back per table and repaired.
 
-Two things are worth carrying out of this walk. **The pair must not run
-concurrently** (§020) — one writer per subject, or the unique index that
-guards against duplicate entities refuses your row on the only run that
-matters, the first. And **assert end states, not transitions** (§024) — an
-idempotency key that has already fired will not fire again, which is the
-product working, not the walk failing.
-
 Running this walk again reuses all of it.
 
+# Gotchas
+
+1. **The pair must not run concurrently.** One writer per subject, or the
+   unique index that guards against duplicate entities refuses your row on
+   the only run that matters, the first — §020.
+2. **Assert end states, not transitions.** An idempotency key that has
+   already fired will not fire again, which is the product working, not the
+   walk failing — §024.
+3. **Gate on `dataset_updated`, never on `rows_ingested`.** They answer
+   different questions — received versus written — and a batch whose row is
+   refused reports `rows_ingested: 1, dataset_updated: 0, status: 'partial'`.
+   A gate on `rows_ingested` calls that green, and the failure surfaces three
+   steps later as a workflow that seems broken — §008, §022.
+4. **The system-template catalog is paginated, and page 1 is not the
+   catalog.** The template you want is as likely to be on page 3; reading
+   page 1 and concluding a template does not exist is the trap — §014.
+5. **The identifier shape is where the contract pair goes wrong, and there
+   are three of them.** A contract's `mdm_input_config` takes `uri` / `type`
+   / `value`; a LegalEntity identification takes `id_type` / `id_number` /
+   `uri`; `POST /mdm/verify` takes `system` / `id_type` / `value` — §019.
+6. **A repair empties more than the table you name, and its `202` means
+   started.** Postgres will not truncate a table with an inbound foreign key,
+   so repairing a parent empties its whole dependent closure; there is no
+   completion callback, so poll until every emptied table reads `caught_up`
+   again — §039.
+
 # See also
 
 - `datalakes.md` — the create body, and what the derived pair is for

package/.agent/cookbook/primary-care.md

@@ -2194,30 +2194,30 @@ After all thirty-one steps run green, on one tenant and **three datalakes**:
   read back, one table emptied and copied again, and every table the repair
   took with it waited back to `caught_up`.
 
-What this surface teaches that the raw cookbooks cannot:
+# Gotchas
 
 1. **A masked jsonb column is `jsonb` in raw and `text` in both copies, and
    the types are supposed to differ.** Logical replication ships a text
    rendering and feeds it to the subscriber's input function, so
    `jsonb → text` always works and `jsonb → text[]` never does. The
    invariant is scalar-ness, not type parity — and `is_array: true`
-   describes the JSON document, not the Postgres column.
+   describes the JSON document, not the Postgres column — §016.
 2. **The tier follows what the prompt can reach.** The triage agent here runs
    `tokenized` because it reads patient messages; the equivalent agent in
    `subscription-saas` runs `raw` because its prompt carries an account
-   number and nothing else. Neither is a house style.
+   number and nothing else. Neither is a house style — §021.
 3. **The two copies are different from each other on purpose.** `tok_<hash>`
    is a stable join key for a machine; `xxxx-<tail>` is an unjoinable
-   placeholder for a person.
+   placeholder for a person — §029.
 4. **A key the contract does not read is not an error.** It renders nothing,
    the column lands `null`, the batch reports green, and the failure appears
    two steps later as an action rejecting an empty recipient. Assert columns
-   on the row.
+   on the row — §015.
 5. **"The copy exists" and "the copy is complete" are different questions.**
    `finished_copy` has not finished — read `caught_up`, not the state's name.
    And a repair is not scoped to the table you name: Postgres will not
    truncate a table anything references, so the dependent closure goes with
-   it. Both are why `emptied` is returned rather than assumed.
+   it. Both are why `emptied` is returned rather than assumed — §030, §031.
 
 # See also
 

package/.agent/cookbook/subscription-saas.md

@@ -2405,7 +2405,7 @@ After all forty-one steps run green, on one tenant and **one raw datalake**:
 - **A second person** is on the tenant with a `member` role, invited and
   accepted entirely through the SDK.
 
-Four things this walk teaches that are easy to learn the expensive way:
+# Gotchas
 
 1. **Never bind a contract pair to one activation client.** The fan-out
    staggers by row, so a pair on one client resolves the same subject twice
@@ -2413,10 +2413,10 @@ Four things this walk teaches that are easy to learn the expensive way:
    sequence them — §012, and again at §030 and §033.
 2. **Gate on `dataset_updated`, not `rows_ingested`.** Received is not
    written. A refused row reports the first and not the second, and a walk
-   gated on the wrong one goes green over an empty table.
+   gated on the wrong one goes green over an empty table — §007, §013.
 3. **Search the idempotency key, never the workflow id.** The key is built
    from a stable business id and names the same message forever; a workflow
-   id changes the moment the resource is recreated.
+   id changes the moment the resource is recreated — §019, §023.
 4. **Assert the end state, not the transition.** An idempotency key fires
    once ever, so every assertion here accepts both the first run's shape and
    the repeat run's — §027 spells that out, and §040 defers its proof to

package/dist/index.d.mts

@@ -679,7 +679,7 @@ type ActionStatusUpdaterResponse = {
    */
   readonly last_run_at?: string | null;
   /**
-   * Why the last poll run failed, or why a `partial` run was truncated; null when the run completed and read its whole window
+   * Why the last poll run failed; null when the run completed and read its whole window
    */
   readonly last_run_error?: string | null;
   /**
@@ -687,9 +687,9 @@ type ActionStatusUpdaterResponse = {
    */
   readonly last_run_events_found?: number | null;
   /**
-   * 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.
+   * Outcome of the last poll run: `ok` when the run read its whole window, `error` when it stopped — read `last_run_error` for why. A run is never partial: every page of the window is read, one job per page.
    */
-  readonly last_run_status?: 'ok' | 'partial' | 'error';
+  readonly last_run_status?: 'ok' | 'error';
   message_config: SimpleTemplateConfigResponse;
   /**
    * Updater name
@@ -990,6 +990,7 @@ declare enum ActionType {
   EMAIL = "email",
   VOICE = "voice",
   DATA_EXCHANGE = "data_exchange",
+  DATA_ACTIVATION = "data_activation",
 }
 /**
  * MDMVerifyRequest
@@ -1185,11 +1186,13 @@ type ActionResponse = {
     tool_call_type: 'aws_lambda_request';
   } & ActionAwsLambdaCallResponse) | ({
     tool_call_type: 'manual_upload';
-  } & ActionManualUploadCallResponse);
+  } & ActionManualUploadCallResponse) | ({
+    tool_call_type: 'run_data_activation_client';
+  } & ActionRunDataActivationClientCallResponse);
   /**
-   * Tool that executes this action
+   * Tool that executes this action. Required for every action type except data_activation, which refuses one: its client carries its own tool.
    */
-  tool_id: string;
+  tool_id?: string | null;
   /**
    * Liquid template that determines when this action executes
    */
@@ -1663,6 +1666,21 @@ type SystemTemplateListResponse = {
 type DataActivationClientS3CallResponse = S3CallResponse & {
   tool_call_type: 's3_request';
 };
+/**
+ * RunDataActivationClientCallRequest
+ *
+ * Runs a data activation client for the row that started the workflow, with the tool call the template renders for that row in place of the client's stored one. Request
+ */
+type RunDataActivationClientCallRequest = {
+  /**
+   * Slug of the data activation client to run, in the workflow's datalake
+   */
+  client_slug: string;
+  /**
+   * Liquid template rendered against the row that started the workflow, to the client's whole tool call as JSON — the shape the run-manually endpoint takes. It replaces the client's stored tool call for this run only.
+   */
+  tool_call_override_template: string;
+};
 /**
  * EmailCallResponse
  *
@@ -2373,6 +2391,12 @@ type AuthenticatedLinkUpdateMessageTrackingRequest = {
 type DataActivationClientSftpCallResponse = SftpCallResponse & {
   tool_call_type: 'sftp_request';
 };
+/**
+ * ActionRunDataActivationClientCallResponse
+ */
+type ActionRunDataActivationClientCallResponse = RunDataActivationClientCallResponse & {
+  tool_call_type: 'run_data_activation_client';
+};
 /**
  * DataSourceRequest
  *
@@ -2615,6 +2639,21 @@ type AlveraApiError = {
    */
   mode?: string | null;
 };
+/**
+ * RunDataActivationClientCallResponse
+ *
+ * Runs a data activation client for the row that started the workflow, with the tool call the template renders for that row in place of the client's stored one.
+ */
+type RunDataActivationClientCallResponse = {
+  /**
+   * Slug of the data activation client to run, in the workflow's datalake
+   */
+  client_slug: string;
+  /**
+   * Liquid template rendered against the row that started the workflow, to the client's whole tool call as JSON — the shape the run-manually endpoint takes. It replaces the client's stored tool call for this run only.
+   */
+  tool_call_override_template: string;
+};
 /**
  * CloudStorageAwsResponse
  *
@@ -3438,7 +3477,7 @@ type EmailResponse = {
    */
   domain?: string;
   /**
-   * Custom Mailgun API base URL (e.g., https://api.eu.mailgun.net/v3 for EU domains, or a WireMock endpoint for integration tests); leave blank for real Mailgun
+   * Custom provider endpoint; leave blank for the real provider. For SES, the whole request URL (e.g., http://localhost:4566 for MiniStack); blank means https://email.<region>.amazonaws.com. For Mailgun, the API base URL (e.g., https://api.eu.mailgun.net/v3 for EU domains, or a WireMock endpoint for integration tests)
    */
   endpoint_url?: string | null;
   /**
@@ -4973,11 +5012,13 @@ type ActionRequestWritable = {
     tool_call_type: 'aws_lambda_request';
   } & ActionAwsLambdaCallRequestWritable) | ({
     tool_call_type: 'manual_upload';
-  } & ActionManualUploadCallRequest);
+  } & ActionManualUploadCallRequest) | ({
+    tool_call_type: 'run_data_activation_client';
+  } & ActionRunDataActivationClientCallRequestWritable);
   /**
-   * Tool that executes this action
+   * Tool that executes this action. Required for every action type except data_activation, which refuses one: its client carries its own tool.
    */
-  tool_id: string;
+  tool_id?: string | null;
   /**
    * Liquid template that determines when this action executes
    */
@@ -5098,7 +5139,7 @@ type EmailRequestWritable = {
    */
   domain?: string;
   /**
-   * Custom Mailgun API base URL (e.g., https://api.eu.mailgun.net/v3 for EU domains, or a WireMock endpoint for integration tests); leave blank for real Mailgun
+   * Custom provider endpoint; leave blank for the real provider. For SES, the whole request URL (e.g., http://localhost:4566 for MiniStack); blank means https://email.<region>.amazonaws.com. For Mailgun, the API base URL (e.g., https://api.eu.mailgun.net/v3 for EU domains, or a WireMock endpoint for integration tests)
    */
   endpoint_url?: string | null;
   /**
@@ -5794,6 +5835,12 @@ type SftpRequestWritable = {
    */
   user_name: string;
 };
+/**
+ * ActionRunDataActivationClientCallRequest
+ */
+type ActionRunDataActivationClientCallRequestWritable = RunDataActivationClientCallRequest & {
+  tool_call_type: 'run_data_activation_client';
+};
 /**
  * CloudStorageCustomRequest
  *