@on-belay/sdk 2.2.1 → 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

@@ -375,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" },
@@ -395,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
@@ -669,7 +688,7 @@ class OnbelayClient {
   isEnrolled(orgId: string): Promise<boolean>
   getEnrolledOrgs(): Promise<string[]>
 
-  shopify(orgId: string, integrationSlug?: "shopify" | "shopify_temp"): ShopifySubClient
+  shopify(orgId: string): ShopifySubClient
   // + one accessor per integration (hubspot, klaviyo, linear, …)
 }
 ```
@@ -727,7 +746,7 @@ The full type surface re-exported from the package root:
 | `ContentType` | Free-form string alias used by `recordPublish`. |
 | `PublishResult` | `recordPublish` return shape. |
 | `LogActionResult` | `logAction` return shape (`{ ok: boolean }`). |
-| `ShopifySlug` | `"shopify" \| "shopify_temp"` — accepted by the Shopify integration helpers. |
+| `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. |
@@ -820,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):
@@ -853,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 },