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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/apps-shopify",
-  "version": "7.71.6",
+  "version": "8.0.0-next.0",
   "type": "module",
   "description": "Deco commerce app: Shopify integration",
   "repository": {
@@ -31,9 +31,9 @@
     "lint:unused": "knip"
   },
   "dependencies": {
-    "@decocms/blocks": "7.71.6",
-    "@decocms/apps-commerce": "7.71.6",
-    "@decocms/tanstack": "7.71.6"
+    "@decocms/blocks": "8.0.0-next.0",
+    "@decocms/apps-commerce": "8.0.0-next.0",
+    "@decocms/tanstack": "8.0.0-next.0"
   },
   "peerDependencies": {
     "react": "^19.0.0",

package/src/index.ts

@@ -34,10 +34,19 @@ export { default as userLoader } from "./loaders/user";
 export { getCartCookie, setCartCookie } from "./utils/cart";
 // Cookie utils
 export { getCookies, setCookie } from "./utils/cookies";
-export { extractGraphqlOperationName } from "./utils/graphqlOperationName";
+export { extractGraphqlOperationName } from "./v8/graphqlOperationName";
 export {
 	type CreateShopifyFetchOptions,
 	createShopifyFetch,
 } from "./utils/instrumentedFetch";
 export { shopifyOperationRouter } from "./utils/operationRouter";
 export { getUserCookie, setUserCookie } from "./utils/user";
+
+// The next-major upstream client (/next/upstream-clients). Everything above is
+// the v7 surface, kept for v7 consumers until v7 is dropped.
+export {
+	createShopifyClient,
+	type ShopifyClient,
+	type ShopifyClientConfig,
+	ShopifyError,
+} from "./v8/client";

package/src/utils/graphqlOperationName.ts

@@ -1,67 +1,2 @@
-/**
- * Extract a semantic operation name from a GraphQL document.
- *
- * Used at the Shopify GraphQL client layer to stamp `init.operation`
- * on the outbound fetch. The framework then suffixes the integration
- * name (`shopify.<operation>`) onto the span and uses the same string
- * as the `fetch.operation` attribute + histogram label.
- *
- * Resolution order:
- *
- *   1. An explicit `operationName` argument (e.g. when the client
- *      received one alongside a multi-operation document) wins.
- *   2. If the document has exactly one named operation, that name
- *      is used.
- *   3. If the document has zero or many anonymous operations, we
- *      return `undefined` so the caller can fall back (typically to
- *      the URL-derived `storefront.graphql` / `admin.graphql`).
- *
- * The parser is deliberately a small regex pass, not a full GraphQL
- * tokenizer:
- *
- *   - GraphQL operation definitions live at the top level of the
- *     document, never nested inside other operations, fragments, or
- *     selection sets, so positional context isn't required to find
- *     them — only to not match the literal words `query` /
- *     `mutation` / `subscription` inside string values.
- *   - We strip block strings (`""" … """`), string literals
- *     (`"…"`), and `# …` comments before matching, which is enough
- *     to make false-positive matches inside comments / docs vanish.
- *
- * If a Shopify operation is ever sufficiently mis-named to break
- * this (unlikely, since the storefront SDK names them deliberately),
- * the caller can always set `init.operation` explicitly.
- */
-
-const OPERATION_RE = /\b(?:query|mutation|subscription)\s+([A-Za-z_][A-Za-z0-9_]*)/g;
-
-const stripCommentsAndStrings = (doc: string): string =>
-	doc
-		.replace(/"""[\s\S]*?"""/g, '""')
-		.replace(/"(?:\\.|[^"\\])*"/g, '""')
-		.replace(/#[^\n]*/g, "");
-
-export function extractGraphqlOperationName(
-	document: string,
-	explicit?: string,
-): string | undefined {
-	if (explicit) return explicit;
-	if (!document) return undefined;
-
-	const stripped = stripCommentsAndStrings(document);
-	const names: string[] = [];
-
-	OPERATION_RE.lastIndex = 0;
-	for (
-		let match = OPERATION_RE.exec(stripped);
-		match !== null;
-		match = OPERATION_RE.exec(stripped)
-	) {
-		const [, name] = match;
-		if (name) names.push(name);
-		if (names.length > 1) break;
-	}
-
-	if (names.length === 1) return names[0];
-	return undefined;
-}
+// Moved to the v8 client tree; re-exported here for the v7 modules.
+export { extractGraphqlOperationName } from "../v8/graphqlOperationName";

package/src/utils/operationRouter.ts

@@ -11,7 +11,7 @@
  * hitting, not what the call actually does. The semantic operation
  * name lives in the GraphQL document itself (`query Foo { ... }`),
  * and is extracted by `extractGraphqlOperationName` (see
- * `./graphqlOperationName.ts`) at the client layer and stamped as
+ * `../v8/graphqlOperationName.ts`) at the client layer and stamped as
  * `init.operation`, which always wins over this router.
  *
  * So this router exists for:

package/src/v8/client.test.ts

@@ -0,0 +1,136 @@
+// @vitest-environment node
+/**
+ * createShopifyClient (/next/upstream-clients#write-a-client): every request
+ * goes through the instrumented fetch as provider "shopify", labeled with the
+ * GraphQL operation name, and errors carry no bodies or tokens.
+ */
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const seen = vi.hoisted(() => ({
+  options: [] as unknown[],
+  operations: [] as (string | undefined)[],
+}));
+
+vi.mock("@decocms/blocks/fetch", async (importOriginal) => {
+  const real = await importOriginal<typeof import("@decocms/blocks/fetch")>();
+  return {
+    createInstrumentedFetch: (options: Parameters<typeof real.createInstrumentedFetch>[0]) => {
+      seen.options.push(options);
+      const request = real.createInstrumentedFetch(options);
+      return (input: string | URL | Request, init?: RequestInit & { operation?: string }) => {
+        seen.operations.push(init?.operation);
+        return request(input, init);
+      };
+    },
+  };
+});
+
+import { createShopifyClient, ShopifyError } from "./client";
+
+function upstream(body: unknown, status = 200) {
+  return vi.fn(
+    async (_input: string | URL | Request, _init?: RequestInit) =>
+      new Response(JSON.stringify(body), { status }),
+  );
+}
+
+const config = { storeName: "acme", storefrontAccessToken: "sf-token", apiVersion: "2026-07" };
+
+beforeEach(() => {
+  seen.options.length = 0;
+  seen.operations.length = 0;
+});
+
+describe("createShopifyClient", () => {
+  it("posts to the Storefront API through the instrumented fetch, with no retries or circuit breaker", async () => {
+    const fetch = upstream({ data: { product: { id: "1" } } });
+    const shopify = createShopifyClient(config, { fetch });
+
+    const data = await shopify.storefront.query<{ product: { id: string } }>(
+      "query ProductByHandle($handle: String!) { product(handle: $handle) { id } }",
+      { handle: "linen-shirt" },
+      { headers: { "Shopify-Storefront-Buyer-IP": "203.0.113.7" } },
+    );
+
+    expect(data).toEqual({ product: { id: "1" } });
+    expect(seen.options).toEqual([{ provider: "shopify", fetch }]);
+    expect(seen.operations).toEqual(["ProductByHandle"]);
+    const [url, init] = fetch.mock.calls[0] ?? [];
+    expect(url).toBe("https://acme.myshopify.com/api/2026-07/graphql.json");
+    expect(init?.method).toBe("POST");
+    expect(init?.headers).toMatchObject({
+      "x-shopify-storefront-access-token": "sf-token",
+      "Shopify-Storefront-Buyer-IP": "203.0.113.7",
+    });
+    expect(JSON.parse(String(init?.body))).toEqual({
+      query: "query ProductByHandle($handle: String!) { product(handle: $handle) { id } }",
+      variables: { handle: "linen-shirt" },
+    });
+  });
+
+  it("labels an unnamed document by its API surface", async () => {
+    const fetch = upstream({ data: { shop: { name: "Acme" } } });
+    const shopify = createShopifyClient(
+      { ...config, adminAccessToken: "admin-token", apiVersion: "2025-07" },
+      { fetch },
+    );
+    await shopify.storefront.query("{ shop { name } }");
+    await shopify.admin.query("{ shop { name } }");
+
+    expect(seen.operations).toEqual(["storefront.graphql", "admin.graphql"]);
+    expect(fetch.mock.calls[1]?.[0]).toBe(
+      "https://acme.myshopify.com/admin/api/2025-07/graphql.json",
+    );
+    expect(fetch.mock.calls[1]?.[1]?.headers).toMatchObject({
+      "x-shopify-access-token": "admin-token",
+    });
+  });
+
+  it("refuses admin calls without an admin token, without sending anything", async () => {
+    const fetch = upstream({ data: {} });
+    const shopify = createShopifyClient(config, { fetch });
+    await expect(shopify.admin.query("{ shop { name } }")).rejects.toThrow(/adminAccessToken/);
+    expect(fetch).not.toHaveBeenCalled();
+  });
+
+  it("reports HTTP failures by operation and status, never the body or token", async () => {
+    const fetch = upstream({ errors: "secret upstream detail sf-token" }, 401);
+    const shopify = createShopifyClient(config, { fetch });
+    const error = (await shopify.storefront
+      .query("query Cart { cart { id } }")
+      .catch((e: unknown) => e)) as ShopifyError;
+
+    expect(error).toBeInstanceOf(ShopifyError);
+    expect(error).toMatchObject({ operation: "Cart", status: 401, codes: [] });
+    expect(error.message).toBe("shopify Cart failed with HTTP 401");
+  });
+
+  it("reports a non-JSON body as INVALID_JSON, never quoting the body", async () => {
+    const fetch = vi.fn(async () => new Response("<html>sf-token</html>", { status: 200 }));
+    const shopify = createShopifyClient(config, { fetch });
+    const error = (await shopify.storefront
+      .query("query Cart { cart { id } }")
+      .catch((e: unknown) => e)) as ShopifyError;
+
+    expect(error).toBeInstanceOf(ShopifyError);
+    expect(error).toMatchObject({ operation: "Cart", status: 200, codes: ["INVALID_JSON"] });
+    expect(error.message).not.toContain("sf-token");
+    expect(error.message).not.toContain("<html");
+  });
+
+  it("reports GraphQL errors by their codes, not their messages", async () => {
+    const fetch = upstream({
+      errors: [
+        { message: "Throttled for customer@example.com", extensions: { code: "THROTTLED" } },
+        { message: "again", extensions: { code: "THROTTLED" } },
+      ],
+    });
+    const shopify = createShopifyClient(config, { fetch });
+    const error = (await shopify.storefront
+      .query("query Cart { cart { id } }")
+      .catch((e: unknown) => e)) as ShopifyError;
+
+    expect(error).toMatchObject({ operation: "Cart", status: 200, codes: ["THROTTLED"] });
+    expect(error.message).not.toContain("customer@example.com");
+  });
+});

package/src/v8/client.ts

@@ -0,0 +1,125 @@
+/**
+ * The Shopify upstream client (/next/upstream-clients): the Storefront and
+ * Admin GraphQL APIs over the framework's instrumented fetch, and nothing
+ * else. Converters to commerce types, cart and customer flows, hooks and
+ * loaders live in the Shopify platform template and site code.
+ *
+ * Every request is measured as provider "shopify", labeled with the GraphQL
+ * operation's own name (`query ProductByHandle { … }` → "ProductByHandle"),
+ * or "storefront.graphql" / "admin.graphql" for an unnamed document. Retries
+ * and the circuit breaker stay off, as for every client but VTEX's; caching
+ * is the framework binding's job.
+ */
+import { createInstrumentedFetch } from "@decocms/blocks/fetch";
+import { extractGraphqlOperationName } from "./graphqlOperationName";
+
+export interface ShopifyClientConfig {
+  /** The store's subdomain: "acme" for acme.myshopify.com. */
+  storeName: string;
+  /** Storefront API access token. */
+  storefrontAccessToken: string;
+  /** Admin API access token; `admin` is only available when it's set. */
+  adminAccessToken?: string;
+  /** The Shopify API version, e.g. "2026-07". The site owns it, so there is no default to go stale. */
+  apiVersion: string;
+}
+
+interface ShopifyRequestOptions {
+  /** Extra request headers, e.g. `Shopify-Storefront-Buyer-IP`. */
+  headers?: Record<string, string>;
+  signal?: AbortSignal;
+}
+
+/** One GraphQL endpoint: send a document, get its `data` back. */
+interface ShopifyGraphQL {
+  query<T, V extends Record<string, unknown> = Record<string, unknown>>(
+    document: string,
+    variables?: V,
+    options?: ShopifyRequestOptions,
+  ): Promise<T>;
+}
+
+export interface ShopifyClient {
+  storefront: ShopifyGraphQL;
+  /** Throws when called without `adminAccessToken` in the config. */
+  admin: ShopifyGraphQL;
+}
+
+/** A failed request. Carries the operation, the HTTP status and Shopify's error codes; never bodies or tokens. */
+export class ShopifyError extends Error {
+  constructor(
+    readonly operation: string,
+    readonly status: number,
+    readonly codes: string[] = [],
+  ) {
+    super(
+      codes.length > 0
+        ? `shopify ${operation} returned GraphQL errors (${codes.join(", ")})`
+        : `shopify ${operation} failed with HTTP ${status}`,
+    );
+    this.name = "ShopifyError";
+  }
+}
+
+export function createShopifyClient(
+  config: ShopifyClientConfig,
+  options: { fetch?: typeof globalThis.fetch } = {},
+): ShopifyClient {
+  const request = createInstrumentedFetch({ provider: "shopify", fetch: options.fetch });
+  const origin = `https://${config.storeName}.myshopify.com`;
+  const version = config.apiVersion;
+
+  const endpoint = (surface: "storefront" | "admin", url: string, auth: Record<string, string>) =>
+    ({
+      async query(document, variables, { headers, signal } = {}) {
+        const operation = extractGraphqlOperationName(document) ?? `${surface}.graphql`;
+        const response = await request(url, {
+          operation,
+          method: "POST",
+          headers: { "content-type": "application/json", ...headers, ...auth },
+          body: JSON.stringify({ query: document, variables }),
+          signal,
+        });
+        if (!response.ok) {
+          void response.body?.cancel().catch(() => {});
+          throw new ShopifyError(operation, response.status);
+        }
+        // A non-JSON body (an HTML error page) must not reach the error: the
+        // SyntaxError's message quotes the start of the body.
+        let body: { data?: unknown; errors?: { extensions?: { code?: unknown } }[] };
+        try {
+          body = await response.json();
+        } catch {
+          throw new ShopifyError(operation, response.status, ["INVALID_JSON"]);
+        }
+        // Partial data alongside errors is rejected as a whole, deliberately:
+        // a thin client doesn't guess which fields are still trustworthy.
+        if (body.errors?.length || body.data == null) {
+          const codes = body.errors?.length
+            ? body.errors.map((e) =>
+                typeof e.extensions?.code === "string" ? e.extensions.code : "UNKNOWN",
+              )
+            : ["MISSING_DATA"];
+          throw new ShopifyError(operation, response.status, [...new Set(codes)]);
+        }
+        return body.data as never;
+      },
+    }) satisfies ShopifyGraphQL;
+
+  const adminToken = config.adminAccessToken;
+  return {
+    storefront: endpoint("storefront", `${origin}/api/${version}/graphql.json`, {
+      "x-shopify-storefront-access-token": config.storefrontAccessToken,
+    }),
+    admin: adminToken
+      ? endpoint("admin", `${origin}/admin/api/${version}/graphql.json`, {
+          "x-shopify-access-token": adminToken,
+        })
+      : {
+          query: () =>
+            Promise.reject(
+              new Error("shopify admin: pass adminAccessToken to createShopifyClient"),
+            ),
+        },
+  };
+}

package/src/v8/graphqlOperationName.test.ts

@@ -0,0 +1,80 @@
+import { describe, expect, it } from "vitest";
+import { extractGraphqlOperationName } from "./graphqlOperationName";
+
+describe("extractGraphqlOperationName", () => {
+  it("returns the explicit name when provided, regardless of body content", () => {
+    expect(extractGraphqlOperationName("query Whatever { x }", "ForcedName")).toBe("ForcedName");
+    expect(extractGraphqlOperationName("", "Override")).toBe("Override");
+  });
+
+  it("extracts a single named query", () => {
+    expect(
+      extractGraphqlOperationName("query ProductBySlug($slug: String!) { product { id } }"),
+    ).toBe("ProductBySlug");
+  });
+
+  it("extracts a single named mutation", () => {
+    expect(
+      extractGraphqlOperationName("mutation CartLinesAdd($cartId: ID!) { cartLinesAdd { } }"),
+    ).toBe("CartLinesAdd");
+  });
+
+  it("extracts a single named subscription", () => {
+    expect(extractGraphqlOperationName("subscription OrderEvents { orderUpdated { id } }")).toBe(
+      "OrderEvents",
+    );
+  });
+
+  it("returns undefined for anonymous operations", () => {
+    expect(extractGraphqlOperationName("{ product { id } }")).toBeUndefined();
+    expect(extractGraphqlOperationName("query { product { id } }")).toBeUndefined();
+  });
+
+  it("returns undefined when document has more than one named operation (caller must disambiguate)", () => {
+    const multi = `
+			query OpA { a }
+			query OpB { b }
+		`;
+    expect(extractGraphqlOperationName(multi)).toBeUndefined();
+  });
+
+  it("ignores the words query/mutation/subscription inside string literals", () => {
+    const docWithStringy = `query RealName { thing(arg: "this query mutation subscription is a string") }`;
+    expect(extractGraphqlOperationName(docWithStringy)).toBe("RealName");
+  });
+
+  it("ignores the words inside block strings (triple-quoted)", () => {
+    const doc = `
+			"""
+			This block string mentions query Inner and mutation Inner2.
+			"""
+			query OuterReal { x }
+		`;
+    expect(extractGraphqlOperationName(doc)).toBe("OuterReal");
+  });
+
+  it("ignores the words inside # comments", () => {
+    const doc = `
+			# query CommentedOut { x }
+			query Active { y }
+		`;
+    expect(extractGraphqlOperationName(doc)).toBe("Active");
+  });
+
+  it("returns undefined on an empty / nullish body", () => {
+    expect(extractGraphqlOperationName("")).toBeUndefined();
+    expect(extractGraphqlOperationName("   \n\t  ")).toBeUndefined();
+  });
+
+  it("handles a real-world Shopify storefront query shape", () => {
+    const doc = `
+			query ProductDetails($handle: String!, $country: CountryCode!) @inContext(country: $country) {
+				product(handle: $handle) {
+					id
+					title
+				}
+			}
+		`;
+    expect(extractGraphqlOperationName(doc)).toBe("ProductDetails");
+  });
+});

package/src/v8/graphqlOperationName.ts

@@ -0,0 +1,67 @@
+/**
+ * Extract a semantic operation name from a GraphQL document.
+ *
+ * Used at the Shopify GraphQL client layer to stamp `init.operation`
+ * on the outbound fetch. The framework then suffixes the integration
+ * name (`shopify.<operation>`) onto the span and uses the same string
+ * as the `fetch.operation` attribute + histogram label.
+ *
+ * Resolution order:
+ *
+ *   1. An explicit `operationName` argument (e.g. when the client
+ *      received one alongside a multi-operation document) wins.
+ *   2. If the document has exactly one named operation, that name
+ *      is used.
+ *   3. If the document has zero or many anonymous operations, we
+ *      return `undefined` so the caller can fall back (typically to
+ *      the URL-derived `storefront.graphql` / `admin.graphql`).
+ *
+ * The parser is deliberately a small regex pass, not a full GraphQL
+ * tokenizer:
+ *
+ *   - GraphQL operation definitions live at the top level of the
+ *     document, never nested inside other operations, fragments, or
+ *     selection sets, so positional context isn't required to find
+ *     them — only to not match the literal words `query` /
+ *     `mutation` / `subscription` inside string values.
+ *   - We strip block strings (`""" … """`), string literals
+ *     (`"…"`), and `# …` comments before matching, which is enough
+ *     to make false-positive matches inside comments / docs vanish.
+ *
+ * If a Shopify operation is ever sufficiently mis-named to break
+ * this (unlikely, since the storefront SDK names them deliberately),
+ * the caller can always set `init.operation` explicitly.
+ */
+
+const OPERATION_RE = /\b(?:query|mutation|subscription)\s+([A-Za-z_][A-Za-z0-9_]*)/g;
+
+const stripCommentsAndStrings = (doc: string): string =>
+  doc
+    .replace(/"""[\s\S]*?"""/g, '""')
+    .replace(/"(?:\\.|[^"\\])*"/g, '""')
+    .replace(/#[^\n]*/g, "");
+
+export function extractGraphqlOperationName(
+  document: string,
+  explicit?: string,
+): string | undefined {
+  if (explicit) return explicit;
+  if (!document) return undefined;
+
+  const stripped = stripCommentsAndStrings(document);
+  const names: string[] = [];
+
+  OPERATION_RE.lastIndex = 0;
+  for (
+    let match = OPERATION_RE.exec(stripped);
+    match !== null;
+    match = OPERATION_RE.exec(stripped)
+  ) {
+    const [, name] = match;
+    if (name) names.push(name);
+    if (names.length > 1) break;
+  }
+
+  if (names.length === 1) return names[0];
+  return undefined;
+}

package/src/utils/__tests__/graphqlOperationName.test.ts

@@ -1,80 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { extractGraphqlOperationName } from "../graphqlOperationName";
-
-describe("extractGraphqlOperationName", () => {
-	it("returns the explicit name when provided, regardless of body content", () => {
-		expect(extractGraphqlOperationName("query Whatever { x }", "ForcedName")).toBe("ForcedName");
-		expect(extractGraphqlOperationName("", "Override")).toBe("Override");
-	});
-
-	it("extracts a single named query", () => {
-		expect(
-			extractGraphqlOperationName("query ProductBySlug($slug: String!) { product { id } }"),
-		).toBe("ProductBySlug");
-	});
-
-	it("extracts a single named mutation", () => {
-		expect(
-			extractGraphqlOperationName("mutation CartLinesAdd($cartId: ID!) { cartLinesAdd { } }"),
-		).toBe("CartLinesAdd");
-	});
-
-	it("extracts a single named subscription", () => {
-		expect(extractGraphqlOperationName("subscription OrderEvents { orderUpdated { id } }")).toBe(
-			"OrderEvents",
-		);
-	});
-
-	it("returns undefined for anonymous operations", () => {
-		expect(extractGraphqlOperationName("{ product { id } }")).toBeUndefined();
-		expect(extractGraphqlOperationName("query { product { id } }")).toBeUndefined();
-	});
-
-	it("returns undefined when document has more than one named operation (caller must disambiguate)", () => {
-		const multi = `
-			query OpA { a }
-			query OpB { b }
-		`;
-		expect(extractGraphqlOperationName(multi)).toBeUndefined();
-	});
-
-	it("ignores the words query/mutation/subscription inside string literals", () => {
-		const docWithStringy = `query RealName { thing(arg: "this query mutation subscription is a string") }`;
-		expect(extractGraphqlOperationName(docWithStringy)).toBe("RealName");
-	});
-
-	it("ignores the words inside block strings (triple-quoted)", () => {
-		const doc = `
-			"""
-			This block string mentions query Inner and mutation Inner2.
-			"""
-			query OuterReal { x }
-		`;
-		expect(extractGraphqlOperationName(doc)).toBe("OuterReal");
-	});
-
-	it("ignores the words inside # comments", () => {
-		const doc = `
-			# query CommentedOut { x }
-			query Active { y }
-		`;
-		expect(extractGraphqlOperationName(doc)).toBe("Active");
-	});
-
-	it("returns undefined on an empty / nullish body", () => {
-		expect(extractGraphqlOperationName("")).toBeUndefined();
-		expect(extractGraphqlOperationName("   \n\t  ")).toBeUndefined();
-	});
-
-	it("handles a real-world Shopify storefront query shape", () => {
-		const doc = `
-			query ProductDetails($handle: String!, $country: CountryCode!) @inContext(country: $country) {
-				product(handle: $handle) {
-					id
-					title
-				}
-			}
-		`;
-		expect(extractGraphqlOperationName(doc)).toBe("ProductDetails");
-	});
-});