@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.
- package/dist/index.d.ts +1 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +1 -1
- package/dist/index.js.map +1 -1
- package/dist/protocol/channel.d.ts +98 -0
- package/dist/protocol/channel.d.ts.map +1 -0
- package/dist/protocol/channel.js +58 -0
- package/dist/protocol/channel.js.map +1 -0
- package/dist/protocol/client.js +2 -2
- package/dist/protocol/client.js.map +1 -1
- package/dist/protocol/conformance/blockMetaVectors.json +214 -0
- package/dist/protocol/conformance/contentHashFixtures.d.ts +22 -0
- package/dist/protocol/conformance/contentHashFixtures.d.ts.map +1 -1
- package/dist/protocol/conformance/contentHashFixtures.js +55 -0
- package/dist/protocol/conformance/contentHashFixtures.js.map +1 -1
- package/dist/protocol/conformance/index.d.ts +2 -1
- package/dist/protocol/conformance/index.d.ts.map +1 -1
- package/dist/protocol/conformance/index.js +2 -1
- package/dist/protocol/conformance/index.js.map +1 -1
- package/dist/protocol/conformance/vectors.d.ts +33 -0
- package/dist/protocol/conformance/vectors.d.ts.map +1 -0
- package/dist/protocol/conformance/vectors.js +3 -0
- package/dist/protocol/conformance/vectors.js.map +1 -0
- package/dist/protocol/index.d.ts +11 -1
- package/dist/protocol/index.d.ts.map +1 -1
- package/dist/protocol/index.js +11 -1
- package/dist/protocol/index.js.map +1 -1
- package/dist/protocol/keys.d.ts +1 -1
- package/dist/protocol/keys.js +1 -1
- package/dist/v8/background.d.ts +13 -0
- package/dist/v8/background.d.ts.map +1 -1
- package/dist/v8/background.js +41 -0
- package/dist/v8/background.js.map +1 -1
- package/dist/v8/blockMeta.d.ts +27 -0
- package/dist/v8/blockMeta.d.ts.map +1 -0
- package/dist/v8/blockMeta.js +75 -0
- package/dist/v8/blockMeta.js.map +1 -0
- package/dist/v8/blockStore.d.ts +43 -0
- package/dist/v8/blockStore.d.ts.map +1 -0
- package/dist/v8/blockStore.js +95 -0
- package/dist/v8/blockStore.js.map +1 -0
- package/dist/v8/boundedJson.d.ts +5 -0
- package/dist/v8/boundedJson.d.ts.map +1 -1
- package/dist/v8/boundedJson.js +10 -2
- package/dist/v8/boundedJson.js.map +1 -1
- package/dist/v8/boundedMap.d.ts +19 -0
- package/dist/v8/boundedMap.d.ts.map +1 -0
- package/dist/v8/boundedMap.js +52 -0
- package/dist/v8/boundedMap.js.map +1 -0
- package/dist/v8/builtins/data.d.ts +18 -2
- package/dist/v8/builtins/data.d.ts.map +1 -1
- package/dist/v8/builtins/data.js +17 -1
- package/dist/v8/builtins/data.js.map +1 -1
- package/dist/v8/builtins/index.d.ts.map +1 -1
- package/dist/v8/builtins/index.js +2 -1
- package/dist/v8/builtins/index.js.map +1 -1
- package/dist/v8/builtins/legacy.d.ts +6 -3
- package/dist/v8/builtins/legacy.d.ts.map +1 -1
- package/dist/v8/builtins/legacy.js +6 -3
- package/dist/v8/builtins/legacy.js.map +1 -1
- package/dist/v8/canonical.d.ts +8 -0
- package/dist/v8/canonical.d.ts.map +1 -1
- package/dist/v8/canonical.js +15 -0
- package/dist/v8/canonical.js.map +1 -1
- package/dist/v8/cli/builtins.d.ts.map +1 -1
- package/dist/v8/cli/builtins.js +1 -0
- package/dist/v8/cli/builtins.js.map +1 -1
- package/dist/v8/cli/check/index.d.ts +10 -0
- package/dist/v8/cli/check/index.d.ts.map +1 -1
- package/dist/v8/cli/check/index.js +91 -7
- package/dist/v8/cli/check/index.js.map +1 -1
- package/dist/v8/cli/content.d.ts +12 -25
- package/dist/v8/cli/content.d.ts.map +1 -1
- package/dist/v8/cli/content.js +46 -75
- package/dist/v8/cli/content.js.map +1 -1
- package/dist/v8/cli/index.d.ts +2 -2
- package/dist/v8/cli/index.d.ts.map +1 -1
- package/dist/v8/cli/index.js +2 -2
- package/dist/v8/cli/index.js.map +1 -1
- package/dist/v8/cli/remote/commands.d.ts +71 -0
- package/dist/v8/cli/remote/commands.d.ts.map +1 -0
- package/dist/v8/cli/remote/commands.js +644 -0
- package/dist/v8/cli/remote/commands.js.map +1 -0
- package/dist/v8/cli/remote/diff.d.ts +15 -0
- package/dist/v8/cli/remote/diff.d.ts.map +1 -0
- package/dist/v8/cli/remote/diff.js +102 -0
- package/dist/v8/cli/remote/diff.js.map +1 -0
- package/dist/v8/cli/remote/env.d.ts +35 -0
- package/dist/v8/cli/remote/env.d.ts.map +1 -0
- package/dist/v8/cli/remote/env.js +84 -0
- package/dist/v8/cli/remote/env.js.map +1 -0
- package/dist/v8/cli/remote/http.d.ts +149 -0
- package/dist/v8/cli/remote/http.d.ts.map +1 -0
- package/dist/v8/cli/remote/http.js +381 -0
- package/dist/v8/cli/remote/http.js.map +1 -0
- package/dist/v8/cli/remote/local.d.ts +90 -0
- package/dist/v8/cli/remote/local.d.ts.map +1 -0
- package/dist/v8/cli/remote/local.js +309 -0
- package/dist/v8/cli/remote/local.js.map +1 -0
- package/dist/v8/cli/root.d.ts +29 -0
- package/dist/v8/cli/root.d.ts.map +1 -1
- package/dist/v8/cli/root.js +28 -0
- package/dist/v8/cli/root.js.map +1 -1
- package/dist/v8/cli/run.d.ts +13 -1
- package/dist/v8/cli/run.d.ts.map +1 -1
- package/dist/v8/cli/run.js +310 -124
- package/dist/v8/cli/run.js.map +1 -1
- package/dist/v8/cli/schema/builtinSchemas.d.ts.map +1 -1
- package/dist/v8/cli/schema/builtinSchemas.js +28 -10
- package/dist/v8/cli/schema/builtinSchemas.js.map +1 -1
- package/dist/v8/cli/schema/generate.js +1 -1
- package/dist/v8/cli/schema/generate.js.map +1 -1
- package/dist/v8/cli/skills.d.ts +25 -0
- package/dist/v8/cli/skills.d.ts.map +1 -0
- package/dist/v8/cli/skills.js +70 -0
- package/dist/v8/cli/skills.js.map +1 -0
- package/dist/v8/client.d.ts +9 -9
- package/dist/v8/client.d.ts.map +1 -1
- package/dist/v8/client.js +138 -50
- package/dist/v8/client.js.map +1 -1
- package/dist/v8/cms.d.ts +2 -1
- package/dist/v8/cms.d.ts.map +1 -1
- package/dist/v8/cms.js +55 -46
- package/dist/v8/cms.js.map +1 -1
- package/dist/v8/content.d.ts +39 -78
- package/dist/v8/content.d.ts.map +1 -1
- package/dist/v8/content.js +155 -195
- package/dist/v8/content.js.map +1 -1
- package/dist/v8/contentIndex.d.ts +71 -0
- package/dist/v8/contentIndex.d.ts.map +1 -0
- package/dist/v8/contentIndex.js +137 -0
- package/dist/v8/contentIndex.js.map +1 -0
- package/dist/v8/draft.d.ts +7 -7
- package/dist/v8/draft.d.ts.map +1 -1
- package/dist/v8/draft.js +10 -9
- package/dist/v8/draft.js.map +1 -1
- package/dist/v8/draftChanges.d.ts +59 -32
- package/dist/v8/draftChanges.d.ts.map +1 -1
- package/dist/v8/draftChanges.js +139 -75
- package/dist/v8/draftChanges.js.map +1 -1
- package/dist/v8/errors.d.ts +21 -0
- package/dist/v8/errors.d.ts.map +1 -1
- package/dist/v8/errors.js +22 -0
- package/dist/v8/errors.js.map +1 -1
- package/dist/v8/hostedSource.d.ts +57 -0
- package/dist/v8/hostedSource.d.ts.map +1 -0
- package/dist/v8/hostedSource.js +18 -0
- package/dist/v8/hostedSource.js.map +1 -0
- package/dist/v8/identity.d.ts +1 -1
- package/dist/v8/identity.js +1 -1
- package/dist/v8/index.d.ts +1 -0
- package/dist/v8/index.d.ts.map +1 -1
- package/dist/v8/index.js +1 -0
- package/dist/v8/index.js.map +1 -1
- package/dist/v8/matchRoute.js +7 -4
- package/dist/v8/matchRoute.js.map +1 -1
- package/dist/v8/pin.d.ts +34 -0
- package/dist/v8/pin.d.ts.map +1 -0
- package/dist/v8/pin.js +156 -0
- package/dist/v8/pin.js.map +1 -0
- package/dist/v8/preview/StudioBridge.d.ts +8 -8
- package/dist/v8/preview/StudioBridge.d.ts.map +1 -1
- package/dist/v8/preview/StudioBridge.js +8 -10
- package/dist/v8/preview/StudioBridge.js.map +1 -1
- package/dist/v8/preview/StudioChannel.d.ts +51 -0
- package/dist/v8/preview/StudioChannel.d.ts.map +1 -0
- package/dist/v8/preview/StudioChannel.js +104 -0
- package/dist/v8/preview/StudioChannel.js.map +1 -0
- package/dist/v8/preview/index.d.ts +3 -0
- package/dist/v8/preview/index.d.ts.map +1 -1
- package/dist/v8/preview/index.js +3 -0
- package/dist/v8/preview/index.js.map +1 -1
- package/dist/v8/remoteLoader.d.ts +42 -5
- package/dist/v8/remoteLoader.d.ts.map +1 -1
- package/dist/v8/remoteLoader.js +317 -259
- package/dist/v8/remoteLoader.js.map +1 -1
- package/dist/v8/resolver.d.ts +22 -8
- package/dist/v8/resolver.d.ts.map +1 -1
- package/dist/v8/resolver.js +37 -32
- package/dist/v8/resolver.js.map +1 -1
- package/dist/v8/revisionId.d.ts +11 -0
- package/dist/v8/revisionId.d.ts.map +1 -0
- package/dist/v8/revisionId.js +13 -0
- package/dist/v8/revisionId.js.map +1 -0
- package/dist/v8/settings.d.ts +6 -6
- package/dist/v8/settings.d.ts.map +1 -1
- package/dist/v8/settings.js +8 -7
- package/dist/v8/settings.js.map +1 -1
- package/dist/v8/telemetry.d.ts +4 -2
- package/dist/v8/telemetry.d.ts.map +1 -1
- package/dist/v8/telemetry.js +2 -2
- package/dist/v8/telemetry.js.map +1 -1
- package/dist/v8/types.d.ts +52 -40
- package/dist/v8/types.d.ts.map +1 -1
- package/dist/v8/variants.d.ts +7 -2
- package/dist/v8/variants.d.ts.map +1 -1
- package/dist/v8/variants.js +21 -24
- package/dist/v8/variants.js.map +1 -1
- package/dist/v8/vite/index.d.ts +2 -2
- package/dist/v8/vite/index.js +1 -1
- package/dist/v8/vite/index.js.map +1 -1
- package/package.json +3 -2
- package/skills/deco-apps/SKILL.md +82 -0
- package/skills/deco-apps/references/algolia.md +51 -0
- package/skills/deco-apps/references/commerce-types.md +132 -0
- package/skills/deco-apps/references/instrumented-fetch.md +144 -0
- package/skills/deco-apps/references/magento.md +55 -0
- package/skills/deco-apps/references/messaging.md +76 -0
- package/skills/deco-apps/references/shopify.md +69 -0
- package/skills/deco-apps/references/vendored-loaders.md +135 -0
- package/skills/deco-apps/references/vtex-cookies-auth.md +146 -0
- package/skills/deco-apps/references/vtex.md +150 -0
- package/skills/deco-apps/references/wake.md +75 -0
- package/skills/deco-cms-schema/SKILL.md +80 -0
- package/skills/deco-cms-schema/references/annotations.md +147 -0
- package/skills/deco-cms-schema/references/content-hygiene.md +91 -0
- package/skills/deco-cms-schema/references/formats-and-widgets.md +112 -0
- package/skills/deco-cms-schema/references/shapes-that-break-the-form.md +165 -0
- package/skills/deco-cms-schema/references/types-to-fields.md +112 -0
- package/skills/deco-go-live/SKILL.md +127 -0
- package/skills/deco-go-live/references/content-releases.md +90 -0
- package/skills/deco-go-live/references/process.md +106 -0
- package/skills/deco-go-live/references/proxy-headers-checkout.md +139 -0
- package/skills/deco-go-live/references/qa-checklist-template.md +150 -0
- package/skills/deco-go-live/references/qa-inventory.md +120 -0
- package/skills/deco-go-live/references/react-spa.md +183 -0
- package/skills/deco-go-live/references/seo-analytics.md +114 -0
- package/skills/deco-go-live/references/traffic-ramp.md +87 -0
- package/skills/deco-go-live/references/worker-runtime.md +93 -0
- package/skills/deco-go-live/scripts/preflight.sh +221 -0
- package/skills/deco-images-media/SKILL.md +64 -0
- package/skills/deco-images-media/references/asset-upload.md +191 -0
- package/skills/deco-images-media/references/components-per-binding.md +167 -0
- package/skills/deco-images-media/references/providers-and-cdn.md +145 -0
- package/skills/deco-images-media/references/quality-and-lcp.md +93 -0
- package/skills/deco-images-media/references/troubleshooting.md +147 -0
- package/skills/deco-images-media/references/video.md +122 -0
- package/skills/deco-make-editable/SKILL.md +94 -0
- package/skills/deco-make-editable/references/a11y-and-e2e.md +104 -0
- package/skills/deco-make-editable/references/content-shapes.md +198 -0
- package/skills/deco-make-editable/references/from-figma.md +110 -0
- package/skills/deco-make-editable/references/i18n-fields.md +112 -0
- package/skills/deco-make-editable/references/inventory.md +79 -0
- package/skills/deco-make-editable/references/pixel-parity.md +175 -0
- package/skills/deco-make-editable/references/seeding-content.md +119 -0
- package/skills/deco-nextjs-site/SKILL.md +74 -0
- package/skills/deco-nextjs-site/references/caching.md +116 -0
- package/skills/deco-nextjs-site/references/metadata-seo.md +100 -0
- package/skills/deco-nextjs-site/references/proxy-and-drafts.md +177 -0
- package/skills/deco-nextjs-site/references/rendering.md +171 -0
- package/skills/deco-nextjs-site/references/setup.md +190 -0
- package/skills/deco-nextjs-site/references/studio-bridge.md +130 -0
- package/skills/deco-site-authoring/SKILL.md +75 -0
- package/skills/deco-site-authoring/references/lazy-blocks.md +155 -0
- package/skills/deco-site-authoring/references/loaders.md +192 -0
- package/skills/deco-site-authoring/references/pages.md +156 -0
- package/skills/deco-site-authoring/references/review-before-publish.md +95 -0
- package/skills/deco-site-authoring/references/sections.md +158 -0
- package/skills/deco-site-authoring/references/seo.md +116 -0
- package/skills/deco-site-workflow/SKILL.md +92 -0
- package/skills/deco-site-workflow/references/check.md +116 -0
- package/skills/deco-site-workflow/references/cli-reference.md +104 -0
- package/skills/deco-site-workflow/references/content-layout.md +93 -0
- package/skills/deco-site-workflow/references/content-sync.md +146 -0
- package/skills/deco-site-workflow/references/delivery.md +51 -0
- package/skills/deco-site-workflow/references/deploy.md +87 -0
- package/skills/deco-site-workflow/references/schema.md +173 -0
- package/skills/deco-site-workflow/references/serve-and-studio.md +138 -0
- package/skills/deco-storefront-caching/SKILL.md +67 -0
- package/skills/deco-storefront-caching/references/cache-keys.md +129 -0
- package/skills/deco-storefront-caching/references/case-study.md +82 -0
- package/skills/deco-storefront-caching/references/egress-traps.md +153 -0
- package/skills/deco-storefront-caching/references/nextjs.md +60 -0
- package/skills/deco-storefront-caching/references/perf-guardrails-e2e.md +123 -0
- package/skills/deco-storefront-caching/references/verification.md +136 -0
- package/skills/deco-storefront-caching/references/worker-page-cache.md +160 -0
- package/skills/deco-storefront-caching/scripts/html-anatomy.mjs +97 -0
- package/skills/deco-storefront-performance/SKILL.md +81 -0
- package/skills/deco-storefront-performance/references/cls-third-party.md +90 -0
- package/skills/deco-storefront-performance/references/hydration.md +116 -0
- package/skills/deco-storefront-performance/references/loaders-n-plus-1.md +107 -0
- package/skills/deco-storefront-performance/references/navigation-ux.md +130 -0
- package/skills/deco-storefront-performance/references/payload-trim.md +163 -0
- package/skills/deco-storefront-performance/references/render-location.md +152 -0
- package/skills/deco-storefront-performance/references/request-dedupe.md +147 -0
- package/skills/deco-storefront-performance/references/trace-reading.md +79 -0
- package/skills/deco-storefront-performance/references/worker-memory.md +176 -0
- package/skills/deco-tanstack-site/SKILL.md +68 -0
- package/skills/deco-tanstack-site/references/document-and-security.md +155 -0
- package/skills/deco-tanstack-site/references/router-and-navigation.md +137 -0
- package/skills/deco-tanstack-site/references/routes-and-pages.md +183 -0
- package/skills/deco-tanstack-site/references/server-functions.md +123 -0
- package/skills/deco-tanstack-site/references/setup.md +153 -0
- package/skills/deco-tanstack-site/references/worker-entry.md +152 -0
- package/skills/deco-v7-to-v8-migration/SKILL.md +122 -0
- package/skills/deco-v7-to-v8-migration/references/caching-and-privacy.md +10 -0
- package/skills/deco-v7-to-v8-migration/references/content.md +25 -0
- package/skills/deco-v7-to-v8-migration/references/editor-forms.md +27 -0
- package/skills/deco-v7-to-v8-migration/references/faststore.md +40 -0
- package/skills/deco-v7-to-v8-migration/references/framework-code.md +53 -0
- package/skills/deco-v7-to-v8-migration/references/hosted-releases.md +16 -0
- package/skills/deco-v7-to-v8-migration/references/import-map.md +81 -0
- package/skills/deco-v7-to-v8-migration/references/legacy-names.md +33 -0
- package/skills/deco-v7-to-v8-migration/references/manual-steps.md +10 -0
- package/skills/deco-v7-to-v8-migration/references/native-apps.md +43 -0
- package/skills/deco-v7-to-v8-migration/references/nextjs.md +19 -0
- package/skills/deco-v7-to-v8-migration/references/parity.md +66 -0
- package/skills/deco-v7-to-v8-migration/references/rendering.md +13 -0
- package/skills/deco-v7-to-v8-migration/references/running-the-script.md +29 -0
- package/skills/deco-v7-to-v8-migration/references/script-steps.md +13 -0
- package/skills/deco-v7-to-v8-migration/references/server-functions.md +15 -0
- package/skills/deco-v7-to-v8-migration/references/sibling-port.md +11 -0
- package/skills/deco-v7-to-v8-migration/references/site-code.md +15 -0
- package/skills/deco-v7-to-v8-migration/references/telemetry.md +10 -0
- package/skills/deco-v7-to-v8-migration/references/verify.md +20 -0
- package/skills/deco-v7-to-v8-migration/scripts/apps.ts +297 -0
- package/skills/deco-v7-to-v8-migration/scripts/asyncRendering.ts +73 -0
- package/skills/deco-v7-to-v8-migration/scripts/blockMap.ts +584 -0
- package/skills/deco-v7-to-v8-migration/scripts/ciSchemaCheck.ts +145 -0
- package/skills/deco-v7-to-v8-migration/scripts/compat.ts +357 -0
- package/skills/deco-v7-to-v8-migration/scripts/content.ts +121 -0
- package/skills/deco-v7-to-v8-migration/scripts/experiments.ts +81 -0
- package/skills/deco-v7-to-v8-migration/scripts/framework.ts +61 -0
- package/skills/deco-v7-to-v8-migration/scripts/imageCopy.ts +276 -0
- package/skills/deco-v7-to-v8-migration/scripts/imageModule.ts +285 -0
- package/skills/deco-v7-to-v8-migration/scripts/imports.ts +942 -0
- package/skills/deco-v7-to-v8-migration/scripts/invoke.ts +624 -0
- package/skills/deco-v7-to-v8-migration/scripts/legacyNames.ts +45 -0
- package/skills/deco-v7-to-v8-migration/scripts/main.ts +59 -0
- package/skills/deco-v7-to-v8-migration/scripts/matchers.ts +41 -0
- package/skills/deco-v7-to-v8-migration/scripts/migrate.ts +176 -0
- package/skills/deco-v7-to-v8-migration/scripts/redirects.ts +455 -0
- package/skills/deco-v7-to-v8-migration/scripts/report.ts +50 -0
- package/skills/deco-v7-to-v8-migration/scripts/scaffold.ts +1119 -0
- package/skills/deco-v7-to-v8-migration/scripts/secrets.ts +35 -0
- package/skills/deco-v7-to-v8-migration/scripts/sectionLoaders.ts +216 -0
- package/skills/deco-v7-to-v8-migration/scripts/siteSettings.ts +261 -0
- package/skills/deco-v7-to-v8-migration/scripts/stubs.ts +388 -0
- package/skills/deco-v7-to-v8-migration/scripts/tsconfig.json +7 -0
- package/skills/deco-v7-to-v8-migration/scripts/vendor.ts +249 -0
- package/skills/deco-v7-to-v8-migration/scripts/vtexInvoke.ts +240 -0
- package/skills/deco-v7-to-v8-migration/scripts/walk.ts +30 -0
- package/skills/deco-variants/SKILL.md +57 -0
- package/skills/deco-variants/references/caching-variants.md +63 -0
- package/skills/deco-variants/references/custom-matchers.md +83 -0
- package/skills/deco-variants/references/draft-preview.md +59 -0
- package/skills/deco-variants/references/experiments-and-campaigns.md +104 -0
- package/skills/deco-variants/references/multivariate.md +85 -0
- package/skills/deco-variants/references/v7-matchers.md +71 -0
- package/src/index.ts +2 -0
- package/src/protocol/channel.ts +127 -0
- package/src/protocol/client.ts +2 -2
- package/src/protocol/conformance/blockMetaVectors.json +214 -0
- package/src/protocol/conformance/contentHashFixtures.ts +74 -0
- package/src/protocol/conformance/index.ts +9 -1
- package/src/protocol/conformance/vectors.ts +36 -0
- package/src/protocol/index.ts +32 -0
- package/src/protocol/keys.ts +1 -1
- package/src/v8/background.ts +42 -0
- package/src/v8/blockMeta.ts +100 -0
- package/src/v8/blockStore.ts +124 -0
- package/src/v8/boundedJson.ts +20 -2
- package/src/v8/boundedMap.ts +53 -0
- package/src/v8/builtins/data.ts +26 -2
- package/src/v8/builtins/index.ts +2 -1
- package/src/v8/builtins/legacy.ts +6 -3
- package/src/v8/canonical.ts +15 -0
- package/src/v8/cli/builtins.ts +1 -0
- package/src/v8/cli/check/index.ts +97 -7
- package/src/v8/cli/content.ts +49 -91
- package/src/v8/cli/index.ts +2 -2
- package/src/v8/cli/remote/commands.ts +834 -0
- package/src/v8/cli/remote/diff.ts +100 -0
- package/src/v8/cli/remote/env.ts +107 -0
- package/src/v8/cli/remote/http.ts +484 -0
- package/src/v8/cli/remote/local.ts +343 -0
- package/src/v8/cli/root.ts +40 -0
- package/src/v8/cli/run.ts +366 -135
- package/src/v8/cli/schema/builtinSchemas.ts +29 -10
- package/src/v8/cli/schema/generate.ts +1 -1
- package/src/v8/cli/skills.ts +91 -0
- package/src/v8/client.ts +162 -60
- package/src/v8/cms.ts +62 -53
- package/src/v8/content.ts +179 -229
- package/src/v8/contentIndex.ts +183 -0
- package/src/v8/draft.ts +15 -14
- package/src/v8/draftChanges.ts +151 -85
- package/src/v8/errors.ts +37 -0
- package/src/v8/hostedSource.ts +67 -0
- package/src/v8/identity.ts +1 -1
- package/src/v8/index.ts +1 -0
- package/src/v8/matchRoute.ts +7 -4
- package/src/v8/pin.ts +176 -0
- package/src/v8/preview/StudioBridge.ts +8 -10
- package/src/v8/preview/StudioChannel.ts +116 -0
- package/src/v8/preview/index.ts +3 -0
- package/src/v8/remoteLoader.ts +350 -286
- package/src/v8/resolver.ts +56 -33
- package/src/v8/revisionId.ts +14 -0
- package/src/v8/settings.ts +10 -9
- package/src/v8/telemetry.ts +3 -3
- package/src/v8/types.ts +52 -40
- package/src/v8/variants.ts +30 -26
- package/src/v8/vite/index.ts +3 -3
- package/dist/v8/cli/serve/server.d.ts +0 -29
- package/dist/v8/cli/serve/server.d.ts.map +0 -1
- package/dist/v8/cli/serve/server.js +0 -296
- package/dist/v8/cli/serve/server.js.map +0 -1
- 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).
|