feat(observability): URL routers + per-call operation names + commerce histograms

[vibe-dex]

Summary

Adds end-to-end semantic operation naming on outbound VTEX + Shopify fetches and emits a provider-labelled commerce duration histogram. Builds on the operation API shipped in @decocms/start@5.3.0-rc.0 (deco-start#179).

After this lands, every outbound commerce call from a storefront produces:

• A span named vtex.<operation> / shopify.<operation> (e.g. vtex.checkout.orderform.items.add, shopify.ProductDetails) instead of a generic vtex.fetch.
• A fetch.operation attribute on the span so the same string is queryable independently of span name.
• A commerce_request_duration_ms histogram record with labels { provider, operation, status_code, cached }.
• W3C traceparent injection (already in the framework).
• URL redaction on log + span attributes (already in the framework).

Zero behavioral change for sites that don't opt in — setVtexFetch(createVtexFetch()) is the one-line opt-in.

What's in here

1. chore(deps): bump @decocms/start devDep → 5.3.0-rc.0, peerDep → >=5.3.0-rc.0.

2. feat(vtex): vtex/utils/operationRouter.ts — pure (url, method) => operation | undefined. Covers IS, checkout/orderForm (incl. POST/PATCH/DELETE differentiation on /items), sessions, segments, catalog, masterdata (entity-suffixed), OMS, vtexid, IO GraphQL, sitemap. 22 vitest cases.

3. feat(shopify): shopify/utils/operationRouter.ts + graphqlOperationName.ts — URL router + GraphQL document parser. Names spans shopify.<OperationName> (extracted from query Foo { ... }) instead of the generic shopify.storefront.graphql. Wired into createGraphqlClient. 11 vitest cases.

4. feat(factories): createVtexFetch() / createShopifyFetch() — pre-wired InstrumentedFetch factories bundling createInstrumentedFetch + URL router + onComplete: commerce_request_duration_ms. 10 vitest cases.

5. refactor(vtex): funnel 9 server-side ad-hoc fetches through the configured _fetch:

   • performVtexLogout → vtexid.logout
   • proxyToVtex / createVtexCheckoutProxy → URL-router
   • notifyMe / subscribe (.aspx) → notifyme / newsletter.subscribe
   • sendEvent × 2 (sp.vtex.com) → analytics.event
   • updateProfileFromRequest → io.graphql.UpdateProfile
   • uploadAttachment → masterdata.attachment.upload

   Adds getVtexFetch() accessor + widens setVtexFetch to accept InstrumentedFetch | typeof fetch + widens vtexFetch* helpers to take InstrumentedFetchInit so the operation field threads through.

6. docs(readme): setup recipe + subpath table.

Out of scope (follow-ups)

• Resend (resend/actions/send.ts) and Google Fonts (website/loaders/fonts/googleFonts.ts) raw fetches — non-VTEX/non-Shopify hosts, low traffic; left as raw fetch to keep PR scope focused. Easy follow-up if/when needed.
• Client-side React hooks (vtex/hooks/use*.ts) intentionally untouched. They run in the browser against same-origin /api/..., which is proxied server-side by proxyToVtex / createVtexCheckoutProxy (now instrumented). Wiring an instrumented fetch in the browser gives no tracer / no metrics — wasted layer.
• Pre-existing test failure on main: vtex/__tests__/client-segment-cookie.test.ts has 2 cases that fail under Node 22 / undici (which treats cookie as a forbidden request header on new Request()). Not introduced by this PR — fails identically with the dep bump stashed. Worth a separate fix/segment-cookie-test to rewrite the fixture before promoting next → main.

Test plan

• npm run typecheck — clean
• npm run lint — clean
• npm test — 411 / 413 passing; the 2 failures are the pre-existing cookie tests called out above
• npx knip — no new findings (and removed one stale ignoreDependencies entry)
• Validate prerelease on a real storefront once semantic-release publishes 1.x.0-next.X from this branch
• Confirm spans land in HyperDX with operation names + the commerce_request_duration_ms histogram shows up in ClickHouse / Grafana

Coordinated release path

This is the apps-start half of a three-PR observability rollout:

1. stats-lake #1 — POST /v1/metrics + OTLP metrics DDLs. Merged + deployed.
2. deco-start #179 — operation API + direct-POST channels. Published manually as 5.3.0-rc.0 on the @rc dist-tag (deco-start's next branch is currently blocked by unrelated unfinished work). Will be promoted to 5.3.0 on main once this rc soaks.
3. This PR — once merged to next, semantic-release publishes @decocms/apps@1.x.0-next.X on the @next tag. Then bump a real storefront to both prereleases and validate end-to-end.

Made with Cursor

---

Summary by cubic

Adds semantic operation names and a commerce_request_duration_ms histogram for all outbound VTEX and Shopify calls. Provides pre-wired fetch factories and URL routers; Shopify GraphQL calls are named per operation.

• New Features

  • createVtexFetch() and createShopifyFetch() pre-wire spans, traceparent, URL redaction, and a histogram with { provider, operation, status_code, cached }.
  • URL routers: vtexOperationRouter and shopifyOperationRouter map URLs to low-cardinality operations.
  • Shopify: extractGraphqlOperationName stamps init.operation, so spans become shopify.<OperationName>; wired into createGraphqlClient.
  • VTEX: new getVtexFetch() accessor; routed ad-hoc server calls through the configured fetch; setVtexFetch now accepts InstrumentedFetch | fetch; VTEX helpers accept InstrumentedFetchInit so operation propagates.

• Migration

  • Requires @decocms/start@>=5.3.0-rc.0.
  • Opt in:
    • VTEX: setVtexFetch(createVtexFetch())
    • Shopify: setShopifyFetch(createShopifyFetch())

^{Written for commit 24d0502. Summary will update on new commits. Review in cubic}

[cubic-dev-ai]

No issues found across 25 files

_{Re-trigger cubic}

[github-actions]

🎉 This PR is included in version 1.15.0-next.1 🎉

The release is available on:

• v1.15.0-next.1
• GitHub release

Your semantic-release bot 📦🚀