@decocms/blocks 8.9.1 → 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 (409) hide show
  1. package/dist/index.d.ts +1 -1
  2. package/dist/index.d.ts.map +1 -1
  3. package/dist/index.js +1 -1
  4. package/dist/index.js.map +1 -1
  5. package/dist/protocol/channel.d.ts +98 -0
  6. package/dist/protocol/channel.d.ts.map +1 -0
  7. package/dist/protocol/channel.js +58 -0
  8. package/dist/protocol/channel.js.map +1 -0
  9. package/dist/protocol/client.js +2 -2
  10. package/dist/protocol/client.js.map +1 -1
  11. package/dist/protocol/conformance/blockMetaVectors.json +214 -0
  12. package/dist/protocol/conformance/contentHashFixtures.d.ts +22 -0
  13. package/dist/protocol/conformance/contentHashFixtures.d.ts.map +1 -1
  14. package/dist/protocol/conformance/contentHashFixtures.js +55 -0
  15. package/dist/protocol/conformance/contentHashFixtures.js.map +1 -1
  16. package/dist/protocol/conformance/index.d.ts +2 -1
  17. package/dist/protocol/conformance/index.d.ts.map +1 -1
  18. package/dist/protocol/conformance/index.js +2 -1
  19. package/dist/protocol/conformance/index.js.map +1 -1
  20. package/dist/protocol/conformance/vectors.d.ts +33 -0
  21. package/dist/protocol/conformance/vectors.d.ts.map +1 -0
  22. package/dist/protocol/conformance/vectors.js +3 -0
  23. package/dist/protocol/conformance/vectors.js.map +1 -0
  24. package/dist/protocol/index.d.ts +11 -1
  25. package/dist/protocol/index.d.ts.map +1 -1
  26. package/dist/protocol/index.js +11 -1
  27. package/dist/protocol/index.js.map +1 -1
  28. package/dist/protocol/keys.d.ts +1 -1
  29. package/dist/protocol/keys.js +1 -1
  30. package/dist/v8/background.d.ts +13 -0
  31. package/dist/v8/background.d.ts.map +1 -1
  32. package/dist/v8/background.js +41 -0
  33. package/dist/v8/background.js.map +1 -1
  34. package/dist/v8/blockMeta.d.ts +27 -0
  35. package/dist/v8/blockMeta.d.ts.map +1 -0
  36. package/dist/v8/blockMeta.js +75 -0
  37. package/dist/v8/blockMeta.js.map +1 -0
  38. package/dist/v8/blockStore.d.ts +43 -0
  39. package/dist/v8/blockStore.d.ts.map +1 -0
  40. package/dist/v8/blockStore.js +95 -0
  41. package/dist/v8/blockStore.js.map +1 -0
  42. package/dist/v8/boundedJson.d.ts +5 -0
  43. package/dist/v8/boundedJson.d.ts.map +1 -1
  44. package/dist/v8/boundedJson.js +10 -2
  45. package/dist/v8/boundedJson.js.map +1 -1
  46. package/dist/v8/boundedMap.d.ts +19 -0
  47. package/dist/v8/boundedMap.d.ts.map +1 -0
  48. package/dist/v8/boundedMap.js +52 -0
  49. package/dist/v8/boundedMap.js.map +1 -0
  50. package/dist/v8/builtins/data.d.ts +18 -2
  51. package/dist/v8/builtins/data.d.ts.map +1 -1
  52. package/dist/v8/builtins/data.js +17 -1
  53. package/dist/v8/builtins/data.js.map +1 -1
  54. package/dist/v8/builtins/index.d.ts.map +1 -1
  55. package/dist/v8/builtins/index.js +2 -1
  56. package/dist/v8/builtins/index.js.map +1 -1
  57. package/dist/v8/builtins/legacy.d.ts +6 -3
  58. package/dist/v8/builtins/legacy.d.ts.map +1 -1
  59. package/dist/v8/builtins/legacy.js +6 -3
  60. package/dist/v8/builtins/legacy.js.map +1 -1
  61. package/dist/v8/canonical.d.ts +8 -0
  62. package/dist/v8/canonical.d.ts.map +1 -1
  63. package/dist/v8/canonical.js +15 -0
  64. package/dist/v8/canonical.js.map +1 -1
  65. package/dist/v8/cli/builtins.d.ts.map +1 -1
  66. package/dist/v8/cli/builtins.js +1 -0
  67. package/dist/v8/cli/builtins.js.map +1 -1
  68. package/dist/v8/cli/check/index.d.ts +10 -0
  69. package/dist/v8/cli/check/index.d.ts.map +1 -1
  70. package/dist/v8/cli/check/index.js +91 -7
  71. package/dist/v8/cli/check/index.js.map +1 -1
  72. package/dist/v8/cli/content.d.ts +12 -25
  73. package/dist/v8/cli/content.d.ts.map +1 -1
  74. package/dist/v8/cli/content.js +46 -75
  75. package/dist/v8/cli/content.js.map +1 -1
  76. package/dist/v8/cli/index.d.ts +2 -2
  77. package/dist/v8/cli/index.d.ts.map +1 -1
  78. package/dist/v8/cli/index.js +2 -2
  79. package/dist/v8/cli/index.js.map +1 -1
  80. package/dist/v8/cli/remote/commands.d.ts +71 -0
  81. package/dist/v8/cli/remote/commands.d.ts.map +1 -0
  82. package/dist/v8/cli/remote/commands.js +644 -0
  83. package/dist/v8/cli/remote/commands.js.map +1 -0
  84. package/dist/v8/cli/remote/diff.d.ts +15 -0
  85. package/dist/v8/cli/remote/diff.d.ts.map +1 -0
  86. package/dist/v8/cli/remote/diff.js +102 -0
  87. package/dist/v8/cli/remote/diff.js.map +1 -0
  88. package/dist/v8/cli/remote/env.d.ts +35 -0
  89. package/dist/v8/cli/remote/env.d.ts.map +1 -0
  90. package/dist/v8/cli/remote/env.js +84 -0
  91. package/dist/v8/cli/remote/env.js.map +1 -0
  92. package/dist/v8/cli/remote/http.d.ts +149 -0
  93. package/dist/v8/cli/remote/http.d.ts.map +1 -0
  94. package/dist/v8/cli/remote/http.js +381 -0
  95. package/dist/v8/cli/remote/http.js.map +1 -0
  96. package/dist/v8/cli/remote/local.d.ts +90 -0
  97. package/dist/v8/cli/remote/local.d.ts.map +1 -0
  98. package/dist/v8/cli/remote/local.js +309 -0
  99. package/dist/v8/cli/remote/local.js.map +1 -0
  100. package/dist/v8/cli/root.d.ts +29 -0
  101. package/dist/v8/cli/root.d.ts.map +1 -1
  102. package/dist/v8/cli/root.js +28 -0
  103. package/dist/v8/cli/root.js.map +1 -1
  104. package/dist/v8/cli/run.d.ts +13 -1
  105. package/dist/v8/cli/run.d.ts.map +1 -1
  106. package/dist/v8/cli/run.js +310 -124
  107. package/dist/v8/cli/run.js.map +1 -1
  108. package/dist/v8/cli/schema/builtinSchemas.d.ts.map +1 -1
  109. package/dist/v8/cli/schema/builtinSchemas.js +28 -10
  110. package/dist/v8/cli/schema/builtinSchemas.js.map +1 -1
  111. package/dist/v8/cli/schema/generate.js +1 -1
  112. package/dist/v8/cli/schema/generate.js.map +1 -1
  113. package/dist/v8/cli/skills.d.ts +25 -0
  114. package/dist/v8/cli/skills.d.ts.map +1 -0
  115. package/dist/v8/cli/skills.js +70 -0
  116. package/dist/v8/cli/skills.js.map +1 -0
  117. package/dist/v8/client.d.ts +9 -9
  118. package/dist/v8/client.d.ts.map +1 -1
  119. package/dist/v8/client.js +138 -50
  120. package/dist/v8/client.js.map +1 -1
  121. package/dist/v8/cms.d.ts +2 -1
  122. package/dist/v8/cms.d.ts.map +1 -1
  123. package/dist/v8/cms.js +55 -46
  124. package/dist/v8/cms.js.map +1 -1
  125. package/dist/v8/content.d.ts +39 -78
  126. package/dist/v8/content.d.ts.map +1 -1
  127. package/dist/v8/content.js +155 -195
  128. package/dist/v8/content.js.map +1 -1
  129. package/dist/v8/contentIndex.d.ts +71 -0
  130. package/dist/v8/contentIndex.d.ts.map +1 -0
  131. package/dist/v8/contentIndex.js +137 -0
  132. package/dist/v8/contentIndex.js.map +1 -0
  133. package/dist/v8/draft.d.ts +7 -7
  134. package/dist/v8/draft.d.ts.map +1 -1
  135. package/dist/v8/draft.js +10 -9
  136. package/dist/v8/draft.js.map +1 -1
  137. package/dist/v8/draftChanges.d.ts +59 -32
  138. package/dist/v8/draftChanges.d.ts.map +1 -1
  139. package/dist/v8/draftChanges.js +139 -75
  140. package/dist/v8/draftChanges.js.map +1 -1
  141. package/dist/v8/errors.d.ts +21 -0
  142. package/dist/v8/errors.d.ts.map +1 -1
  143. package/dist/v8/errors.js +22 -0
  144. package/dist/v8/errors.js.map +1 -1
  145. package/dist/v8/hostedSource.d.ts +57 -0
  146. package/dist/v8/hostedSource.d.ts.map +1 -0
  147. package/dist/v8/hostedSource.js +18 -0
  148. package/dist/v8/hostedSource.js.map +1 -0
  149. package/dist/v8/identity.d.ts +1 -1
  150. package/dist/v8/identity.js +1 -1
  151. package/dist/v8/index.d.ts +1 -0
  152. package/dist/v8/index.d.ts.map +1 -1
  153. package/dist/v8/index.js +1 -0
  154. package/dist/v8/index.js.map +1 -1
  155. package/dist/v8/matchRoute.js +7 -4
  156. package/dist/v8/matchRoute.js.map +1 -1
  157. package/dist/v8/pin.d.ts +34 -0
  158. package/dist/v8/pin.d.ts.map +1 -0
  159. package/dist/v8/pin.js +156 -0
  160. package/dist/v8/pin.js.map +1 -0
  161. package/dist/v8/preview/StudioBridge.d.ts +8 -8
  162. package/dist/v8/preview/StudioBridge.d.ts.map +1 -1
  163. package/dist/v8/preview/StudioBridge.js +8 -10
  164. package/dist/v8/preview/StudioBridge.js.map +1 -1
  165. package/dist/v8/preview/StudioChannel.d.ts +51 -0
  166. package/dist/v8/preview/StudioChannel.d.ts.map +1 -0
  167. package/dist/v8/preview/StudioChannel.js +104 -0
  168. package/dist/v8/preview/StudioChannel.js.map +1 -0
  169. package/dist/v8/preview/index.d.ts +3 -0
  170. package/dist/v8/preview/index.d.ts.map +1 -1
  171. package/dist/v8/preview/index.js +3 -0
  172. package/dist/v8/preview/index.js.map +1 -1
  173. package/dist/v8/remoteLoader.d.ts +42 -5
  174. package/dist/v8/remoteLoader.d.ts.map +1 -1
  175. package/dist/v8/remoteLoader.js +317 -259
  176. package/dist/v8/remoteLoader.js.map +1 -1
  177. package/dist/v8/resolver.d.ts +22 -8
  178. package/dist/v8/resolver.d.ts.map +1 -1
  179. package/dist/v8/resolver.js +37 -32
  180. package/dist/v8/resolver.js.map +1 -1
  181. package/dist/v8/revisionId.d.ts +11 -0
  182. package/dist/v8/revisionId.d.ts.map +1 -0
  183. package/dist/v8/revisionId.js +13 -0
  184. package/dist/v8/revisionId.js.map +1 -0
  185. package/dist/v8/settings.d.ts +6 -6
  186. package/dist/v8/settings.d.ts.map +1 -1
  187. package/dist/v8/settings.js +8 -7
  188. package/dist/v8/settings.js.map +1 -1
  189. package/dist/v8/telemetry.d.ts +4 -2
  190. package/dist/v8/telemetry.d.ts.map +1 -1
  191. package/dist/v8/telemetry.js +2 -2
  192. package/dist/v8/telemetry.js.map +1 -1
  193. package/dist/v8/types.d.ts +52 -40
  194. package/dist/v8/types.d.ts.map +1 -1
  195. package/dist/v8/variants.d.ts +7 -2
  196. package/dist/v8/variants.d.ts.map +1 -1
  197. package/dist/v8/variants.js +21 -24
  198. package/dist/v8/variants.js.map +1 -1
  199. package/dist/v8/vite/index.d.ts +2 -2
  200. package/dist/v8/vite/index.js +1 -1
  201. package/dist/v8/vite/index.js.map +1 -1
  202. package/package.json +3 -2
  203. package/skills/deco-apps/SKILL.md +82 -0
  204. package/skills/deco-apps/references/algolia.md +51 -0
  205. package/skills/deco-apps/references/commerce-types.md +132 -0
  206. package/skills/deco-apps/references/instrumented-fetch.md +144 -0
  207. package/skills/deco-apps/references/magento.md +55 -0
  208. package/skills/deco-apps/references/messaging.md +76 -0
  209. package/skills/deco-apps/references/shopify.md +69 -0
  210. package/skills/deco-apps/references/vendored-loaders.md +135 -0
  211. package/skills/deco-apps/references/vtex-cookies-auth.md +146 -0
  212. package/skills/deco-apps/references/vtex.md +150 -0
  213. package/skills/deco-apps/references/wake.md +75 -0
  214. package/skills/deco-cms-schema/SKILL.md +80 -0
  215. package/skills/deco-cms-schema/references/annotations.md +147 -0
  216. package/skills/deco-cms-schema/references/content-hygiene.md +91 -0
  217. package/skills/deco-cms-schema/references/formats-and-widgets.md +112 -0
  218. package/skills/deco-cms-schema/references/shapes-that-break-the-form.md +165 -0
  219. package/skills/deco-cms-schema/references/types-to-fields.md +112 -0
  220. package/skills/deco-go-live/SKILL.md +127 -0
  221. package/skills/deco-go-live/references/content-releases.md +90 -0
  222. package/skills/deco-go-live/references/process.md +106 -0
  223. package/skills/deco-go-live/references/proxy-headers-checkout.md +139 -0
  224. package/skills/deco-go-live/references/qa-checklist-template.md +150 -0
  225. package/skills/deco-go-live/references/qa-inventory.md +120 -0
  226. package/skills/deco-go-live/references/react-spa.md +183 -0
  227. package/skills/deco-go-live/references/seo-analytics.md +114 -0
  228. package/skills/deco-go-live/references/traffic-ramp.md +87 -0
  229. package/skills/deco-go-live/references/worker-runtime.md +93 -0
  230. package/skills/deco-go-live/scripts/preflight.sh +221 -0
  231. package/skills/deco-images-media/SKILL.md +64 -0
  232. package/skills/deco-images-media/references/asset-upload.md +191 -0
  233. package/skills/deco-images-media/references/components-per-binding.md +167 -0
  234. package/skills/deco-images-media/references/providers-and-cdn.md +145 -0
  235. package/skills/deco-images-media/references/quality-and-lcp.md +93 -0
  236. package/skills/deco-images-media/references/troubleshooting.md +147 -0
  237. package/skills/deco-images-media/references/video.md +122 -0
  238. package/skills/deco-make-editable/SKILL.md +94 -0
  239. package/skills/deco-make-editable/references/a11y-and-e2e.md +104 -0
  240. package/skills/deco-make-editable/references/content-shapes.md +198 -0
  241. package/skills/deco-make-editable/references/from-figma.md +110 -0
  242. package/skills/deco-make-editable/references/i18n-fields.md +112 -0
  243. package/skills/deco-make-editable/references/inventory.md +79 -0
  244. package/skills/deco-make-editable/references/pixel-parity.md +175 -0
  245. package/skills/deco-make-editable/references/seeding-content.md +119 -0
  246. package/skills/deco-nextjs-site/SKILL.md +74 -0
  247. package/skills/deco-nextjs-site/references/caching.md +116 -0
  248. package/skills/deco-nextjs-site/references/metadata-seo.md +100 -0
  249. package/skills/deco-nextjs-site/references/proxy-and-drafts.md +177 -0
  250. package/skills/deco-nextjs-site/references/rendering.md +171 -0
  251. package/skills/deco-nextjs-site/references/setup.md +190 -0
  252. package/skills/deco-nextjs-site/references/studio-bridge.md +130 -0
  253. package/skills/deco-site-authoring/SKILL.md +75 -0
  254. package/skills/deco-site-authoring/references/lazy-blocks.md +155 -0
  255. package/skills/deco-site-authoring/references/loaders.md +192 -0
  256. package/skills/deco-site-authoring/references/pages.md +156 -0
  257. package/skills/deco-site-authoring/references/review-before-publish.md +95 -0
  258. package/skills/deco-site-authoring/references/sections.md +158 -0
  259. package/skills/deco-site-authoring/references/seo.md +116 -0
  260. package/skills/deco-site-workflow/SKILL.md +92 -0
  261. package/skills/deco-site-workflow/references/check.md +116 -0
  262. package/skills/deco-site-workflow/references/cli-reference.md +104 -0
  263. package/skills/deco-site-workflow/references/content-layout.md +93 -0
  264. package/skills/deco-site-workflow/references/content-sync.md +146 -0
  265. package/skills/deco-site-workflow/references/delivery.md +51 -0
  266. package/skills/deco-site-workflow/references/deploy.md +87 -0
  267. package/skills/deco-site-workflow/references/schema.md +173 -0
  268. package/skills/deco-site-workflow/references/serve-and-studio.md +138 -0
  269. package/skills/deco-storefront-caching/SKILL.md +67 -0
  270. package/skills/deco-storefront-caching/references/cache-keys.md +129 -0
  271. package/skills/deco-storefront-caching/references/case-study.md +82 -0
  272. package/skills/deco-storefront-caching/references/egress-traps.md +153 -0
  273. package/skills/deco-storefront-caching/references/nextjs.md +60 -0
  274. package/skills/deco-storefront-caching/references/perf-guardrails-e2e.md +123 -0
  275. package/skills/deco-storefront-caching/references/verification.md +136 -0
  276. package/skills/deco-storefront-caching/references/worker-page-cache.md +160 -0
  277. package/skills/deco-storefront-caching/scripts/html-anatomy.mjs +97 -0
  278. package/skills/deco-storefront-performance/SKILL.md +81 -0
  279. package/skills/deco-storefront-performance/references/cls-third-party.md +90 -0
  280. package/skills/deco-storefront-performance/references/hydration.md +116 -0
  281. package/skills/deco-storefront-performance/references/loaders-n-plus-1.md +107 -0
  282. package/skills/deco-storefront-performance/references/navigation-ux.md +130 -0
  283. package/skills/deco-storefront-performance/references/payload-trim.md +163 -0
  284. package/skills/deco-storefront-performance/references/render-location.md +152 -0
  285. package/skills/deco-storefront-performance/references/request-dedupe.md +147 -0
  286. package/skills/deco-storefront-performance/references/trace-reading.md +79 -0
  287. package/skills/deco-storefront-performance/references/worker-memory.md +176 -0
  288. package/skills/deco-tanstack-site/SKILL.md +68 -0
  289. package/skills/deco-tanstack-site/references/document-and-security.md +155 -0
  290. package/skills/deco-tanstack-site/references/router-and-navigation.md +137 -0
  291. package/skills/deco-tanstack-site/references/routes-and-pages.md +183 -0
  292. package/skills/deco-tanstack-site/references/server-functions.md +123 -0
  293. package/skills/deco-tanstack-site/references/setup.md +153 -0
  294. package/skills/deco-tanstack-site/references/worker-entry.md +152 -0
  295. package/skills/deco-v7-to-v8-migration/SKILL.md +122 -0
  296. package/skills/deco-v7-to-v8-migration/references/caching-and-privacy.md +10 -0
  297. package/skills/deco-v7-to-v8-migration/references/content.md +25 -0
  298. package/skills/deco-v7-to-v8-migration/references/editor-forms.md +27 -0
  299. package/skills/deco-v7-to-v8-migration/references/faststore.md +40 -0
  300. package/skills/deco-v7-to-v8-migration/references/framework-code.md +53 -0
  301. package/skills/deco-v7-to-v8-migration/references/hosted-releases.md +16 -0
  302. package/skills/deco-v7-to-v8-migration/references/import-map.md +81 -0
  303. package/skills/deco-v7-to-v8-migration/references/legacy-names.md +33 -0
  304. package/skills/deco-v7-to-v8-migration/references/manual-steps.md +10 -0
  305. package/skills/deco-v7-to-v8-migration/references/native-apps.md +43 -0
  306. package/skills/deco-v7-to-v8-migration/references/nextjs.md +19 -0
  307. package/skills/deco-v7-to-v8-migration/references/parity.md +66 -0
  308. package/skills/deco-v7-to-v8-migration/references/rendering.md +13 -0
  309. package/skills/deco-v7-to-v8-migration/references/running-the-script.md +29 -0
  310. package/skills/deco-v7-to-v8-migration/references/script-steps.md +13 -0
  311. package/skills/deco-v7-to-v8-migration/references/server-functions.md +15 -0
  312. package/skills/deco-v7-to-v8-migration/references/sibling-port.md +11 -0
  313. package/skills/deco-v7-to-v8-migration/references/site-code.md +15 -0
  314. package/skills/deco-v7-to-v8-migration/references/telemetry.md +10 -0
  315. package/skills/deco-v7-to-v8-migration/references/verify.md +20 -0
  316. package/skills/deco-v7-to-v8-migration/scripts/apps.ts +297 -0
  317. package/skills/deco-v7-to-v8-migration/scripts/asyncRendering.ts +73 -0
  318. package/skills/deco-v7-to-v8-migration/scripts/blockMap.ts +584 -0
  319. package/skills/deco-v7-to-v8-migration/scripts/ciSchemaCheck.ts +145 -0
  320. package/skills/deco-v7-to-v8-migration/scripts/compat.ts +357 -0
  321. package/skills/deco-v7-to-v8-migration/scripts/content.ts +121 -0
  322. package/skills/deco-v7-to-v8-migration/scripts/experiments.ts +81 -0
  323. package/skills/deco-v7-to-v8-migration/scripts/framework.ts +61 -0
  324. package/skills/deco-v7-to-v8-migration/scripts/imageCopy.ts +276 -0
  325. package/skills/deco-v7-to-v8-migration/scripts/imageModule.ts +285 -0
  326. package/skills/deco-v7-to-v8-migration/scripts/imports.ts +942 -0
  327. package/skills/deco-v7-to-v8-migration/scripts/invoke.ts +624 -0
  328. package/skills/deco-v7-to-v8-migration/scripts/legacyNames.ts +45 -0
  329. package/skills/deco-v7-to-v8-migration/scripts/main.ts +59 -0
  330. package/skills/deco-v7-to-v8-migration/scripts/matchers.ts +41 -0
  331. package/skills/deco-v7-to-v8-migration/scripts/migrate.ts +176 -0
  332. package/skills/deco-v7-to-v8-migration/scripts/redirects.ts +455 -0
  333. package/skills/deco-v7-to-v8-migration/scripts/report.ts +50 -0
  334. package/skills/deco-v7-to-v8-migration/scripts/scaffold.ts +1119 -0
  335. package/skills/deco-v7-to-v8-migration/scripts/secrets.ts +35 -0
  336. package/skills/deco-v7-to-v8-migration/scripts/sectionLoaders.ts +216 -0
  337. package/skills/deco-v7-to-v8-migration/scripts/siteSettings.ts +261 -0
  338. package/skills/deco-v7-to-v8-migration/scripts/stubs.ts +388 -0
  339. package/skills/deco-v7-to-v8-migration/scripts/tsconfig.json +7 -0
  340. package/skills/deco-v7-to-v8-migration/scripts/vendor.ts +249 -0
  341. package/skills/deco-v7-to-v8-migration/scripts/vtexInvoke.ts +240 -0
  342. package/skills/deco-v7-to-v8-migration/scripts/walk.ts +30 -0
  343. package/skills/deco-variants/SKILL.md +57 -0
  344. package/skills/deco-variants/references/caching-variants.md +63 -0
  345. package/skills/deco-variants/references/custom-matchers.md +83 -0
  346. package/skills/deco-variants/references/draft-preview.md +59 -0
  347. package/skills/deco-variants/references/experiments-and-campaigns.md +104 -0
  348. package/skills/deco-variants/references/multivariate.md +85 -0
  349. package/skills/deco-variants/references/v7-matchers.md +71 -0
  350. package/src/index.ts +2 -0
  351. package/src/protocol/channel.ts +127 -0
  352. package/src/protocol/client.ts +2 -2
  353. package/src/protocol/conformance/blockMetaVectors.json +214 -0
  354. package/src/protocol/conformance/contentHashFixtures.ts +74 -0
  355. package/src/protocol/conformance/index.ts +9 -1
  356. package/src/protocol/conformance/vectors.ts +36 -0
  357. package/src/protocol/index.ts +32 -0
  358. package/src/protocol/keys.ts +1 -1
  359. package/src/v8/background.ts +42 -0
  360. package/src/v8/blockMeta.ts +100 -0
  361. package/src/v8/blockStore.ts +124 -0
  362. package/src/v8/boundedJson.ts +20 -2
  363. package/src/v8/boundedMap.ts +53 -0
  364. package/src/v8/builtins/data.ts +26 -2
  365. package/src/v8/builtins/index.ts +2 -1
  366. package/src/v8/builtins/legacy.ts +6 -3
  367. package/src/v8/canonical.ts +15 -0
  368. package/src/v8/cli/builtins.ts +1 -0
  369. package/src/v8/cli/check/index.ts +97 -7
  370. package/src/v8/cli/content.ts +49 -91
  371. package/src/v8/cli/index.ts +2 -2
  372. package/src/v8/cli/remote/commands.ts +834 -0
  373. package/src/v8/cli/remote/diff.ts +100 -0
  374. package/src/v8/cli/remote/env.ts +107 -0
  375. package/src/v8/cli/remote/http.ts +484 -0
  376. package/src/v8/cli/remote/local.ts +343 -0
  377. package/src/v8/cli/root.ts +40 -0
  378. package/src/v8/cli/run.ts +366 -135
  379. package/src/v8/cli/schema/builtinSchemas.ts +29 -10
  380. package/src/v8/cli/schema/generate.ts +1 -1
  381. package/src/v8/cli/skills.ts +91 -0
  382. package/src/v8/client.ts +162 -60
  383. package/src/v8/cms.ts +62 -53
  384. package/src/v8/content.ts +179 -229
  385. package/src/v8/contentIndex.ts +183 -0
  386. package/src/v8/draft.ts +15 -14
  387. package/src/v8/draftChanges.ts +151 -85
  388. package/src/v8/errors.ts +37 -0
  389. package/src/v8/hostedSource.ts +67 -0
  390. package/src/v8/identity.ts +1 -1
  391. package/src/v8/index.ts +1 -0
  392. package/src/v8/matchRoute.ts +7 -4
  393. package/src/v8/pin.ts +176 -0
  394. package/src/v8/preview/StudioBridge.ts +8 -10
  395. package/src/v8/preview/StudioChannel.ts +116 -0
  396. package/src/v8/preview/index.ts +3 -0
  397. package/src/v8/remoteLoader.ts +350 -286
  398. package/src/v8/resolver.ts +56 -33
  399. package/src/v8/revisionId.ts +14 -0
  400. package/src/v8/settings.ts +10 -9
  401. package/src/v8/telemetry.ts +3 -3
  402. package/src/v8/types.ts +52 -40
  403. package/src/v8/variants.ts +30 -26
  404. package/src/v8/vite/index.ts +3 -3
  405. package/dist/v8/cli/serve/server.d.ts +0 -29
  406. package/dist/v8/cli/serve/server.d.ts.map +0 -1
  407. package/dist/v8/cli/serve/server.js +0 -296
  408. package/dist/v8/cli/serve/server.js.map +0 -1
  409. package/src/v8/cli/serve/server.ts +0 -348
@@ -0,0 +1,132 @@
1
+ # Commerce types and helpers (`@decocms/compat-v7/commerce`)
2
+
3
+ The v8 clients return each platform's own types. The shared schema.org model that v7
4
+ sections were written against (`Product`, `Offer`, `ProductListingPage`…) lives in
5
+ `@decocms/compat-v7`, under `/commerce`. It is v7's `@decocms/apps-commerce`, file for
6
+ file: replace `@decocms/apps-commerce/` with `@decocms/compat-v7/commerce/` in an import
7
+ and nothing else changes. None of it uses React.
8
+
9
+ The site's converters (vendored from v7, see [`vendored-loaders.md`](./vendored-loaders.md))
10
+ turn the client's response into these types. Sections, JSON-LD and analytics read them.
11
+
12
+ ## Entry points
13
+
14
+ | Import | What is there |
15
+ |---|---|
16
+ | `@decocms/compat-v7/commerce/types` (also `/commerce`) | The schema.org types and the analytics events; re-exports the cart types |
17
+ | `@decocms/compat-v7/commerce/types/cart` | `CartSection`, `SECTIONS_MINIMAL`, `SECTIONS_DRAWER`, `SECTIONS_FULL`, `defaultSectionsFor`, cart projections, `MinicartItem` |
18
+ | `/commerce/sdk/formatPrice` | `formatPrice(price, currency = "BRL", locale = "pt-BR")`, `formatPriceRange` |
19
+ | `/commerce/sdk/useOffer` | `useOffer(aggregateOffer)`, `bestInstallment` |
20
+ | `/commerce/sdk/useVariantPossibilities` | `useVariantPossibilities` |
21
+ | `/commerce/sdk/url` | `relative(link, { stripSearchParams? })` |
22
+ | `/commerce/sdk/analytics` | `mapProductToAnalyticsItem`, `mapProductToAnalyticsItemList`, category mappers |
23
+ | `/commerce/utils/productToAnalyticsItem` | v7's other `mapProductToAnalyticsItem` (`{ product, breadcrumbList, price, listPrice, … }`) |
24
+ | `/commerce/utils/canonical` | `canonicalFromBreadcrumblist` |
25
+ | `/commerce/utils/constants` | `DEFAULT_IMAGE` |
26
+ | `/commerce/utils/filters` | `parseRange`, `formatRange` |
27
+ | `/commerce/utils/stateByZip` | `getStateFromZip` (default export) |
28
+
29
+ `useOffer` and `useVariantPossibilities` are plain functions despite the names. They are
30
+ safe in Server Components and loaders.
31
+
32
+ ## The model
33
+
34
+ ```
35
+ Product (a SKU) productID, sku, name, offers?: AggregateOffer,
36
+ isVariantOf?: ProductGroup, additionalProperty?, image?
37
+ ProductGroup (the product) productGroupID, hasVariant: ProductLeaf[], model?
38
+ AggregateOffer highPrice, lowPrice, offerCount, offers: Offer[]
39
+ Offer price, availability, inventoryLevel, priceSpecification[],
40
+ seller?, sellerName?, priceValidUntil?, teasers?, giftSkuIds?
41
+ ProductDetailsPage breadcrumbList, product, seo?
42
+ ProductListingPage breadcrumb, filters, products, pageInfo, sortOptions, seo?
43
+ ```
44
+
45
+ `ProductLeaf` is `Product` without `isVariantOf`, which stops the variant tree from
46
+ recursing. Filters are `FilterToggle` (`values`, `quantity`) or `FilterRange`
47
+ (`values: { min, max }`). Navigation is `SiteNavigationElement` with `children`.
48
+
49
+ `availability` is a schema.org URL (`"https://schema.org/InStock"`,
50
+ `"https://schema.org/OutOfStock"`, …). Price types are URLs too:
51
+ `priceType` is `ListPrice`, `SalePrice`, `SRP`, …; an installment is a
52
+ `UnitPriceSpecification` with `priceComponentType: "https://schema.org/Installment"`,
53
+ `billingDuration` (count) and `billingIncrement` (value per installment).
54
+
55
+ ## Rules a converter must keep
56
+
57
+ Sections and helpers assume these. A converter that breaks one renders wrong prices
58
+ or breaks the cart, without a type error.
59
+
60
+ 1. **`Offer.seller` is the seller ID** (`"1"`), never the display name. The name goes
61
+ in `sellerName`. Add-to-cart sends `seller` to the platform.
62
+ 2. **Prices are decimals** (`199.9`), not cents.
63
+ 3. **`Product.productID` and `Product.sku` are the SKU ID**; `ProductGroup.productGroupID`
64
+ is the product ID. Cart calls use the SKU.
65
+ 4. **Put the offer to show first.** `useOffer` reads `offers[0]` only: its price, the
66
+ `ListPrice` spec as `listPrice`, and the best installment (lowest total, then most
67
+ installments).
68
+ 5. **`category` uses `>` between levels** (`"Furniture > Chairs"`). The analytics
69
+ mappers split on `>`.
70
+ 6. **Breadcrumb items are `ListItem<string>`** with a 1-based `position` and the URL in
71
+ `item`. `canonicalFromBreadcrumblist` returns the `item` with the highest position.
72
+ 7. **Images are `ImageObject[]`** with `url` and `alternateName`.
73
+
74
+ ## VTEX to schema.org, field by field
75
+
76
+ The v7 VTEX converter mapped the client's response like this. Use it to check or
77
+ write a converter. VTEX field names are those of `@decocms/apps-vtex`'s response
78
+ types.
79
+
80
+ **Product (one SKU)**
81
+
82
+ | VTEX | schema.org |
83
+ |---|---|
84
+ | `item.itemId` | `productID`, `sku` |
85
+ | `item.name` | `name` |
86
+ | `item.complementName` | `alternateName` |
87
+ | `item.ean` | `gtin` |
88
+ | `product.description` | `description` |
89
+ | `product.brand`, `brandId`, `brandImageUrl` | `brand.name`, `brand["@id"]`, `brand.logo` |
90
+ | `product.releaseDate` | `releaseDate` |
91
+ | `product.categories[0]` | `category` (split on `/`, joined with ` > `) |
92
+ | `product.productId` | `inProductGroupWithID` |
93
+ | `item.images[]`: `imageUrl`, `imageText`, `imageLabel` | `image[]`: `url`, `alternateName`, `name` |
94
+
95
+ **ProductGroup (`isVariantOf`)**: `productId` → `productGroupID`; each of `product.items`
96
+ → `hasVariant` (converted without `isVariantOf`); `/{linkText}/p` → `url`;
97
+ `productName` → `name`; `productReference` → `model`.
98
+
99
+ **Offer (one seller of the SKU)**
100
+
101
+ | VTEX `sellers[]` | schema.org |
102
+ |---|---|
103
+ | `sellerId` | `seller` |
104
+ | `sellerName` | `sellerName` |
105
+ | `sellerDefault: true` | `identifier: "default"` |
106
+ | `commertialOffer.spotPrice ?? Price` | `price` |
107
+ | `commertialOffer.PriceValidUntil` | `priceValidUntil` |
108
+ | `commertialOffer.AvailableQuantity` | `inventoryLevel.value`; `> 0` → `InStock`, else `OutOfStock` |
109
+ | `commertialOffer.GiftSkuIds`, `teasers` | `giftSkuIds`, `teasers` |
110
+ | `ListPrice` / `Price` / `PriceWithoutDiscount` | `priceSpecification` with `ListPrice` / `SalePrice` / `SRP` |
111
+ | `Installments[]`: `NumberOfInstallments`, `Value`, `TotalValuePlusInterestRate`, `PaymentSystemName`, `Name` | installment specs: `billingDuration`, `billingIncrement`, `price`, `name`, `description` |
112
+
113
+ **Breadcrumb**: each segment of `categories[0]` is a `ListItem` with its position and
114
+ URL, then the product name last, at `/{linkText}/p`.
115
+
116
+ **Legacy or Intelligent Search?** A product with `origin === "intelligent-search"`
117
+ came from `vtex.search.*`; otherwise it came from the legacy Catalog
118
+ (`vtex.catalog.products`), whose items have a different shape (`LegacyItem`).
119
+
120
+ `additionalProperty` collects SKU variations, categories, clusters
121
+ (`productClusters`), reference IDs, `estimatedDateArrival` and `modalType`.
122
+
123
+ ## Cart sections
124
+
125
+ `CartSection` names VTEX's orderForm sections. Three presets:
126
+
127
+ - `SECTIONS_MINIMAL`: `items`, `totalizers`, `messages`. Enough after add-to-cart.
128
+ - `SECTIONS_DRAWER`: what a minicart renders (adds marketing, sellers, rates, shipping…).
129
+ - `SECTIONS_FULL`: all fifteen, v7's old default.
130
+
131
+ Pass one as `sections` to `vtex.checkout.orderForm` ([`vtex.md`](./vtex.md)). A smaller
132
+ set means a smaller payload from VTEX and less work to serialize.
@@ -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.