@decocms/apps-vtex 7.71.6 → 8.0.0-next.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/apps-vtex",
-  "version": "7.71.6",
+  "version": "8.0.0-next.0",
   "type": "module",
   "description": "Deco commerce app: VTEX integration",
   "repository": {
@@ -51,10 +51,10 @@
     "lint:unused": "knip"
   },
   "dependencies": {
-    "@decocms/blocks": "7.71.6",
-    "@decocms/apps-commerce": "7.71.6",
-    "@decocms/apps-website": "7.71.6",
-    "@decocms/tanstack": "7.71.6"
+    "@decocms/blocks": "8.0.0-next.0",
+    "@decocms/apps-commerce": "8.0.0-next.0",
+    "@decocms/apps-website": "8.0.0-next.0",
+    "@decocms/tanstack": "8.0.0-next.0"
   },
   "peerDependencies": {
     "@tanstack/react-query": ">=5.0.0",

package/src/__conformance__/upstream.test.ts

@@ -0,0 +1,158 @@
+// @vitest-environment node
+/**
+ * Conformance: upstream-clients.mdx (Calling APIs) against the next-major
+ * client packages. Only the v8 client modules are checked; the v7 app
+ * surfaces that still ship beside them are out of scope until v7 is removed.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { createAlgoliaClient } from "@decocms/apps-algolia";
+import { createVtexClient } from "@decocms/apps-vtex";
+import { describe, expect, it, vi } from "vitest";
+
+const PACKAGES = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../..");
+
+/** The next-major client module of each platform package. */
+const V8_CLIENTS: Record<string, string[]> = {
+  "apps-vtex": ["src/vtexClient.ts"],
+  "apps-shopify": ["src/v8/client.ts", "src/v8/graphqlOperationName.ts"],
+  "apps-wake": ["src/wakeClient.ts"],
+  "apps-magento": ["src/magentoClient.ts"],
+  "apps-algolia": ["src/index.ts"],
+  "apps-resend": ["src/emails.ts"],
+  "apps-sfmc-personalization": ["src/index.ts"],
+};
+
+/** The source without comments, so doc examples (`process.env.X!` in a JSDoc) don't count. */
+function code(pkg: string, file: string): string {
+  return fs
+    .readFileSync(path.join(PACKAGES, pkg, file), "utf8")
+    .replace(/\/\*[\s\S]*?\*\//g, "")
+    .replace(/(^|[^:"'`])\/\/.*$/gm, "$1");
+}
+
+describe("what a client is (upstream-clients.mdx)", () => {
+  it("up-01: VTEX, Shopify, Wake, Magento, Algolia, Resend (and others) ship a client built on createInstrumentedFetch", () => {
+    for (const [pkg, files] of Object.entries(V8_CLIENTS)) {
+      expect(fs.existsSync(path.join(PACKAGES, pkg, "package.json"))).toBe(true);
+      expect([pkg, code(pkg, files[0]!)]).toEqual([
+        pkg,
+        expect.stringMatching(/import \{[^}]*createInstrumentedFetch[^}]*\} from "@decocms\/blocks\/fetch"/),
+      ]);
+    }
+  });
+
+  it("up-02: clients take settings as arguments: no environment reads inside a client", () => {
+    for (const [pkg, files] of Object.entries(V8_CLIENTS)) {
+      for (const file of files) {
+        expect([pkg, file, /process\.env|import\.meta\.env|Deno\.env/.test(code(pkg, file))]).toEqual(
+          [pkg, file, false],
+        );
+      }
+    }
+  });
+
+  it("up-03: no React hooks, client components or shared-commerce converters in a client", () => {
+    for (const [pkg, files] of Object.entries(V8_CLIENTS)) {
+      for (const file of files) {
+        const text = code(pkg, file);
+        const found = [
+          /["']use client["']/,
+          /from ["']react["']/,
+          /\buse(Cart|User|Wishlist)\b/,
+          /@decocms\/apps-commerce/,
+          /from ["']\.\/(loaders|actions|hooks)\//,
+        ].filter((pattern) => pattern.test(text));
+        expect([pkg, file, found]).toEqual([pkg, file, []]);
+      }
+    }
+  });
+
+  it("up-05: the Salesforce client is @decocms/apps-sfmc-personalization; @decocms/apps-salesforce is gone", () => {
+    const pkg = JSON.parse(
+      fs.readFileSync(path.join(PACKAGES, "apps-sfmc-personalization/package.json"), "utf8"),
+    );
+    expect(pkg.name).toBe("@decocms/apps-sfmc-personalization");
+    const names = fs
+      .readdirSync(PACKAGES)
+      .filter((dir) => fs.existsSync(path.join(PACKAGES, dir, "package.json")))
+      .map((dir) => JSON.parse(fs.readFileSync(path.join(PACKAGES, dir, "package.json"), "utf8")).name);
+    expect(names).not.toContain("@decocms/apps-salesforce");
+  });
+
+  it("up-07: clients don't cache upstream responses", () => {
+    for (const [pkg, files] of Object.entries(V8_CLIENTS)) {
+      for (const file of files) {
+        expect([
+          pkg,
+          file,
+          /createFetchCache|fetchWithCache|fetchCache|caches\.default|caches\.open|cachedLoader/.test(
+            code(pkg, file),
+          ),
+        ]).toEqual([pkg, file, false]);
+      }
+    }
+  });
+});
+
+describe("call a client (upstream-clients.mdx)", () => {
+  it("up-06: createVtexClient({ account, appKey, appToken }) and vtex.search.products({ query, count })", async () => {
+    const fetch = vi.fn(
+      async (_input: string | URL | Request, _init?: RequestInit) =>
+        new Response(JSON.stringify({ products: [] }), { status: 200 }),
+    );
+    const vtex = createVtexClient({
+      account: "mystore",
+      appKey: "key",
+      appToken: "token",
+      fetch: fetch as unknown as typeof globalThis.fetch,
+    });
+    const products = await vtex.search.products({ query: "linen shirt", count: 12 });
+    expect(products).toEqual({ products: [] });
+    const url = new URL(String(fetch.mock.calls[0]![0]));
+    expect(url.host).toBe("mystore.vtexcommercestable.com.br");
+    expect(url.pathname).toContain("product_search");
+    expect(url.searchParams.get("query")).toBe("linen shirt");
+    expect(url.searchParams.get("count")).toBe("12");
+  });
+});
+
+describe("retries and failures (upstream-clients.mdx)", () => {
+  it("up-08: the VTEX client retries by default", async () => {
+    const statuses = [503, 200];
+    const fetch = vi.fn(
+      async () => new Response("{}", { status: statuses.shift() ?? 200 }),
+    );
+    const vtex = createVtexClient({
+      account: "mystore",
+      fetch: fetch as unknown as typeof globalThis.fetch,
+    });
+    await vtex.search.products({ query: "shirt" });
+    expect(fetch).toHaveBeenCalledTimes(2);
+  });
+
+  it("up-08: the VTEX client's circuit breaker fails fast after repeated failures", async () => {
+    const fetch = vi.fn(async () => new Response("{}", { status: 503 }));
+    const vtex = createVtexClient({
+      account: "mystore",
+      fetch: fetch as unknown as typeof globalThis.fetch,
+    });
+    for (let i = 0; i < 5; i++) await expect(vtex.search.products({ query: "shirt" })).rejects.toThrow();
+    const before = fetch.mock.calls.length;
+    await expect(vtex.search.products({ query: "shirt" })).rejects.toThrow();
+    expect(fetch.mock.calls.length).toBe(before);
+  }, 20_000);
+
+  it("up-08: other clients leave retries off (one attempt on a 503)", async () => {
+    const fetch = vi.fn(async () => new Response("{}", { status: 503 }));
+    const algolia = createAlgoliaClient(
+      { applicationId: "APP123", apiKey: "k" },
+      { fetch: fetch as unknown as typeof globalThis.fetch },
+    );
+    await expect(algolia.search([{ indexName: "products", query: "shirt" }] as never)).rejects.toThrow(
+      "algolia search failed with HTTP 503",
+    );
+    expect(fetch).toHaveBeenCalledTimes(1);
+  });
+});

package/src/index.ts

@@ -1,6 +1,11 @@
 /**
- * VTEX app entry point for @decocms/apps.
- * Re-exports client config + initializer + app contract.
+ * VTEX app entry point.
+ *
+ * Next major: `createVtexClient` is the thin, instrumented VTEX client
+ * (see ./vtexClient.ts and /next/upstream-clients). Everything else below is
+ * the v7 app surface, kept exported for v7 consumers until v7 is dropped.
+ *
+ * v7: re-exports client config + initializer + app contract.
  *
  * For actions/loaders/utils, use sub-path imports:
  *   import { addItemsToCart } from "@decocms/apps/vtex/actions/checkout"
@@ -15,3 +20,13 @@ export * from "./client";
 export { configure, type VtexState } from "./mod";
 export { type CreateVtexFetchOptions, createVtexFetch } from "./utils/instrumentedFetch";
 export { vtexOperationRouter } from "./utils/operationRouter";
+export {
+	createVtexClient,
+	type VtexCatalogSearchArgs,
+	type VtexClient,
+	type VtexClientConfig,
+	VtexError,
+	type VtexRequestOptions,
+	type VtexResponse,
+	type VtexSearchArgs,
+} from "./vtexClient";

package/src/vtexClient.test.ts

@@ -0,0 +1,204 @@
+// @vitest-environment node
+/**
+ * The VTEX upstream client (/next/upstream-clients): typed calls over the
+ * framework's instrumented fetch, labeled provider "vtex" with a named
+ * operation, retries and a circuit breaker on by default, per-shopper inputs
+ * as arguments, and errors that carry no body, URL, token or cookie.
+ */
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+const instrumented = vi.hoisted(() => ({
+	options: [] as Record<string, unknown>[],
+	operations: [] as (string | undefined)[],
+}));
+
+vi.mock("@decocms/blocks/fetch", async (importActual) => {
+	const actual = await importActual<typeof import("@decocms/blocks/fetch")>();
+	return {
+		...actual,
+		createInstrumentedFetch: (options: Parameters<typeof actual.createInstrumentedFetch>[0]) => {
+			instrumented.options.push(options as unknown as Record<string, unknown>);
+			const request = actual.createInstrumentedFetch(options);
+			return (input: string | URL | Request, init?: RequestInit & { operation?: string }) => {
+				instrumented.operations.push(init?.operation);
+				return request(input, init);
+			};
+		},
+	};
+});
+
+import { createVtexClient, VtexError } from ".";
+
+type Call = { url: string; init: RequestInit };
+
+/** An upstream answering with `statuses` in order, recording each request. */
+function upstream(statuses: number[] = [], headers: Record<string, string | string[]> = {}) {
+	const calls: Call[] = [];
+	const fetch = vi.fn(async (input: string | URL | Request, init: RequestInit = {}) => {
+		calls.push({ url: String(input), init });
+		const response = new Response('{"secret-body":"token-123"}', { status: statuses.shift() ?? 200 });
+		for (const [name, value] of Object.entries(headers)) {
+			for (const v of Array.isArray(value) ? value : [value]) response.headers.append(name, v);
+		}
+		return response;
+	});
+	return { calls, fetch: fetch as unknown as typeof globalThis.fetch };
+}
+
+const header = (call: Call | undefined, name: string) => new Headers(call?.init.headers).get(name);
+
+afterEach(() => {
+	instrumented.options.length = 0;
+	instrumented.operations.length = 0;
+});
+
+describe("createVtexClient", () => {
+	it("uses the instrumented fetch as provider vtex, with retries and a circuit breaker on", () => {
+		createVtexClient({ account: "store" });
+		expect(instrumented.options[0]).toMatchObject({
+			provider: "vtex",
+			retry: { attempts: 2, backoffMs: 150 },
+			circuitBreaker: { failures: 5, cooldownMs: 5000 },
+		});
+	});
+
+	it("turns retries and the circuit breaker off when asked", () => {
+		createVtexClient({ account: "store", retry: false, circuitBreaker: false });
+		expect(instrumented.options[0]?.retry).toBeUndefined();
+		expect(instrumented.options[0]?.circuitBreaker).toBeUndefined();
+	});
+
+	it("searches Intelligent Search with facets, region, locale and sales channel as arguments", async () => {
+		const { calls, fetch } = upstream();
+		const vtex = createVtexClient({
+			account: "store",
+			appKey: "key",
+			appToken: "token",
+			salesChannel: "2",
+			locale: "pt-BR",
+			fetch,
+		});
+		await vtex.search.products({
+			query: "linen shirt",
+			count: 12,
+			facets: [{ key: "category-1", value: "shirts" }],
+			regionId: "v2.ABC",
+		});
+		const url = new URL(calls[0]!.url);
+		expect(url.origin).toBe("https://store.vtexcommercestable.com.br");
+		expect(url.pathname).toBe("/api/io/_v/api/intelligent-search/product_search/category-1/shirts");
+		expect(Object.fromEntries(url.searchParams)).toEqual({
+			query: "linen shirt",
+			count: "12",
+			locale: "pt-BR",
+			regionId: "v2.ABC",
+			sc: "2",
+		});
+		expect(header(calls[0], "x-vtex-api-appkey")).toBe("key");
+		expect(header(calls[0], "x-vtex-api-apptoken")).toBe("token");
+		expect(header(calls[0], "cookie")).toBeNull();
+		expect(instrumented.operations).toEqual(["intelligent-search.product_search"]);
+	});
+
+	it("names every operation from the VTEX API, never a URL", async () => {
+		const { fetch } = upstream();
+		const vtex = createVtexClient({ account: "store", fetch });
+		await vtex.catalog.pageType("/shirts/linen");
+		await vtex.catalog.products({ fq: ["productId:1", "productId:2"], from: 0, to: 9 });
+		await vtex.checkout.simulation({ items: [{ id: "1", quantity: 1, seller: "1" }] });
+		await vtex.checkout.regions({ postalCode: "01000-000", country: "BRA" });
+		await vtex.sessions.get();
+		expect(instrumented.operations).toEqual([
+			"catalog.pagetype",
+			"catalog.products.search",
+			"checkout.simulation",
+			"checkout.regions",
+			"sessions.get",
+		]);
+	});
+
+	it("retries an idempotent call and fails fast once the breaker opens", async () => {
+		const { calls, fetch } = upstream([503, 200]);
+		const vtex = createVtexClient({ account: "store", fetch, retry: { attempts: 1, backoffMs: 0 } });
+		await expect(vtex.catalog.categoryTree()).resolves.toBeDefined();
+		expect(calls).toHaveLength(2);
+
+		const down = upstream([500, 500, 500]);
+		const failing = createVtexClient({
+			account: "store",
+			fetch: down.fetch,
+			retry: false,
+			circuitBreaker: { failures: 2, cooldownMs: 60_000 },
+		});
+		await expect(failing.catalog.categoryTree()).rejects.toBeInstanceOf(VtexError);
+		await expect(failing.catalog.categoryTree()).rejects.toBeInstanceOf(VtexError);
+		await expect(failing.catalog.categoryTree()).rejects.toThrow(/circuit open/);
+		expect(down.calls).toHaveLength(2);
+	});
+
+	it("never retries a cart write", async () => {
+		const { calls, fetch } = upstream([503, 200]);
+		const vtex = createVtexClient({ account: "store", fetch, retry: { attempts: 3, backoffMs: 0 } });
+		await expect(vtex.checkout.addItems("of1", [{ id: 1, quantity: 1, seller: "1" }])).rejects.toThrow(
+			VtexError,
+		);
+		expect(calls).toHaveLength(1);
+	});
+
+	it("forwards the shopper's cookie, sanitized, and hands back VTEX's Set-Cookie values", async () => {
+		const { calls, fetch } = upstream([], {
+			"set-cookie": ["checkout.vtex.com=__ofid=of1; Domain=store.vtexcommercestable.com.br; Path=/"],
+		});
+		const vtex = createVtexClient({ account: "store", appKey: "key", appToken: "token", fetch });
+		const result = await vtex.checkout.orderForm({
+			cookie: "checkout.vtex.com=__ofid=of1; tag=cateçoria",
+		});
+		expect(header(calls[0], "cookie")).toBe("checkout.vtex.com=__ofid=of1");
+		expect(calls[0]?.init.method).toBe("POST");
+		// Every orderForm section, and no app credentials next to a shopper's cookie.
+		expect(calls[0]?.init.body).toBe("{}");
+		expect(header(calls[0], "x-vtex-api-appkey")).toBeNull();
+		expect(header(calls[0], "x-vtex-api-apptoken")).toBeNull();
+		expect(result.setCookies).toEqual([
+			"checkout.vtex.com=__ofid=of1; Domain=store.vtexcommercestable.com.br; Path=/",
+		]);
+		expect(result.data).toEqual({ "secret-body": "token-123" });
+	});
+
+	it("throws errors that carry the operation and status, never the body, URL or credentials", async () => {
+		const { fetch } = upstream([400]);
+		const vtex = createVtexClient({ account: "store", appKey: "key", appToken: "token-123", fetch });
+		const error = await vtex.search.products({ query: "q" }).catch((e: unknown) => e);
+		expect(error).toBeInstanceOf(VtexError);
+		expect(error).toMatchObject({ operation: "intelligent-search.product_search", status: 400 });
+		expect((error as Error).message).toBe("vtex intelligent-search.product_search failed with HTTP 400");
+	});
+
+	it("narrows the orderForm sections only when asked", async () => {
+		const { calls, fetch } = upstream();
+		const vtex = createVtexClient({ account: "store", fetch });
+		await vtex.checkout.orderForm({ sections: ["items", "totalizers"] });
+		expect(calls[0]?.init.body).toBe('{"expectedOrderFormSections":["items","totalizers"]}');
+	});
+
+	it("keeps caller paths inside their endpoint", async () => {
+		const { calls, fetch } = upstream();
+		const vtex = createVtexClient({ account: "store", appKey: "key", appToken: "token", fetch });
+		for (const path of [
+			"../../api/dataentities/CL/search",
+			"/shirts/%2e%2e/%2E%2E/api/dataentities/CL/search",
+			"shirts/./linen",
+		]) {
+			await expect(vtex.catalog.pageType(path)).rejects.toThrow(/invalid path segment/);
+		}
+		await expect(vtex.catalog.products({ term: "a/../../../api/x" })).rejects.toThrow(
+			/invalid path segment/,
+		);
+		expect(calls).toHaveLength(0);
+
+		await vtex.catalog.pageType("/shirts/linen?_where=x#y");
+		const url = new URL(calls[0]!.url);
+		expect(url.pathname).toBe("/api/catalog_system/pub/portal/pagetype/shirts/linen%3F_where%3Dx%23y");
+		expect(url.search).toBe("");
+	});
+});

package/src/vtexClient.ts

@@ -0,0 +1,433 @@
+/**
+ * The VTEX upstream client: typed request functions over the framework's
+ * instrumented fetch (`@decocms/blocks/fetch`). See /next/upstream-clients.
+ *
+ * ```ts
+ * import { createVtexClient } from "@decocms/apps-vtex";
+ *
+ * export const vtex = createVtexClient({
+ *   account: process.env.VTEX_ACCOUNT!,
+ *   appKey: process.env.VTEX_APP_KEY!,
+ *   appToken: process.env.VTEX_APP_TOKEN!,
+ * });
+ *
+ * const result = await vtex.search.products({ query: "linen shirt", count: 12 });
+ * ```
+ *
+ * Thin by design: it returns VTEX's own types, takes every setting and every
+ * per-shopper input (cookies, region) as arguments, and never reads the
+ * incoming request, caches, or converts. Converters, hooks, cart/session/sign-in
+ * flows and loaders live in the VTEX platform template and site code; upstream
+ * caching lives in the framework binding (/next/caching#upstream-data), keyed
+ * by everything a response depends on, such as `regionId`.
+ *
+ * Retries and a circuit breaker are ON by default for VTEX (and only for
+ * VTEX). Retries apply to idempotent requests only, so a checkout POST is
+ * never repeated. Pass `retry: false` / `circuitBreaker: false` to turn them off.
+ */
+import { createInstrumentedFetch } from "@decocms/blocks/fetch";
+import { DEFAULT_RESILIENCE_CONFIG } from "./utils/constants";
+import { sanitizeOutboundCookieHeader } from "./utils/cookieSanitizer";
+import { vtexOperationRouter } from "./utils/operationRouter";
+import type {
+	Category,
+	FacetSearchResult,
+	Fuzzy,
+	LegacyProduct,
+	LegacySort,
+	CrossSellingType,
+	OrderForm,
+	OrderFormItemInput,
+	PageType,
+	ProductSearchResult,
+	SelectedFacet,
+	Session,
+	SimulationBehavior,
+	SimulationOrderForm,
+	Sort,
+	Suggestion,
+} from "./utils/types";
+
+export interface VtexClientConfig {
+	/** The VTEX account name, e.g. `mystore`. */
+	account: string;
+	/** Sent as `X-VTEX-API-AppKey` when set together with `appToken`. */
+	appKey?: string;
+	/** Sent as `X-VTEX-API-AppToken` when set together with `appKey`. */
+	appToken?: string;
+	/** @default "vtexcommercestable" */
+	environment?: string;
+	/** @default "com.br" */
+	domain?: string;
+	/** Default sales channel (`sc`), overridable per call where VTEX accepts one. */
+	salesChannel?: string;
+	/** Default Intelligent Search locale, e.g. `pt-BR`. */
+	locale?: string;
+	/** The fetch underneath; for tests. Defaults to `globalThis.fetch`. */
+	fetch?: typeof fetch;
+	/** On by default (2 retries, 150ms backoff); idempotent requests only. `false` turns it off. */
+	retry?: { attempts: number; backoffMs?: number } | false;
+	/** On by default (opens after 5 failures, for 5s). `false` turns it off. */
+	circuitBreaker?: { failures: number; cooldownMs: number } | false;
+}
+
+const VTEX_DEFAULT_RETRY = {
+	attempts: DEFAULT_RESILIENCE_CONFIG.maxRetries,
+	backoffMs: DEFAULT_RESILIENCE_CONFIG.backoffBaseMs,
+} as const;
+
+const VTEX_DEFAULT_CIRCUIT_BREAKER = {
+	failures: DEFAULT_RESILIENCE_CONFIG.breakerConsecutiveFailures,
+	cooldownMs: DEFAULT_RESILIENCE_CONFIG.breakerOpenCooldownMs,
+} as const;
+
+/** Per-call inputs. Nothing is read from the incoming request. */
+export interface VtexRequestOptions {
+	/** The shopper's `Cookie` header to forward (non-ASCII and malformed pairs are dropped). */
+	cookie?: string;
+	signal?: AbortSignal;
+}
+
+/** A shopper-scoped response: the body plus VTEX's `Set-Cookie` values, unmodified, for the caller to forward. */
+export interface VtexResponse<T> {
+	data: T;
+	setCookies: string[];
+}
+
+/** A failed VTEX call. Carries the operation and the status, never a body, URL, token or cookie. */
+export class VtexError extends Error {
+	constructor(
+		readonly operation: string,
+		readonly status: number,
+	) {
+		super(`vtex ${operation} failed with HTTP ${status}`);
+		this.name = "VtexError";
+	}
+}
+
+/** Intelligent Search arguments, mirroring its query parameters. */
+export interface VtexSearchArgs extends VtexRequestOptions {
+	query?: string;
+	/** Selected facets, sent as the path (`category-1/shirts/brand/acme`). */
+	facets?: SelectedFacet[];
+	/** Intelligent Search's 1-based page. */
+	page?: number;
+	count?: number;
+	sort?: Sort;
+	fuzzy?: Fuzzy;
+	locale?: string;
+	hideUnavailableItems?: boolean;
+	simulationBehavior?: SimulationBehavior;
+	/** The shopper's region (from the `vtex_segment` cookie); part of the cache key. */
+	regionId?: string;
+	salesChannel?: string;
+}
+
+/** Legacy Catalog search arguments (`/api/catalog_system/pub/products/search`). */
+export interface VtexCatalogSearchArgs extends VtexRequestOptions {
+	/** Path term, e.g. a category path. */
+	term?: string;
+	/** Full-text query (`ft`). */
+	ft?: string;
+	/** Filter queries (`fq`), e.g. `productId:123`. */
+	fq?: string[];
+	/** `_from`, 0-based inclusive. */
+	from?: number;
+	/** `_to`, 0-based inclusive. */
+	to?: number;
+	/** `O`. */
+	sort?: LegacySort;
+	salesChannel?: string;
+}
+
+interface CallInit extends VtexRequestOptions {
+	method?: string;
+	body?: unknown;
+	headers?: Record<string, string>;
+}
+
+/**
+ * Encodes a caller-supplied path (e.g. the shopper's URL path) segment by
+ * segment, so it can't climb out of its endpoint (`..`, `%2e%2e`) or inject a
+ * query (`?`, `#`) while the app credentials are attached.
+ */
+function pathSegments(path: string): string {
+	return path
+		.split("/")
+		.filter((segment) => segment !== "")
+		.map((segment) => {
+			if (/^(\.|%2e){1,2}$/i.test(segment)) throw new Error("vtex: invalid path segment");
+			return encodeURIComponent(segment);
+		})
+		.join("/");
+}
+
+export function createVtexClient(config: VtexClientConfig) {
+	const host = `${config.account}.${config.environment ?? "vtexcommercestable"}.${config.domain ?? "com.br"}`;
+	const base = `https://${host}`;
+	const request = createInstrumentedFetch({
+		provider: "vtex",
+		fetch: config.fetch,
+		retry: config.retry === false ? undefined : (config.retry ?? VTEX_DEFAULT_RETRY),
+		circuitBreaker:
+			config.circuitBreaker === false
+				? undefined
+				: (config.circuitBreaker ?? VTEX_DEFAULT_CIRCUIT_BREAKER),
+	});
+
+	async function call(url: string | URL, init: CallInit = {}): Promise<Response> {
+		const method = (init.method ?? "GET").toUpperCase();
+		const operation = vtexOperationRouter(String(url), method) ?? "unknown";
+		const headers = new Headers({ accept: "application/json", ...init.headers });
+		if (init.body !== undefined) headers.set("content-type", "application/json");
+		// Shopper-scoped calls go out as the shopper only: with app credentials
+		// VTEX would answer an orderForm with the profile data unmasked.
+		if (config.appKey && config.appToken && !init.cookie) {
+			headers.set("x-vtex-api-appkey", config.appKey);
+			headers.set("x-vtex-api-apptoken", config.appToken);
+		}
+		if (init.cookie) {
+			const { cookies } = sanitizeOutboundCookieHeader(init.cookie);
+			if (cookies) headers.set("cookie", cookies);
+		}
+		const response = await request(url, {
+			method,
+			headers,
+			body: init.body === undefined ? undefined : JSON.stringify(init.body),
+			signal: init.signal,
+			operation,
+		});
+		if (!response.ok) {
+			void response.body?.cancel().catch(() => {});
+			throw new VtexError(operation, response.status);
+		}
+		return response;
+	}
+
+	/** Only the per-call request options, never the operation's other arguments. */
+	const pick = (options: VtexRequestOptions = {}): VtexRequestOptions => ({
+		cookie: options.cookie,
+		signal: options.signal,
+	});
+
+	const json = async <T>(url: string | URL, init?: CallInit): Promise<T> =>
+		(await call(url, init)).json() as Promise<T>;
+
+	const withCookies = async <T>(url: string | URL, init?: CallInit): Promise<VtexResponse<T>> => {
+		const response = await call(url, init);
+		const setCookies =
+			typeof response.headers.getSetCookie === "function" ? response.headers.getSetCookie() : [];
+		return { data: (await response.json()) as T, setCookies };
+	};
+
+	const url = (path: string, params: Record<string, string | number | boolean | undefined> = {}) => {
+		const result = new URL(path, base);
+		for (const [key, value] of Object.entries(params)) {
+			if (value !== undefined && value !== "") result.searchParams.set(key, String(value));
+		}
+		return result;
+	};
+
+	const isUrl = (endpoint: string, args: VtexSearchArgs) => {
+		const facetPath = (args.facets ?? [])
+			.map(({ key, value }) =>
+				key ? `${encodeURIComponent(key)}/${encodeURIComponent(value)}` : encodeURIComponent(value),
+			)
+			.join("/");
+		return url(`/api/io/_v/api/intelligent-search/${endpoint}/${facetPath}`, {
+			query: args.query,
+			page: args.page,
+			count: args.count,
+			sort: args.sort,
+			fuzzy: args.fuzzy,
+			locale: args.locale ?? config.locale,
+			hideUnavailableItems: args.hideUnavailableItems,
+			simulationBehavior: args.simulationBehavior,
+			regionId: args.regionId,
+			sc: args.salesChannel ?? config.salesChannel,
+		});
+	};
+
+	const orderFormPath = (orderFormId: string, rest = "") =>
+		`/api/checkout/pub/orderForm/${encodeURIComponent(orderFormId)}${rest}`;
+
+	return {
+		/** Intelligent Search. */
+		search: {
+			products: (args: VtexSearchArgs = {}) =>
+				json<ProductSearchResult>(isUrl("product_search", args), pick(args)),
+			facets: (args: VtexSearchArgs = {}) => json<FacetSearchResult>(isUrl("facets", args), pick(args)),
+			suggestions: (args: VtexSearchArgs) =>
+				json<Suggestion>(isUrl("search_suggestions", { ...args, facets: [] }), pick(args)),
+			autocomplete: (args: VtexSearchArgs) =>
+				json<Suggestion>(isUrl("autocomplete_suggestions", { ...args, facets: [] }), pick(args)),
+			topSearches: (args: VtexSearchArgs = {}) =>
+				json<Suggestion>(isUrl("top_searches", { ...args, facets: [] }), pick(args)),
+		},
+
+		/** Legacy Catalog API. */
+		catalog: {
+			pageType: async (path: string, options?: VtexRequestOptions) =>
+				json<PageType>(url(`/api/catalog_system/pub/portal/pagetype/${pathSegments(path)}`), options),
+			products: async (args: VtexCatalogSearchArgs = {}) => {
+				const target = url(
+					`/api/catalog_system/pub/products/search/${pathSegments(args.term ?? "")}`,
+					{
+						ft: args.ft,
+						_from: args.from,
+						_to: args.to,
+						O: args.sort,
+						sc: args.salesChannel ?? config.salesChannel,
+					},
+				);
+				for (const fq of args.fq ?? []) target.searchParams.append("fq", fq);
+				return json<LegacyProduct[]>(target, pick(args));
+			},
+			crossSelling: (type: CrossSellingType, productId: string, options?: VtexRequestOptions) =>
+				json<LegacyProduct[]>(
+					url(
+						`/api/catalog_system/pub/products/crossselling/${type}/${encodeURIComponent(productId)}`,
+					),
+					options,
+				),
+			categoryTree: (levels = 3, options?: VtexRequestOptions) =>
+				json<Category[]>(url(`/api/catalog_system/pub/category/tree/${levels}`), options),
+		},
+
+		/** Checkout API. Cart calls are shopper-scoped and return VTEX's `Set-Cookie` values. */
+		checkout: {
+			/**
+			 * Gets the shopper's cart from their `checkout.vtex.com` cookie, or creates one.
+			 * Every section by default; `sections` narrows it (`expectedOrderFormSections`).
+			 */
+			orderForm: (options: VtexRequestOptions & { sections?: string[] } = {}) =>
+				withCookies<OrderForm>(url("/api/checkout/pub/orderForm"), {
+					...pick(options),
+					method: "POST",
+					body: options.sections ? { expectedOrderFormSections: options.sections } : {},
+				}),
+			addItems: (orderFormId: string, orderItems: OrderFormItemInput[], options?: VtexRequestOptions) =>
+				withCookies<OrderForm>(url(orderFormPath(orderFormId, "/items")), {
+					...options,
+					method: "POST",
+					body: { orderItems },
+				}),
+			updateItems: (
+				orderFormId: string,
+				orderItems: { index: number; quantity: number }[],
+				options?: VtexRequestOptions,
+			) =>
+				withCookies<OrderForm>(url(orderFormPath(orderFormId, "/items/update")), {
+					...options,
+					method: "POST",
+					body: { orderItems },
+				}),
+			addCoupon: (orderFormId: string, text: string, options?: VtexRequestOptions) =>
+				withCookies<OrderForm>(url(orderFormPath(orderFormId, "/coupons")), {
+					...options,
+					method: "POST",
+					body: { text },
+				}),
+			attachment: (
+				orderFormId: string,
+				name: string,
+				body: Record<string, unknown>,
+				options?: VtexRequestOptions,
+			) =>
+				withCookies<OrderForm>(
+					url(orderFormPath(orderFormId, `/attachments/${encodeURIComponent(name)}`)),
+					{ ...options, method: "POST", body },
+				),
+			simulation: (
+				body: {
+					items: { id: string; quantity: number; seller: string }[];
+					postalCode?: string;
+					country?: string;
+				},
+				options: VtexRequestOptions & { salesChannel?: string } = {},
+			) =>
+				json<SimulationOrderForm>(
+					url("/api/checkout/pub/orderForms/simulation", {
+						sc: options.salesChannel ?? config.salesChannel,
+					}),
+					{ ...pick(options), method: "POST", body },
+				),
+			/** The region (and its sellers) serving a postal code; its `id` is the `regionId`. */
+			regions: (
+				args: { postalCode: string; country: string; salesChannel?: string },
+				options?: VtexRequestOptions,
+			) =>
+				json<{ id: string; sellers: { id: string; name: string }[] }[]>(
+					url("/api/checkout/pub/regions", {
+						postalCode: args.postalCode,
+						country: args.country,
+						sc: args.salesChannel ?? config.salesChannel,
+					}),
+					options,
+				),
+		},
+
+		/** Session API. Shopper-scoped; returns VTEX's `Set-Cookie` values. */
+		sessions: {
+			get: (options: VtexRequestOptions & { items?: string[] } = {}) =>
+				withCookies<Session>(
+					url("/api/sessions", { items: options.items?.join(",") }),
+					pick(options),
+				),
+			update: (publicProps: Record<string, { value: string }>, options?: VtexRequestOptions) =>
+				withCookies<{ id: string; sessionToken?: string }>(url("/api/sessions"), {
+					...options,
+					method: "POST",
+					body: { public: publicProps },
+				}),
+		},
+
+		/** VTEX IO's private GraphQL endpoint (`{account}.myvtex.com`). */
+		io: {
+			graphql: async <T>(
+				body: { query: string; variables?: Record<string, unknown>; operationName?: string },
+				options?: VtexRequestOptions,
+			): Promise<T> => {
+				const result = await json<{ data: T; errors?: unknown[] }>(
+					`https://${config.account}.myvtex.com/_v/private/graphql/v1`,
+					{ ...options, method: "POST", body },
+				);
+				// GraphQL errors arrive with HTTP 200; their messages can echo inputs, so they stay out.
+				if (result.errors?.length) throw new VtexError("io.graphql", 200);
+				return result.data;
+			},
+		},
+
+		/** Master Data v1. */
+		masterdata: {
+			search: <T>(
+				entity: string,
+				args: VtexRequestOptions & {
+					where?: string;
+					fields?: string[];
+					sort?: string;
+					from?: number;
+					to?: number;
+				} = {},
+			) =>
+				json<T[]>(
+					url(`/api/dataentities/${encodeURIComponent(entity)}/search`, {
+						_where: args.where,
+						_fields: args.fields?.join(","),
+						_sort: args.sort,
+					}),
+					{
+						...pick(args),
+						headers: { "rest-range": `resources=${args.from ?? 0}-${args.to ?? 10}` },
+					},
+				),
+			create: (entity: string, document: Record<string, unknown>, options?: VtexRequestOptions) =>
+				json<{ Id: string; Href: string; DocumentId: string }>(
+					url(`/api/dataentities/${encodeURIComponent(entity)}/documents`),
+					{ ...options, method: "POST", body: document },
+				),
+		},
+	};
+}
+
+export type VtexClient = ReturnType<typeof createVtexClient>;