@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,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.
@@ -0,0 +1,150 @@
1
+ # `@decocms/apps-vtex`
2
+
3
+ A typed client for VTEX's Intelligent Search, legacy Catalog, Checkout, Session, Master
4
+ Data v1 and IO GraphQL APIs. It returns VTEX's own response types. Cookies and
5
+ `Set-Cookie` are covered in [`vtex-cookies-auth.md`](./vtex-cookies-auth.md).
6
+
7
+ ## Configure
8
+
9
+ ```ts
10
+ import { createVtexClient } from "@decocms/apps-vtex";
11
+
12
+ export const vtex = createVtexClient({
13
+ account: "mystore",
14
+ appKey: secrets.VTEX_APP_KEY, // from the deploy platform's secrets; optional,
15
+ appToken: secrets.VTEX_APP_TOKEN, // sent only when both are set
16
+ salesChannel: "1", // default `sc`
17
+ locale: "pt-BR", // default Intelligent Search locale
18
+ // environment: "vtexcommercestable", domain: "com.br" (defaults)
19
+ // fetch, retry, circuitBreaker: see instrumented-fetch.md
20
+ });
21
+ ```
22
+
23
+ - Requests go to `https://{account}.{environment}.{domain}`. `io.graphql` goes to
24
+ `https://{account}.myvtex.com/_v/private/graphql/v1`.
25
+ - `appKey` and `appToken` are sent as `X-VTEX-API-AppKey` / `X-VTEX-API-AppToken`, but
26
+ **only on calls without a `cookie`**. A call made for a shopper goes out as the
27
+ shopper. With app credentials, VTEX would return the orderForm with profile data
28
+ unmasked.
29
+ - Exported names: `createVtexClient`, `VtexClient`, `VtexClientConfig`, `VtexError`,
30
+ `VtexRequestOptions`, `VtexCheckoutOptions`, `VtexResponse`, `VtexSearchArgs`,
31
+ `VtexCatalogSearchArgs`. VTEX's response types (`ProductSearchResult`, `OrderForm`,
32
+ `Session`…) are not exported by name. Get them from the client:
33
+ `Awaited<ReturnType<VtexClient["search"]["products"]>>`.
34
+
35
+ Every operation accepts `cookie` and `signal` in its options.
36
+
37
+ ## Operations
38
+
39
+ **Intelligent Search** (GET, retried)
40
+
41
+ | Call | Endpoint |
42
+ |---|---|
43
+ | `search.products(args)` | `product_search` |
44
+ | `search.facets(args)` | `facets` |
45
+ | `search.suggestions(args)` | `search_suggestions` |
46
+ | `search.autocomplete(args)` | `autocomplete_suggestions` |
47
+ | `search.topSearches(args)` | `top_searches` |
48
+
49
+ `args`: `query`, `facets` (`[{ key, value }]`, sent as the path
50
+ `category-1/shirts/brand/acme`), `page` (1-based), `count`, `sort` (`"price:asc"`,
51
+ `"orders:desc"`…), `fuzzy` (`"0" | "1" | "auto"`), `locale`, `hideUnavailableItems`,
52
+ `simulationBehavior` (`"default" | "skip" | "only1P"`), `regionId`, `salesChannel`.
53
+ Suggestions, autocomplete and top searches ignore `facets`.
54
+
55
+ **Legacy Catalog** (GET, retried)
56
+
57
+ | Call | Notes |
58
+ |---|---|
59
+ | `catalog.products({ term, ft, fq, from, to, sort, salesChannel })` | `from`/`to` are 0-based inclusive (`_from`, `_to`); `fq` is a list; `sort` is the `O` value (`"OrderByPriceASC"`…) |
60
+ | `catalog.pageType(path)` | Page type of a URL path (`Product`, `Category`, `Brand`, `NotFound`…) |
61
+ | `catalog.crossSelling(type, productId)` | VTEX's cross-selling lists by type |
62
+ | `catalog.categoryTree(levels = 3)` | |
63
+
64
+ `term` and `pageType`'s `path` usually come from the shopper's URL. The client encodes
65
+ them segment by segment and throws on `.` or `..` segments, so a path can't climb to
66
+ another endpoint or add a query while credentials are attached.
67
+
68
+ **Checkout** (POST, never retried; shopper-scoped)
69
+
70
+ | Call | Returns |
71
+ |---|---|
72
+ | `checkout.orderForm({ cookie, sections?, salesChannel? })` | `VtexResponse<OrderForm>` |
73
+ | `checkout.addItems(orderFormId, [{ id, quantity, seller }], options)` | `VtexResponse<OrderForm>` |
74
+ | `checkout.updateItems(orderFormId, [{ index, quantity }], options)` | `VtexResponse<OrderForm>` |
75
+ | `checkout.addCoupon(orderFormId, text, options)` | `VtexResponse<OrderForm>` |
76
+ | `checkout.attachment(orderFormId, name, body, options)` | `VtexResponse<OrderForm>` |
77
+ | `checkout.simulation({ items, postalCode?, country? }, options)` | `SimulationOrderForm` |
78
+ | `checkout.regions({ postalCode, country, salesChannel? })` (GET) | `[{ id, sellers }]` |
79
+
80
+ `VtexResponse<T>` is `{ data, setCookies }`. Forward `setCookies` to the browser.
81
+
82
+ **Session**: `sessions.get({ cookie, items? })` and `sessions.update(publicProps, { cookie })`,
83
+ both `VtexResponse`. `items` is a list such as `["profile.email", "profile.isAuthenticated"]`.
84
+
85
+ **Master Data v1**
86
+
87
+ - `masterdata.search(entity, { where, fields, sort, from = 0, to = 10, cookie })`:
88
+ `from`/`to` go in the `REST-Range` header.
89
+ - `masterdata.create(entity, document, { cookie })`: when the client has app
90
+ credentials, it sends them and leaves the shopper's cookie out (Master Data refuses
91
+ anonymous writes). It returns `{ Id, Href, DocumentId }`.
92
+
93
+ **IO GraphQL**: `io.graphql<T>({ query, variables?, operationName? }, { cookie })`
94
+ returns `data`. GraphQL `errors` (sent with HTTP 200) throw `VtexError("io.graphql", 200)`
95
+ without the messages, since they can echo inputs.
96
+
97
+ ## Sales channel (`sc`)
98
+
99
+ A wrong or missing sales channel gives wrong prices, missing products or checkout
100
+ errors. VTEX answers 200 with a well-formed body either way, so nothing fails loudly.
101
+
102
+ - The client sends `sc` on Intelligent Search, `catalog.products`, every orderForm and
103
+ simulation call, and `regions`. The per-call `salesChannel` wins over the config's.
104
+ - With no channel configured or passed, no `sc` is sent (never an empty `sc=`). VTEX
105
+ then uses the account default.
106
+ - `pageType`, `crossSelling` and `categoryTree` send no `sc`.
107
+ - A store with several channels reads the shopper's channel per request (v7 read the
108
+ `VTEXSC` cookie) and passes it on cart calls, the same one the search used.
109
+
110
+ ## Region (`regionId`)
111
+
112
+ Regionalized stores price and stock by region. Get the region for a postal code with
113
+ `checkout.regions({ postalCode, country })`; its `id` is the `regionId`. VTEX also keeps
114
+ it in the shopper's `vtex_segment` cookie.
115
+
116
+ - Pass `regionId` to `search.*`. It goes on the query string, so it is part of the URL
117
+ and of any cache key built from it.
118
+ - A block function has no request, so it can't read `vtex_segment` itself. Fetch
119
+ regionalized results where you have the request, or pass the region in as an input.
120
+ Pages split by region are a cache decision: see `deco-storefront-caching`.
121
+ - Delivery promise badges, PLP delivery filters and postal-code capture are in the
122
+ `vtex-delivery-promise` skill (decocms/skills).
123
+
124
+ ## orderForm sections
125
+
126
+ `checkout.orderForm` sends `{ expectedOrderFormSections: sections }` when you pass
127
+ `sections`, and `{}` otherwise, which per the client asks for every section. Ask for
128
+ what the view needs: `SECTIONS_MINIMAL`, `SECTIONS_DRAWER` or `SECTIONS_FULL` from
129
+ `@decocms/compat-v7/commerce/types/cart` ([`commerce-types.md`](./commerce-types.md)).
130
+
131
+ `addItems`, `updateItems` and `addCoupon` send only their payload. `attachment` sends
132
+ the `body` you give it, so include `expectedOrderFormSections` there if you need it.
133
+
134
+ ## Images
135
+
136
+ `@decocms/apps-vtex/image` exports `ImageProvider`s for `createImageUrl` from
137
+ `@decocms/blocks/image`: `vtexCatalog()`, `vtexCatalogFrame({ frame? })`,
138
+ `vtexCatalogWebp({ quality? })` and `vtexFileManager({ via: "query" | "thumbor" })`.
139
+ List them before `decoCdn`. Which one matches a site, and the binding wiring, is in
140
+ `deco-images-media`.
141
+
142
+ ## Failure modes
143
+
144
+ | Symptom | Likely cause |
145
+ |---|---|
146
+ | Prices differ from the VTEX storefront | No `sc`, or a different `sc` than the shopper's; `regionId` missing on a regionalized store |
147
+ | Cart empties after each action | `setCookies` not forwarded, or joined into one header ([`vtex-cookies-auth.md`](./vtex-cookies-auth.md)) |
148
+ | A new, empty cart on every call | The cart call got no `cookie`: with no `checkout.vtex.com` cookie VTEX starts a new cart, and the call goes out with the app's credentials instead of as the shopper |
149
+ | Every call fails at once for a few seconds | The circuit breaker opened after 5 failures in a row on any operation |
150
+ | `vtex: invalid path segment` | A `.` or `..` segment in `term` or `pageType`'s path |
@@ -0,0 +1,75 @@
1
+ # `@decocms/apps-wake`
2
+
3
+ A client for Wake's Storefront GraphQL API, plus the one checkout REST call a storefront
4
+ needs (`getLogin`). Operations and their generated types ship with it.
5
+
6
+ ## Configure
7
+
8
+ ```ts
9
+ import { createWakeClient } from "@decocms/apps-wake";
10
+
11
+ export const wake = createWakeClient(
12
+ {
13
+ storefrontToken: secrets.WAKE_TOKEN, // sent as TCS-Access-Token
14
+ checkoutUrl: "https://acme.checkout.fbits.store", // needed by getLogin
15
+ // storefrontEndpoint: defaults to https://storefront-api.fbits.net/graphql
16
+ },
17
+ { fetch: cachedFetch }, // optional
18
+ );
19
+ ```
20
+
21
+ Exports: `createWakeClient`, `WakeClient`, `WakeClientConfig`, `WakeClientOptions`,
22
+ `WakeError`, and the type `UserAuthenticate`.
23
+
24
+ ## Run an operation
25
+
26
+ ```ts
27
+ import { GetProduct } from "@decocms/apps-wake/storefront";
28
+ import type { GetProductQuery, GetProductQueryVariables } from "@decocms/apps-wake/storefront/types";
29
+
30
+ const data = await wake.graphql<GetProductQuery, GetProductQueryVariables>(GetProduct, { productId: 1 });
31
+ ```
32
+
33
+ - `graphql(document, variables?, { headers? })` takes a string or one of the operation
34
+ objects (`{ query, fragments? }`) from `/storefront`, and returns `data`.
35
+ - `/storefront` exports Wake's Storefront operations: `GetProduct`, `GetProducts`, `Search`,
36
+ `Autocomplete`, `ProductRecommendations`, `GetURL`, `Hotsite`, `Shop`,
37
+ `GetCart`, `CreateCart`, `AddItemToCart`, `RemoveItemFromCart`, `AddCoupon`,
38
+ `RemoveCoupon`, `AddKit`, `RemoveKit`, `ShippingQuotes`, `GetUser`, `GetWishlist`,
39
+ `WishlistAddProduct`, `WishlistRemoveProduct`, `ProductRestockAlert`,
40
+ `CreateNewsletterRegister`, `CreateProductReview`, `SendGenericForm`, `GetBuyList`,
41
+ `GetPartners`, `CheckoutPartnerAssociate`, `CheckoutPartnerDisassociate` and
42
+ `productOptions`, plus two fragment strings (`Customer`, `WishlistReducedProduct`).
43
+ `/storefront/types` has a `…Query` or `…Mutation` type and a `…Variables` type for
44
+ each, named after the GraphQL operation inside, not the export: `GetURL` →
45
+ `GetUrlQuery`, `GetBuyList` → `BuyListQuery`.
46
+ - Per-call `headers` add things such as `X-Forwarded-For` or a customer access token.
47
+ They can't override the token or the content type.
48
+ - The label is the document's operation name; an unnamed one is `graphql`.
49
+ - This call takes no `signal`.
50
+
51
+ ## `getLogin(cookie)`
52
+
53
+ `GET {checkoutUrl}/api/Login/Get` with the shopper's checkout cookies (the
54
+ `fbits-login` cookie). It returns the shopper's account (`UserAuthenticate`: `Id`,
55
+ `Email`, `Name`, `Cpf`, `CustomerAccessToken`, …) or `null` when they aren't signed in
56
+ (401, 403 or 404). Any other failure, such as a 429, throws `WakeError`. It throws a
57
+ plain `Error` when `checkoutUrl` isn't set.
58
+
59
+ Customer operations take the returned `CustomerAccessToken` as the
60
+ `customerAccessToken` variable (`GetUser`, `WishlistAddProduct`, …). Both the cookie
61
+ and the token are per shopper: run these in a server function and don't cache the
62
+ results.
63
+
64
+ ## Errors
65
+
66
+ `WakeError` has `operation`, `status` and `graphqlErrors` (how many GraphQL errors the
67
+ response had; 0 for an HTTP failure). A response with no `data` also throws. No retries
68
+ or circuit breaker.
69
+
70
+ ## Vendored GraphQL documents
71
+
72
+ A migrated site may keep v7's `queries.ts` under `src/vendor/wake`. Don't run a
73
+ formatter over it: a reflowed document changes every request body, and a replaying
74
+ parity harness misses every call. Prefer the operations from
75
+ `@decocms/apps-wake/storefront` once parity is done.
@@ -0,0 +1,80 @@
1
+ ---
2
+ name: deco-cms-schema
3
+ description: "@decocms/blocks 8: how a section's Props type becomes the Studio form. Covers what `deco schema` (packages/blocks/src/v8/cli/schema/typeToSchema.ts) reads: the JSDoc tags (@title, @description, @titleBy, @format, @options, @hide, @ignore, @default, validation tags), widget aliases (ImageWidget, RichText, Color, Secret…) and format aliases, what each TypeScript shape turns into (literal unions, object unions, Lazy<T>, ReactNode, block-fillable fields), and declaration order as form order. Also the shapes that hurt editors (sibling anonymous inline types, one-to-many relations linked by a typed key, null holes in arrays, enum plus dead fields instead of a union), blank-on-empty sections, dead fields, and layout controls posing as content. Load it before adding or changing props on a section, loader or page, when a Studio form looks wrong (raw labels, missing widget, select with no options, unlabeled list rows), or when deco check rejects content after a Props change."
4
+ ---
5
+
6
+ # Deco CMS schema
7
+
8
+ A section's `Props` type is the form an editor fills in Studio. A badly shaped
9
+ field is not ugly code: it is a person stuck in front of a form that does not
10
+ say what it wants.
11
+
12
+ Load this when you add or change props, when a Studio form looks wrong, or when
13
+ `deco check` starts failing after a type change.
14
+
15
+ ## The pipeline
16
+
17
+ 1. `deco schema` reads the default export of `.deco/index.ts` (the block map).
18
+ For each block it takes the first parameter's type and writes one JSON Schema
19
+ per type into `.deco/schema.gen.json`.
20
+ 2. `deco schema push` uploads that file so Studio can draw forms. Until it runs,
21
+ Studio shows the old form.
22
+ 3. `deco check` validates every saved block in content against the committed
23
+ `.deco/schema.gen.json`.
24
+
25
+ Nothing regenerates the schema for you during `vite dev`. Run `deco schema`
26
+ after each `Props` change, or keep `deco schema --watch` running. In CI,
27
+ `deco schema --check` fails when the committed file is stale. Running these
28
+ commands day to day is covered by the `deco-site-workflow` skill.
29
+
30
+ The generator writes warnings you should not ignore:
31
+
32
+ - `its props are typed any, so its form is empty`
33
+ - `its first parameter isn't an object of props, so its form is empty`
34
+ - `returns any, so it isn't offered for any field`
35
+
36
+ ## When to load what
37
+
38
+ | Reference | Load it when |
39
+ |---|---|
40
+ | [`references/annotations.md`](./references/annotations.md) | Writing JSDoc on a prop: which tags the generator reads, how values are coerced, `@hide` vs `@ignore`, `@options` lists, `/** */` vs `//` |
41
+ | [`references/formats-and-widgets.md`](./references/formats-and-widgets.md) | Picking a widget: image, video, color, rich text, HTML, textarea, date, secret; `@format` on a field or on a type alias; which formats `deco check` validates |
42
+ | [`references/types-to-fields.md`](./references/types-to-fields.md) | A field came out as the wrong kind: selects, variant pickers, section pickers, `Lazy<T>`, fields a loader can fill, hidden or missing props |
43
+ | [`references/shapes-that-break-the-form.md`](./references/shapes-that-break-the-form.md) | Designing arrays, relations and variants: sibling inline types, keyed relations, null holes, variants as a union |
44
+ | [`references/content-hygiene.md`](./references/content-hygiene.md) | Reviewing a section for editors: empty props, dead fields, layout controls, removing or renaming a field that has saved content |
45
+
46
+ ## Two rules that cover most of it
47
+
48
+ 1. **Give every prop a `@title`.** Without one the label is the identifier,
49
+ title-cased: `desktopCardWidth` becomes "Desktop Card Width". That is a
50
+ developer's word, not an editor's.
51
+ 2. **Declaration order is form order.** Fields come out in the order the type
52
+ declares them. Put what editors touch most at the top: content before
53
+ settings, the heading before the padding.
54
+
55
+ ## Checklist before `deco schema`
56
+
57
+ - [ ] Every prop has `@title`; `@description` where the field is not obvious,
58
+ written for the editor.
59
+ - [ ] Every type used as an array item has `@titleBy <field>`.
60
+ - [ ] Image, video, color, rich text, date and secret fields use a widget
61
+ alias or `@format`. No free-text field holding an image URL.
62
+ - [ ] `@options` is one JSON array, not one tag per choice.
63
+ - [ ] One-to-many relations nest. No two sibling arrays joined by a typed key.
64
+ - [ ] No two sibling fields share the same anonymous inline type.
65
+ - [ ] Arrays from `Props` are compacted before the first `.map`.
66
+ - [ ] The section renders something sensible with empty props.
67
+ - [ ] Every field reaches the DOM. No layout controls posing as content.
68
+
69
+ Then run `deco schema`, read `.deco/schema.gen.json` for the block you changed,
70
+ and run `deco check`.
71
+
72
+ ## Related skills
73
+
74
+ - `deco-site-workflow`: running `deco schema`, `deco schema push`, `deco check`.
75
+ - `deco-site-authoring`: writing the section itself.
76
+ - `deco-variants`: multivariate blocks inside arrays and fields.
77
+ - `deco-images-media`: what an image field's `@description` should say.
78
+ - `deco-make-editable`: turning hardcoded content into blocks.
79
+ - `deco-v7-to-v8-migration`: form differences between v7 and v8 after a
80
+ migration.
@@ -0,0 +1,147 @@
1
+ # Annotations `deco schema` reads
2
+
3
+ The generator is `packages/blocks/src/v8/cli/schema/typeToSchema.ts`
4
+ (`getJsDocTags` and `applyJsDocToSchema`). It was ported from v7's generator,
5
+ so most tags behave as they did. The differences are called out below.
6
+
7
+ ## Only `/** */` reaches the schema
8
+
9
+ The generator reads JSDoc blocks. A `//` comment never reaches the form. Use
10
+ the split on purpose:
11
+
12
+ - `/** @title … @description … */` is for whoever fills the form.
13
+ - `// comment` is for whoever reads the code: measurements, the reason behind
14
+ a value, links to tickets.
15
+
16
+ One section shipped a `@description` with twenty lines of typography
17
+ measurements and production URLs. The editor opened the form and got a spec
18
+ sheet where the help text should be.
19
+
20
+ The free text at the top of a JSDoc block becomes `description`. An explicit
21
+ `@description` tag replaces it.
22
+
23
+ A tag followed directly by punctuation (`@description: text`) is skipped. Write
24
+ `@description text`.
25
+
26
+ Put each prop's JSDoc on its own line, above the prop. A one-line type such
27
+ as `{ /** @title Ratio */ ratio: string }` loses the tag: the generator does
28
+ not read a JSDoc that sits on the same line, right after the opening brace.
29
+
30
+ ## Tag table
31
+
32
+ | Tag | What lands in the schema |
33
+ |---|---|
34
+ | `@title` | `title`, the field label. Without it: the prop name title-cased (`marginTop` → "Margin Top") |
35
+ | `@description` | `description`, help text |
36
+ | `@titleBy <field>` | Passed through. On an array item's type, names the field that labels each row |
37
+ | `@format <name>` | `format`, the widget. `datetime` is rewritten to `date-time`. See [formats-and-widgets.md](./formats-and-widgets.md) |
38
+ | `@default <value>` | `default`, coerced (below) |
39
+ | `@options <JSON array>` | `enum` (and `enumNames` when items have labels). Anything else is dropped (below) |
40
+ | `@hide` | `hide: "true"`. The field stays in the schema and in content, hidden from the form |
41
+ | `@ignore` | The prop is left out of the schema |
42
+ | `@examples` | `examples`: one per line, or a JSON value |
43
+ | `@minimum` `@maximum` `@exclusiveMinimum` `@exclusiveMaximum` `@multipleOf` | Numbers |
44
+ | `@minLength` `@maxLength` | Numbers |
45
+ | `@minItems` `@maxItems` `@minProperties` `@maxProperties` | Numbers |
46
+ | `@readOnly` `@writeOnly` `@deprecated` `@uniqueItems` | Booleans |
47
+ | Any other tag (`@pattern`, `@placeholder`, `@widget`, `@icon`, `@mode`…) | Passed through as a string. The generator gives it no meaning; whether Studio does is Studio's call |
48
+
49
+ `deco check` validates content with Ajv against the generated schema, so the
50
+ standard JSON Schema keywords above (`minimum`, `maxLength`, `pattern`,
51
+ `minItems`…) are enforced on saved content too, not only in the form.
52
+
53
+ ## Coercion
54
+
55
+ - **Numeric tags** become `Number(value)`. Always give a value: a bare
56
+ `@minimum` is `Number("true")`, which is `NaN` and is written to
57
+ `.deco/schema.gen.json` as `null`.
58
+ - **Boolean tags** are `true` when the value is `true` or missing. A bare
59
+ `@deprecated` or `@uniqueItems` works. Anything else, including `yes`, is
60
+ `false`.
61
+ - **`@default`**: `true`, `false` and `null` become those values; a numeric
62
+ string becomes a number; otherwise it is parsed as JSON, and if that fails it
63
+ is kept as the raw string. `@default hello` is `"hello"`;
64
+ `@default ["a","b"]` is an array.
65
+ - **`@hide`** sets `hide: "true"` whatever value follows it.
66
+
67
+ ## `@titleBy`: make array rows readable
68
+
69
+ Put `@titleBy` on every type used as an array item. Without it Studio has no
70
+ field to label rows with, and the editor opens each row to find out what it
71
+ is.
72
+
73
+ ```ts
74
+ /** @titleBy label */
75
+ export interface FooterLink {
76
+ /** @title Label */
77
+ label: string;
78
+ /** @title URL */
79
+ href: string;
80
+ }
81
+ ```
82
+
83
+ ## `@options`: one JSON array
84
+
85
+ A static list must be one JSON array in one tag:
86
+
87
+ ```ts
88
+ /**
89
+ * @title Align
90
+ * @options ["left", "center", "right"]
91
+ */
92
+ align: string;
93
+
94
+ /**
95
+ * @title Level
96
+ * @options [{ "value": "advanced", "label": "Advanced" }, { "value": "basic", "label": "Basic" }]
97
+ */
98
+ level: string;
99
+ ```
100
+
101
+ Items are strings, numbers or `{ value, label }` objects. Labels go to
102
+ `enumNames`.
103
+
104
+ What does not work in v8:
105
+
106
+ - **One `@options` tag per choice.** The generator keeps one value per tag
107
+ name, so only the last line survives. A single object is not an array, so it
108
+ is dropped and the field is plain text.
109
+ - **A loader path** (`@options site/loaders/x.ts`, often with
110
+ `@format dynamic-options`). The v8 site editor never runs site code, so the
111
+ list is dropped and the field is a text field. Make sure the field still accepts what an editor would type,
112
+ and rewrite any `@description` that promises suggestions.
113
+
114
+ A string-literal union needs no `@options`: `align: "left" | "center"` is
115
+ already a select. See [types-to-fields.md](./types-to-fields.md).
116
+
117
+ ## `@hide` vs `@ignore`
118
+
119
+ - `@ignore` removes the prop from the schema. Studio does not know it exists.
120
+ Saved content that still has the key fails `deco check` (a field the code
121
+ does not declare).
122
+ - `@hide` keeps the field in the schema and in content, and hides it in the
123
+ form. Use it for a value another tool or old content still sets, or a field
124
+ you are retiring (see [content-hygiene.md](./content-hygiene.md)).
125
+
126
+ A hidden prop that is not optional is not marked `required`, since no editor
127
+ can fill it, unless it has a `@default` (or a literal type, which gets a
128
+ default).
129
+
130
+ Leave a `//` comment that says why a field is hidden or ignored. Otherwise the
131
+ next person sees a prop that is mysteriously missing from the form.
132
+
133
+ ## Tags on a type, not a field
134
+
135
+ JSDoc on an interface or type alias applies to the object schema built from
136
+ it. This is how a union member gets its name in a variant picker:
137
+
138
+ ```ts
139
+ /** @title Wide */
140
+ export interface WideLayout {
141
+ /** @title Aspect ratio */
142
+ aspectRatio: string;
143
+ }
144
+ ```
145
+
146
+ `@format` on a type alias reaches every field of that type. See
147
+ [formats-and-widgets.md](./formats-and-widgets.md).