@decocms/blocks 8.10.0 → 8.11.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (163) hide show
  1. package/dist/v8/cli/index.d.ts +1 -0
  2. package/dist/v8/cli/index.d.ts.map +1 -1
  3. package/dist/v8/cli/index.js +1 -0
  4. package/dist/v8/cli/index.js.map +1 -1
  5. package/dist/v8/cli/run.d.ts +2 -0
  6. package/dist/v8/cli/run.d.ts.map +1 -1
  7. package/dist/v8/cli/run.js +30 -1
  8. package/dist/v8/cli/run.js.map +1 -1
  9. package/dist/v8/cli/skills.d.ts +25 -0
  10. package/dist/v8/cli/skills.d.ts.map +1 -0
  11. package/dist/v8/cli/skills.js +70 -0
  12. package/dist/v8/cli/skills.js.map +1 -0
  13. package/package.json +3 -2
  14. package/skills/deco-apps/SKILL.md +82 -0
  15. package/skills/deco-apps/references/algolia.md +51 -0
  16. package/skills/deco-apps/references/commerce-types.md +132 -0
  17. package/skills/deco-apps/references/instrumented-fetch.md +144 -0
  18. package/skills/deco-apps/references/magento.md +55 -0
  19. package/skills/deco-apps/references/messaging.md +76 -0
  20. package/skills/deco-apps/references/shopify.md +69 -0
  21. package/skills/deco-apps/references/vendored-loaders.md +135 -0
  22. package/skills/deco-apps/references/vtex-cookies-auth.md +146 -0
  23. package/skills/deco-apps/references/vtex.md +150 -0
  24. package/skills/deco-apps/references/wake.md +75 -0
  25. package/skills/deco-cms-schema/SKILL.md +80 -0
  26. package/skills/deco-cms-schema/references/annotations.md +147 -0
  27. package/skills/deco-cms-schema/references/content-hygiene.md +91 -0
  28. package/skills/deco-cms-schema/references/formats-and-widgets.md +112 -0
  29. package/skills/deco-cms-schema/references/shapes-that-break-the-form.md +165 -0
  30. package/skills/deco-cms-schema/references/types-to-fields.md +112 -0
  31. package/skills/deco-go-live/SKILL.md +127 -0
  32. package/skills/deco-go-live/references/content-releases.md +90 -0
  33. package/skills/deco-go-live/references/process.md +106 -0
  34. package/skills/deco-go-live/references/proxy-headers-checkout.md +139 -0
  35. package/skills/deco-go-live/references/qa-checklist-template.md +150 -0
  36. package/skills/deco-go-live/references/qa-inventory.md +120 -0
  37. package/skills/deco-go-live/references/react-spa.md +183 -0
  38. package/skills/deco-go-live/references/seo-analytics.md +114 -0
  39. package/skills/deco-go-live/references/traffic-ramp.md +87 -0
  40. package/skills/deco-go-live/references/worker-runtime.md +93 -0
  41. package/skills/deco-go-live/scripts/preflight.sh +221 -0
  42. package/skills/deco-images-media/SKILL.md +64 -0
  43. package/skills/deco-images-media/references/asset-upload.md +191 -0
  44. package/skills/deco-images-media/references/components-per-binding.md +167 -0
  45. package/skills/deco-images-media/references/providers-and-cdn.md +145 -0
  46. package/skills/deco-images-media/references/quality-and-lcp.md +93 -0
  47. package/skills/deco-images-media/references/troubleshooting.md +147 -0
  48. package/skills/deco-images-media/references/video.md +122 -0
  49. package/skills/deco-make-editable/SKILL.md +94 -0
  50. package/skills/deco-make-editable/references/a11y-and-e2e.md +104 -0
  51. package/skills/deco-make-editable/references/content-shapes.md +198 -0
  52. package/skills/deco-make-editable/references/from-figma.md +110 -0
  53. package/skills/deco-make-editable/references/i18n-fields.md +112 -0
  54. package/skills/deco-make-editable/references/inventory.md +79 -0
  55. package/skills/deco-make-editable/references/pixel-parity.md +175 -0
  56. package/skills/deco-make-editable/references/seeding-content.md +119 -0
  57. package/skills/deco-nextjs-site/SKILL.md +74 -0
  58. package/skills/deco-nextjs-site/references/caching.md +116 -0
  59. package/skills/deco-nextjs-site/references/metadata-seo.md +100 -0
  60. package/skills/deco-nextjs-site/references/proxy-and-drafts.md +177 -0
  61. package/skills/deco-nextjs-site/references/rendering.md +171 -0
  62. package/skills/deco-nextjs-site/references/setup.md +190 -0
  63. package/skills/deco-nextjs-site/references/studio-bridge.md +130 -0
  64. package/skills/deco-site-authoring/SKILL.md +75 -0
  65. package/skills/deco-site-authoring/references/lazy-blocks.md +155 -0
  66. package/skills/deco-site-authoring/references/loaders.md +192 -0
  67. package/skills/deco-site-authoring/references/pages.md +156 -0
  68. package/skills/deco-site-authoring/references/review-before-publish.md +95 -0
  69. package/skills/deco-site-authoring/references/sections.md +158 -0
  70. package/skills/deco-site-authoring/references/seo.md +116 -0
  71. package/skills/deco-site-workflow/SKILL.md +92 -0
  72. package/skills/deco-site-workflow/references/check.md +116 -0
  73. package/skills/deco-site-workflow/references/cli-reference.md +104 -0
  74. package/skills/deco-site-workflow/references/content-layout.md +93 -0
  75. package/skills/deco-site-workflow/references/content-sync.md +146 -0
  76. package/skills/deco-site-workflow/references/delivery.md +51 -0
  77. package/skills/deco-site-workflow/references/deploy.md +87 -0
  78. package/skills/deco-site-workflow/references/schema.md +173 -0
  79. package/skills/deco-site-workflow/references/serve-and-studio.md +138 -0
  80. package/skills/deco-storefront-caching/SKILL.md +67 -0
  81. package/skills/deco-storefront-caching/references/cache-keys.md +129 -0
  82. package/skills/deco-storefront-caching/references/case-study.md +82 -0
  83. package/skills/deco-storefront-caching/references/egress-traps.md +153 -0
  84. package/skills/deco-storefront-caching/references/nextjs.md +60 -0
  85. package/skills/deco-storefront-caching/references/perf-guardrails-e2e.md +123 -0
  86. package/skills/deco-storefront-caching/references/verification.md +136 -0
  87. package/skills/deco-storefront-caching/references/worker-page-cache.md +160 -0
  88. package/skills/deco-storefront-caching/scripts/html-anatomy.mjs +97 -0
  89. package/skills/deco-storefront-performance/SKILL.md +81 -0
  90. package/skills/deco-storefront-performance/references/cls-third-party.md +90 -0
  91. package/skills/deco-storefront-performance/references/hydration.md +116 -0
  92. package/skills/deco-storefront-performance/references/loaders-n-plus-1.md +107 -0
  93. package/skills/deco-storefront-performance/references/navigation-ux.md +130 -0
  94. package/skills/deco-storefront-performance/references/payload-trim.md +163 -0
  95. package/skills/deco-storefront-performance/references/render-location.md +152 -0
  96. package/skills/deco-storefront-performance/references/request-dedupe.md +147 -0
  97. package/skills/deco-storefront-performance/references/trace-reading.md +79 -0
  98. package/skills/deco-storefront-performance/references/worker-memory.md +176 -0
  99. package/skills/deco-tanstack-site/SKILL.md +68 -0
  100. package/skills/deco-tanstack-site/references/document-and-security.md +155 -0
  101. package/skills/deco-tanstack-site/references/router-and-navigation.md +137 -0
  102. package/skills/deco-tanstack-site/references/routes-and-pages.md +183 -0
  103. package/skills/deco-tanstack-site/references/server-functions.md +123 -0
  104. package/skills/deco-tanstack-site/references/setup.md +153 -0
  105. package/skills/deco-tanstack-site/references/worker-entry.md +152 -0
  106. package/skills/deco-v7-to-v8-migration/SKILL.md +122 -0
  107. package/skills/deco-v7-to-v8-migration/references/caching-and-privacy.md +10 -0
  108. package/skills/deco-v7-to-v8-migration/references/content.md +25 -0
  109. package/skills/deco-v7-to-v8-migration/references/editor-forms.md +27 -0
  110. package/skills/deco-v7-to-v8-migration/references/faststore.md +40 -0
  111. package/skills/deco-v7-to-v8-migration/references/framework-code.md +53 -0
  112. package/skills/deco-v7-to-v8-migration/references/hosted-releases.md +16 -0
  113. package/skills/deco-v7-to-v8-migration/references/import-map.md +81 -0
  114. package/skills/deco-v7-to-v8-migration/references/legacy-names.md +33 -0
  115. package/skills/deco-v7-to-v8-migration/references/manual-steps.md +10 -0
  116. package/skills/deco-v7-to-v8-migration/references/native-apps.md +43 -0
  117. package/skills/deco-v7-to-v8-migration/references/nextjs.md +19 -0
  118. package/skills/deco-v7-to-v8-migration/references/parity.md +66 -0
  119. package/skills/deco-v7-to-v8-migration/references/rendering.md +13 -0
  120. package/skills/deco-v7-to-v8-migration/references/running-the-script.md +29 -0
  121. package/skills/deco-v7-to-v8-migration/references/script-steps.md +13 -0
  122. package/skills/deco-v7-to-v8-migration/references/server-functions.md +15 -0
  123. package/skills/deco-v7-to-v8-migration/references/sibling-port.md +11 -0
  124. package/skills/deco-v7-to-v8-migration/references/site-code.md +15 -0
  125. package/skills/deco-v7-to-v8-migration/references/telemetry.md +10 -0
  126. package/skills/deco-v7-to-v8-migration/references/verify.md +20 -0
  127. package/skills/deco-v7-to-v8-migration/scripts/apps.ts +297 -0
  128. package/skills/deco-v7-to-v8-migration/scripts/asyncRendering.ts +73 -0
  129. package/skills/deco-v7-to-v8-migration/scripts/blockMap.ts +584 -0
  130. package/skills/deco-v7-to-v8-migration/scripts/ciSchemaCheck.ts +145 -0
  131. package/skills/deco-v7-to-v8-migration/scripts/compat.ts +357 -0
  132. package/skills/deco-v7-to-v8-migration/scripts/content.ts +121 -0
  133. package/skills/deco-v7-to-v8-migration/scripts/experiments.ts +81 -0
  134. package/skills/deco-v7-to-v8-migration/scripts/framework.ts +61 -0
  135. package/skills/deco-v7-to-v8-migration/scripts/imageCopy.ts +276 -0
  136. package/skills/deco-v7-to-v8-migration/scripts/imageModule.ts +285 -0
  137. package/skills/deco-v7-to-v8-migration/scripts/imports.ts +942 -0
  138. package/skills/deco-v7-to-v8-migration/scripts/invoke.ts +624 -0
  139. package/skills/deco-v7-to-v8-migration/scripts/legacyNames.ts +45 -0
  140. package/skills/deco-v7-to-v8-migration/scripts/main.ts +59 -0
  141. package/skills/deco-v7-to-v8-migration/scripts/matchers.ts +41 -0
  142. package/skills/deco-v7-to-v8-migration/scripts/migrate.ts +176 -0
  143. package/skills/deco-v7-to-v8-migration/scripts/redirects.ts +455 -0
  144. package/skills/deco-v7-to-v8-migration/scripts/report.ts +50 -0
  145. package/skills/deco-v7-to-v8-migration/scripts/scaffold.ts +1119 -0
  146. package/skills/deco-v7-to-v8-migration/scripts/secrets.ts +35 -0
  147. package/skills/deco-v7-to-v8-migration/scripts/sectionLoaders.ts +216 -0
  148. package/skills/deco-v7-to-v8-migration/scripts/siteSettings.ts +261 -0
  149. package/skills/deco-v7-to-v8-migration/scripts/stubs.ts +388 -0
  150. package/skills/deco-v7-to-v8-migration/scripts/tsconfig.json +7 -0
  151. package/skills/deco-v7-to-v8-migration/scripts/vendor.ts +249 -0
  152. package/skills/deco-v7-to-v8-migration/scripts/vtexInvoke.ts +240 -0
  153. package/skills/deco-v7-to-v8-migration/scripts/walk.ts +30 -0
  154. package/skills/deco-variants/SKILL.md +57 -0
  155. package/skills/deco-variants/references/caching-variants.md +63 -0
  156. package/skills/deco-variants/references/custom-matchers.md +83 -0
  157. package/skills/deco-variants/references/draft-preview.md +59 -0
  158. package/skills/deco-variants/references/experiments-and-campaigns.md +104 -0
  159. package/skills/deco-variants/references/multivariate.md +85 -0
  160. package/skills/deco-variants/references/v7-matchers.md +71 -0
  161. package/src/v8/cli/index.ts +1 -0
  162. package/src/v8/cli/run.ts +35 -1
  163. package/src/v8/cli/skills.ts +91 -0
@@ -0,0 +1,144 @@
1
+ # Errors, retries, telemetry and upstream caching
2
+
3
+ Every `@decocms/apps-*` client sends its requests through `createInstrumentedFetch`
4
+ from `@decocms/blocks/fetch`. The client never calls `fetch` directly; a guardrail test
5
+ in the repo enforces it. This file covers what that layer does and what it means for
6
+ the site.
7
+
8
+ ## What a request goes through
9
+
10
+ ```ts
11
+ createInstrumentedFetch({
12
+ provider: "vtex", // the provider label
13
+ fetch?, // the fetch underneath; default globalThis.fetch
14
+ retry?: { attempts, backoffMs? }, // off unless set
15
+ circuitBreaker?: { failures, cooldownMs } // off unless set
16
+ })
17
+ ```
18
+
19
+ The returned function takes `(input, init & { operation? })`. `operation` is the label
20
+ of the call (`"unknown"` when missing).
21
+
22
+ ### Retries
23
+
24
+ - Only for idempotent methods: `GET`, `HEAD`, `OPTIONS`, `PUT`, `DELETE`. A `POST` is
25
+ never retried, so a checkout call is never sent twice.
26
+ - Retried on HTTP 429, 502, 503, 504 and on network errors. An abort or timeout
27
+ (`AbortError`, `TimeoutError`) is not retried.
28
+ - Backoff is `backoffMs * 2^n` (default `backoffMs` 100).
29
+ - Only the VTEX client turns retries on: 2 retries, 150 ms base. Pass `retry: false` in
30
+ its config to turn them off, or `{ attempts, backoffMs }` to change them.
31
+
32
+ ### Circuit breaker
33
+
34
+ - After `failures` consecutive failures, every call fails fast for `cooldownMs`. A
35
+ failure is a network error or a status of 500 or more.
36
+ - The count lives in the client instance and covers **every operation** of that
37
+ client. If one VTEX endpoint keeps returning 5xx, search calls fail fast too until
38
+ the cooldown ends.
39
+ - Only the VTEX client turns it on: 5 failures, 5 s cooldown. Pass
40
+ `circuitBreaker: false` to turn it off.
41
+ - Create the client once per isolate. A new client per request starts at zero failures
42
+ every time, so the breaker never opens.
43
+
44
+ ## Errors
45
+
46
+ Each client throws its own error class on a non-2xx response. It carries the operation
47
+ and the status and nothing from the response, so it is safe to log.
48
+
49
+ | Client | Class | Fields | Also thrown when |
50
+ |---|---|---|---|
51
+ | VTEX | `VtexError` | `operation`, `status` | `io.graphql` returns `errors` (status 200) |
52
+ | Shopify | `ShopifyError` | `operation`, `status`, `codes` | GraphQL `errors`, no `data`, or a body that isn't JSON |
53
+ | Wake | `WakeError` | `operation`, `status`, `graphqlErrors` | GraphQL `errors`, or no `data` |
54
+ | Magento | `MagentoError` | `operation`, `status`, `graphqlErrors` | GraphQL `errors`, or no `data` |
55
+ | Algolia | `AlgoliaError` | `operation`, `status` | |
56
+ | Resend | `ResendError` | `operation`, `status` | |
57
+ | SFMC Personalization | `SfmcPersonalizationError` | `operation`, `status` | |
58
+
59
+ Two failures don't use these classes:
60
+
61
+ - **Network errors** (DNS, reset, abort) are rethrown as the underlying `fetch` threw them.
62
+ - **An open circuit** throws a plain `Error`: `"<provider> <operation>: circuit open after N failures"`.
63
+
64
+ So a loader that wants to show a fallback catches all errors, not only the client's
65
+ class. Checking `error instanceof VtexError && error.status === 404` is fine for "not
66
+ found"; anything else is an outage.
67
+
68
+ ## Telemetry
69
+
70
+ Each request is measured once, however many retries it took, as
71
+ `http.client.request.duration` (seconds) with these labels:
72
+
73
+ | Label | Value |
74
+ |---|---|
75
+ | `provider` | `vtex`, `shopify`, `wake`, `magento`, `algolia`, `resend`, `sfmc-personalization` |
76
+ | `operation` | The call's label (see below) |
77
+ | `status_class` | `2xx`, `4xx`, `5xx`, or `error` when there was no response |
78
+ | `cached` | `true` when the response has `x-cache: HIT` |
79
+ | `retries` | How many retries it took |
80
+
81
+ A request with no response also logs an error with code `FETCH_FAILED`. Sampled
82
+ requests produce a client span named `<provider> <operation>`. Nothing about the
83
+ request body, headers or query string is recorded. With no telemetry destination
84
+ configured on the CMS, nothing is recorded.
85
+
86
+ How each client names `operation`:
87
+
88
+ - **VTEX**: from the URL path, by an internal router (`intelligent-search.product_search`,
89
+ `checkout.orderform.items.add`, `catalog.pagetype`, `masterdata.<entity>`, `io.graphql`…).
90
+ A path the router doesn't know is `unknown`.
91
+ - **Shopify, Wake**: the GraphQL operation's name (`query ProductByHandle { … }` →
92
+ `ProductByHandle`). An unnamed document is `storefront.graphql` / `admin.graphql`
93
+ (Shopify) or `graphql` (Wake). **Name your GraphQL operations**, or every call shares
94
+ one label.
95
+ - **Magento**: the `operation` you pass to `request`/`rest`, and `operationName` for
96
+ `graphql`. Use the API's name for the call, never a URL.
97
+ - **Algolia**: `search`. **Resend**: `sendEmail`. **SFMC**: `sendEvent`.
98
+
99
+ ## Upstream caching
100
+
101
+ Clients never cache. To cache upstream responses, pass your own `fetch`:
102
+
103
+ ```ts
104
+ import { createVtexClient } from "@decocms/apps-vtex";
105
+
106
+ const vtex = createVtexClient({
107
+ account: "mystore",
108
+ fetch: cachedFetch, // your function with fetch's signature
109
+ });
110
+ ```
111
+
112
+ - Your `fetch` gets the final URL and `RequestInit` (headers included). Its cache key
113
+ must include everything the response depends on: the full URL with its query
114
+ (`sc`, `regionId`, `locale`, page, facets) and any header that changes the answer.
115
+ - Set `x-cache: HIT` on a response served from the cache. Telemetry then counts it as
116
+ `cached=true`.
117
+ - Cache only shopper-invariant responses: requests sent **without** a `cookie` and
118
+ without a per-customer `Authorization`. Never cache checkout, session, profile or
119
+ Master Data writes. VTEX rules: [`vtex-cookies-auth.md`](./vtex-cookies-auth.md).
120
+ - Retries run around your `fetch`, and a cache hit counts as a success for the breaker.
121
+
122
+ How the site caches pages (the page cache, segments, private responses) is in the
123
+ `deco-storefront-caching` skill.
124
+
125
+ ## Calling an endpoint no client covers
126
+
127
+ The clients cover a fixed set of operations. For anything else, build your own
128
+ instrumented fetch in the site so it is still measured:
129
+
130
+ ```ts
131
+ import { createInstrumentedFetch } from "@decocms/blocks/fetch";
132
+
133
+ const vtexFetch = createInstrumentedFetch({ provider: "vtex" });
134
+
135
+ const response = await vtexFetch(`https://${account}.vtexcommercestable.com.br/api/…`, {
136
+ operation: "wishlist.get", // low-cardinality: no ids, slugs or search terms
137
+ headers: { cookie },
138
+ });
139
+ ```
140
+
141
+ You then own what the client did for you: credentials, cookie sanitizing
142
+ ([`vtex-cookies-auth.md`](./vtex-cookies-auth.md)), path encoding, error handling, and
143
+ not logging bodies. VTEX's operation router is internal to `@decocms/apps-vtex`, so
144
+ pass `operation` yourself.
@@ -0,0 +1,55 @@
1
+ # `@decocms/apps-magento`
2
+
3
+ A client for one Magento store's REST and GraphQL APIs. Everything goes to the store's
4
+ own origin.
5
+
6
+ ## Configure
7
+
8
+ ```ts
9
+ import { createMagentoClient } from "@decocms/apps-magento";
10
+
11
+ export const magento = createMagentoClient(
12
+ {
13
+ baseUrl: "https://store.example.com", // only its origin is used
14
+ apiKey: secrets.MAGENTO_API_KEY, // integration token, optional
15
+ originHeader: secrets.MAGENTO_ORIGIN, // optional, sent as x-origin-header
16
+ },
17
+ { fetch: cachedFetch }, // optional
18
+ );
19
+ ```
20
+
21
+ - `originHeader` is for stores behind an origin guard that expects a shared value.
22
+ - Exports: `createMagentoClient`, `MagentoClient`, `MagentoClientConfig`,
23
+ `MagentoClientOptions`, `MagentoError`, `MagentoRequestInit`.
24
+
25
+ ## Three ways to call
26
+
27
+ | Call | Returns | `apiKey` sent by default |
28
+ |---|---|---|
29
+ | `request(path, { operation, authenticated?, ...init })` | the raw `Response` | yes |
30
+ | `rest<T>(path, { operation, authenticated?, ...init })` | parsed JSON (`undefined` on 204) | yes |
31
+ | `graphql<T, V>(query, variables, { operationName, headers?, authenticated? })` | `data` | no |
32
+
33
+ - **Paths only.** `request` and `rest` resolve the path against the store's origin and
34
+ throw if the result is another origin, so the token never leaves the store.
35
+ - **`operation` is required** on `request`/`rest`, and `operationName` on `graphql`. It
36
+ is the telemetry label and appears in errors. Use the API's own name (`getCart`), never
37
+ a URL.
38
+ - **The bearer token.** With `authenticated` true and an `apiKey`, the client sets
39
+ `Authorization: Bearer <apiKey>`, unless the call already set an `Authorization`
40
+ header. Pass a customer token as `Authorization` for customer calls; the integration
41
+ token never replaces it.
42
+ - **GraphQL is public** on Magento, so `graphql` sends the `apiKey` only with
43
+ `authenticated: true`. Pass the store view as a `Store` header when needed.
44
+ - `rest` sets `content-type: application/json` when there is a body and none was set.
45
+ `graphql` always sends `operationName` in the body.
46
+
47
+ ## Errors
48
+
49
+ `MagentoError` has `operation`, `status` and `graphqlErrors` (0 for an HTTP failure).
50
+ `request` doesn't throw on an HTTP error; it returns the response. No retries or circuit
51
+ breaker.
52
+
53
+ Customer and cart calls carry a customer token or session: run them in a server
54
+ function and don't cache them. Caching catalog reads is the site's job:
55
+ [`instrumented-fetch.md`](./instrumented-fetch.md).
@@ -0,0 +1,76 @@
1
+ # Email and personalization: Resend, SFMC Personalization
2
+
3
+ Two small clients with one operation each. Both are POSTs, so neither is retried, and
4
+ neither may be cached.
5
+
6
+ ## `@decocms/apps-resend`
7
+
8
+ ```ts
9
+ import { createResendClient } from "@decocms/apps-resend";
10
+
11
+ export const resend = createResendClient({ apiKey: secrets.RESEND_API_KEY });
12
+
13
+ const { id } = await resend.sendEmail({
14
+ from: "Store <contact@store.example.com>",
15
+ to: ["shopper@example.com"],
16
+ subject: "Your quote",
17
+ html: "<p>…</p>",
18
+ reply_to: "sales@store.example.com",
19
+ });
20
+ ```
21
+
22
+ - `sendEmail(email)` posts to `https://api.resend.com/emails` with
23
+ `Authorization: Bearer <apiKey>` and returns `{ id }`.
24
+ - `from` is required by the type: the API needs a sender. Other fields: `to`, `subject`,
25
+ `cc`, `bcc`, `reply_to`, `html`, `text`, `headers`.
26
+ - No retries or circuit breaker: sending an email isn't safe to repeat. On
27
+ `ResendError` (`operation`, `status`), decide in the site whether to retry.
28
+ - Default sender, recipients and subject belong to the site. A migrated site has them
29
+ in `resendSettings` (`emailFrom`, `emailTo`, `subject`) in `src/clients/resend.ts`;
30
+ v7's default sender was `Contact <onboarding@resend.dev>`.
31
+ - Exports: `createResendClient`, `ResendClient`, `ResendClientConfig`, `ResendError`,
32
+ `SendEmailOptions`, `CreateEmailOptions`, `CreateEmailResponseSuccess`.
33
+
34
+ Send from a server function or route handler (a contact form, a newsletter sign-up).
35
+ Validate and rate-limit the input there: the key sends mail as the store.
36
+
37
+ ## `@decocms/apps-sfmc-personalization`
38
+
39
+ Salesforce Marketing Cloud Personalization (formerly Evergage), Event API.
40
+
41
+ ```ts
42
+ import { createSfmcPersonalizationClient } from "@decocms/apps-sfmc-personalization";
43
+
44
+ export const sfmc = createSfmcPersonalizationClient({
45
+ baseUrl: "https://<account>.<instance>.evergage.com",
46
+ dataset: "engage",
47
+ });
48
+
49
+ const { campaignResponses } = await sfmc.sendEvent({
50
+ source: { channel: "Web", url: pageUrl },
51
+ interaction: { name: "View Item" },
52
+ user: { anonymousId },
53
+ pageView: true,
54
+ });
55
+ ```
56
+
57
+ - `sendEvent(event)` posts to `/api2/event/{dataset}` on `baseUrl` and returns the
58
+ campaigns the interaction triggered: `campaignResponses[]`, each with `campaignId` and
59
+ a `payload` (`experience`, `headerText`, `products`, `userGroup`, and whatever the
60
+ campaign defines).
61
+ - `event.user` carries `anonymousId`, `encryptedId` or `attributes`; `interaction` can
62
+ carry `lineItems` for cart-aware events; `flags` has `nonInteractive` and `doNotTrack`.
63
+ - `PersonalizationProduct` keeps the common product fields (`id`, `name`, `price`,
64
+ `salePrice`, `inventoryCount`, `imageUrls`, `url`, `currency`) and accepts the rest
65
+ of the dataset's catalog fields.
66
+ - The client sends no credentials. Reading the shopper's ID from its cookie, mapping
67
+ products to commerce types and any caching are site code.
68
+ - Errors: `SfmcPersonalizationError` (`operation`, `status`). No retries.
69
+ - Exports: `createSfmcPersonalizationClient`, `SfmcPersonalizationClient`,
70
+ `SfmcPersonalizationConfig`, `SfmcPersonalizationError`, and the types
71
+ `PersonalizationEvent`, `PersonalizationResponse`, `CampaignResponse`,
72
+ `PersonalizationProduct`, `PersonalizationLineItem`.
73
+
74
+ The response depends on the shopper, so a section that renders campaign products is
75
+ per-visitor. Fetch it after the page loads, or from a private server function, so the
76
+ page itself stays cacheable.
@@ -0,0 +1,69 @@
1
+ # `@decocms/apps-shopify`
2
+
3
+ A client for Shopify's Storefront and Admin GraphQL APIs, and nothing else. Converters,
4
+ cart and customer flows are site code.
5
+
6
+ ## Configure
7
+
8
+ ```ts
9
+ import { createShopifyClient } from "@decocms/apps-shopify";
10
+
11
+ export const shopify = createShopifyClient(
12
+ {
13
+ storeName: "acme", // acme.myshopify.com
14
+ storefrontAccessToken: secrets.SHOPIFY_STOREFRONT_TOKEN,
15
+ adminAccessToken: secrets.SHOPIFY_ADMIN_TOKEN, // optional; enables `admin`
16
+ apiVersion: "2026-07", // required, no default
17
+ },
18
+ { fetch: cachedFetch }, // optional
19
+ );
20
+ ```
21
+
22
+ - `apiVersion` has no default on purpose: the site owns it, so it never goes stale
23
+ inside the package. A migrated site starts with the version its v7 app used.
24
+ - Requests go to `https://{storeName}.myshopify.com/api/{apiVersion}/graphql.json`
25
+ (header `X-Shopify-Storefront-Access-Token`) and
26
+ `/admin/api/{apiVersion}/graphql.json` (header `X-Shopify-Access-Token`).
27
+ - Without `adminAccessToken`, `admin.query` rejects with
28
+ `"shopify admin: pass adminAccessToken to createShopifyClient"`. Never use the Admin
29
+ API from code a shopper's request can steer without checking the input.
30
+ - Exports: `createShopifyClient`, `ShopifyClient`, `ShopifyClientConfig`, `ShopifyError`.
31
+
32
+ ## Query
33
+
34
+ ```ts
35
+ const data = await shopify.storefront.query<ProductByHandleQuery, { handle: string }>(
36
+ `query ProductByHandle($handle: String!) { product(handle: $handle) { id title } }`,
37
+ { handle },
38
+ { headers: { "Shopify-Storefront-Buyer-IP": buyerIp }, signal },
39
+ );
40
+ ```
41
+
42
+ - `query(document, variables?, { headers?, signal? })` returns `data`.
43
+ - The telemetry label is the document's operation name (`ProductByHandle`). An unnamed
44
+ document is labeled `storefront.graphql` or `admin.graphql`; name every operation.
45
+ - Extra `headers` can't override the access token.
46
+
47
+ ## Errors
48
+
49
+ `ShopifyError` has `operation`, `status` and `codes`:
50
+
51
+ | Case | `codes` |
52
+ |---|---|
53
+ | HTTP error | `[]` |
54
+ | GraphQL `errors` | each error's `extensions.code`, or `UNKNOWN`, deduplicated |
55
+ | No `data` | `["MISSING_DATA"]` |
56
+ | Body isn't JSON (an HTML error page) | `["INVALID_JSON"]` |
57
+
58
+ A response with both `data` and `errors` is rejected as a whole. The client doesn't
59
+ guess which fields are still trustworthy. If a query can partly fail and you still want
60
+ the rest, split it into separate queries.
61
+
62
+ No retries and no circuit breaker. Caching is the site's: see
63
+ [`instrumented-fetch.md`](./instrumented-fetch.md).
64
+
65
+ ## Images
66
+
67
+ `@decocms/apps-shopify/image` exports `shopifyCdn()`, an `ImageProvider` for
68
+ `https://cdn.shopify.com` URLs (sets `width`, `height` when given, and `crop=center`).
69
+ List it before `decoCdn`; see `deco-images-media`.
@@ -0,0 +1,135 @@
1
+ # Client files and vendored loaders
2
+
3
+ v8 apps ship no loaders, actions, hooks or converters. A migrated site keeps the ones its
4
+ content uses as its own code, and calls the thin client from them. The
5
+ `deco-v7-to-v8-migration` skill's script does the copy; this file covers what it
6
+ leaves you and how to move that code onto the v8 client.
7
+
8
+ ## What the migration script writes
9
+
10
+ **`src/clients/<app>.ts`**, one per v7 app block the content has (`deco-vtex`,
11
+ `deco-shopify`, `deco-wake`, `deco-resend`). Each exports a function that creates the
12
+ client on first use:
13
+
14
+ ```ts
15
+ // src/clients/vtex.ts (shape of the generated file, TanStack Start)
16
+ import { createVtexClient, type VtexClient } from "@decocms/apps-vtex";
17
+ import { env } from "cloudflare:workers";
18
+
19
+ const variable = (name: string) =>
20
+ (env as unknown as Record<string, string | undefined>)[name] || undefined;
21
+
22
+ export const vtexSettings = { publicUrl: "…", country: "…", invalidPageNotFound: false } as const;
23
+
24
+ let client: VtexClient | undefined;
25
+
26
+ export function vtexClient(): VtexClient {
27
+ client ??= createVtexClient({
28
+ account: "mystore",
29
+ salesChannel: "1",
30
+ appKey: variable("VTEX_APP_KEY"),
31
+ appToken: variable("VTEX_APP_TOKEN"),
32
+ });
33
+ return client;
34
+ }
35
+ ```
36
+
37
+ - Settings come from the saved block, with v7's defaults: VTEX sales channel `"1"`,
38
+ Wake checkout `https://<account>.checkout.fbits.store`, and for Shopify the
39
+ Storefront API version the installed v7 app used.
40
+ - A credential that was encrypted in content is read from the variable v7 fell back
41
+ to: `VTEX_APP_KEY`, `VTEX_APP_TOKEN`, `SHOPIFY_STOREFRONT_TOKEN`, `WAKE_TOKEN`,
42
+ `RESEND_API_KEY`. Set them in the deploy platform's secrets (on Workers,
43
+ `wrangler secret put`). On Next.js the file reads `process.env`.
44
+ - What v7 kept beside the client (VTEX's `publicUrl`, Resend's sender) is an exported
45
+ `<app>Settings` constant.
46
+ - The saved app block stays until the variables are set. Then delete it: `deco check`
47
+ rejects it.
48
+
49
+ **`src/vendor/<app>/<path>`**: every app loader and action the content calls, copied
50
+ from the installed v7 package with the modules it imports from that package. Imports
51
+ of the package by name become relative imports. The block map registers each one
52
+ under its v7 type name, so saved content keeps resolving.
53
+
54
+ **`src/server/invoke.functions.ts`** (TanStack) or **`invoke.actions.ts`** (Next.js):
55
+ one server function per `/deco/invoke` key the site called. With
56
+ `--vtex-invoke v8`, the VTEX cart keys go to `src/server/vtex-invoke.server.ts` over
57
+ `vtexClient()`. Details are in `deco-v7-to-v8-migration`.
58
+
59
+ ## Keep v7's client, or move to the v8 one
60
+
61
+ A vendored loader may still call v7's own fetch code, copied along with it. That keeps
62
+ every upstream request identical to v7, so recorded upstream fixtures still replay in
63
+ a parity run. It also keeps v7's in-memory fetch cache, which v8 doesn't have.
64
+
65
+ - **Keep it** while you prove parity. Drop the v8 `@decocms/apps-<platform>` dependency
66
+ if nothing imports it, and list the move to the v8 client as a follow-up.
67
+ - **Move to the v8 client** to get telemetry, retries, the circuit breaker and cookie
68
+ sanitizing, and to delete v7 code. Do it loader by loader, after parity.
69
+
70
+ ## Moving a vendored loader onto the client
71
+
72
+ 1. **One argument.** A block function gets its inputs and nothing else: no `req`, no
73
+ `ctx`. Remove the second and third parameters. A value the loader read from the
74
+ request (a cookie, the URL) must come in as an input, or the call belongs in a
75
+ server function. See `deco-site-authoring` for loaders.
76
+ 2. **Replace the fetch with a client call.** `vtexClient().search.products({…})` instead
77
+ of a hand-built Intelligent Search URL. The table below maps v7's VTEX calls.
78
+ 3. **Keep the converter.** The client returns VTEX's own types. The vendored
79
+ `transform` code that builds `Product`, `ProductListingPage` and the rest stays in
80
+ `src/vendor`. Import the commerce types from `@decocms/compat-v7/commerce/types`
81
+ ([`commerce-types.md`](./commerce-types.md)).
82
+ 4. **Remove `ctx.invoke`.** Call the other handler module directly, or the client.
83
+ `src/migration-stubs.ts` stubs (`unportedInvoke`, `appState`) reject or throw at run time
84
+ until replaced.
85
+ 5. **Actions are not block functions.** A cart or session mutation runs in a server
86
+ function (TanStack) or a route handler or server action (Next.js), with the shopper's
87
+ request. Forward VTEX's cookies there: [`vtex-cookies-auth.md`](./vtex-cookies-auth.md).
88
+
89
+ ### v7 VTEX calls and the v8 operation
90
+
91
+ | v7 call | v8 client |
92
+ |---|---|
93
+ | Intelligent Search `product_search` | `vtex.search.products(args)` |
94
+ | Intelligent Search `facets` | `vtex.search.facets(args)` |
95
+ | `search_suggestions`, `autocomplete_suggestions`, `top_searches` | `vtex.search.suggestions`, `.autocomplete`, `.topSearches` |
96
+ | `/api/catalog_system/pub/products/search` | `vtex.catalog.products({ term, ft, fq, from, to, sort })` |
97
+ | `/pub/portal/pagetype/<path>` | `vtex.catalog.pageType(path)` |
98
+ | `/pub/products/crossselling/<type>/<id>` | `vtex.catalog.crossSelling(type, productId)` |
99
+ | `/pub/category/tree/<levels>` | `vtex.catalog.categoryTree(levels)` |
100
+ | `getOrCreateCart` | `vtex.checkout.orderForm({ cookie, sections? })` |
101
+ | `addItemsToCart` | `vtex.checkout.addItems(orderFormId, items, { cookie })` |
102
+ | `updateCartItems` | `vtex.checkout.updateItems(orderFormId, items, { cookie })` |
103
+ | `addCouponToCart` | `vtex.checkout.addCoupon(orderFormId, text, { cookie })` |
104
+ | `updateOrderFormAttachment` | `vtex.checkout.attachment(orderFormId, name, body, { cookie })` |
105
+ | `simulateCart` | `vtex.checkout.simulation({ items, postalCode, country })` |
106
+ | `getSellersByRegion` | `vtex.checkout.regions({ postalCode, country })` |
107
+ | `/api/sessions` (get, edit) | `vtex.sessions.get({ cookie, items })`, `vtex.sessions.update(public, { cookie })` |
108
+ | Master Data v1 search, create | `vtex.masterdata.search(entity, args)`, `.create(entity, doc)` |
109
+ | IO GraphQL (`myvtex.com/_v/private/graphql/v1`) | `vtex.io.graphql({ query, variables })` |
110
+
111
+ What the v8 cart calls do differently from v7's handlers (the migration report lists
112
+ these too):
113
+
114
+ - `orderForm` gets the cart from the shopper's `checkout.vtex.com` cookie. v7 fetched
115
+ `props.orderFormId` when given.
116
+ - No `allowedOutdatedData=paymentData` on add or update, no `noSplitItem` on update,
117
+ no `RnbBehavior=1` on simulation.
118
+ - `addItems` types each SKU `id` as a number.
119
+ - Item images keep VTEX's `http:` URLs. v7 rewrote them to `https:`. Do it in your
120
+ converter if the site needs it.
121
+
122
+ Wishlist, OMS orders, VTEX ID sign-in, profile and address calls have no operation in
123
+ the v8 client. Keep the vendored code, or write the call with `createInstrumentedFetch`
124
+ ([`instrumented-fetch.md`](./instrumented-fetch.md)).
125
+
126
+ ## Housekeeping
127
+
128
+ - **The script vendors every loader the content references**, including ones v7 never
129
+ ran. Check which ones render before keeping them; delete the rest with the saved
130
+ blocks nothing references.
131
+ - **Don't reformat vendored GraphQL documents.** Prettier reflows a vendored
132
+ `queries.ts`, which changes every request body sent upstream; a replaying parity
133
+ harness then misses every call. Keep such files in `.prettierignore`.
134
+ - **Tailwind** may scan `src/vendor` now, where v7 never scanned `node_modules`. See
135
+ `deco-v7-to-v8-migration` if classes change.
@@ -0,0 +1,146 @@
1
+ # VTEX cookies, sign-in and what may be cached
2
+
3
+ VTEX keeps the shopper's cart, session, region and sign-in in cookies. The v8 client
4
+ never reads the incoming request and never writes a response. The site passes the
5
+ shopper's `Cookie` header in, and sends VTEX's `Set-Cookie` values out. Most VTEX cart
6
+ and sign-in bugs on a migrated site are one of those two steps.
7
+
8
+ ## Cookies in
9
+
10
+ Pass the request's `Cookie` header as `cookie` on every shopper-scoped call:
11
+
12
+ ```ts
13
+ const cookie = request.headers.get("cookie") ?? undefined;
14
+ const { data: orderForm, setCookies } = await vtex.checkout.orderForm({ cookie });
15
+ ```
16
+
17
+ - A call with `cookie` goes out **as the shopper**: the client leaves the app key and
18
+ token off. A cart call without `cookie` carries no `checkout.vtex.com` cookie, so
19
+ VTEX starts a new cart (and the client sends the app key and token, when configured).
20
+ - The client cleans the header first. It drops pairs without `=`, pairs whose name
21
+ isn't a valid token, and pairs whose value has non-ASCII bytes. VTEX's gateway
22
+ answers `503` with an empty body to a cookie with non-ASCII bytes, before the request
23
+ reaches the service. One analytics tag that writes an accented category name into
24
+ `document.cookie` would otherwise break every checkout call for that shopper. Dropped
25
+ cookies are not reported.
26
+ - It does **not** filter by name. Every clean cookie the browser sent goes to VTEX.
27
+
28
+ ### Sending only VTEX's cookies
29
+
30
+ The package keeps a list of the cookie name prefixes VTEX APIs read. It is internal (not
31
+ exported), and the client does not apply it:
32
+
33
+ `VtexIdclientAutCookie`, `checkout.vtex.com`, `CheckoutOrderFormOwnership`,
34
+ `vtex_session`, `vtex_segment`, `vtex_is_`, `janus_sid`
35
+
36
+ To keep third-party cookies away from VTEX (a smaller header, nothing extra sent
37
+ upstream), filter in the site before you pass `cookie`:
38
+
39
+ ```ts
40
+ const VTEX_PREFIXES = ["VtexIdclientAutCookie", "checkout.vtex.com", "CheckoutOrderFormOwnership",
41
+ "vtex_session", "vtex_segment", "vtex_is_", "janus_sid"];
42
+
43
+ const vtexCookies = (header: string | null) =>
44
+ (header ?? "")
45
+ .split(";")
46
+ .map((pair) => pair.trim())
47
+ .filter((pair) => VTEX_PREFIXES.some((prefix) => pair.startsWith(prefix)))
48
+ .join("; ") || undefined;
49
+ ```
50
+
51
+ ## Cookies out
52
+
53
+ Calls that change shopper state return `VtexResponse<T>`: `{ data, setCookies }`. The
54
+ checkout calls (except `simulation` and `regions`) and both session calls do.
55
+ `setCookies` comes from `Headers.getSetCookie()`: one string per cookie, unmodified.
56
+
57
+ **Append each value as its own `Set-Cookie` header.** A cart call returns several
58
+ cookies. Never copy them with `headers.entries()` or `forEach`, and never join them:
59
+ those collapse the values into one comma-joined header, which browsers discard. The
60
+ cart then looks empty on the next request although VTEX returned the items.
61
+
62
+ Check in DevTools: the cart call's response has **several** `Set-Cookie` rows, not one
63
+ long one.
64
+
65
+ **TanStack Start**: in the server function, append to the response headers. This is
66
+ the forwarder the migration script writes for `--vtex-invoke v8`:
67
+
68
+ ```ts
69
+ import { getResponseHeaders } from "@tanstack/react-start/server";
70
+ import type { VtexResponse } from "@decocms/apps-vtex";
71
+
72
+ async function forward<T>(response: Promise<VtexResponse<T>>, request: Request): Promise<T> {
73
+ const { data, setCookies } = await response;
74
+ const host = new URL(request.url).hostname;
75
+ const headers = getResponseHeaders();
76
+ for (const cookie of setCookies) {
77
+ if (cookie.startsWith("vtex_is_session=") || cookie.startsWith("vtex_is_anonymous=")) continue;
78
+ headers.append("set-cookie", cookie.replace(/(;\s*)domain=[^;]*/i, `$1Domain=${host}`));
79
+ }
80
+ return data;
81
+ }
82
+ ```
83
+
84
+ - `Domain` is rewritten to the site's host. VTEX names its own domain, and a browser
85
+ rejects a cookie set for a domain other than the one it is talking to.
86
+ - Intelligent Search's session cookies stay on the server, as v7 kept them.
87
+
88
+ **Next.js**: a server action can only set cookies through `cookies()`, which
89
+ percent-encodes the value. `checkout.vtex.com=__ofid=…` would reach VTEX as
90
+ `__ofid%3D…` and lose the cart. Run cart calls in a **route handler** and append each
91
+ `setCookies` value to the `Response` headers.
92
+
93
+ ## Intelligent Search cookies
94
+
95
+ v7's middleware created `vtex_is_session` and `vtex_is_anonymous` (random UUIDs) when
96
+ the request had none, and sent them on Intelligent Search calls. v8 does neither: the
97
+ client sends only the `cookie` you pass (after the cleanup above), and no cookie when
98
+ you pass none.
99
+
100
+ If the store relies on those cookies, set them in the site and include them in the
101
+ search's `cookie`. That makes the search shopper-scoped: don't put it in a shared
102
+ cache (below). Without them, a search is the same for every shopper and can be cached.
103
+
104
+ ## Sign-in: `VtexIdclientAutCookie`
105
+
106
+ - **It is HttpOnly.** Browser code can't read it with `document.cookie`. A client
107
+ component that checks `document.cookie` for sign-in always sees a signed-out shopper.
108
+ Ask the server instead: a server function calls
109
+ `vtex.sessions.get({ cookie, items: ["profile.isAuthenticated", "profile.email"] })`
110
+ and returns what the UI needs, marked private.
111
+ - **Two names.** VTEX also sets `VtexIdclientAutCookie_<account>`. v7's client sent both
112
+ names, with the same token, on authenticated IO GraphQL calls. The v8 client sends
113
+ what the browser has; if only one name is there, add the other to the `cookie` you
114
+ pass to `io.graphql`.
115
+ - **Authorized hosts.** VTEX accepts headless sign-in only from hosts listed in the
116
+ store's settings in the VTEX admin. Add every host the site is served from:
117
+ production, preview hosts, and `localhost:<port>` for local work. A missing host
118
+ shows as a sign-in that redirects in a loop.
119
+ - **Testing without a sign-in flow.** Sign in on an authorized host, copy every cookie
120
+ whose name starts with `VtexIdclientAutCookie` from DevTools (Application → Cookies),
121
+ and set them on the target host. They expire; copy them again when the session drops.
122
+
123
+ | Symptom | Likely cause |
124
+ |---|---|
125
+ | Sign-in redirects in a loop | The host isn't in the store's authorized hosts |
126
+ | Copied cookies don't keep the session | Expired, or the target host isn't authorized |
127
+ | UI shows signed-out while VTEX checkout shows signed-in | The UI reads `document.cookie`; ask the server |
128
+
129
+ ## What may be cached
130
+
131
+ Only responses that are the same for every shopper.
132
+
133
+ - **Never cache** a call made with `cookie`, any `VtexResponse` (checkout, sessions),
134
+ Master Data reads made for a shopper, or `io.graphql` with a sign-in cookie.
135
+ - **Cacheable**: `search.*` and `catalog.*` sent without `cookie`. Key on the full URL:
136
+ `sc`, `regionId`, `locale`, page, sort and facets are all in it. See
137
+ [`instrumented-fetch.md`](./instrumented-fetch.md) for the client's `fetch` option.
138
+ - **Server functions that return shopper data** (cart, user, wishlist, addresses) answer
139
+ `Cache-Control: private, no-store`. On TanStack Start, call `markPrivate()` from
140
+ `@decocms/tanstack/server` in them.
141
+ - **A signed-in shopper never shares a cached page.** On TanStack Start, the worker
142
+ entry's `buildSegment` returns `loggedIn: true` when the request has the cookie the
143
+ sign-in flow actually sets, and that page is not cached. Details in
144
+ `deco-storefront-caching`.
145
+ - **One React Query client per router**, never per isolate: a shared one leaks the
146
+ previous request's cart and user to the next shopper.