@alvera-ai/platform-sdk 0.18.0 → 0.18.1

package/.agent/AGENTS.md

@@ -259,6 +259,10 @@ numbered steps inside the cookbook whose use case motivates it.
    DATA ACTIVATION  (how data flows in)
    ───────────────
    generic_tables.md            Schema-on-write tables.
+   advanced_migrations.md       Hand-written DDL for one lake —
+                                  indexes, foreign keys, anything
+                                  past the CREATE TABLE / ADD COLUMN
+                                  the platform writes for itself.
    interoperability_contracts.md Liquid template mappings.
    data_activation_clients.md    Ingestion pipelines — both the
                                   binding row (CRUD) and the
@@ -298,6 +302,7 @@ wire name (snake_case):
     api.connectedApps                   connected_apps.md
     api.mdm                             mdm.md
     api.genericTables                   generic_tables.md
+    api.advancedMigrations              advanced_migrations.md
     api.interoperabilityContracts       interoperability_contracts.md
     api.dataActivationClients           data_activation_clients.md
     api.workflows                       workflows.md
@@ -327,8 +332,12 @@ Each cookbook structure:
   are lifted from, anchor file first), `status`. `use_case` is one
   of the four surfaces — `organic-marketing`,
   `subscription-saas`, `payments-compliance`,
-  `primary-care-feedback` — and there is exactly one cookbook per
-  use case, at `cookbook/<use-case>.md`.
+  `primary-care-feedback` — and there is exactly one cookbook per use
+  case. Three are at `cookbook/<use-case>.md`; the fourth is at
+  `cookbook/primary-care.md`, because `use_case` tracks the integration
+  suite it is lifted from (`integration-tests/tests/primary-care-feedback/`)
+  and the filename does not. Read `use_case` from the front matter rather
+  than deriving it from the filename.
 - **Problem** — the business-outcome statement in domain terms,
   sourced from the anchor vitest's behaviour (not from
   customer-narrative documentation).

package/.agent/advanced_migrations.md

@@ -0,0 +1,202 @@
+# Advanced migrations
+
+SQL a person wrote by hand for one datalake.
+
+The platform writes its own DDL when a generic table is created or gains a
+column — `CREATE TABLE` and `ALTER TABLE … ADD COLUMN`, and nothing else.
+Everything past that is yours to write here: an index, a foreign key, a column
+rename, a type change, a drop. The same migrator runs both.
+
+**One name, two spellings.** Outwardly these are *advanced migrations*, which is
+what the API path and this guide call them. The platform stores them in
+`datalake_migrations`, and its own logs and internals use that name. Both are
+correct; do not coin a third.
+
+    api.advancedMigrations        →  this guide
+    /datalakes/{slug}/advanced-migrations
+
+## 1. Wire shape
+
+```typescript
+const { data: created } = await api.advancedMigrations.create(
+  tenantSlug,
+  datalakeSlug,          // scope comes from the PATH — see below
+  {
+    name: 'AddEmailIndexToContactSubmissions',
+    up_statement:
+      'CREATE INDEX IF NOT EXISTS idx_contact_submissions_email ' +
+      'ON alvera_custom_contact_submissions (email)',
+    down_statement:
+      'DROP INDEX IF EXISTS idx_contact_submissions_email',
+  },
+)
+// created.id           — server-derived UUID
+// created.version      — server-assigned from a sequence; orders execution
+// created.datalake_id  — server-derived from the path
+// created.checksum     — server-computed; the drift fingerprint
+```
+
+Three fields, all required, all strings:
+
+```
+name             required string — capitalized identifier, unique per datalake
+up_statement     required string — the DDL to run
+down_statement   required string — the DDL that reverses it
+```
+
+**`datalake_id` is NOT a body field.** This is the one place the shape departs
+from every other datalake-scoped kind. Elsewhere — tools, workflows, generic
+tables — you send `datalake_id` in the body. Here it is `readOnly`: the scope
+comes from `datalakeSlug` in the path, and the server fills the field in. Sending
+it is not how you say which lake this belongs to.
+
+**`version` is server-assigned and orders execution.** It comes from a sequence,
+not from you, and it is the thing that decides what runs first — not the name,
+and not the order you declared them in. Generated migrations carry a year-style
+prefix in their names to read well beside yours; that prefix is cosmetic.
+
+## 2. Rules the type cannot encode
+
+### An applied migration is frozen — update and delete both refuse
+
+Once a migration has run successfully, `update()` and `delete()` each answer
+**409 Conflict**. The reasons differ and both are worth knowing.
+
+**Update** is refused because a statement that has already executed cannot be
+rewritten after the fact: the new text would no longer describe what happened.
+
+**Delete** is refused because the run log cascades on delete, so removing an
+applied migration would also erase the record of it having run.
+
+So a migration has exactly two lives. Before it runs it is ordinary and
+editable. After it runs it is history. **Changing applied DDL means writing a
+NEW migration that alters what the old one built** — the same shape as changing
+a generic table column's `privacy_requirement`, which is delete-and-recreate
+rather than an edit.
+
+"Applied" means precisely: a run log row exists for this migration with
+direction `up` and status `success`. A failed run does not freeze it.
+
+### Write the statement to be safe on a second run
+
+The platform tracks what it has applied and will not run an applied migration
+twice, so you do not need `IF NOT EXISTS` for that. You need it for the other
+case: a run that failed **partway**. The applied-migrations record stops a second
+run; it does not undo a first one that got halfway.
+
+```sql
+-- safe to meet again
+CREATE INDEX IF NOT EXISTS idx_submissions_email ON … (email)
+
+-- Postgres has no ADD CONSTRAINT IF NOT EXISTS, so guard it yourself
+DO $$
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1 FROM pg_constraint WHERE conname = 'fk_submissions_lead'
+  ) THEN
+    ALTER TABLE alvera_custom_contact_submissions
+      ADD CONSTRAINT fk_submissions_lead
+      FOREIGN KEY (lead_id) REFERENCES alvera_custom_leads (id);
+  END IF;
+END $$;
+```
+
+The same applies to `down_statement`, which is likelier to be run against a
+database that is not in the state you assumed.
+
+### The table names are the platform's, not yours
+
+A generic table you declared as `contact_submissions` is physically
+`alvera_custom_contact_submissions`. Read the name back from the created table
+rather than composing it — see `generic_tables.md` — because your migration
+statement has to name the physical table, and getting it wrong is a runtime
+failure inside DDL rather than a validation error.
+
+### Ordering is real, and it is the version's job
+
+Adding an index and then a foreign key that depends on it are two migrations,
+and the sequence decides which runs first. Two migrations created in one session
+run in creation order because the sequence is monotonic — but if you need B
+after A, that is a fact about your two `version` values, not about how you
+listed them.
+
+## 3. Field ownership
+
+**Caller-authored (Request).** `name`, `up_statement`, `down_statement`. That is
+the whole writable surface.
+
+**Server-derived (Response-only).** `id`, `datalake_id`, `version`, `checksum`,
+`inserted_at`, `updated_at`. None may be sent; see `type_naming.md` for why the
+Writable types exclude them.
+
+`name` is unique per datalake, so two lakes may each carry a
+`AddEmailIndex` and neither collides.
+
+## 4. Error envelopes
+
+Standard JSON:API envelope throughout — see `errors.md`.
+
+| Status | When |
+|---|---|
+| 422 | a required field is missing, or `name` collides within this datalake |
+| 409 | the migration has already been applied — `update` and `delete` both |
+| 404 | the id belongs to a different datalake (deliberately not "403": its existence is not leaked) |
+
+A 409 here is not a retryable condition. It is telling you the migration is
+history and you want a new one.
+
+## 5. Lifecycle
+
+```
+create      →  the row exists; nothing has run yet
+migrate     →  the datalake's migrator runs it, in version order
+              (POST /datalakes/{slug}/migrate — asynchronous, 202)
+applied     →  a run log row: direction up, status success
+              from here: update 409, delete 409
+```
+
+Creating a migration does **not** run it. The datalake's migrate call does, and
+it is asynchronous — it answers 202 as soon as the job is enqueued. Poll the
+datalake for `status: ready` the way you would after creating one; see
+`datalakes.md`.
+
+## 6. Gotchas
+
+**A created migration that never ran is invisible in the database.** The row
+exists, `list()` returns it, and nothing has happened to any table. Reading the
+catalog is the only way to know whether it took effect — the migration record
+says what you asked for, not what is true.
+
+**Proving one worked means asking the database, not the API.** The response
+carries `checksum`, `datalake_id`, `down_statement`, `id`, `inserted_at`,
+`name`, `up_statement`, `updated_at` and `version` — no status, no applied
+flag, and `version` is execution ORDER rather than proof of execution. So the
+honest check is a query against the catalog for the object the statement was
+supposed to create:
+
+```typescript
+// an index
+const { data: indexRows } = await api.datalakes.executeSql(tenantSlug, datalakeSlug, {
+  sql: `select 1 from pg_indexes
+         where tablename = 'alvera_custom_contact_submissions'
+           and indexname = 'idx_contact_submissions_email'`,
+  mode: 'raw',
+})
+
+// a foreign key
+const { data: fkRows } = await api.datalakes.executeSql(tenantSlug, datalakeSlug, {
+  sql: `select 1 from information_schema.table_constraints
+         where constraint_type = 'FOREIGN KEY'
+           and table_name      = 'alvera_custom_contact_submissions'
+           and constraint_name = 'fk_submissions_lead'`,
+  mode: 'raw',
+})
+```
+
+**`down_statement` is required and is rarely exercised.** Nothing makes you
+prove it works, and it is the statement you will want on your worst day. Write
+it as carefully as the `up`.
+
+**A migration belongs to exactly one datalake.** There is no shared or
+tenant-level migration. Three lakes needing the same index need three
+migrations — which is also why `name` only has to be unique per lake.

package/.agent/datalakes.md

@@ -261,6 +261,75 @@ The tier is chosen per call, not per datalake — `mode` on
 `executeSql`, `dataAccessMode` on a dataset search. Nothing about
 the datalake decides it.
 
+### How the copies get turned on
+
+Nothing in this SDK turns them on directly, and that is worth stating
+before the mechanism, because the field involved is one you cannot send.
+
+**Through the `alvera` CLI it is one boolean on the datalake block:**
+
+```toml
+[datalakes.my-lake]
+enable_tokenization = true
+```
+
+`enable_tokenization` is a **CLI-only manifest key**. The CLI strips it
+before the request reaches the API — there is no such field on
+`DatalakeRequest`, and adding one to an SDK call does nothing. What it
+drives is a separate endpoint, `POST /datalakes/<slug>/tokenization`,
+which the CLI calls on your behalf after the raw lake reaches `ready`.
+Calling that endpoint yourself is the SDK-level equivalent.
+
+Four things about it that are not guessable from the field:
+
+**Both copies or neither.** They are created, destroyed and billed
+together. There is no way to ask for a tokenized lake without a redacted
+one.
+
+**Order is handled for you, and it matters.** A derived lake's own
+migration creates its tables and starts the copy, so the raw lake must be
+`ready` first. `apply` turns the copies on after that, then waits for
+both to reach `ready` themselves.
+
+**It only goes one way.** Nothing turns tokenization off — no endpoint
+deletes a derived lake — which is why the platform declined to make it an
+authored field in the first place: `true → false` would let a caller
+declare a state the platform cannot honour.
+
+**`[tokenization.<slug>]` is retired.** If you meet a manifest carrying
+that block, it is pre-0.18 and the CLI now refuses it by name.
+
+### What turning them on actually requires
+
+One boolean, three prerequisites — and the platform **probes** each and
+**refuses** when it is missing. It never issues `CREATE DATABASE` or
+`CreateBucket`, deliberately: a platform that can create one can create
+it in the wrong place, and a datalake's storage belongs to the operator.
+
+**1 · Two more databases.** Named from the raw lake's own database name
+with the mode appended — `<raw>_tokenized` and `<raw>_redacted`. Postgres
+truncates an over-long identifier *silently*, which would land two
+derived lakes on one physical database, so a name that would exceed the
+63-byte identifier limit is refused rather than truncated. Long raw
+database names are where that bites.
+
+**2 · On two more Postgres servers.** A derived lake does not live beside
+the raw one. Locally the tokenized copy is on `:5433` and the redacted on
+`:5434`, beside the raw lake on `:5432`. Separate servers on purpose: a
+derived lake runs `postgresql_anonymizer` and PL/Python, which the raw
+lake — holding the real values — must not have.
+
+**3 · Three buckets, not one.** The raw lake's bucket plus
+`<bucket>-tokenized` and `<bucket>-redacted`.
+
+**The failure mode is worth knowing in advance, because it is
+mis-attributed by default.** A missing copy bucket is reported against
+the **primary** lake, naming the lake rather than the bucket that is
+actually absent — and it surfaces minutes into a create, as a 422 that
+reads like a platform defect. It has been diagnosed as one. If a create
+fails on cloud storage for a lake declaring the copies, check that all
+three buckets exist before looking anywhere else.
+
 ### What decides what a reader sees
 
 **`privacy_requirement` on the column.** That single declaration is

package/.agent/generic_tables.md

@@ -57,6 +57,17 @@ const { data: created } = await api.genericTables.create(
         is_unique: true,
         privacy_requirement: 'none',
       },
+      {
+        name: 'email',
+        title: 'Email',
+        type: 'string',
+        description: 'Submitter email',
+        is_unique: false,
+        // The masking pair: WHETHER, and WHAT it is so the right
+        // function masks it. See "a pair" below.
+        privacy_requirement: 'tokenize',
+        semantic_kind: 'email',
+      },
       // ... more columns
     ],
   },
@@ -122,8 +133,29 @@ is_array             optional bool   — column holds an array of `type` values
 description          required string — narrative; surfaces in catalogs
 is_unique            required bool   — Postgres UNIQUE constraint at migration time
 privacy_requirement  required enum   — 'none' | 'tokenize' | 'redact'
+semantic_kind        optional enum   — 'string' | 'text' | 'email' | 'phone'
+                                      | 'date' | 'json' | 'image' | 'pdf'
+                                      | 'attachment'; nullable
 ```
 
+#### `privacy_requirement` and `semantic_kind` are a pair
+
+They answer two different questions and a masked column needs both.
+
+**`privacy_requirement` says WHETHER the column is masked** in the derived
+lakes — see the table in §2 below. Immutable once the column exists.
+
+**`semantic_kind` says WHAT the value is, which decides WHICH function
+masks it.** A tokenized email should come back looking like an email; a
+tokenized phone like a phone. Without one, the platform can only treat
+the value as free text, so **a masked column with no `semantic_kind` gets
+a worse mask than it should** — still masked, but less useful to
+everything downstream that expected the shape to survive.
+
+It is optional, and nothing fails without it, which is exactly why it is
+easy to miss. **Set it on every column you mark `tokenize` or `redact`.**
+On a `none` column it is documentation and costs nothing.
+
 #### Column types
 
 ```

package/.agent/mock-services.md

@@ -4,7 +4,7 @@
 
 How the platform reaches mocked third-party APIs, on a laptop and from deployed
 environments. Two mock surfaces exist and they answer different questions:
-**WireMock** stands in for third-party SaaS APIs, **LocalStack** stands in for AWS.
+**WireMock** stands in for third-party SaaS APIs, **MiniStack** stands in for AWS.
 
 ## The two surfaces
 
@@ -12,14 +12,15 @@ environments. Two mock surfaces exist and they answer different questions:
 `wm_mappings/`, with response bodies in `wm_response_files/`. It covers the
 third-party APIs the platform integrates with — Athenahealth, Twilio, Mailgun,
 Stripe, SendGrid, HubSpot, QuickBooks, Airtable, Atomic FI, the LLM providers,
-and a small set of AWS endpoints LocalStack cannot serve.
+and a small set of AWS endpoints MiniStack cannot serve.
 
-**LocalStack** serves AWS itself: `s3,lambda,sns,ssm,sqs,sts,logs,secretsmanager,cloudformation`
+**MiniStack** serves AWS itself: `s3,lambda,sns,ssm,sqs,sts,logs,secretsmanager,cloudformation`
 (`local-dependencies.yml`). See [Datalakes](datalakes.md) for how datalake
 provisioning uses it.
 
-The division is not arbitrary. LocalStack Community **cannot** serve
-`pinpoint-sms-voice-v2` (501 — Ultimate tier only), so End User Messaging points
+The division is not arbitrary. No AWS emulator here serves
+`pinpoint-sms-voice-v2` — LocalStack Community answered 501 (Ultimate tier
+only) and MiniStack has no such service at all — so End User Messaging points
 at WireMock for its send, its S3 media staging, and its STS credential probe. A
 tool has one `endpoint_url`, so all three land on the same host.
 
@@ -62,11 +63,11 @@ the hosted instance — see below.
 
 ## Running locally
 
-`make run-backing-services` starts both. WireMock listens on `:8080`, LocalStack
+`make run-backing-services` starts both. WireMock listens on `:8080`, MiniStack
 on `:4566`. Tool bodies reach them by setting `endpoint_url` — blank means real
 AWS, any value replaces host, port and scheme.
 
-LocalStack's S3 state does **not** survive a container restart. Recreate a bucket
+MiniStack's S3 state does **not** survive a container restart. Recreate a bucket
 after one:
 
 ```bash
@@ -176,10 +177,10 @@ identical POSTs return three *different* bodies in a fixed order. Matching hashe
 across three successive calls proves both environments walked the same state
 machine — something no stateless matcher could fake.
 
-## LocalStack at the edge
+## MiniStack at the edge
 
-Not done, and deliberately scoped apart. LocalStack is also just an image and
-rides the same mechanism, but Containers **sleep by design** and LocalStack's S3
+Not done, and deliberately scoped apart. MiniStack is also just an image and
+rides the same mechanism, but Containers **sleep by design** and MiniStack's S3
 state already does not survive a restart. What is an occasional annoyance locally
 becomes routine when instances sleep between runs. Anything depending on objects
 persisting must move to R2, which speaks S3 natively — migration work, not a flag
@@ -188,5 +189,5 @@ flip.
 ## Related
 
 - [Tools](tools.md) — tool bodies, `endpoint_url`, and REST API auth methods
-- [Datalakes](datalakes.md) — how datalake provisioning uses LocalStack
+- [Datalakes](datalakes.md) — how datalake provisioning uses MiniStack
 - [Connected Apps](connected_apps.md) — the third-party integrations the corpus stands in for

package/dist/index.d.mts

@@ -127,6 +127,18 @@ type ActionExecutionLogResponse = {
    * Creation timestamp
    */
   inserted_at?: string;
+  /**
+   * How many times the job has been attempted. `0` means it has not run yet.
+   */
+  readonly job_attempt?: number | null;
+  /**
+   * When the job will next be attempted. Equal to `scheduled_at` until something moves it; a snoozing job carries the instant it wakes.
+   */
+  readonly job_next_attempt_at?: string | null;
+  /**
+   * State of the job carrying this action — one of `available`, `scheduled`, `executing`, `retryable`, `completed`, `discarded`, `cancelled`. Null when no job carries it.
+   */
+  readonly job_state?: string | null;
   /**
    * Rendered message body for this action (mode-driven; null when no message was sent)
    */
@@ -441,7 +453,7 @@ type CloudWatchLogGroupResponse = {
   auth_method: 'access_key' | 'iam_role' | 'assume_role';
   base_filter_pattern?: ComplexTemplateConfigResponse | null;
   /**
-   * Custom CloudWatch Logs endpoint URL (e.g., http://localhost:4566 for LocalStack)
+   * Custom CloudWatch Logs endpoint URL (e.g., http://localhost:4566 for MiniStack)
    */
   endpoint_url?: string | null;
   /**
@@ -878,7 +890,7 @@ type ExecuteActionRequest = {
    */
   mode?: 'live' | 'dry_run';
   /**
-   * When true, the action's `trigger_template` schedule is bypassed and the queued job is dispatched immediately. The ActionExecutionLog still records the trigger-rendered `scheduled_at` — only the Oban job is fast-forwarded. Use this to force a future-triggered action (e.g. a year-roll birthday SMS) to fire now, which is the only way to drive such a workflow to completion inside a live test or cookbook run.
+   * When true, the action's `trigger_template` schedule is bypassed and the queued job is dispatched immediately. The ActionExecutionLog still records the trigger-rendered `scheduled_at` — only the Oban job is fast-forwarded. Use this to force an action whose trigger renders a future instant (e.g. a year-roll birthday SMS) to fire now, which is the only way to drive such a workflow to completion inside a live test or cookbook run. An action whose trigger renders a past instant does not need it: a past `scheduled_at` is staged on the next pass and runs on its own.
    */
   trigger_override?: boolean;
 };
@@ -2568,17 +2580,17 @@ type DatalakeResponse = {
    */
   db_reader_enable_ssl: boolean;
   /**
-   * Reader DB host
+   * Reader DB host. Null while a derived lake's database is still being provisioned
    */
-  db_reader_host: string;
+  db_reader_host: string | null;
   /**
    * Reader DB name
    */
   db_reader_name: string;
   /**
-   * Reader DB port
+   * Reader DB port. Null while a derived lake's database is still being provisioned
    */
-  db_reader_port: number;
+  db_reader_port: number | null;
   /**
    * Reader DB schema name
    */
@@ -2592,17 +2604,17 @@ type DatalakeResponse = {
    */
   db_writer_enable_ssl: boolean;
   /**
-   * Writer DB host
+   * Writer DB host. Null while a derived lake's database is still being provisioned
    */
-  db_writer_host: string;
+  db_writer_host: string | null;
   /**
    * Writer DB name
    */
   db_writer_name: string;
   /**
-   * Writer DB port
+   * Writer DB port. Null while a derived lake's database is still being provisioned
    */
-  db_writer_port: number;
+  db_writer_port: number | null;
   /**
    * Writer DB schema name
    */
@@ -2642,7 +2654,7 @@ type DatalakeResponse = {
   /**
    * Datalake setup status
    */
-  readonly status?: 'new' | 'processing' | 'ready';
+  readonly status?: 'provisioning' | 'new' | 'processing' | 'ready';
   tenant?: TenantResponse;
   /**
    * Datalake reporting timezone. Closed whitelist of 8 US timezones — general IANA values (including `UTC`) are rejected.
@@ -2685,6 +2697,10 @@ type AlveraApiError = {
      */
     title: string;
   }>;
+  /**
+   * Which derived copy failed to provision — `tokenized` or `redacted`. `null` on every other structured error, which is why it is not required. Without it a client is told a copy of the pair failed but not which one, and a copy is repaired one mode at a time.
+   */
+  mode?: string | null;
 };
 /**
  * CloudStorageAwsResponse
@@ -3216,7 +3232,7 @@ type SnsResponse = {
   auth_method: 'access_key' | 'iam_role' | 'assume_role';
   base_message?: ComplexTemplateConfigResponse | null;
   /**
-   * Custom SNS endpoint URL (e.g., http://localhost:4566 for LocalStack); leave blank for real AWS
+   * Custom SNS endpoint URL (e.g., http://localhost:4566 for MiniStack); leave blank for real AWS
    */
   endpoint_url?: string | null;
   /**
@@ -3561,12 +3577,16 @@ type WorkflowLogResponse = {
    * Completed action count
    */
   actions_completed?: number;
+  /**
+   * Actions that have started and not finished. A run showing `actions_pending: 1, actions_executing: 0` is waiting to be picked up; one showing `actions_pending: 1, actions_executing: 1` is mid-flight and may be stuck.
+   */
+  actions_executing?: number;
   /**
    * Failed action count
    */
   actions_failed?: number;
   /**
-   * Pending action count
+   * Unfinished action count — actions still queued plus actions already running. `actions_executing` is the running share of it.
    */
   actions_pending?: number;
   /**
@@ -3930,6 +3950,14 @@ type TwilioRequest = {
    * Twilio Account SID (required on a primary; supplied by the primary on a variant)
    */
   account_sid?: string | null;
+  /**
+   * Twilio API Key SID (required when auth_method is api_key)
+   */
+  api_key_sid?: string | null;
+  /**
+   * How this primary authenticates to Twilio. Defaults to auth_token.
+   */
+  auth_method?: 'auth_token' | 'api_key';
   base_message?: ComplexTemplateConfigRequest;
   /**
    * Custom Twilio API base URL (e.g., http://localhost:8080 for WireMock); leave blank for https://api.twilio.com
@@ -4589,6 +4617,14 @@ type TwilioResponse = {
    * Twilio Account SID (required on a primary; supplied by the primary on a variant)
    */
   account_sid?: string | null;
+  /**
+   * Twilio API Key SID (required when auth_method is api_key)
+   */
+  api_key_sid?: string | null;
+  /**
+   * How this primary authenticates to Twilio. Defaults to auth_token.
+   */
+  auth_method?: 'auth_token' | 'api_key';
   base_message?: ComplexTemplateConfigResponse | null;
   /**
    * Custom Twilio API base URL (e.g., http://localhost:8080 for WireMock); leave blank for https://api.twilio.com
@@ -4643,9 +4679,9 @@ type DatalakeRequestWritable = {
    */
   db_reader_enable_ssl: boolean;
   /**
-   * Reader DB host
+   * Reader DB host. Null while a derived lake's database is still being provisioned
    */
-  db_reader_host: string;
+  db_reader_host: string | null;
   /**
    * Reader DB name
    */
@@ -4655,9 +4691,9 @@ type DatalakeRequestWritable = {
    */
   db_reader_pass: string;
   /**
-   * Reader DB port
+   * Reader DB port. Null while a derived lake's database is still being provisioned
    */
-  db_reader_port: number;
+  db_reader_port: number | null;
   /**
    * Reader DB schema name
    */
@@ -4675,9 +4711,9 @@ type DatalakeRequestWritable = {
    */
   db_writer_enable_ssl: boolean;
   /**
-   * Writer DB host
+   * Writer DB host. Null while a derived lake's database is still being provisioned
    */
-  db_writer_host: string;
+  db_writer_host: string | null;
   /**
    * Writer DB name
    */
@@ -4687,9 +4723,9 @@ type DatalakeRequestWritable = {
    */
   db_writer_pass: string;
   /**
-   * Writer DB port
+   * Writer DB port. Null while a derived lake's database is still being provisioned
    */
-  db_writer_port: number;
+  db_writer_port: number | null;
   /**
    * Writer DB schema name
    */
@@ -5485,7 +5521,7 @@ type CloudWatchLogGroupRequestWritable = {
   auth_method: 'access_key' | 'iam_role' | 'assume_role';
   base_filter_pattern?: ComplexTemplateConfigRequest;
   /**
-   * Custom CloudWatch Logs endpoint URL (e.g., http://localhost:4566 for LocalStack)
+   * Custom CloudWatch Logs endpoint URL (e.g., http://localhost:4566 for MiniStack)
    */
   endpoint_url?: string | null;
   /**
@@ -5521,7 +5557,7 @@ type SnsRequestWritable = {
   auth_method: 'access_key' | 'iam_role' | 'assume_role';
   base_message?: ComplexTemplateConfigRequest;
   /**
-   * Custom SNS endpoint URL (e.g., http://localhost:4566 for LocalStack); leave blank for real AWS
+   * Custom SNS endpoint URL (e.g., http://localhost:4566 for MiniStack); leave blank for real AWS
    */
   endpoint_url?: string | null;
   /**
@@ -6000,6 +6036,18 @@ type TwilioRequestWritable = {
    * Twilio Account SID (required on a primary; supplied by the primary on a variant)
    */
   account_sid?: string | null;
+  /**
+   * Twilio API Key Secret (required when auth_method is api_key)
+   */
+  api_key_secret?: string | null;
+  /**
+   * Twilio API Key SID (required when auth_method is api_key)
+   */
+  api_key_sid?: string | null;
+  /**
+   * How this primary authenticates to Twilio. Defaults to auth_token.
+   */
+  auth_method?: 'auth_token' | 'api_key';
   /**
    * Twilio Auth Token (required on a primary; supplied by the primary on a variant)
    */