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