@on-belay/sdk 2.2.0 → 3.0.0

package/CHANGELOG.md

@@ -0,0 +1,246 @@
+# Changelog — `@on-belay/sdk`
+
+## 3.0.0 — 2026-08-23
+
+**A major version by semver, with near-zero real migration work.** Two exported functions
+are gone and 24 change arity, which is unambiguously major — but the 23 are helpers that
+**404 on every call in 2.2.1**, so no working code depends on their current shape. If your
+fieldset compiles against 2.2.1 today and does not call an Acumatica detail helper, it
+compiles against 3.0.0 unchanged.
+
+### Why this release exists
+
+`scripts/generate-integration-helpers.ts` imported only `prisma/operation-defs-part1` and
+`-part2`, by name, while the operation catalog had grown to `part15` — so 330 operations
+across 15 integrations were unreachable by construction. On top of that, the generator had
+not been run in full since **2026-05-11** (SDK 2.2.0), so even operations added to part1 and
+part2 after that date never reached the package. `shopmonkey.listInventoryParts` below is one
+of those: it was catalogued on 2026-08-20 in *part2*, a file the generator did read.
+
+Both gaps were invisible for the same reason: nothing compared the generated output to the
+catalog. The only changes the generated directory received in those three months were two
+single-file **hand-edits** (#825, #1059) to files whose header says
+*"AUTO-GENERATED — do not edit by hand"*. Both happen to survive this regeneration — the
+`get_video_analytics` deletion because its catalog row was deleted too, and the
+`ShopifySlug` narrowing because it was folded into the generator — but that was luck, and
+nothing was checking.
+
+| | 2.2.1 | 3.0.0 |
+|---|---:|---:|
+| Operations exposed | 941 | **1,547** |
+| Integration modules | 75 | **110** |
+
+### Added — 608 helpers, 35 new integration modules
+
+`air`, `airtable`, `amazon-ads`, `applovin`, `box`, `celigo`, `cloudflare`, `cloudinary`,
+`feishu`, `gemini`, `gooddata`, `google-business-profile`, `impact`, `instagram-insights`,
+`instagram-public`, `judge-me`, `knocommerce`, `linkedin-pages`, `magento`, `microsoft-ads`,
+`mixpanel`, `okta`, `openai-ads`, `pinterest-organic`, `railway`, `rippling`, `salsify`,
+`semrush`, `sharepoint`, `shopmy`, `smile-io`, `teachable`, `tiktok-organic`,
+`transcriptapi`, `web-search`, `windsor`.
+
+440 of the 606 net-new helpers are in those 35 modules; the other 166 landed on modules that
+already existed. Two examples of what the gap cost in practice:
+
+- **`shopmonkey.listInventoryParts`** (`/v3/inventory_part`). A production fieldset
+  hand-rolled a raw `executeProxyCall` around this, with the comment *"the SDK exposes only
+  a generic `listInventory` (→ /v3/inventory); the spec's op is `list_inventory_parts`
+  (→ /v3/inventory_part)"* — `owl-shopmonkey-import/src/lib/inventory-resolve.ts:233`. It is
+  a typed helper now, and that workaround can be deleted.
+- **`amazonSeller.pullConnector`** (`/amazon_sp`). The only Amazon operation that returns
+  real Amazon data. The SDK previously exposed ten Amazon operations that the proxy silently
+  rewrites to Windsor aggregates, and not this one.
+
+### Fixed — 23 Acumatica helpers built a malformed URL and 404'd on every call
+
+`analyzePathPattern` converts a regex `pathPattern` into a template literal. A trailing bare
+character class with no quantifier — Acumatica's `[^?/]` — matched none of its substitutions,
+so `split("/")` sheared the class and the emitted path ended in the literal text `[^`.
+
+```
+2.2.1   /entity/Default/${defaultId}/SalesOrder/[^
+3.0.0   /entity/Default/${endpointVersion}/SalesOrder/${salesOrderId}
+```
+
+This shipped: `npm unpack @on-belay/sdk@2.2.1` shows the leaked `[^` in `dist/index.js`.
+Affected every detail fetch/update/delete across `SalesOrder`, `Customer`, `Vendor`,
+`StockItem`, `NonStockItem`, `PurchaseOrder`, `Invoice`, `Payment`, `Contact`, `Employee`,
+`GeneralLedgerTransaction`, `Account`, `Bill`.
+
+**Each of these helpers now takes one more argument** — the resource key that used to be
+`[^`. That is the breaking change, and it is the fix.
+
+Also fixed: `sharepoint.searchDrive` emitted `/root/searchq='[^']*'` instead of
+`/root/search(q='${param1}')`. New in this release, so nothing depended on the broken form.
+
+### Fixed — 14 Google helpers dropped the `:action` suffix from the path
+
+`ga4.run_report.*`, `gemini.generateContent`, `gemini.streamGenerateContent`,
+`gemini.embedContent`, `gemini.countTokens` and others emitted the resource path with the
+action suffix **missing**:
+
+```
+2.2.1   /v1beta/properties/${propertyId}
+3.0.0   /v1beta/properties/${propertyId}:runReport
+```
+
+A path segment that merely *contained* the parameter placeholder was being collapsed down
+to the placeholder, so anything else in that segment was thrown away. Unlike the Acumatica
+case this leaves nothing regex-shaped behind, so it is invisible to a "did any regex
+punctuation survive?" check — the path is simply, silently, a different endpoint. Our own
+proxy rejects it too, because the proxy validates the request path against the same
+`pathPattern`.
+
+The same collapse was dropping the literal `v` from version segments, so 27 Google Ads and
+Salesforce helpers emitted `/${version}/…` where the API needs `/v18/…`. Now
+`/v${version}/…`.
+
+### Fixed — a regex quantifier ate a parameter
+
+`judgeMe.getProduct` emitted the literal path `/products/-`. Its pattern is
+`^/products/-?\d+`; the parameter was substituted, then the query-string strip cut from the
+`-?` quantifier onward and took the parameter with it. Now `/products/${productId}` — and
+the helper takes the `productId` argument it always should have.
+
+### Fixed — 10 helpers were unparseable TypeScript
+
+44 catalog keys are dotted (`shopify.themes.list`, `ga4.run_report.overall`). The generator
+left the dots in the function name, emitting `export async function shopify.themes.list<T>(`.
+Ten such keys were already reachable, so the generator produced a file that would not parse.
+Identifiers are now sanitized (`shopifyThemesList`); the dotted string is unchanged as the
+operation key sent to the proxy.
+
+### Not changed — Shopify REST paths still omit `.json`
+
+Unchanged from 2.2.1. Recorded because it was changed and reverted twice during review, and
+the reasoning is worth having in one place.
+
+```
+2.2.1 and 3.0.0   /admin/api/{version}/orders
+catalog pattern   ^/admin/api/[^/]+/orders\.json      ← requires .json
+```
+
+**Your calls are not failing.** Shopify accepts both forms — 154 json-less `/admin/api/`
+calls over 30 days, **every one status 200**, zero failures. And the platform check that
+*would* reject a json-less path is unreachable from a fieldset: it runs only for
+group-access callers with an enforcing grant, and fieldset tokens never take that branch.
+
+⚠️ **The argument for the other choice, stated fairly:** all 17 of the catalog's
+hand-curated Shopify `/admin/api/` `examplePath` values carry `.json`. That is real, and it
+is why this flipped once. It was judged **documentation** divergence rather than evidence of
+breakage — a 55-path behaviour change needs a functional reason, and there is none for this
+package's consumers. Those 17 appear in `PATH-DIVERGENCE.json` as expected entries.
+
+### Changed — caller-supplies-the-path operations now take that path as a parameter
+
+Three patterns are bare prefixes rather than fixed endpoints. `shopify.admin.fetch` says so
+in its own description — *"The path is chosen by the caller, so this operation is broad"* —
+and its example is `/admin/api/2026-01/shop.json`. The generator emitted the prefix with no
+parameter, so the helper could not reach any resource:
+
+```
+2.2.1   shopifyAdminFetch(orgId, slug, options)          → /admin/api/2024-01
+3.0.0   shopifyAdminFetch(orgId, slug, resourcePath, …)  → /admin/api/2026-01/${resourcePath}
+```
+
+5 operations: `shopify.admin.fetch`, github `get_file_contents` / `create_update_file`,
+cloudinary `get_asset` / `delete_asset`. All five are new in 3.0.0 except
+`shopify.admin.fetch`, whose 2.2.1 form could not be used for anything.
+
+### Known — 5 operations emit a path their pattern rejects, and are still shipped
+
+`gmail.searchMessages`, `youtube.getVideo`, `googleDrive.downloadFile`,
+`microsoftTeams.listTeams`, `yotpo.getProductReviews`. Their patterns bake a
+**caller-supplied query value** into the path (`\?q=`, `\?.*id=`, `\?alt=media`, `\?.*resourceProvisioningOptions`), which a path
+template cannot express.
+
+**They are shipped, deliberately.** `youtube.getVideo` emits `/youtube/v3/videos` and that
+exact path has **3 live 200s** in the last 90 days — pass the id in `queryParams`. An earlier
+draft of this release omitted several of these; that was reverted. The patterns are
+over-specified, and loosening them is a catalog change tracked separately.
+
+All divergences are listed in `src/integrations/PATH-DIVERGENCE.json`.
+
+### Fixed — Shopify Admin API version was `2024-01`
+
+Over a year past Shopify's end-of-life for that version. Now `2026-01`, read from the
+platform's own `SHOPIFY_API_VERSION` constant at generate time so the two cannot drift.
+
+### Breaking changes — complete list
+
+**27 changes require a caller to change code. 24 of them are path fixes.**
+
+| Change | Count | Source |
+|---|---:|---|
+| Acumatica detail helpers take one more argument | 22 | **This release** — the 404 fix |
+| `github.getFileContents` / `createUpdateFile` take a `resourcePath` argument | 2 | **This release** — the bare-prefix fix |
+| `shopify.getAnalyticsReport`: `options.queryParams` → `options.body` | 1 | Catalog |
+| `shopmonkey.getOrderFees` removed | 1 | Catalog |
+| `shopmonkey.listInventory` removed | 1 | Catalog |
+
+The last three are **catalog-driven, not authored in the SDK** — upstream operation
+definitions changed and the SDK had simply not been regenerated since. `getAnalyticsReport`
+moved because Shopify **deleted** the REST `reports.json` resource, so the operation is a
+GraphQL POST now. Both `shopmonkey` keys were deleted from the catalog because the endpoints
+no longer exist; `/v3/order/{id}/fee` 404s.
+
+**41 parameters were renamed. These are not breaking for positional calls** — arity and
+types are unchanged, and every helper is called positionally. They are corrections to names
+a developer would otherwise trust and get wrong:
+
+- `defaultId` → `endpointVersion` (Acumatica). The segment after `/entity/Default/` is the
+  endpoint *version* — `Default` is the endpoint *name* — so the old name read as an
+  identifier of something called Default.
+- `salesorderId` → `salesOrderId`, `inventoryitemId` → `inventoryItemId`,
+  `generalledgertransactionId` → `generalLedgerTransactionId`, `localpostId` → `localPostId`,
+  and similar across `acumatica`, `netsuite`, `linkedin-ads`, `gooddata`,
+  `google-business-profile`. Names were being derived from a lowercased string, collapsing
+  the word boundaries.
+- `accountId` → `adAccountId` on six `redditAds` helpers (catalog-driven).
+
+### Known affected consumers: none
+
+`owl-shopmonkey-import` is the only external consumer. It pins `^2.2.0`, so it will **not**
+pick up 3.0.0 automatically, and it calls none of the removed or changed helpers — verified
+against its source: it uses `shopify.listInventoryLevels` and raw `executeProxyCall`.
+
+### Guardrails added, so this cannot recur silently
+
+- The generator reads `prisma/operation-defs.ts` — the same aggregate seeded into the live
+  `IntegrationOperation` table — and **fails loudly** if any `operation-defs-part*.ts` file
+  on disk holds operations the aggregate does not carry. A future `part16` that nobody wires
+  in aborts the run and names the missing keys.
+- **A path-divergence report.** After conversion, a value is substituted for every
+  `${param}` and the concrete path is tested against the source `pathPattern`. Mismatches
+  are written to a committed `src/integrations/PATH-DIVERGENCE.json` and the set is **pinned
+  by the test suite**, so it cannot grow unnoticed. Current run: **1,547 of 1,547 emitted,
+  0 omitted, 64 divergences recorded.**
+  🚫 It is deliberately **not** a gate. It was one, briefly, and as a gate it removed 55
+  working Shopify helpers plus `youtube.getVideo` — whose "broken" path has three live
+  200s. A divergence says the template and the pattern disagree; it does not say which is
+  wrong.
+- Colliding helper names, module filenames, or barrel namespaces abort the run instead of
+  silently shadowing.
+- CI asserts the generated output matches the catalog exactly, in both directions, plus
+  identifier validity, barrel uniqueness, regression pins on each non-trivial path idiom,
+  and the Shopify version mirror. The staleness that hid these operations for three months
+  is now a red build, not a silence.
+- ⚠️ **The divergence check replaced an earlier "no regex punctuation survived" check,
+  which was blind in both directions** and is the reason three defect classes in this
+  release shipped in 2.2.1 at all. A *dropped* literal leaves nothing regex-shaped behind
+  (`:runReport` vanishing passed it cleanly), and `?` is both regex punctuation and an
+  ordinary URL character (so google_drive's correct path was refused). The round-trip
+  subsumes it and needs no list of known idioms, so a shape nobody has seen yet is still
+  caught.
+- **The examplePath check is the primary path signal.** 616 ops carry a hand-curated
+  `examplePath`; the test asserts every emitted template can produce its own. It caught what
+  nothing else could — `shopify.admin.fetch`'s bare prefix passed the pattern round-trip,
+  because a prefix pattern matches trivially. Three blind spots in sequence: punctuation
+  missed deletions, the round-trip missed under-specification, the example caught it.
+  **17 known mismatches**, pinned: 15 shopify + 1 yotpo are the deliberate json-less form
+  above, and 1 is `cloudinary.uploadAssetRemote`, where the pattern is a 4-way alternation
+  (`^/(image|video|auto|raw)/upload`) collapsed to the first option.
+- Real path defects are pinned by tests that encode what the **upstream API** requires,
+  not agreement with a regex: the `:action` suffix and `v` version literal (28,142 live
+  google_ads calls, 100% carrying both), acumatica's sheared character class, and
+  judge_me's `/products/-`. Evidence about the API is the authority — a pattern is not.

package/README.md

@@ -4,7 +4,7 @@ Build a fieldset that runs on the [On Belay](https://app.onbelay.ai) governance
 
 [![npm](https://img.shields.io/npm/v/@on-belay/sdk)](https://www.npmjs.com/package/@on-belay/sdk)
 
-`@on-belay/sdk@2.0.0` is the HTTP-only contract between the On Belay platform and an external fieldset (a Node service you write and host). The platform calls your service over a signed webhook on a schedule; you call the platform back through `/api/sdk/*` to reach connected integrations on behalf of enrolled orgs. No platform internals are imported. No customer credentials live in your code. Node 20+, one runtime dependency (`jose`).
+`@on-belay/sdk` is the HTTP-only contract between the On Belay platform and an external fieldset (a Node service you write and host). The platform calls your service over a signed webhook on a schedule; you call the platform back through `/api/sdk/*` to reach connected integrations on behalf of enrolled orgs. No platform internals are imported. No customer credentials live in your code. Node 20+, one runtime dependency (`jose`).
 
 ---
 
@@ -17,6 +17,8 @@ Build a fieldset that runs on the [On Belay](https://app.onbelay.ai) governance
 5. [Quickstart — Hello World](#5-quickstart--hello-world)
 6. [The webhook handler](#6-the-webhook-handler)
 7. [SDK API reference](#7-sdk-api-reference)
+   - [Typed integration helpers](#typed-integration-helpers)
+   - [logAction](#logaction)
 8. [Webhook payload contract](#8-webhook-payload-contract)
 9. [Embedded UI / dashboard tokens](#9-embedded-ui--dashboard-tokens)
 10. [Migration from 1.0.0](#10-migration-from-100)
@@ -30,7 +32,7 @@ Build a fieldset that runs on the [On Belay](https://app.onbelay.ai) governance
 ## 1. Install
 
 ```bash
-npm install @on-belay/sdk@^2.0.0
+npm install @on-belay/sdk@^2.2.0
 ```
 
 Minimal usage — a complete signed-webhook receiver in five lines:
@@ -106,7 +108,7 @@ Optional: `NEON_CONNECTION_STRING` (per-enrollment, injected when an org has a N
 
 ## 5. Quickstart — Hello World
 
-A fully working sample fieldset lives at [`packages/fieldset-hello-world/`](../fieldset-hello-world/). It is the canonical 2.0.0 reference — start there. The summary:
+A fully working sample fieldset lives at [`packages/fieldset-hello-world/`](../fieldset-hello-world/). It is the canonical reference fieldset — start there. The summary:
 
 ```bash
 # 1. Clone the scaffold (or fork the Hello World fieldset).
@@ -261,6 +263,62 @@ Every HTTP-bound function shares one network contract:
 
 All `/api/sdk/*` success bodies are wrapped on the wire as `{ "data": T }`; errors are `{ "error": { "code", "message" } }`. **The SDK unwraps the envelope for you** — the return types below are the unwrapped `T`. If you bypass the SDK with `curl`, expect the wrapped wire shape.
 
+### Typed integration helpers
+
+*Added in 2.1.0.* The package ships **75 integration modules** — auto-generated typed wrappers over `executeProxyCall`, one per connected integration (`shopify`, `hubspot`, `klaviyo`, `linear`, …). Each helper has the `operationKey` and upstream path baked in, and returns the same `Promise<ProxyResult<T>>` with the **identical retry and error contract** described above. They are a typed convenience layer, not a new transport.
+
+Operations are **namespaced, never bare exports.** Many integrations share operation names (`listOrders`, `listCustomers`), so the SDK exports one namespace object per integration rather than colliding top-level functions. There are three ways to reach a helper:
+
+```ts
+import { shopify, createShopifySubClient, OnbelayClient } from "@on-belay/sdk"
+
+// 1. Namespace object — pass orgId + integrationSlug on every call.
+const a = await shopify.listOrders<MyOrder[]>(orgId, "shopify", {
+  queryParams: { status: "any" },
+})
+
+// 2. Sub-client factory — bind orgId + slug + config once.
+const sc = createShopifySubClient(orgId, "shopify", { fieldsetSlug: "my-fieldset" })
+const b = await sc.listOrders<MyOrder[]>({ queryParams: { status: "any" } })
+
+// 3. Via OnbelayClient — the accessor returns the same bound sub-client.
+const client = new OnbelayClient({ fieldsetSlug: "my-fieldset" })
+const c = await client.shopify(orgId).listOrders<MyOrder[]>()
+```
+
+Helpers that target a single resource take the id as a positional argument. `getLocation` is a **Shopify integration helper** (not a top-level SDK function) — it looks up one location:
+
+```ts
+// Namespace form:
+const loc = await shopify.getLocation<{ location: ShopifyLocation }>(
+  orgId,
+  "shopify",
+  locationId,
+)
+
+// OnbelayClient form — orgId is already bound by the accessor:
+const loc2 = await client.shopify(orgId).getLocation<{ location: ShopifyLocation }>(
+  locationId,
+)
+
+if (loc.ok) console.log(loc.data.location.name)
+```
+
+GraphQL integrations (Linear, Monday) expose helpers that post `{ query, variables }` to `/graphql` — pass the GraphQL document through `options.body`:
+
+```ts
+import { linear } from "@on-belay/sdk"
+
+const issues = await linear.listIssues<{ issues: { nodes: unknown[] } }>(orgId, {
+  body: {
+    query: "query { issues(first: 20) { nodes { id title } } }",
+    variables: {},
+  },
+})
+```
+
+> A typed helper is exactly as permitted as the raw `executeProxyCall` it wraps. It does **not** bypass proxy permission gates — the org must have the integration connected, and the helper's `operationKey` (e.g. `get_location`) must be declared in your fieldset's `requiredOperations`. Calling a helper for an operation you have not declared still returns `403 operation_not_permitted`.
+
 ### `OnbelayConfig`
 
 ```ts
@@ -317,7 +375,7 @@ import { executeProxyCall } from "@on-belay/sdk"
 const result = await executeProxyCall<{ products: Array<{ id: number; title: string }> }>(
   orgId,
   "shopify",
-  "shopify.products.list",
+  "list_products",
   "/admin/api/2024-01/products.json?limit=1",
   { method: "GET" },
   { fieldsetSlug: "my-fieldset" },
@@ -337,6 +395,25 @@ console.log(result.data.products[0]?.title)
 
 The org must have the integration connected; your fieldset's `requiredOperations` must include `operationKey`; the org must be enrolled in your fieldset. Each of those gates returns a different `ProxyErrorCode`.
 
+> **`operationKey` is the operation's own catalog key, matched by exact string
+> equality.** `list_products`, `create_contact`, `shopify.themes.assets.update` —
+> passed alongside a separate `integrationSlug` argument. It is **not** a
+> resource-and-verb path: `"shopify.products.list"` is not a catalog key on anything
+> and is refused. There is no normalization, aliasing or wildcarding: the key you
+> pass must be byte-identical to the one in your `requiredOperations`, which must in
+> turn be a real key on that integration. Some catalog keys contain dots of their
+> own; paste those exactly as written. The
+> [typed integration helpers](#typed-integration-helpers) are generated from the
+> catalog, so using them removes this class of mistake entirely.
+>
+> On the **application form** the pair is written as one string,
+> `integrationSlug.operationKey` — e.g. `shopify.list_products`. A few catalog keys
+> are themselves slug-prefixed, so an entry like `reddit_ads.get_report` reads two
+> ways (the key `reddit_ads.get_report`, or the key `get_report` on `reddit_ads` —
+> two different operations, with different path patterns). Those are rejected rather
+> than guessed; write them with a colon — `reddit_ads:get_report` — which is never
+> ambiguous.
+
 ### `getOrgContext`
 
 ```ts
@@ -351,7 +428,7 @@ interface OrgContext {
 interface ConnectedIntegration {
   slug: string
   status: "active" | "error" | "pending"
-  /** Server-allowlisted public config. v2.0.0: shopify → { shopDomain }, others → {}. */
+  /** Server-allowlisted public config. shopify → { shopDomain }, others → {}. */
   extraConfig: Record<string, string | null>
 }
 ```
@@ -425,7 +502,7 @@ function recordPublish(
 
 interface PublishResult {
   count: number          // new running count after this publish
-  freeAllowance: number  // 10 by default in 2.0.0
+  freeAllowance: number  // 10 by default
   billable: boolean      // true once count > freeAllowance
 }
 ```
@@ -440,7 +517,7 @@ const result = await recordPublish(orgId, "product_brief", {
 console.log(`${result.count}/${result.freeAllowance} — billable: ${result.billable}`)
 ```
 
-> **No `idempotencyKey` in 2.0.0.** The atomic upsert on `(orgId, fieldsetId, contentType)` is the only concurrency guarantee. Strict per-key idempotency requires a `BillingIdempotency` table that is deferred to v2.1. Until then, dedupe on `payload.runId` in your handler before calling `recordPublish` so retries don't double-bill.
+> **No `idempotencyKey`.** The atomic upsert on `(orgId, fieldsetId, contentType)` is the only concurrency guarantee. Strict per-key idempotency requires a `BillingIdempotency` table that is deferred to a future release. Until then, dedupe on `payload.runId` in your handler before calling `recordPublish` so retries don't double-bill.
 
 ### `isEnrolled`
 
@@ -467,6 +544,34 @@ const orgs = await getEnrolledOrgs({ fieldsetSlug: "my-fieldset" })
 // → ["clk_abc123", "clk_def456"]
 ```
 
+### `logAction`
+
+```ts
+function logAction(
+  orgId: string,
+  action: string,
+  metadata?: Record<string, unknown>,
+  config?: OnbelayConfig,
+): Promise<{ ok: boolean }>
+```
+
+*Added in 2.2.0.* `POST /api/sdk/orgs/:orgId/audit`. Writes a governance-visible `AuditLog` row for an org-scoped action your fieldset took. `action` must match `/^[a-z0-9_-]+$/` and be at most 128 characters; the platform stores it namespaced as `external_fieldset_<action>`. The `orgId`, your fieldset id, and the timestamp are taken from the verified Bearer token — never from the request body — so the row cannot be spoofed to another org or fieldset.
+
+> **`logAction` is audit-only — it is NEVER billed.** It does not touch any publish counter. Use `recordPublish` when content goes live and should count toward billing; use `logAction` to record everything else worth an audit trail (a sync started, an org skipped, a threshold crossed).
+
+Throws `OnbelayProtocolError` on a 4xx (e.g. `invalid_action` when `action` fails the pattern or length check). Throws `OnbelayTransportError` on transport failure or a platform 5xx after the single retry.
+
+```ts
+const result = await logAction(orgId, "daily_sync_completed", {
+  productsScanned: 142,
+  runId: payload.runId,
+})
+// Stored as AuditLog action "external_fieldset_daily_sync_completed".
+console.log(result.ok) // → true
+```
+
+Also available as an `OnbelayClient` method — `client.logAction(orgId, action, metadata?)`.
+
 ### `validateWebhookSignature`
 
 ```ts
@@ -575,12 +680,20 @@ class OnbelayClient {
     contentType: string,
     metadata?: Record<string, unknown>,
   ): Promise<PublishResult>
+  logAction(
+    orgId: string,
+    action: string,
+    metadata?: Record<string, unknown>,
+  ): Promise<{ ok: boolean }>
   isEnrolled(orgId: string): Promise<boolean>
   getEnrolledOrgs(): Promise<string[]>
+
+  shopify(orgId: string): ShopifySubClient
+  // + one accessor per integration (hubspot, klaviyo, linear, …)
 }
 ```
 
-Convenience class that holds an `OnbelayConfig` and exposes the seven HTTP-bound functions as instance methods. Pure ergonomic wrapper — every method delegates to the equivalent free function with the bound config. Constructor throws if `fieldsetSlug` is missing.
+Convenience class that holds an `OnbelayConfig` and exposes the eight HTTP-bound functions as instance methods, plus one bound sub-client accessor per integration (see [Typed integration helpers](#typed-integration-helpers)). Pure ergonomic wrapper — every method delegates to the equivalent free function or sub-client factory with the bound config. Constructor throws if `fieldsetSlug` is missing.
 
 ```ts
 import { OnbelayClient } from "@on-belay/sdk"
@@ -617,7 +730,7 @@ class OnbelayProtocolError extends Error {
 }
 ```
 
-Thrown by HTTP-bound functions that return raw values (`getOrgContext`, `getFieldsetConfig`, `setFieldsetConfig`, `recordPublish`, `isEnrolled`, `getEnrolledOrgs`) when the platform returns a 4xx. **`executeProxyCall` does NOT throw this** — it returns the typed `ProxyResult` envelope so you can branch without a `try/catch`.
+Thrown by HTTP-bound functions that return raw values (`getOrgContext`, `getFieldsetConfig`, `setFieldsetConfig`, `recordPublish`, `logAction`, `isEnrolled`, `getEnrolledOrgs`) when the platform returns a 4xx. **`executeProxyCall` does NOT throw this** — it returns the typed `ProxyResult` envelope so you can branch without a `try/catch`.
 
 ### Public types
 
@@ -632,6 +745,8 @@ The full type surface re-exported from the package root:
 | `EnrolledOrg` | Forward-compatible richer enrollment shape (the function returns `string[]`; this is exposed for typed downstream usage). |
 | `ContentType` | Free-form string alias used by `recordPublish`. |
 | `PublishResult` | `recordPublish` return shape. |
+| `LogActionResult` | `logAction` return shape (`{ ok: boolean }`). |
+| `ShopifySlug` | `"shopify"` — accepted by the Shopify integration helpers. |
 | `WebhookPayload` | Inbound webhook body. See [§8](#8-webhook-payload-contract). |
 | `WebhookHandlerOptions`, `WebhookHandlerContext`, `WebhookResult` | `createOnbelayWebhookHandler` shapes. |
 | `WebhookVerifyOptions` | Options for `validateWebhookSignature` / handler. |
@@ -673,7 +788,7 @@ X-Onbelay-Timestamp: <ISO 8601, equal to payload.timestamp>
 |---|---|---|
 | `orgId` | yes | The enrolled org this run targets. |
 | `fieldsetSlug` | yes | Your fieldset slug. The handler verifies this matches `options.fieldsetSlug`. |
-| `triggerType` | yes | `scheduled` (daily 8am UTC) or `manual` (owner clicked "Trigger run"). The other three values are reserved for future platform features; the SDK type accepts them but the platform does not currently emit them in 2.0.0. |
+| `triggerType` | yes | `scheduled` (daily 8am UTC) or `manual` (owner clicked "Trigger run"). The other three values are reserved for future platform features; the SDK type accepts them but the platform does not currently emit them. |
 | `timestamp` | yes | ISO 8601. Used together with `maxAgeSeconds` for replay protection. |
 | `runId` | yes | Deterministic: `ofs_<orgFieldsetId>-<YYYYMMDD>-<triggerType>`. Inngest retries on non-200 reuse the same `runId` — dedupe on this and you trivially survive retries. |
 | `neonConnectionString` | optional | Present only when this org has a Neon branch provisioned. Read/write on your branch only. |
@@ -724,9 +839,27 @@ The full webhook contract is specified in `qa-brightline-dod-external-fieldset-s
 If you ship an embedded UI, the platform renders it as an iframe at `/dashboard/fieldsets/[slug]` with `sandbox="allow-scripts allow-forms"`. The handshake:
 
 1. Iframe loads. It posts `{ type: "onbelay:ready" }` to `https://app.onbelay.ai`.
-2. Platform issues a 15-minute HS256 JWT and posts `{ type: "onbelay:context", token, orgId, userId }` back to the iframe.
+2. Platform issues a **1-hour** HS256 JWT and posts `{ type: "onbelay:context", token, proxyUrl, fieldsetSlug }` back to the iframe. There is **no top-level `orgId` or `userId`** — both are inside the JWT and are returned by `validateDashboardToken`. `proxyUrl` is a **base** URL (e.g. `https://app.onbelay.ai`), the same shape as `ONBELAY_PROXY_URL` and `OnbelayConfig.proxyUrl` — the SDK appends `/api/sdk/proxy` itself, so do **not** append it yourself or you will request `.../api/sdk/proxy/api/sdk/proxy`.
 3. Iframe sends `token` to **its own backend**, which calls `validateDashboardToken(token, ONBELAY_DASHBOARD_SECRET)` and then performs proxy calls scoped to the validated `orgId`.
-4. On `visibilitychange`, the platform re-issues a fresh token.
+4. The platform re-issues a fresh token on `visibilitychange` **and** on a ~10-minute timer, so your listener must tolerate repeated `onbelay:context` messages — each supersedes the last.
+
+> ⚠️ **Do not write the guard yourself — use `isOnbelayContextMessage`.**
+>
+> ```ts
+> import { isOnbelayContextMessage } from "@on-belay/sdk"
+>
+> window.addEventListener("message", (event) => {
+>   if (event.origin !== "https://app.onbelay.ai") return
+>   if (!isOnbelayContextMessage(event.data)) return
+>   // event.data is narrowed: { type, token, proxyUrl, fieldsetSlug }
+> })
+> ```
+>
+> A hand-written guard of the shape `if (!d.token || !d.orgId) return` rejects
+> **every** message, because `orgId` is not at the top level. The symptom is not an
+> error — the UI renders and every API call becomes a silent no-op. This is a real
+> incident, not a hypothetical: it is what happened on `owl-shopmonkey-import`
+> (`docs/fieldsets/owl-shopmonkey-import/specs/qa-test-pass.md:81`).
 
 ```ts
 // Inside your iframe (browser):
@@ -757,7 +890,7 @@ if (!ctx) return new Response(JSON.stringify({ error: "invalid_token" }), { stat
 const result = await executeProxyCall(
   ctx.orgId,
   "shopify",
-  "shopify.products.list",
+  "list_products",
   "/admin/api/2024-01/products.json",
   undefined,
   { fieldsetSlug: ctx.fieldsetSlug },
@@ -774,6 +907,8 @@ A worked example lives in [`packages/fieldset-hello-world/src/app/dashboard/page
 
 ## 10. Migration from 1.0.0
 
+> **Upgrading from 2.0.0 or later? No code changes.** 2.1.0 (typed integration helpers) and 2.2.0 (`logAction`) are purely additive over 2.0.0 — no exports were removed and no existing signature changed. Upgrading from any 2.x release to 2.2.0 is a no-code `npm install @on-belay/sdk@2.2.0`. The steps below apply **only** to services still on 1.0.0.
+
 `@on-belay/sdk@2.0.0` is a complete rewrite. The 1.0.0 SDK depended on platform internals and could not be installed cleanly outside the On Belay monorepo. 2.0.0 is HTTP-only, framework-agnostic, and has exactly one runtime dependency (`jose`).
 
 ### Removed exports
@@ -791,14 +926,14 @@ These exports do not exist in 2.0.0 — importing them fails at install or compi
 
 ### Other breaking changes
 
-- **`recordPublish` no longer accepts `idempotencyKey`** (Decision B; coming back in v2.1 with a `BillingIdempotency` table). Dedupe on `payload.runId` in your handler instead.
+- **`recordPublish` no longer accepts `idempotencyKey`** (Decision B; coming back in a future release with a `BillingIdempotency` table). Dedupe on `payload.runId` in your handler instead.
 - **`executeProxyCall` signature changed.** New positional arguments: `(orgId, integrationSlug, operationKey, path, options?, config?)`. The `fieldsetSlug` argument is gone — the SDK reads it from `OnbelayConfig`.
 - **The fieldset token is no longer included in the webhook payload.** Read it from `process.env.ONBELAY_FIELDSET_TOKEN`. The SDK does this by default.
 - **`ONBELAY_PROXY_URL` is base URL only** — `https://app.onbelay.ai`. The SDK appends paths internally. The 1.0.0 value ended in `/api/sdk/proxy`; the platform team runs a backfill script for existing services on cutover.
 
 ### Migration checklist
 
-1. `npm install @on-belay/sdk@2.0.0`
+1. `npm install @on-belay/sdk@2.2.0`
 2. Delete imports of the removed exports listed above.
 3. Replace your scheduler/runner setup with `createOnbelayWebhookHandler` from §6.
 4. Update `executeProxyCall` call sites for the new positional signature.
@@ -821,7 +956,7 @@ These exports do not exist in 2.0.0 — importing them fails at install or compi
 | Proxy returns `403 integration_not_connected` | The org has not connected the upstream integration. Skip gracefully — do not throw. The org admin will reconnect on their schedule. |
 | Proxy returns `403 org_not_enrolled` | This org is not enrolled in your fieldset, or enrollment was paused. Check `OrgFieldset.status = "active"`. |
 | Proxy returns `403 fieldset_inactive` | The platform owner deactivated your fieldset (kill switch). Contact On Belay support. |
-| Proxy returns `429 rate_limited` | You exceeded the per-token bucket: 60 proxy calls / 60 s, 30 writes / 60 s, 120 reads / 60 s. Wait 60 seconds before retrying — the bucket refills every 60 s. (`@on-belay/sdk@2.0.0` does not surface the `Retry-After` header on `ProxyResult`; a future patch will.) |
+| Proxy returns `429 rate_limited` | You exceeded the per-token bucket: 60 proxy calls / 60 s, 30 writes / 60 s, 120 reads / 60 s. Wait 60 seconds before retrying — the bucket refills every 60 s. (The SDK does not surface the `Retry-After` header on `ProxyResult`; a future patch will.) |
 | `OnbelayTransportError` with `attempts === 2` | Platform retried once on a 502/503/504 and the second attempt also failed. Catch in your handler, log to Sentry, and let the next scheduled run pick up the work. |
 | `OnbelayTransportError` with `status === 500` | Platform-side bug, not transient. Not retried. Open a support ticket with the run id. |
 | Inngest is retrying my webhook 3× for the same `runId` | Your handler returned 5xx or timed out (>30 s). Implement idempotency on `runId` so retries are cheap, and offload long work to a background queue while returning 200 quickly. |