@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,132 @@
|
|
|
1
|
+
# Commerce types and helpers (`@decocms/compat-v7/commerce`)
|
|
2
|
+
|
|
3
|
+
The v8 clients return each platform's own types. The shared schema.org model that v7
|
|
4
|
+
sections were written against (`Product`, `Offer`, `ProductListingPage`…) lives in
|
|
5
|
+
`@decocms/compat-v7`, under `/commerce`. It is v7's `@decocms/apps-commerce`, file for
|
|
6
|
+
file: replace `@decocms/apps-commerce/` with `@decocms/compat-v7/commerce/` in an import
|
|
7
|
+
and nothing else changes. None of it uses React.
|
|
8
|
+
|
|
9
|
+
The site's converters (vendored from v7, see [`vendored-loaders.md`](./vendored-loaders.md))
|
|
10
|
+
turn the client's response into these types. Sections, JSON-LD and analytics read them.
|
|
11
|
+
|
|
12
|
+
## Entry points
|
|
13
|
+
|
|
14
|
+
| Import | What is there |
|
|
15
|
+
|---|---|
|
|
16
|
+
| `@decocms/compat-v7/commerce/types` (also `/commerce`) | The schema.org types and the analytics events; re-exports the cart types |
|
|
17
|
+
| `@decocms/compat-v7/commerce/types/cart` | `CartSection`, `SECTIONS_MINIMAL`, `SECTIONS_DRAWER`, `SECTIONS_FULL`, `defaultSectionsFor`, cart projections, `MinicartItem` |
|
|
18
|
+
| `/commerce/sdk/formatPrice` | `formatPrice(price, currency = "BRL", locale = "pt-BR")`, `formatPriceRange` |
|
|
19
|
+
| `/commerce/sdk/useOffer` | `useOffer(aggregateOffer)`, `bestInstallment` |
|
|
20
|
+
| `/commerce/sdk/useVariantPossibilities` | `useVariantPossibilities` |
|
|
21
|
+
| `/commerce/sdk/url` | `relative(link, { stripSearchParams? })` |
|
|
22
|
+
| `/commerce/sdk/analytics` | `mapProductToAnalyticsItem`, `mapProductToAnalyticsItemList`, category mappers |
|
|
23
|
+
| `/commerce/utils/productToAnalyticsItem` | v7's other `mapProductToAnalyticsItem` (`{ product, breadcrumbList, price, listPrice, … }`) |
|
|
24
|
+
| `/commerce/utils/canonical` | `canonicalFromBreadcrumblist` |
|
|
25
|
+
| `/commerce/utils/constants` | `DEFAULT_IMAGE` |
|
|
26
|
+
| `/commerce/utils/filters` | `parseRange`, `formatRange` |
|
|
27
|
+
| `/commerce/utils/stateByZip` | `getStateFromZip` (default export) |
|
|
28
|
+
|
|
29
|
+
`useOffer` and `useVariantPossibilities` are plain functions despite the names. They are
|
|
30
|
+
safe in Server Components and loaders.
|
|
31
|
+
|
|
32
|
+
## The model
|
|
33
|
+
|
|
34
|
+
```
|
|
35
|
+
Product (a SKU) productID, sku, name, offers?: AggregateOffer,
|
|
36
|
+
isVariantOf?: ProductGroup, additionalProperty?, image?
|
|
37
|
+
ProductGroup (the product) productGroupID, hasVariant: ProductLeaf[], model?
|
|
38
|
+
AggregateOffer highPrice, lowPrice, offerCount, offers: Offer[]
|
|
39
|
+
Offer price, availability, inventoryLevel, priceSpecification[],
|
|
40
|
+
seller?, sellerName?, priceValidUntil?, teasers?, giftSkuIds?
|
|
41
|
+
ProductDetailsPage breadcrumbList, product, seo?
|
|
42
|
+
ProductListingPage breadcrumb, filters, products, pageInfo, sortOptions, seo?
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
`ProductLeaf` is `Product` without `isVariantOf`, which stops the variant tree from
|
|
46
|
+
recursing. Filters are `FilterToggle` (`values`, `quantity`) or `FilterRange`
|
|
47
|
+
(`values: { min, max }`). Navigation is `SiteNavigationElement` with `children`.
|
|
48
|
+
|
|
49
|
+
`availability` is a schema.org URL (`"https://schema.org/InStock"`,
|
|
50
|
+
`"https://schema.org/OutOfStock"`, …). Price types are URLs too:
|
|
51
|
+
`priceType` is `ListPrice`, `SalePrice`, `SRP`, …; an installment is a
|
|
52
|
+
`UnitPriceSpecification` with `priceComponentType: "https://schema.org/Installment"`,
|
|
53
|
+
`billingDuration` (count) and `billingIncrement` (value per installment).
|
|
54
|
+
|
|
55
|
+
## Rules a converter must keep
|
|
56
|
+
|
|
57
|
+
Sections and helpers assume these. A converter that breaks one renders wrong prices
|
|
58
|
+
or breaks the cart, without a type error.
|
|
59
|
+
|
|
60
|
+
1. **`Offer.seller` is the seller ID** (`"1"`), never the display name. The name goes
|
|
61
|
+
in `sellerName`. Add-to-cart sends `seller` to the platform.
|
|
62
|
+
2. **Prices are decimals** (`199.9`), not cents.
|
|
63
|
+
3. **`Product.productID` and `Product.sku` are the SKU ID**; `ProductGroup.productGroupID`
|
|
64
|
+
is the product ID. Cart calls use the SKU.
|
|
65
|
+
4. **Put the offer to show first.** `useOffer` reads `offers[0]` only: its price, the
|
|
66
|
+
`ListPrice` spec as `listPrice`, and the best installment (lowest total, then most
|
|
67
|
+
installments).
|
|
68
|
+
5. **`category` uses `>` between levels** (`"Furniture > Chairs"`). The analytics
|
|
69
|
+
mappers split on `>`.
|
|
70
|
+
6. **Breadcrumb items are `ListItem<string>`** with a 1-based `position` and the URL in
|
|
71
|
+
`item`. `canonicalFromBreadcrumblist` returns the `item` with the highest position.
|
|
72
|
+
7. **Images are `ImageObject[]`** with `url` and `alternateName`.
|
|
73
|
+
|
|
74
|
+
## VTEX to schema.org, field by field
|
|
75
|
+
|
|
76
|
+
The v7 VTEX converter mapped the client's response like this. Use it to check or
|
|
77
|
+
write a converter. VTEX field names are those of `@decocms/apps-vtex`'s response
|
|
78
|
+
types.
|
|
79
|
+
|
|
80
|
+
**Product (one SKU)**
|
|
81
|
+
|
|
82
|
+
| VTEX | schema.org |
|
|
83
|
+
|---|---|
|
|
84
|
+
| `item.itemId` | `productID`, `sku` |
|
|
85
|
+
| `item.name` | `name` |
|
|
86
|
+
| `item.complementName` | `alternateName` |
|
|
87
|
+
| `item.ean` | `gtin` |
|
|
88
|
+
| `product.description` | `description` |
|
|
89
|
+
| `product.brand`, `brandId`, `brandImageUrl` | `brand.name`, `brand["@id"]`, `brand.logo` |
|
|
90
|
+
| `product.releaseDate` | `releaseDate` |
|
|
91
|
+
| `product.categories[0]` | `category` (split on `/`, joined with ` > `) |
|
|
92
|
+
| `product.productId` | `inProductGroupWithID` |
|
|
93
|
+
| `item.images[]`: `imageUrl`, `imageText`, `imageLabel` | `image[]`: `url`, `alternateName`, `name` |
|
|
94
|
+
|
|
95
|
+
**ProductGroup (`isVariantOf`)**: `productId` → `productGroupID`; each of `product.items`
|
|
96
|
+
→ `hasVariant` (converted without `isVariantOf`); `/{linkText}/p` → `url`;
|
|
97
|
+
`productName` → `name`; `productReference` → `model`.
|
|
98
|
+
|
|
99
|
+
**Offer (one seller of the SKU)**
|
|
100
|
+
|
|
101
|
+
| VTEX `sellers[]` | schema.org |
|
|
102
|
+
|---|---|
|
|
103
|
+
| `sellerId` | `seller` |
|
|
104
|
+
| `sellerName` | `sellerName` |
|
|
105
|
+
| `sellerDefault: true` | `identifier: "default"` |
|
|
106
|
+
| `commertialOffer.spotPrice ?? Price` | `price` |
|
|
107
|
+
| `commertialOffer.PriceValidUntil` | `priceValidUntil` |
|
|
108
|
+
| `commertialOffer.AvailableQuantity` | `inventoryLevel.value`; `> 0` → `InStock`, else `OutOfStock` |
|
|
109
|
+
| `commertialOffer.GiftSkuIds`, `teasers` | `giftSkuIds`, `teasers` |
|
|
110
|
+
| `ListPrice` / `Price` / `PriceWithoutDiscount` | `priceSpecification` with `ListPrice` / `SalePrice` / `SRP` |
|
|
111
|
+
| `Installments[]`: `NumberOfInstallments`, `Value`, `TotalValuePlusInterestRate`, `PaymentSystemName`, `Name` | installment specs: `billingDuration`, `billingIncrement`, `price`, `name`, `description` |
|
|
112
|
+
|
|
113
|
+
**Breadcrumb**: each segment of `categories[0]` is a `ListItem` with its position and
|
|
114
|
+
URL, then the product name last, at `/{linkText}/p`.
|
|
115
|
+
|
|
116
|
+
**Legacy or Intelligent Search?** A product with `origin === "intelligent-search"`
|
|
117
|
+
came from `vtex.search.*`; otherwise it came from the legacy Catalog
|
|
118
|
+
(`vtex.catalog.products`), whose items have a different shape (`LegacyItem`).
|
|
119
|
+
|
|
120
|
+
`additionalProperty` collects SKU variations, categories, clusters
|
|
121
|
+
(`productClusters`), reference IDs, `estimatedDateArrival` and `modalType`.
|
|
122
|
+
|
|
123
|
+
## Cart sections
|
|
124
|
+
|
|
125
|
+
`CartSection` names VTEX's orderForm sections. Three presets:
|
|
126
|
+
|
|
127
|
+
- `SECTIONS_MINIMAL`: `items`, `totalizers`, `messages`. Enough after add-to-cart.
|
|
128
|
+
- `SECTIONS_DRAWER`: what a minicart renders (adds marketing, sellers, rates, shipping…).
|
|
129
|
+
- `SECTIONS_FULL`: all fifteen, v7's old default.
|
|
130
|
+
|
|
131
|
+
Pass one as `sections` to `vtex.checkout.orderForm` ([`vtex.md`](./vtex.md)). A smaller
|
|
132
|
+
set means a smaller payload from VTEX and less work to serialize.
|
|
@@ -0,0 +1,144 @@
|
|
|
1
|
+
# Errors, retries, telemetry and upstream caching
|
|
2
|
+
|
|
3
|
+
Every `@decocms/apps-*` client sends its requests through `createInstrumentedFetch`
|
|
4
|
+
from `@decocms/blocks/fetch`. The client never calls `fetch` directly; a guardrail test
|
|
5
|
+
in the repo enforces it. This file covers what that layer does and what it means for
|
|
6
|
+
the site.
|
|
7
|
+
|
|
8
|
+
## What a request goes through
|
|
9
|
+
|
|
10
|
+
```ts
|
|
11
|
+
createInstrumentedFetch({
|
|
12
|
+
provider: "vtex", // the provider label
|
|
13
|
+
fetch?, // the fetch underneath; default globalThis.fetch
|
|
14
|
+
retry?: { attempts, backoffMs? }, // off unless set
|
|
15
|
+
circuitBreaker?: { failures, cooldownMs } // off unless set
|
|
16
|
+
})
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
The returned function takes `(input, init & { operation? })`. `operation` is the label
|
|
20
|
+
of the call (`"unknown"` when missing).
|
|
21
|
+
|
|
22
|
+
### Retries
|
|
23
|
+
|
|
24
|
+
- Only for idempotent methods: `GET`, `HEAD`, `OPTIONS`, `PUT`, `DELETE`. A `POST` is
|
|
25
|
+
never retried, so a checkout call is never sent twice.
|
|
26
|
+
- Retried on HTTP 429, 502, 503, 504 and on network errors. An abort or timeout
|
|
27
|
+
(`AbortError`, `TimeoutError`) is not retried.
|
|
28
|
+
- Backoff is `backoffMs * 2^n` (default `backoffMs` 100).
|
|
29
|
+
- Only the VTEX client turns retries on: 2 retries, 150 ms base. Pass `retry: false` in
|
|
30
|
+
its config to turn them off, or `{ attempts, backoffMs }` to change them.
|
|
31
|
+
|
|
32
|
+
### Circuit breaker
|
|
33
|
+
|
|
34
|
+
- After `failures` consecutive failures, every call fails fast for `cooldownMs`. A
|
|
35
|
+
failure is a network error or a status of 500 or more.
|
|
36
|
+
- The count lives in the client instance and covers **every operation** of that
|
|
37
|
+
client. If one VTEX endpoint keeps returning 5xx, search calls fail fast too until
|
|
38
|
+
the cooldown ends.
|
|
39
|
+
- Only the VTEX client turns it on: 5 failures, 5 s cooldown. Pass
|
|
40
|
+
`circuitBreaker: false` to turn it off.
|
|
41
|
+
- Create the client once per isolate. A new client per request starts at zero failures
|
|
42
|
+
every time, so the breaker never opens.
|
|
43
|
+
|
|
44
|
+
## Errors
|
|
45
|
+
|
|
46
|
+
Each client throws its own error class on a non-2xx response. It carries the operation
|
|
47
|
+
and the status and nothing from the response, so it is safe to log.
|
|
48
|
+
|
|
49
|
+
| Client | Class | Fields | Also thrown when |
|
|
50
|
+
|---|---|---|---|
|
|
51
|
+
| VTEX | `VtexError` | `operation`, `status` | `io.graphql` returns `errors` (status 200) |
|
|
52
|
+
| Shopify | `ShopifyError` | `operation`, `status`, `codes` | GraphQL `errors`, no `data`, or a body that isn't JSON |
|
|
53
|
+
| Wake | `WakeError` | `operation`, `status`, `graphqlErrors` | GraphQL `errors`, or no `data` |
|
|
54
|
+
| Magento | `MagentoError` | `operation`, `status`, `graphqlErrors` | GraphQL `errors`, or no `data` |
|
|
55
|
+
| Algolia | `AlgoliaError` | `operation`, `status` | |
|
|
56
|
+
| Resend | `ResendError` | `operation`, `status` | |
|
|
57
|
+
| SFMC Personalization | `SfmcPersonalizationError` | `operation`, `status` | |
|
|
58
|
+
|
|
59
|
+
Two failures don't use these classes:
|
|
60
|
+
|
|
61
|
+
- **Network errors** (DNS, reset, abort) are rethrown as the underlying `fetch` threw them.
|
|
62
|
+
- **An open circuit** throws a plain `Error`: `"<provider> <operation>: circuit open after N failures"`.
|
|
63
|
+
|
|
64
|
+
So a loader that wants to show a fallback catches all errors, not only the client's
|
|
65
|
+
class. Checking `error instanceof VtexError && error.status === 404` is fine for "not
|
|
66
|
+
found"; anything else is an outage.
|
|
67
|
+
|
|
68
|
+
## Telemetry
|
|
69
|
+
|
|
70
|
+
Each request is measured once, however many retries it took, as
|
|
71
|
+
`http.client.request.duration` (seconds) with these labels:
|
|
72
|
+
|
|
73
|
+
| Label | Value |
|
|
74
|
+
|---|---|
|
|
75
|
+
| `provider` | `vtex`, `shopify`, `wake`, `magento`, `algolia`, `resend`, `sfmc-personalization` |
|
|
76
|
+
| `operation` | The call's label (see below) |
|
|
77
|
+
| `status_class` | `2xx`, `4xx`, `5xx`, or `error` when there was no response |
|
|
78
|
+
| `cached` | `true` when the response has `x-cache: HIT` |
|
|
79
|
+
| `retries` | How many retries it took |
|
|
80
|
+
|
|
81
|
+
A request with no response also logs an error with code `FETCH_FAILED`. Sampled
|
|
82
|
+
requests produce a client span named `<provider> <operation>`. Nothing about the
|
|
83
|
+
request body, headers or query string is recorded. With no telemetry destination
|
|
84
|
+
configured on the CMS, nothing is recorded.
|
|
85
|
+
|
|
86
|
+
How each client names `operation`:
|
|
87
|
+
|
|
88
|
+
- **VTEX**: from the URL path, by an internal router (`intelligent-search.product_search`,
|
|
89
|
+
`checkout.orderform.items.add`, `catalog.pagetype`, `masterdata.<entity>`, `io.graphql`…).
|
|
90
|
+
A path the router doesn't know is `unknown`.
|
|
91
|
+
- **Shopify, Wake**: the GraphQL operation's name (`query ProductByHandle { … }` →
|
|
92
|
+
`ProductByHandle`). An unnamed document is `storefront.graphql` / `admin.graphql`
|
|
93
|
+
(Shopify) or `graphql` (Wake). **Name your GraphQL operations**, or every call shares
|
|
94
|
+
one label.
|
|
95
|
+
- **Magento**: the `operation` you pass to `request`/`rest`, and `operationName` for
|
|
96
|
+
`graphql`. Use the API's name for the call, never a URL.
|
|
97
|
+
- **Algolia**: `search`. **Resend**: `sendEmail`. **SFMC**: `sendEvent`.
|
|
98
|
+
|
|
99
|
+
## Upstream caching
|
|
100
|
+
|
|
101
|
+
Clients never cache. To cache upstream responses, pass your own `fetch`:
|
|
102
|
+
|
|
103
|
+
```ts
|
|
104
|
+
import { createVtexClient } from "@decocms/apps-vtex";
|
|
105
|
+
|
|
106
|
+
const vtex = createVtexClient({
|
|
107
|
+
account: "mystore",
|
|
108
|
+
fetch: cachedFetch, // your function with fetch's signature
|
|
109
|
+
});
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
- Your `fetch` gets the final URL and `RequestInit` (headers included). Its cache key
|
|
113
|
+
must include everything the response depends on: the full URL with its query
|
|
114
|
+
(`sc`, `regionId`, `locale`, page, facets) and any header that changes the answer.
|
|
115
|
+
- Set `x-cache: HIT` on a response served from the cache. Telemetry then counts it as
|
|
116
|
+
`cached=true`.
|
|
117
|
+
- Cache only shopper-invariant responses: requests sent **without** a `cookie` and
|
|
118
|
+
without a per-customer `Authorization`. Never cache checkout, session, profile or
|
|
119
|
+
Master Data writes. VTEX rules: [`vtex-cookies-auth.md`](./vtex-cookies-auth.md).
|
|
120
|
+
- Retries run around your `fetch`, and a cache hit counts as a success for the breaker.
|
|
121
|
+
|
|
122
|
+
How the site caches pages (the page cache, segments, private responses) is in the
|
|
123
|
+
`deco-storefront-caching` skill.
|
|
124
|
+
|
|
125
|
+
## Calling an endpoint no client covers
|
|
126
|
+
|
|
127
|
+
The clients cover a fixed set of operations. For anything else, build your own
|
|
128
|
+
instrumented fetch in the site so it is still measured:
|
|
129
|
+
|
|
130
|
+
```ts
|
|
131
|
+
import { createInstrumentedFetch } from "@decocms/blocks/fetch";
|
|
132
|
+
|
|
133
|
+
const vtexFetch = createInstrumentedFetch({ provider: "vtex" });
|
|
134
|
+
|
|
135
|
+
const response = await vtexFetch(`https://${account}.vtexcommercestable.com.br/api/…`, {
|
|
136
|
+
operation: "wishlist.get", // low-cardinality: no ids, slugs or search terms
|
|
137
|
+
headers: { cookie },
|
|
138
|
+
});
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
You then own what the client did for you: credentials, cookie sanitizing
|
|
142
|
+
([`vtex-cookies-auth.md`](./vtex-cookies-auth.md)), path encoding, error handling, and
|
|
143
|
+
not logging bodies. VTEX's operation router is internal to `@decocms/apps-vtex`, so
|
|
144
|
+
pass `operation` yourself.
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
# `@decocms/apps-magento`
|
|
2
|
+
|
|
3
|
+
A client for one Magento store's REST and GraphQL APIs. Everything goes to the store's
|
|
4
|
+
own origin.
|
|
5
|
+
|
|
6
|
+
## Configure
|
|
7
|
+
|
|
8
|
+
```ts
|
|
9
|
+
import { createMagentoClient } from "@decocms/apps-magento";
|
|
10
|
+
|
|
11
|
+
export const magento = createMagentoClient(
|
|
12
|
+
{
|
|
13
|
+
baseUrl: "https://store.example.com", // only its origin is used
|
|
14
|
+
apiKey: secrets.MAGENTO_API_KEY, // integration token, optional
|
|
15
|
+
originHeader: secrets.MAGENTO_ORIGIN, // optional, sent as x-origin-header
|
|
16
|
+
},
|
|
17
|
+
{ fetch: cachedFetch }, // optional
|
|
18
|
+
);
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
- `originHeader` is for stores behind an origin guard that expects a shared value.
|
|
22
|
+
- Exports: `createMagentoClient`, `MagentoClient`, `MagentoClientConfig`,
|
|
23
|
+
`MagentoClientOptions`, `MagentoError`, `MagentoRequestInit`.
|
|
24
|
+
|
|
25
|
+
## Three ways to call
|
|
26
|
+
|
|
27
|
+
| Call | Returns | `apiKey` sent by default |
|
|
28
|
+
|---|---|---|
|
|
29
|
+
| `request(path, { operation, authenticated?, ...init })` | the raw `Response` | yes |
|
|
30
|
+
| `rest<T>(path, { operation, authenticated?, ...init })` | parsed JSON (`undefined` on 204) | yes |
|
|
31
|
+
| `graphql<T, V>(query, variables, { operationName, headers?, authenticated? })` | `data` | no |
|
|
32
|
+
|
|
33
|
+
- **Paths only.** `request` and `rest` resolve the path against the store's origin and
|
|
34
|
+
throw if the result is another origin, so the token never leaves the store.
|
|
35
|
+
- **`operation` is required** on `request`/`rest`, and `operationName` on `graphql`. It
|
|
36
|
+
is the telemetry label and appears in errors. Use the API's own name (`getCart`), never
|
|
37
|
+
a URL.
|
|
38
|
+
- **The bearer token.** With `authenticated` true and an `apiKey`, the client sets
|
|
39
|
+
`Authorization: Bearer <apiKey>`, unless the call already set an `Authorization`
|
|
40
|
+
header. Pass a customer token as `Authorization` for customer calls; the integration
|
|
41
|
+
token never replaces it.
|
|
42
|
+
- **GraphQL is public** on Magento, so `graphql` sends the `apiKey` only with
|
|
43
|
+
`authenticated: true`. Pass the store view as a `Store` header when needed.
|
|
44
|
+
- `rest` sets `content-type: application/json` when there is a body and none was set.
|
|
45
|
+
`graphql` always sends `operationName` in the body.
|
|
46
|
+
|
|
47
|
+
## Errors
|
|
48
|
+
|
|
49
|
+
`MagentoError` has `operation`, `status` and `graphqlErrors` (0 for an HTTP failure).
|
|
50
|
+
`request` doesn't throw on an HTTP error; it returns the response. No retries or circuit
|
|
51
|
+
breaker.
|
|
52
|
+
|
|
53
|
+
Customer and cart calls carry a customer token or session: run them in a server
|
|
54
|
+
function and don't cache them. Caching catalog reads is the site's job:
|
|
55
|
+
[`instrumented-fetch.md`](./instrumented-fetch.md).
|
|
@@ -0,0 +1,76 @@
|
|
|
1
|
+
# Email and personalization: Resend, SFMC Personalization
|
|
2
|
+
|
|
3
|
+
Two small clients with one operation each. Both are POSTs, so neither is retried, and
|
|
4
|
+
neither may be cached.
|
|
5
|
+
|
|
6
|
+
## `@decocms/apps-resend`
|
|
7
|
+
|
|
8
|
+
```ts
|
|
9
|
+
import { createResendClient } from "@decocms/apps-resend";
|
|
10
|
+
|
|
11
|
+
export const resend = createResendClient({ apiKey: secrets.RESEND_API_KEY });
|
|
12
|
+
|
|
13
|
+
const { id } = await resend.sendEmail({
|
|
14
|
+
from: "Store <contact@store.example.com>",
|
|
15
|
+
to: ["shopper@example.com"],
|
|
16
|
+
subject: "Your quote",
|
|
17
|
+
html: "<p>…</p>",
|
|
18
|
+
reply_to: "sales@store.example.com",
|
|
19
|
+
});
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
- `sendEmail(email)` posts to `https://api.resend.com/emails` with
|
|
23
|
+
`Authorization: Bearer <apiKey>` and returns `{ id }`.
|
|
24
|
+
- `from` is required by the type: the API needs a sender. Other fields: `to`, `subject`,
|
|
25
|
+
`cc`, `bcc`, `reply_to`, `html`, `text`, `headers`.
|
|
26
|
+
- No retries or circuit breaker: sending an email isn't safe to repeat. On
|
|
27
|
+
`ResendError` (`operation`, `status`), decide in the site whether to retry.
|
|
28
|
+
- Default sender, recipients and subject belong to the site. A migrated site has them
|
|
29
|
+
in `resendSettings` (`emailFrom`, `emailTo`, `subject`) in `src/clients/resend.ts`;
|
|
30
|
+
v7's default sender was `Contact <onboarding@resend.dev>`.
|
|
31
|
+
- Exports: `createResendClient`, `ResendClient`, `ResendClientConfig`, `ResendError`,
|
|
32
|
+
`SendEmailOptions`, `CreateEmailOptions`, `CreateEmailResponseSuccess`.
|
|
33
|
+
|
|
34
|
+
Send from a server function or route handler (a contact form, a newsletter sign-up).
|
|
35
|
+
Validate and rate-limit the input there: the key sends mail as the store.
|
|
36
|
+
|
|
37
|
+
## `@decocms/apps-sfmc-personalization`
|
|
38
|
+
|
|
39
|
+
Salesforce Marketing Cloud Personalization (formerly Evergage), Event API.
|
|
40
|
+
|
|
41
|
+
```ts
|
|
42
|
+
import { createSfmcPersonalizationClient } from "@decocms/apps-sfmc-personalization";
|
|
43
|
+
|
|
44
|
+
export const sfmc = createSfmcPersonalizationClient({
|
|
45
|
+
baseUrl: "https://<account>.<instance>.evergage.com",
|
|
46
|
+
dataset: "engage",
|
|
47
|
+
});
|
|
48
|
+
|
|
49
|
+
const { campaignResponses } = await sfmc.sendEvent({
|
|
50
|
+
source: { channel: "Web", url: pageUrl },
|
|
51
|
+
interaction: { name: "View Item" },
|
|
52
|
+
user: { anonymousId },
|
|
53
|
+
pageView: true,
|
|
54
|
+
});
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
- `sendEvent(event)` posts to `/api2/event/{dataset}` on `baseUrl` and returns the
|
|
58
|
+
campaigns the interaction triggered: `campaignResponses[]`, each with `campaignId` and
|
|
59
|
+
a `payload` (`experience`, `headerText`, `products`, `userGroup`, and whatever the
|
|
60
|
+
campaign defines).
|
|
61
|
+
- `event.user` carries `anonymousId`, `encryptedId` or `attributes`; `interaction` can
|
|
62
|
+
carry `lineItems` for cart-aware events; `flags` has `nonInteractive` and `doNotTrack`.
|
|
63
|
+
- `PersonalizationProduct` keeps the common product fields (`id`, `name`, `price`,
|
|
64
|
+
`salePrice`, `inventoryCount`, `imageUrls`, `url`, `currency`) and accepts the rest
|
|
65
|
+
of the dataset's catalog fields.
|
|
66
|
+
- The client sends no credentials. Reading the shopper's ID from its cookie, mapping
|
|
67
|
+
products to commerce types and any caching are site code.
|
|
68
|
+
- Errors: `SfmcPersonalizationError` (`operation`, `status`). No retries.
|
|
69
|
+
- Exports: `createSfmcPersonalizationClient`, `SfmcPersonalizationClient`,
|
|
70
|
+
`SfmcPersonalizationConfig`, `SfmcPersonalizationError`, and the types
|
|
71
|
+
`PersonalizationEvent`, `PersonalizationResponse`, `CampaignResponse`,
|
|
72
|
+
`PersonalizationProduct`, `PersonalizationLineItem`.
|
|
73
|
+
|
|
74
|
+
The response depends on the shopper, so a section that renders campaign products is
|
|
75
|
+
per-visitor. Fetch it after the page loads, or from a private server function, so the
|
|
76
|
+
page itself stays cacheable.
|
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
# `@decocms/apps-shopify`
|
|
2
|
+
|
|
3
|
+
A client for Shopify's Storefront and Admin GraphQL APIs, and nothing else. Converters,
|
|
4
|
+
cart and customer flows are site code.
|
|
5
|
+
|
|
6
|
+
## Configure
|
|
7
|
+
|
|
8
|
+
```ts
|
|
9
|
+
import { createShopifyClient } from "@decocms/apps-shopify";
|
|
10
|
+
|
|
11
|
+
export const shopify = createShopifyClient(
|
|
12
|
+
{
|
|
13
|
+
storeName: "acme", // acme.myshopify.com
|
|
14
|
+
storefrontAccessToken: secrets.SHOPIFY_STOREFRONT_TOKEN,
|
|
15
|
+
adminAccessToken: secrets.SHOPIFY_ADMIN_TOKEN, // optional; enables `admin`
|
|
16
|
+
apiVersion: "2026-07", // required, no default
|
|
17
|
+
},
|
|
18
|
+
{ fetch: cachedFetch }, // optional
|
|
19
|
+
);
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
- `apiVersion` has no default on purpose: the site owns it, so it never goes stale
|
|
23
|
+
inside the package. A migrated site starts with the version its v7 app used.
|
|
24
|
+
- Requests go to `https://{storeName}.myshopify.com/api/{apiVersion}/graphql.json`
|
|
25
|
+
(header `X-Shopify-Storefront-Access-Token`) and
|
|
26
|
+
`/admin/api/{apiVersion}/graphql.json` (header `X-Shopify-Access-Token`).
|
|
27
|
+
- Without `adminAccessToken`, `admin.query` rejects with
|
|
28
|
+
`"shopify admin: pass adminAccessToken to createShopifyClient"`. Never use the Admin
|
|
29
|
+
API from code a shopper's request can steer without checking the input.
|
|
30
|
+
- Exports: `createShopifyClient`, `ShopifyClient`, `ShopifyClientConfig`, `ShopifyError`.
|
|
31
|
+
|
|
32
|
+
## Query
|
|
33
|
+
|
|
34
|
+
```ts
|
|
35
|
+
const data = await shopify.storefront.query<ProductByHandleQuery, { handle: string }>(
|
|
36
|
+
`query ProductByHandle($handle: String!) { product(handle: $handle) { id title } }`,
|
|
37
|
+
{ handle },
|
|
38
|
+
{ headers: { "Shopify-Storefront-Buyer-IP": buyerIp }, signal },
|
|
39
|
+
);
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
- `query(document, variables?, { headers?, signal? })` returns `data`.
|
|
43
|
+
- The telemetry label is the document's operation name (`ProductByHandle`). An unnamed
|
|
44
|
+
document is labeled `storefront.graphql` or `admin.graphql`; name every operation.
|
|
45
|
+
- Extra `headers` can't override the access token.
|
|
46
|
+
|
|
47
|
+
## Errors
|
|
48
|
+
|
|
49
|
+
`ShopifyError` has `operation`, `status` and `codes`:
|
|
50
|
+
|
|
51
|
+
| Case | `codes` |
|
|
52
|
+
|---|---|
|
|
53
|
+
| HTTP error | `[]` |
|
|
54
|
+
| GraphQL `errors` | each error's `extensions.code`, or `UNKNOWN`, deduplicated |
|
|
55
|
+
| No `data` | `["MISSING_DATA"]` |
|
|
56
|
+
| Body isn't JSON (an HTML error page) | `["INVALID_JSON"]` |
|
|
57
|
+
|
|
58
|
+
A response with both `data` and `errors` is rejected as a whole. The client doesn't
|
|
59
|
+
guess which fields are still trustworthy. If a query can partly fail and you still want
|
|
60
|
+
the rest, split it into separate queries.
|
|
61
|
+
|
|
62
|
+
No retries and no circuit breaker. Caching is the site's: see
|
|
63
|
+
[`instrumented-fetch.md`](./instrumented-fetch.md).
|
|
64
|
+
|
|
65
|
+
## Images
|
|
66
|
+
|
|
67
|
+
`@decocms/apps-shopify/image` exports `shopifyCdn()`, an `ImageProvider` for
|
|
68
|
+
`https://cdn.shopify.com` URLs (sets `width`, `height` when given, and `crop=center`).
|
|
69
|
+
List it before `decoCdn`; see `deco-images-media`.
|
|
@@ -0,0 +1,135 @@
|
|
|
1
|
+
# Client files and vendored loaders
|
|
2
|
+
|
|
3
|
+
v8 apps ship no loaders, actions, hooks or converters. A migrated site keeps the ones its
|
|
4
|
+
content uses as its own code, and calls the thin client from them. The
|
|
5
|
+
`deco-v7-to-v8-migration` skill's script does the copy; this file covers what it
|
|
6
|
+
leaves you and how to move that code onto the v8 client.
|
|
7
|
+
|
|
8
|
+
## What the migration script writes
|
|
9
|
+
|
|
10
|
+
**`src/clients/<app>.ts`**, one per v7 app block the content has (`deco-vtex`,
|
|
11
|
+
`deco-shopify`, `deco-wake`, `deco-resend`). Each exports a function that creates the
|
|
12
|
+
client on first use:
|
|
13
|
+
|
|
14
|
+
```ts
|
|
15
|
+
// src/clients/vtex.ts (shape of the generated file, TanStack Start)
|
|
16
|
+
import { createVtexClient, type VtexClient } from "@decocms/apps-vtex";
|
|
17
|
+
import { env } from "cloudflare:workers";
|
|
18
|
+
|
|
19
|
+
const variable = (name: string) =>
|
|
20
|
+
(env as unknown as Record<string, string | undefined>)[name] || undefined;
|
|
21
|
+
|
|
22
|
+
export const vtexSettings = { publicUrl: "…", country: "…", invalidPageNotFound: false } as const;
|
|
23
|
+
|
|
24
|
+
let client: VtexClient | undefined;
|
|
25
|
+
|
|
26
|
+
export function vtexClient(): VtexClient {
|
|
27
|
+
client ??= createVtexClient({
|
|
28
|
+
account: "mystore",
|
|
29
|
+
salesChannel: "1",
|
|
30
|
+
appKey: variable("VTEX_APP_KEY"),
|
|
31
|
+
appToken: variable("VTEX_APP_TOKEN"),
|
|
32
|
+
});
|
|
33
|
+
return client;
|
|
34
|
+
}
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
- Settings come from the saved block, with v7's defaults: VTEX sales channel `"1"`,
|
|
38
|
+
Wake checkout `https://<account>.checkout.fbits.store`, and for Shopify the
|
|
39
|
+
Storefront API version the installed v7 app used.
|
|
40
|
+
- A credential that was encrypted in content is read from the variable v7 fell back
|
|
41
|
+
to: `VTEX_APP_KEY`, `VTEX_APP_TOKEN`, `SHOPIFY_STOREFRONT_TOKEN`, `WAKE_TOKEN`,
|
|
42
|
+
`RESEND_API_KEY`. Set them in the deploy platform's secrets (on Workers,
|
|
43
|
+
`wrangler secret put`). On Next.js the file reads `process.env`.
|
|
44
|
+
- What v7 kept beside the client (VTEX's `publicUrl`, Resend's sender) is an exported
|
|
45
|
+
`<app>Settings` constant.
|
|
46
|
+
- The saved app block stays until the variables are set. Then delete it: `deco check`
|
|
47
|
+
rejects it.
|
|
48
|
+
|
|
49
|
+
**`src/vendor/<app>/<path>`**: every app loader and action the content calls, copied
|
|
50
|
+
from the installed v7 package with the modules it imports from that package. Imports
|
|
51
|
+
of the package by name become relative imports. The block map registers each one
|
|
52
|
+
under its v7 type name, so saved content keeps resolving.
|
|
53
|
+
|
|
54
|
+
**`src/server/invoke.functions.ts`** (TanStack) or **`invoke.actions.ts`** (Next.js):
|
|
55
|
+
one server function per `/deco/invoke` key the site called. With
|
|
56
|
+
`--vtex-invoke v8`, the VTEX cart keys go to `src/server/vtex-invoke.server.ts` over
|
|
57
|
+
`vtexClient()`. Details are in `deco-v7-to-v8-migration`.
|
|
58
|
+
|
|
59
|
+
## Keep v7's client, or move to the v8 one
|
|
60
|
+
|
|
61
|
+
A vendored loader may still call v7's own fetch code, copied along with it. That keeps
|
|
62
|
+
every upstream request identical to v7, so recorded upstream fixtures still replay in
|
|
63
|
+
a parity run. It also keeps v7's in-memory fetch cache, which v8 doesn't have.
|
|
64
|
+
|
|
65
|
+
- **Keep it** while you prove parity. Drop the v8 `@decocms/apps-<platform>` dependency
|
|
66
|
+
if nothing imports it, and list the move to the v8 client as a follow-up.
|
|
67
|
+
- **Move to the v8 client** to get telemetry, retries, the circuit breaker and cookie
|
|
68
|
+
sanitizing, and to delete v7 code. Do it loader by loader, after parity.
|
|
69
|
+
|
|
70
|
+
## Moving a vendored loader onto the client
|
|
71
|
+
|
|
72
|
+
1. **One argument.** A block function gets its inputs and nothing else: no `req`, no
|
|
73
|
+
`ctx`. Remove the second and third parameters. A value the loader read from the
|
|
74
|
+
request (a cookie, the URL) must come in as an input, or the call belongs in a
|
|
75
|
+
server function. See `deco-site-authoring` for loaders.
|
|
76
|
+
2. **Replace the fetch with a client call.** `vtexClient().search.products({…})` instead
|
|
77
|
+
of a hand-built Intelligent Search URL. The table below maps v7's VTEX calls.
|
|
78
|
+
3. **Keep the converter.** The client returns VTEX's own types. The vendored
|
|
79
|
+
`transform` code that builds `Product`, `ProductListingPage` and the rest stays in
|
|
80
|
+
`src/vendor`. Import the commerce types from `@decocms/compat-v7/commerce/types`
|
|
81
|
+
([`commerce-types.md`](./commerce-types.md)).
|
|
82
|
+
4. **Remove `ctx.invoke`.** Call the other handler module directly, or the client.
|
|
83
|
+
`src/migration-stubs.ts` stubs (`unportedInvoke`, `appState`) reject or throw at run time
|
|
84
|
+
until replaced.
|
|
85
|
+
5. **Actions are not block functions.** A cart or session mutation runs in a server
|
|
86
|
+
function (TanStack) or a route handler or server action (Next.js), with the shopper's
|
|
87
|
+
request. Forward VTEX's cookies there: [`vtex-cookies-auth.md`](./vtex-cookies-auth.md).
|
|
88
|
+
|
|
89
|
+
### v7 VTEX calls and the v8 operation
|
|
90
|
+
|
|
91
|
+
| v7 call | v8 client |
|
|
92
|
+
|---|---|
|
|
93
|
+
| Intelligent Search `product_search` | `vtex.search.products(args)` |
|
|
94
|
+
| Intelligent Search `facets` | `vtex.search.facets(args)` |
|
|
95
|
+
| `search_suggestions`, `autocomplete_suggestions`, `top_searches` | `vtex.search.suggestions`, `.autocomplete`, `.topSearches` |
|
|
96
|
+
| `/api/catalog_system/pub/products/search` | `vtex.catalog.products({ term, ft, fq, from, to, sort })` |
|
|
97
|
+
| `/pub/portal/pagetype/<path>` | `vtex.catalog.pageType(path)` |
|
|
98
|
+
| `/pub/products/crossselling/<type>/<id>` | `vtex.catalog.crossSelling(type, productId)` |
|
|
99
|
+
| `/pub/category/tree/<levels>` | `vtex.catalog.categoryTree(levels)` |
|
|
100
|
+
| `getOrCreateCart` | `vtex.checkout.orderForm({ cookie, sections? })` |
|
|
101
|
+
| `addItemsToCart` | `vtex.checkout.addItems(orderFormId, items, { cookie })` |
|
|
102
|
+
| `updateCartItems` | `vtex.checkout.updateItems(orderFormId, items, { cookie })` |
|
|
103
|
+
| `addCouponToCart` | `vtex.checkout.addCoupon(orderFormId, text, { cookie })` |
|
|
104
|
+
| `updateOrderFormAttachment` | `vtex.checkout.attachment(orderFormId, name, body, { cookie })` |
|
|
105
|
+
| `simulateCart` | `vtex.checkout.simulation({ items, postalCode, country })` |
|
|
106
|
+
| `getSellersByRegion` | `vtex.checkout.regions({ postalCode, country })` |
|
|
107
|
+
| `/api/sessions` (get, edit) | `vtex.sessions.get({ cookie, items })`, `vtex.sessions.update(public, { cookie })` |
|
|
108
|
+
| Master Data v1 search, create | `vtex.masterdata.search(entity, args)`, `.create(entity, doc)` |
|
|
109
|
+
| IO GraphQL (`myvtex.com/_v/private/graphql/v1`) | `vtex.io.graphql({ query, variables })` |
|
|
110
|
+
|
|
111
|
+
What the v8 cart calls do differently from v7's handlers (the migration report lists
|
|
112
|
+
these too):
|
|
113
|
+
|
|
114
|
+
- `orderForm` gets the cart from the shopper's `checkout.vtex.com` cookie. v7 fetched
|
|
115
|
+
`props.orderFormId` when given.
|
|
116
|
+
- No `allowedOutdatedData=paymentData` on add or update, no `noSplitItem` on update,
|
|
117
|
+
no `RnbBehavior=1` on simulation.
|
|
118
|
+
- `addItems` types each SKU `id` as a number.
|
|
119
|
+
- Item images keep VTEX's `http:` URLs. v7 rewrote them to `https:`. Do it in your
|
|
120
|
+
converter if the site needs it.
|
|
121
|
+
|
|
122
|
+
Wishlist, OMS orders, VTEX ID sign-in, profile and address calls have no operation in
|
|
123
|
+
the v8 client. Keep the vendored code, or write the call with `createInstrumentedFetch`
|
|
124
|
+
([`instrumented-fetch.md`](./instrumented-fetch.md)).
|
|
125
|
+
|
|
126
|
+
## Housekeeping
|
|
127
|
+
|
|
128
|
+
- **The script vendors every loader the content references**, including ones v7 never
|
|
129
|
+
ran. Check which ones render before keeping them; delete the rest with the saved
|
|
130
|
+
blocks nothing references.
|
|
131
|
+
- **Don't reformat vendored GraphQL documents.** Prettier reflows a vendored
|
|
132
|
+
`queries.ts`, which changes every request body sent upstream; a replaying parity
|
|
133
|
+
harness then misses every call. Keep such files in `.prettierignore`.
|
|
134
|
+
- **Tailwind** may scan `src/vendor` now, where v7 never scanned `node_modules`. See
|
|
135
|
+
`deco-v7-to-v8-migration` if classes change.
|