@alvera-ai/platform-sdk 0.13.0 → 0.15.0

package/.agent/cookbook/appointment-review-sms-workflow.md

@@ -675,6 +675,38 @@ if (!tracked.message?.opened_at || !tracked.message?.form_submitted_at) {
 }
 ```
 
+## 016 — write the integration test
+
+End the build with a test you keep: re-read the workflow and prove the
+pipeline still executes — without a side effect. `mode: 'dry_run'` with a
+never-matching selection runs the FULL pipeline (selection → filter →
+decision) and intercepts only the final action call, so no message
+leaves, yet the acknowledgement proves the workflow is runnable. This
+block runs live under `make validate-cookbook`.
+
+```typescript
+// Re-GET — the workflow must still be live, or nothing will run.
+const { data: wfRow } = await api.workflows.get(tenantSlug, datalakeSlug, workflowId)
+if (wfRow.status !== 'live') {
+  throw new Error(`workflow regressed from live: ${wfRow.status}`)
+}
+// Behavioural probe — a dry run against a selection no row can match:
+// the pipeline executes end-to-end, the final action call is
+// intercepted, and the acknowledgement carries the run-log id.
+const { data: probeRun } = await api.workflows.run(tenantSlug, datalakeSlug, ctx.workflowSlug, {
+  sql_where_clause: "ra.batch_id = 'test-never-matching-batch'",
+  mode: 'dry_run',
+  manual_override: false,
+})
+if (typeof probeRun.workflow_run_log_id !== 'string' || probeRun.workflow_run_log_id.length === 0) {
+  throw new Error('dry-run probe returned no workflow_run_log_id')
+}
+```
+
+If the probe fails in production, escalate with the run response as
+evidence — don't flip the workflow's status or rewrite its configs to
+chase the error.
+
 # Branches
 
 - **The cancelled appointment is filtered, not failed** — §012

package/.agent/cookbook/birthday-greeting-sms-trigger.md

@@ -175,7 +175,7 @@ const workflowResp = await api.workflows.create(tenantSlug, datalakeSlug, {
       position: 0,
       trigger_template: TRIGGER_TEMPLATE,
       idempotency_template:
-        '{{ subject_id }}-{{ workflow_id }}-{{ action_id }}-{{ "" | uuid }}',
+        '{{ subject_id }}-{{ workflow_id }}-{{ action_id }}',
       connected_app_id: connectedAppId,
       connected_app_route: '/forms/birthday-greeting',
       connected_app_metadata_template:
@@ -577,6 +577,40 @@ if (!tracked.message?.opened_at || !tracked.message?.form_submitted_at) {
 }
 ```
 
+## 015 — write the integration test
+
+End the build with a test you keep: re-read the workflow and prove the
+pipeline still executes — without a side effect. `mode: 'dry_run'` with a
+never-matching selection runs the FULL pipeline (selection → filter →
+decision) and intercepts only the final action call, so no message
+leaves, yet the acknowledgement proves the workflow is runnable. This
+block runs live under `make validate-cookbook`.
+
+```typescript
+// Re-GET — the workflow must still be live, or nothing will run.
+const { data: wfRow } = await api.workflows.get(tenantSlug, datalakeSlug, workflowId)
+if (wfRow.status !== 'live') {
+  throw new Error(`workflow regressed from live: ${wfRow.status}`)
+}
+// Behavioural probe — a dry run against a selection no row can match:
+// the pipeline executes end-to-end, the final action call is
+// intercepted, and the acknowledgement carries the run-log id. The
+// clause must speak this workflow's selection dialect — the dataset
+// alias is `rle` here, the same alias the live run above uses.
+const { data: probeRun } = await api.workflows.run(tenantSlug, datalakeSlug, ctx.workflowSlug, {
+  sql_where_clause: "rle.batch_id = 'test-never-matching-batch'",
+  mode: 'dry_run',
+  manual_override: false,
+})
+if (typeof probeRun.workflow_run_log_id !== 'string' || probeRun.workflow_run_log_id.length === 0) {
+  throw new Error('dry-run probe returned no workflow_run_log_id')
+}
+```
+
+If the probe fails in production, escalate with the run response as
+evidence — don't flip the workflow's status or rewrite its configs to
+chase the error.
+
 # Branches
 
 - **The no-DoB row is filtered, not failed** — §011 asserts the no-DoB

package/.agent/cookbook/bulk-ingest.md

@@ -229,6 +229,54 @@ if (rows.length < 4) {
 }
 ```
 
+## 009 — write the integration test
+
+End the build with a test you keep: run the bulk path in miniature —
+mint a link, PUT a tiny inline CSV, enqueue it — and assert each call's
+own acknowledgement. The probe rows are `test-`-prefixed so they are
+unmistakably synthetic wherever they surface, and the test asserts the
+enqueue ack (`job_id`), never synchronous merge completion — the worker
+owns that. This block runs live under `make validate-cookbook`.
+
+```typescript
+// Re-GET — the client must still be there and carry its ingest slug.
+const { data: dacRow } = await api.dataActivationClients.get(tenantSlug, datalakeSlug, dacId)
+if (dacRow.slug !== ctx.dacSlug) {
+  throw new Error(`DAC slug drifted on read-back: ${dacRow.slug}`)
+}
+// Behavioural probe — the three-step bulk path, each step asserted on
+// its own response.
+const probeCsv =
+  'customer_number,customer_type,status,name,email,currency\n' +
+  `test-PROBE-1-${runSuffix},individual,contracted,test-Grace Hopper,test-grace-${runSuffix}@example.com,USD\n`
+const { data: probeLink } = await api.datalakes.createUploadLink(tenantSlug, datalakeSlug, {
+  content_type: 'text/csv',
+  filename: `test-bulk-probe-${runSuffix}.csv`,
+})
+if (!probeLink.url || !probeLink.key) {
+  throw new Error('createUploadLink returned no url/key')
+}
+const probePut = await fetch(probeLink.url, {
+  method: 'PUT',
+  headers: { 'Content-Type': 'text/csv' },
+  body: probeCsv,
+})
+if (probePut.status !== 200) {
+  throw new Error(`presigned PUT failed: ${probePut.status}`)
+}
+const { data: probeJob } = await api.dataActivationClients.ingestFile(tenantSlug, datalakeSlug, ctx.dacSlug, {
+  key: probeLink.key,
+})
+// job_id is a NUMBER on the wire (an Oban job id), status "scheduled".
+if (probeJob.job_id === undefined || probeJob.job_id === null) {
+  throw new Error('ingestFile probe returned no job_id')
+}
+```
+
+If the probe fails in production, escalate with the failing call's
+response — don't retry the enqueue in a loop or reach into the worker's
+storage to "help it along".
+
 # Gotchas
 
 - **The file PUT is raw HTTP, not the SDK.** `createUploadLink` and `ingestFile`

package/.agent/cookbook/contact-us-triage-with-llm.md

@@ -326,7 +326,7 @@ const workflowResp = await api.workflows.create(tenantSlug, datalakeSlug, {
     tool_id: toolId,
     position: 0,
     trigger_template: 'now',
-    idempotency_template: `{{ subject_id }}-{{ action_id }}-${bucket}-{{ "" | uuid }}`,
+    idempotency_template: `{{ subject_id }}-{{ action_id }}-${bucket}`,
     tool_call: {
       tool_call_type: 'sms_request',
       to: { type: 'custom', body: '+15551234567' },
@@ -543,6 +543,41 @@ for (const wel of ourWels) {
 }
 ```
 
+## 011 — write the integration test
+
+End the build with a test you keep: re-read the workflow and prove the
+pipeline still executes — without a side effect. `mode: 'dry_run'` with a
+never-matching selection runs the FULL pipeline (selection → filter →
+decision) and intercepts only the final action call, so no message
+leaves, yet the acknowledgement proves the workflow is runnable. This
+block runs live under `make validate-cookbook`.
+
+```typescript
+// Re-GET — the workflow must still be live, or nothing will run.
+const { data: wfRow } = await api.workflows.get(tenantSlug, datalakeSlug, workflowId)
+if (wfRow.status !== 'live') {
+  throw new Error(`workflow regressed from live: ${wfRow.status}`)
+}
+// Behavioural probe — a dry run against a selection no row can match:
+// the pipeline executes end-to-end, the final action call is
+// intercepted, and the acknowledgement carries the run-log id. The
+// clause speaks this workflow's selection dialect: a GENERIC-TABLE
+// dataset is addressed by its own columns (no `ra.` dataset alias —
+// that alias exists only for system-dataset selections).
+const { data: probeRun } = await api.workflows.run(tenantSlug, datalakeSlug, ctx.workflowSlug, {
+  sql_where_clause: "submission_id = 'test-never-matching-submission'",
+  mode: 'dry_run',
+  manual_override: false,
+})
+if (typeof probeRun.workflow_run_log_id !== 'string' || probeRun.workflow_run_log_id.length === 0) {
+  throw new Error('dry-run probe returned no workflow_run_log_id')
+}
+```
+
+If the probe fails in production, escalate with the run response as
+evidence — don't flip the workflow's status or rewrite its configs to
+chase the error.
+
 # Branches
 
 - **The filter is permissive** — `filter_config.body: 'true'`

package/.agent/cookbook/dunning-sms-for-delinquent.md

@@ -189,7 +189,7 @@ const workflowResp = await api.workflows.create(tenantSlug, datalakeSlug, {
       decision_key: DECISION_KEY,
       position: 0,
       trigger_template: 'now',
-      idempotency_template: '{{ customer_id }}-{{ decision_key }}-{{ "" | uuid }}',
+      idempotency_template: '{{ customer_id }}-{{ decision_key }}',
       connected_app_id: connectedAppId,
       connected_app_route: '/portal/pay',
       connected_app_metadata_template:
@@ -533,6 +533,38 @@ if (!tracked.message?.opened_at || !tracked.message?.form_submitted_at) {
 }
 ```
 
+## 014 — write the integration test
+
+End the build with a test you keep: re-read the workflow and prove the
+pipeline still executes — without a side effect. `mode: 'dry_run'` with a
+never-matching selection runs the FULL pipeline (selection → filter →
+decision) and intercepts only the final action call, so no message
+leaves, yet the acknowledgement proves the workflow is runnable. This
+block runs live under `make validate-cookbook`.
+
+```typescript
+// Re-GET — the workflow must still be live, or nothing will run.
+const { data: wfRow } = await api.workflows.get(tenantSlug, datalakeSlug, workflowId)
+if (wfRow.status !== 'live') {
+  throw new Error(`workflow regressed from live: ${wfRow.status}`)
+}
+// Behavioural probe — a dry run against a selection no row can match:
+// the pipeline executes end-to-end, the final action call is
+// intercepted, and the acknowledgement carries the run-log id.
+const { data: probeRun } = await api.workflows.run(tenantSlug, datalakeSlug, ctx.workflowSlug, {
+  sql_where_clause: "ra.batch_id = 'test-never-matching-batch'",
+  mode: 'dry_run',
+  manual_override: false,
+})
+if (typeof probeRun.workflow_run_log_id !== 'string' || probeRun.workflow_run_log_id.length === 0) {
+  throw new Error('dry-run probe returned no workflow_run_log_id')
+}
+```
+
+If the probe fails in production, escalate with the run response as
+evidence — don't flip the workflow's status or rewrite its configs to
+chase the error.
+
 # Branches
 
 - **The unverified customer is filtered, not failed** — §011

package/.agent/cookbook/generic-tables.md

@@ -175,6 +175,46 @@ if (!row || row.submission_id !== ctx.submissionId) {
 }
 ```
 
+## 007 — write the integration test
+
+End the build with a test you keep: re-read the table and prove the two
+facts every consumer of it depends on — the deploy completed (with the
+server-derived physical name), and the ingest path accepts a row. The
+probe row is `test-`-prefixed so it is unmistakably synthetic wherever it
+surfaces. This block runs live under `make validate-cookbook`.
+
+```typescript
+// Re-GET — deployed, with the server-derived alvera_custom_ name.
+const { data: tableRow } = await api.genericTables.get(tenantSlug, datalakeSlug, genericTableId)
+if (tableRow.status !== 'deployed') {
+  throw new Error(`generic table regressed from deployed: ${tableRow.status}`)
+}
+if (tableRow.name !== ctx.tableName) {
+  throw new Error(`physical name drifted on read-back: ${tableRow.name}`)
+}
+// Behavioural probe — one synthetic row through the auto-provisioned
+// default client; ingest is async (202), so assert the batch
+// acknowledgement, never synchronous row completion.
+const { data: probeAck } = await api.dataActivationClients.ingest(
+  tenantSlug, datalakeSlug, ctx.defaultDacSlug,
+  {
+    data: {
+      submission_id: `test-CDS-probe-${runSuffix}`,
+      customer_name: 'test-Ada Lovelace',
+      email: 'test-ada@example.test',
+      message: 'test: integration-test probe row.',
+      source_channel: 'portal',
+    },
+  },
+)
+if (typeof probeAck.batch_id !== 'string' || probeAck.batch_id.length === 0) {
+  throw new Error('default-client ingest did not enqueue a batch')
+}
+```
+
+If the probe fails in production, escalate with the failing response —
+don't re-create the table or hand-edit the physical schema.
+
 # Gotchas
 
 - **`privacy_requirement` is load-bearing.** It drives the regulated/unregulated

package/.agent/cookbook/kyc-notification-on-account-activation.md

@@ -188,7 +188,7 @@ const workflowResp = await api.workflows.create(tenantSlug, datalakeSlug, {
       decision_key: DECISION_KEY,
       position: 0,
       trigger_template: 'now',
-      idempotency_template: '{{ payment_account.id }}-{{ decision_key }}-{{ "" | uuid }}',
+      idempotency_template: '{{ payment_account.id }}-{{ decision_key }}',
       connected_app_id: connectedAppId,
       connected_app_route: '/portal/kyc',
       connected_app_metadata_template: '{"payment_account_id":"{{ payment_account.id }}"}',
@@ -531,6 +531,40 @@ if (!tracked.message?.opened_at || !tracked.message?.form_submitted_at) {
 }
 ```
 
+## 014 — write the integration test
+
+End the build with a test you keep: re-read the workflow and prove the
+pipeline still executes — without a side effect. `mode: 'dry_run'` with a
+never-matching selection runs the FULL pipeline (selection → filter →
+decision) and intercepts only the final action call, so no message
+leaves, yet the acknowledgement proves the workflow is runnable. This
+block runs live under `make validate-cookbook`.
+
+```typescript
+// Re-GET — the workflow must still be live, or nothing will run.
+const { data: wfRow } = await api.workflows.get(tenantSlug, datalakeSlug, workflowId)
+if (wfRow.status !== 'live') {
+  throw new Error(`workflow regressed from live: ${wfRow.status}`)
+}
+// Behavioural probe — a dry run against a selection no row can match:
+// the pipeline executes end-to-end, the final action call is
+// intercepted, and the acknowledgement carries the run-log id. The
+// clause must speak this workflow's selection dialect — the dataset
+// alias is `rpa` here, the same alias the live run above uses.
+const { data: probeRun } = await api.workflows.run(tenantSlug, datalakeSlug, ctx.workflowSlug, {
+  sql_where_clause: "rpa.batch_id = 'test-never-matching-batch'",
+  mode: 'dry_run',
+  manual_override: false,
+})
+if (typeof probeRun.workflow_run_log_id !== 'string' || probeRun.workflow_run_log_id.length === 0) {
+  throw new Error('dry-run probe returned no workflow_run_log_id')
+}
+```
+
+If the probe fails in production, escalate with the run response as
+evidence — don't flip the workflow's status or rewrite its configs to
+chase the error.
+
 # Branches
 
 - **The suspended account is filtered, not failed** — §011

package/.agent/cookbook/marketing-campaign-send.md

@@ -918,6 +918,41 @@ while (Date.now() < flagDeadline) {
 if (!flagged) throw new Error('the re-ingest did not flag the reply potential_duplicate within 120s')
 ```
 
+## 013 — write the integration test
+
+End the build with a test you keep: re-read the workflow and prove the
+pipeline still executes — without a side effect. `mode: 'dry_run'` with a
+never-matching selection runs the FULL pipeline (selection → filter →
+decision) and intercepts only the final action call, so no message
+leaves, yet the acknowledgement proves the workflow is runnable. This
+block runs live under `make validate-cookbook`.
+
+```typescript
+// Re-GET — the workflow must still be live, or nothing will run.
+const { data: wfRow } = await api.workflows.get(tenantSlug, datalakeSlug, workflowId)
+if (wfRow.status !== 'live') {
+  throw new Error(`workflow regressed from live: ${wfRow.status}`)
+}
+// Behavioural probe — a dry run against a selection no row can match:
+// the pipeline executes end-to-end, the final action call is
+// intercepted, and the acknowledgement carries the run-log id. The
+// clause speaks this workflow's selection dialect: a GENERIC-TABLE
+// audience is addressed by its own columns (no `ra.` dataset alias —
+// that alias exists only for system-dataset selections).
+const { data: probeRun } = await api.workflows.run(tenantSlug, datalakeSlug, ctx.workflowSlug, {
+  sql_where_clause: "end_customer_id = 'test-never-matching-customer'",
+  mode: 'dry_run',
+  manual_override: false,
+})
+if (typeof probeRun.workflow_run_log_id !== 'string' || probeRun.workflow_run_log_id.length === 0) {
+  throw new Error('dry-run probe returned no workflow_run_log_id')
+}
+```
+
+If the probe fails in production, escalate with the run response as
+evidence — don't flip the workflow's status or rewrite its configs to
+chase the error.
+
 # Branches
 
 - **Suppressed and unreachable are `:filtered`, not `:failed`.** Both