@alvera-ai/platform-sdk 0.16.2 → 0.17.0

package/.agent/AGENTS.md

@@ -576,6 +576,13 @@ of restating:
 | Async + readiness                             | `async.md`       |
 | Debugging (HTTP interceptor + safe redaction) | `debugging.md`   |
 | Type naming + server-derived fields           | `type_naming.md` |
+| Local mock surfaces (WireMock / LocalStack)   | `mock-services.md` |
+
+`mock-services.md` answers the local-development questions the other
+pages assume away: how the platform reaches mocked third-party APIs on
+a laptop, the `endpoint_url` override on the sender tools, and why End
+User Messaging points at WireMock rather than LocalStack. It is fetched
+from the platform-metadata channel, not authored here.
 
 ## Just getting started?
 

package/.agent/messages.md

@@ -36,19 +36,28 @@ alias: `rm`.
 ## 1. The status lifecycle — and who writes each hop
 
 ```
-   pending → queued → sent → delivered
-                        └──→ failed  (+ failure_reason)
+   pending → accepted → queued → sending → sent → delivered
+                                             └──→ failed  (+ failure_reason)
 
-   also: invalidated  (idempotency rejected a duplicate)
+   also: duplicate    (provider id already held by another send —
+                       the send HAPPENED; terminal, never retried)
+         invalidated  (idempotency key collision — the fire was
+                       rejected, nothing went out)
          received     (inbound message, direction: 'inbound')
          clicked      (link in the message was clicked)
 ```
 
+`accepted` (the provider took the send request) and `sending`
+(dispatching to the carrier) are intermediate hops between `pending`
+and `sent`; the order above is the order the contract declares them.
+Treat any of them as "in flight, outcome unknown" — see **Status is
+eventually honest** below.
+
 Three different writers touch a message row. Know which is which:
 
 | Writer | Writes | When |
 |---|---|---|
-| the action executor | the row itself; `pending`→`sent`, `external_id`, `sent_at` | at execution (writes the row at `pending`; advances to `sent` + sets `external_id` only on a live tool call — a dry-run stops at `pending`) |
+| the action executor | the row itself; `pending`→`sent`, `external_id`, `sent_at`; also `duplicate` | at execution (writes the row at `pending`; advances to `sent` + sets `external_id` only on a live tool call — a dry-run stops at `pending`). Lands `duplicate` when the provider id it got back is already held by another send through the same tool |
 | the action status updater | `delivered` / `failed`, `delivered_at`, `failure_reason` | later, when its poll runs (see `action_status_updaters.md` §7) |
 | `connectedApps.updateMessageTracking` | `opened_at`, `form_submitted_at` — **never `status`** | when the recipient opens/submits the magic-link page |
 
@@ -63,6 +72,34 @@ Two consequences:
   delivered nor failed yet. A UI should show that in-between state,
   not guess.
 
+### `failed` vs `duplicate` — never retry the second
+
+These are **not** interchangeable, and the difference decides whether
+a row is safe to re-send:
+
+| | `failed` | `duplicate` |
+|---|---|---|
+| provider id | none was ever returned | one came back, but another send through the same tool already holds it |
+| did anything go out? | no | **yes — the send happened** |
+| retryable? | yes | **no** — never retried, never re-sent |
+
+So a "retry everything that didn't reach `delivered`" sweep is wrong:
+it must select on `failed`, never on "not delivered". Re-sending a
+`duplicate` sends a second real message to a recipient who already
+got one.
+
+One consequence worth internalising: **the send path never records a
+message that has an `external_id` as `failed`.** Once a provider id
+comes back, the row stays `pending` until the delivery poller
+resolves it. `failed` therefore means "nothing left the building",
+not "we don't know yet".
+
+`invalidated` is a third, separate thing — an idempotency-key
+collision rejected the fire before it went out (see `idempotency_key`
+in §2). Do not read the word "duplicate" in that context as the
+`duplicate` status: `invalidated` means nothing was sent,
+`duplicate` means something was.
+
 ## 2. Fields
 
 Identity + routing:
@@ -98,8 +135,10 @@ Provenance (which workflow produced this):
 ```
 workflow_id, action_id, decision_key, context_key,
 idempotency_key            — unique per (mdm_subject_id,
-                             idempotency_key); a duplicate fire
-                             lands as status 'invalidated'
+                             idempotency_key); a repeat fire on the
+                             same key lands as status 'invalidated'
+                             (nothing sent) — NOT status 'duplicate',
+                             which means a send did go out
 sender_tool_id
 ```
 

package/.agent/mock-services.md

@@ -0,0 +1,192 @@
+# Mock Services
+
+<!-- MDOC !-->
+
+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.
+
+## The two surfaces
+
+**WireMock** (`wiremock/wiremock:3.10.0`) serves the stub corpus in
+`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.
+
+**LocalStack** 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
+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.
+
+## The corpus
+
+Counted on `release/0.23.0` — 16 files, 98 stubs. The feature mix is what makes
+WireMock itself load-bearing rather than incidental:
+
+| Feature | Uses | What it does |
+|---|---:|---|
+| `urlPathPattern` | 80 | Regex path matching |
+| `jsonBody` / `body` / `base64Body` | 85 | Inline response bodies |
+| `bodyFileName` | 21 | Bodies served from `wm_response_files/` |
+| `bodyPatterns` | 11 | Request-body matching |
+| `queryParameters` | 9 | Query matching |
+| `scenarioName` + `newScenarioState` | 7 | **Stateful scenarios — a state machine across requests** |
+| `--global-response-templating` | on | Handlebars templating in responses |
+
+The last two rows are why the corpus is served by the real WireMock image
+everywhere rather than by a bespoke matcher. Reimplementing stateful scenarios
+and a templating engine means re-earning fidelity, and a gap in a mock surfaces
+as a test passing against a fiction rather than as a failure.
+
+### Two gotchas that cost real time
+
+**WireMock rejects unknown keys on a stub mapping.** A stray `_comment` field
+makes it refuse to load the *whole file* and 404 everything in it, while
+`json.load` and any JSON linter pass it happily. Put prose in the free-form
+`metadata` object instead.
+
+**WireMock loads mappings at boot.** After editing `wm_mappings/`, reload the
+local container without restarting it:
+
+```bash
+curl -X POST http://localhost:8080/__admin/mappings/reset
+```
+
+That is the first thing to try when a stub 404s locally. It is not available on
+the hosted instance — see below.
+
+## Running locally
+
+`make run-backing-services` starts both. WireMock listens on `:8080`, LocalStack
+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
+after one:
+
+```bash
+AWS_ACCESS_KEY_ID=test AWS_SECRET_ACCESS_KEY=test AWS_DEFAULT_REGION=us-east-1 \
+  aws s3 mb s3://healthcare-lake-regulated --endpoint-url http://localhost:4566
+```
+
+## The hosted mock — `wiremock.alvera.ai`
+
+Deployed environments used to need their own always-on WireMock, which is the
+wrong billing shape for a service that is idle almost all of the time. The corpus
+now runs on Cloudflare Containers behind one hostname, billed only while awake.
+
+```mermaid
+flowchart TD
+    C["Consumers<br/>platform dev · UAT · integration-tests · CI"]
+    C -->|"https://wiremock.alvera.ai"| W
+
+    subgraph CF["Cloudflare"]
+        F["WAF custom rule<br/>/__admin → Block"]
+        W["Worker + Durable Object<br/>container binding"]
+        K["Container — basic<br/>wiremock/wiremock:3.10.0<br/>/mappings ◀ wm_mappings/<br/>/__files ◀ wm_response_files/"]
+        F -.->|"blocks before the Worker runs"| W
+        W -->|fetch| K
+    end
+```
+
+**It lives in this repo**, at `mock-edge/`. Deploy from a normal checkout:
+
+```bash
+cd mock-edge && wrangler deploy
+```
+
+The single line that makes this work without a vendored copy of the corpus:
+
+```jsonc
+"image_build_context": ".."
+```
+
+That sets the Docker build context to the repo root, so the Dockerfile copies
+`wm_mappings/` and `wm_response_files/` from where they already live. Without it
+the context is `mock-edge/` and the corpus would have to be duplicated there —
+two directories that look identical until they quietly aren't.
+
+### There is no authentication
+
+The hostname is public and deliberately so. The corpus is synthetic fixture data,
+the mock authenticates nobody, and a gate in front of it caused more problems
+than it solved:
+
+- Nineteen of the 98 stubs match on the `Authorization` header, because they
+  assert the *tool* authenticated to the API being mocked. Cloudflare Access
+  consumes `Authorization` for its own credential, so gating on that header made
+  those nineteen stubs stop matching.
+- Any gate means a credential per consumer, which means minting, distributing,
+  rotating and revoking — for a service whose contents are fixtures.
+
+The accepted risk is bot traffic waking the container. Workers include 10 million
+requests a month before any charge, so the exposure is container time, not
+request volume — and it is small enough to deal with if it ever shows up.
+
+### The admin API is blocked
+
+WireMock's admin API has no authentication of its own: anything that can reach
+`/__admin` can read the request journal, reset scenarios, or reprogram stubs.
+Publicly hosted, that surfaces as CI failing for no visible reason. A WAF custom
+rule on the zone refuses it:
+
+```
+(http.host eq "wiremock.alvera.ai" and http.request.uri.path contains "/__admin")  →  Block
+```
+
+Scoped by `http.host` so it cannot affect the other services on `alvera.ai`.
+Cloudflare normalises the URL before evaluating rules, so `/%5f%5fadmin` and
+`//__admin` are blocked too — verified, not assumed.
+
+> #### The block is safe *because* the corpus is baked {: .warning}
+>
+> Stubs live in the image. Nothing registers them at runtime, so nothing needs
+> the admin API in production. **If that ever changes — if an app wants to
+> register stubs at runtime — this rule must be reconsidered, not worked
+> around.** It would also need `max_instances: 1` and a fixed container name,
+> because registrations do not survive an instance sleeping or a request landing
+> on a different instance.
+
+### Adding or changing a stub
+
+Edit `wm_mappings/` (or `wm_response_files/`), then redeploy. There is no hot
+reload on the hosted instance — the image is the state, which makes the hosted
+mock immutable per deploy and reproducible for CI.
+
+### Verifying the hosted mock matches local
+
+The failure worth catching is the two environments quietly disagreeing. Compare
+them by hashing responses rather than asserting content, so the check does not
+break when someone edits a stub — only when local and edge diverge:
+
+```bash
+for base in http://localhost:8080 https://wiremock.alvera.ai; do
+  curl -s -X POST -H 'content-type: application/json' -d '{"contents":[]}' \
+    "$base/gemini/v1beta/models/gemini-2.0-flash:generateContent" | shasum -a 256
+done
+```
+
+The gemini stubs are the sharpest test: they use a seven-state scenario, so three
+identical POSTs return three *different* bodies in a fixed order. Matching hashes
+across three successive calls proves both environments walked the same state
+machine — something no stateless matcher could fake.
+
+## LocalStack 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
+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
+flip.
+
+## Related
+
+- [Tools](tools.md) — tool bodies, `endpoint_url`, and REST API auth methods
+- [Datalakes](datalakes.md) — how datalake provisioning uses LocalStack
+- [Connected Apps](connected_apps.md) — the third-party integrations the corpus stands in for

package/.agent/tools.md

@@ -257,11 +257,12 @@ Each branch has its own required-list. Common patterns:
                             OR (iam_role)
                             OR (assume_role_arn +
                                 assume_role_external_id);
-                              optional endpoint_url (overrides the End
-                              User Messaging API endpoint) and
-                              media_endpoint_url (overrides the S3
-                              media-staging endpoint; blank ⇒ S3
-                              derived from the tool's region)
+                              optional endpoint_url (ONE override,
+                              covering everything the tool reaches:
+                              the SendMediaMessage send, S3 media
+                              staging, and the save-time credential
+                              probe; blank ⇒ each service resolves to
+                              its own regional AWS host)
 
    sql_database body        db_type, db_host, db_port, db_name,
                               auth_method, db_username,
@@ -283,6 +284,45 @@ The full per-branch shape lives in
 `packages/sdk/src/generated/types.gen.ts` under the matching
 `Tool<Type>BodyWritable` types.
 
+### Authoring an End User Messaging tool locally — every auth method works
+
+`endpoint_url` is one override for the whole tool. Point it at a local
+AWS-compatible stub and the send, the media staging, and the
+save-time credential probe all follow it; leave it blank and each
+service resolves to its own regional AWS host. There is no second
+endpoint field — `media_bucket` names a bucket, not a host.
+
+All three auth methods can be authored locally **and** against real
+AWS. They do not all reach the same host, and are not meant to:
+
+```
+   auth_method    endpoint_url set (local)        endpoint_url blank
+   ───────────────────────────────────────────────────────────────────
+   access_key     everything → your stub          everything → AWS
+   iam_role       everything → your stub, but     everything → AWS
+                    the credential itself still
+                    comes from the platform's
+                    ambient chain
+   assume_role    send + staging → your stub;     everything → AWS
+                    the STS AssumeRole leg is
+                    NOT tool-steered (below)
+```
+
+**Why `assume_role` deliberately splits.** That STS request is signed
+with the **platform's own** ambient credentials — your role trusts a
+platform identity, and the tool contributes only `assume_role_arn`
+(the role in YOUR account) and `assume_role_external_id`. Letting a
+tool field steer it would send a live SigV4 signature made with the
+platform task role to a host the tool's author picked. So the STS
+endpoint is a per-deployment constant, resolved by the platform, and
+`assume_role` is the one auth method where the tool does not choose
+it. This is by design — not a gap, and not a reason to prefer another
+auth method when authoring locally.
+
+If a local `assume_role` save is reaching real STS when you expected a
+stub, that is the platform deployment's own STS configuration, not the
+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`

package/dist/index.d.mts

@@ -991,7 +991,7 @@ type ResolvePageResponse = {
     /**
      * Delivery status
      */
-    status: 'pending' | 'queued' | 'sent' | 'delivered' | 'read' | 'opened' | 'clicked' | 'form_submitted' | 'failed' | 'invalidated' | 'customer_rejected' | 'dry_run' | 'received';
+    status: 'pending' | 'accepted' | 'queued' | 'sending' | 'sent' | 'delivered' | 'read' | 'opened' | 'clicked' | 'form_submitted' | 'failed' | 'invalidated' | 'duplicate' | '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)
      */
@@ -1943,7 +1943,7 @@ type UpdatePageResponse = {
     /**
      * 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';
+    status?: 'pending' | 'accepted' | 'queued' | 'sending' | 'sent' | 'delivered' | 'read' | 'opened' | 'clicked' | 'form_submitted' | 'failed' | 'invalidated' | 'duplicate' | 'customer_rejected' | 'dry_run' | 'received';
   };
 };
 /**
@@ -2322,10 +2322,6 @@ type EndUserMessagingResponse = {
    * 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
    */
@@ -4845,10 +4841,6 @@ type EndUserMessagingRequestWritable = {
    * 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
    */