@decocms/apps-shopify 8.0.0 → 8.1.0-next.1

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@decocms/apps-shopify",
-  "version": "8.0.0",
+  "version": "8.1.0-next.1",
   "type": "module",
-  "description": "Deco commerce app: Shopify integration",
+  "description": "Thin Shopify Storefront API client for Deco sites",
   "repository": {
     "type": "git",
     "url": "https://github.com/decocms/blocks.git",
@@ -10,39 +10,22 @@
   },
   "files": [
     "src",
-    "tsconfig.json"
+    "!src/**/*.test.ts",
+    "!src/**/__tests__"
   ],
   "main": "./src/index.ts",
   "exports": {
-    ".": "./src/index.ts",
-    "./mod": "./src/mod.ts",
-    "./client": "./src/client.ts",
-    "./loaders/*": "./src/loaders/*.ts",
-    "./actions/*": "./src/actions/*.ts",
-    "./actions/cart/*": "./src/actions/cart/*.ts",
-    "./actions/user/*": "./src/actions/user/*.ts",
-    "./utils/*": "./src/utils/*.ts",
-    "./registry": "./src/registry.ts"
+    ".": "./src/index.ts"
   },
   "scripts": {
     "build": "tsc",
     "test": "vitest run --root ../.. packages/apps-shopify/",
-    "typecheck": "tsc --noEmit",
-    "lint:unused": "knip"
+    "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@decocms/blocks": "8.0.0",
-    "@decocms/apps-commerce": "8.0.0",
-    "@decocms/tanstack": "8.0.0"
-  },
-  "peerDependencies": {
-    "react": "^19.0.0",
-    "react-dom": "^19.0.0"
+    "@decocms/blocks": "8.1.0-next.1"
   },
   "devDependencies": {
-    "@types/react": "^19.0.0",
-    "@types/react-dom": "^19.0.0",
-    "knip": "^5.86.0",
     "typescript": "^5.9.0"
   },
   "publishConfig": {

package/src/client.ts

@@ -1,58 +1,125 @@
-import { createGraphqlClient, type GraphQLClient } from "./utils/graphql";
-
-export interface ShopifyConfig {
-	storeName: string;
-	storefrontAccessToken: string;
-	publicUrl?: string;
-}
-
-let _client: GraphQLClient | null = null;
-let _config: ShopifyConfig | null = null;
-let _fetch: typeof fetch | undefined;
-
 /**
- * Override the fetch function used by the Shopify GraphQL client.
- * Use this to plug in instrumented fetch for logging/tracing.
+ * 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.
  *
- * @example
- * ```ts
- * import { createInstrumentedFetch } from "@decocms/blocks/sdk/instrumentedFetch";
- * import { setShopifyFetch } from "@decocms/apps/shopify";
- * setShopifyFetch(createInstrumentedFetch("shopify"));
- * ```
+ * 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 site's job.
  */
-export function setShopifyFetch(fetchFn: typeof fetch) {
-	_fetch = fetchFn;
-	if (_config) configureShopify(_config);
+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;
 }
 
-export function configureShopify(config: ShopifyConfig) {
-	_config = config;
-	_client = createGraphqlClient(
-		`https://${config.storeName}.myshopify.com/api/2025-04/graphql.json`,
-		{
-			"X-Shopify-Storefront-Access-Token": config.storefrontAccessToken,
-		},
-		_fetch,
-	);
+interface ShopifyRequestOptions {
+  /** Extra request headers, e.g. `Shopify-Storefront-Buyer-IP`. */
+  headers?: Record<string, string>;
+  signal?: AbortSignal;
 }
 
-export function getShopifyClient(): GraphQLClient {
-	if (!_client || !_config) {
-		throw new Error(
-			"Shopify not configured. Call configureShopify() first or check deco-shopify.json block.",
-		);
-	}
-	return _client;
+/** 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 function getShopifyConfig(): ShopifyConfig {
-	if (!_config) {
-		throw new Error("Shopify not configured.");
-	}
-	return _config;
+export interface ShopifyClient {
+  storefront: ShopifyGraphQL;
+  /** Throws when called without `adminAccessToken` in the config. */
+  admin: ShopifyGraphQL;
 }
 
-export function getBaseUrl(): string {
-	return _config?.publicUrl || "";
+/** 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/{utils/graphqlOperationName.ts → graphqlOperationName.ts}

@@ -36,32 +36,32 @@
 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, "");
+  doc
+    .replace(/"""[\s\S]*?"""/g, '""')
+    .replace(/"(?:\\.|[^"\\])*"/g, '""')
+    .replace(/#[^\n]*/g, "");
 
 export function extractGraphqlOperationName(
-	document: string,
-	explicit?: string,
+  document: string,
+  explicit?: string,
 ): string | undefined {
-	if (explicit) return explicit;
-	if (!document) return undefined;
+  if (explicit) return explicit;
+  if (!document) return undefined;
 
-	const stripped = stripCommentsAndStrings(document);
-	const names: string[] = [];
+  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;
-	}
+  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;
+  if (names.length === 1) return names[0];
+  return undefined;
 }

package/src/index.ts

@@ -1,43 +1,10 @@
-// App contract
-export { configure, type ShopifyState } from "./mod";
-
-// Client & Config
-
-export { default as addItems } from "./actions/cart/addItems";
-export { default as updateCoupons } from "./actions/cart/updateCoupons";
-export { default as updateItems } from "./actions/cart/updateItems";
-export { default as signIn } from "./actions/user/signIn";
-export { default as signUp } from "./actions/user/signUp";
-export type { ShopifyConfig } from "./client";
+/**
+ * `@decocms/apps-shopify`: a thin client for the Shopify Storefront API.
+ * See /next/upstream-clients.
+ */
 export {
-	configureShopify,
-	getBaseUrl,
-	getShopifyClient,
-	getShopifyConfig,
-	setShopifyFetch,
+  createShopifyClient,
+  type ShopifyClient,
+  type ShopifyClientConfig,
+  ShopifyError,
 } from "./client";
-export { initShopify, initShopifyFromBlocks } from "./init";
-export type { CartLine, ShopifyCart } from "./loaders/cart";
-// Cart
-export { createCart, getCart } from "./loaders/cart";
-export { default as productDetailsPageLoader } from "./loaders/ProductDetailsPage";
-// Product Loaders
-export { default as productListLoader } from "./loaders/ProductList";
-export { default as productListingPageLoader } from "./loaders/ProductListingPage";
-export { default as relatedProductsLoader } from "./loaders/RelatedProducts";
-export type { Shop } from "./loaders/shop";
-// Shop
-export { default as shopLoader } from "./loaders/shop";
-export type { ShopifyUser } from "./loaders/user";
-// User
-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 {
-	type CreateShopifyFetchOptions,
-	createShopifyFetch,
-} from "./utils/instrumentedFetch";
-export { shopifyOperationRouter } from "./utils/operationRouter";
-export { getUserCookie, setUserCookie } from "./utils/user";

package/src/actions/cart/addItems.ts

@@ -1,36 +0,0 @@
-import { getShopifyClient } from "../../client";
-import type { ShopifyCart } from "../../loaders/cart";
-import { getCartCookie, setCartCookie } from "../../utils/cart";
-import { AddItemToCart } from "../../utils/storefront/queries";
-
-export interface AddItemProps {
-	lines: {
-		merchandiseId: string;
-		attributes?: Array<{ key: string; value: string }>;
-		quantity?: number;
-		sellingPlanId?: string;
-	};
-	requestHeaders: Headers;
-	responseHeaders?: Headers;
-}
-
-export default async function addItems({
-	lines,
-	requestHeaders,
-	responseHeaders,
-}: AddItemProps): Promise<ShopifyCart | null> {
-	const client = getShopifyClient();
-	const cartId = getCartCookie(requestHeaders);
-
-	if (!cartId) throw new Error("Missing cart cookie");
-
-	const data = await client.query<{
-		payload?: { cart?: ShopifyCart };
-	}>(AddItemToCart, { cartId, lines });
-
-	if (responseHeaders) {
-		setCartCookie(responseHeaders, cartId);
-	}
-
-	return data.payload?.cart ?? null;
-}

package/src/actions/cart/updateCoupons.ts

@@ -1,31 +0,0 @@
-import { getShopifyClient } from "../../client";
-import type { ShopifyCart } from "../../loaders/cart";
-import { getCartCookie, setCartCookie } from "../../utils/cart";
-import { AddCoupon } from "../../utils/storefront/queries";
-
-export interface UpdateCouponsProps {
-	discountCodes: string[];
-	requestHeaders: Headers;
-	responseHeaders?: Headers;
-}
-
-export default async function updateCoupons({
-	discountCodes,
-	requestHeaders,
-	responseHeaders,
-}: UpdateCouponsProps): Promise<ShopifyCart | null> {
-	const client = getShopifyClient();
-	const cartId = getCartCookie(requestHeaders);
-
-	if (!cartId) throw new Error("Missing cart cookie");
-
-	const data = await client.query<{
-		payload?: { cart?: ShopifyCart };
-	}>(AddCoupon, { cartId, discountCodes });
-
-	if (responseHeaders) {
-		setCartCookie(responseHeaders, cartId);
-	}
-
-	return data.payload?.cart ?? null;
-}

package/src/actions/cart/updateItems.ts

@@ -1,31 +0,0 @@
-import { getShopifyClient } from "../../client";
-import type { ShopifyCart } from "../../loaders/cart";
-import { getCartCookie, setCartCookie } from "../../utils/cart";
-import { UpdateItems } from "../../utils/storefront/queries";
-
-export interface UpdateItemsProps {
-	lines: Array<{ id: string; quantity: number }>;
-	requestHeaders: Headers;
-	responseHeaders?: Headers;
-}
-
-export default async function updateItems({
-	lines,
-	requestHeaders,
-	responseHeaders,
-}: UpdateItemsProps): Promise<ShopifyCart | null> {
-	const client = getShopifyClient();
-	const cartId = getCartCookie(requestHeaders);
-
-	if (!cartId) throw new Error("Missing cart cookie");
-
-	const data = await client.query<{
-		payload?: { cart?: ShopifyCart };
-	}>(UpdateItems, { cartId, lines });
-
-	if (responseHeaders) {
-		setCartCookie(responseHeaders, cartId);
-	}
-
-	return data.payload?.cart ?? null;
-}

package/src/actions/user/signIn.ts

@@ -1,40 +0,0 @@
-import { getShopifyClient } from "../../client";
-import { SignInWithEmailAndPassword } from "../../utils/storefront/queries";
-import { getUserCookie, setUserCookie } from "../../utils/user";
-
-export interface SignInProps {
-	email: string;
-	password: string;
-	requestHeaders: Headers;
-	responseHeaders?: Headers;
-}
-
-export interface SignInResult {
-	customerAccessTokenCreate: {
-		customerAccessToken?: { accessToken: string; expiresAt: string } | null;
-		customerUserErrors?: Array<{ code?: string; message: string }>;
-	};
-}
-
-export default async function signIn(props: SignInProps): Promise<SignInResult | null> {
-	const client = getShopifyClient();
-	const { email, password, requestHeaders, responseHeaders } = props;
-
-	const existingToken = getUserCookie(requestHeaders);
-	if (existingToken) return null;
-
-	try {
-		const data = await client.query<SignInResult>(SignInWithEmailAndPassword, { email, password });
-
-		if (data.customerAccessTokenCreate.customerAccessToken && responseHeaders) {
-			setUserCookie(
-				responseHeaders,
-				data.customerAccessTokenCreate.customerAccessToken.accessToken,
-			);
-		}
-
-		return data;
-	} catch {
-		return null;
-	}
-}

package/src/actions/user/signUp.ts

@@ -1,31 +0,0 @@
-import { getShopifyClient } from "../../client";
-import { RegisterAccount } from "../../utils/storefront/queries";
-
-export interface SignUpProps {
-	email: string;
-	password: string;
-	firstName?: string;
-	lastName?: string;
-	acceptsMarketing?: boolean;
-}
-
-export interface SignUpResult {
-	customerCreate: {
-		customer?: { id: string } | null;
-		customerUserErrors?: Array<{ code?: string; message: string }>;
-	};
-}
-
-export default async function signUp(props: SignUpProps): Promise<SignUpResult> {
-	const client = getShopifyClient();
-
-	const data = await client.query<SignUpResult>(RegisterAccount, {
-		email: props.email,
-		password: props.password,
-		firstName: props.firstName,
-		lastName: props.lastName,
-		acceptsMarketing: props.acceptsMarketing,
-	});
-
-	return data;
-}

package/src/init.ts

@@ -1,39 +0,0 @@
-import { configureShopify } from "./client";
-
-let initialized = false;
-
-/**
- * Initialize Shopify from raw block data.
- * The site is responsible for reading the blocks and passing the config here.
- */
-export function initShopify(config: { storeName: string; storefrontAccessToken: string }) {
-	if (initialized) return;
-
-	if (!config.storeName || !config.storefrontAccessToken) {
-		console.warn("[Shopify] Missing storeName or storefrontAccessToken.");
-		return;
-	}
-
-	console.log(`[Shopify] Initializing: ${config.storeName}.myshopify.com`);
-	configureShopify(config);
-	initialized = true;
-}
-
-/**
- * Initialize Shopify from a blocks map (convenience wrapper).
- * Looks for the "deco-shopify" block and extracts credentials.
- */
-export function initShopifyFromBlocks(blocks: Record<string, unknown>) {
-	const shopifyBlock = blocks["deco-shopify"] as
-		| { storeName: string; storefrontAccessToken: string }
-		| undefined;
-	if (!shopifyBlock) {
-		console.warn("[Shopify] No deco-shopify block found.");
-		return;
-	}
-
-	initShopify({
-		storeName: shopifyBlock.storeName,
-		storefrontAccessToken: shopifyBlock.storefrontAccessToken,
-	});
-}

package/src/loaders/ProductDetailsPage.ts

@@ -1,31 +0,0 @@
-import type { ProductDetailsPage } from "@decocms/apps-commerce/types";
-import { getShopifyClient } from "../client";
-import { GetProduct } from "../utils/storefront/queries";
-import { type ProductShopify, toProductPage } from "../utils/transform";
-import type { Metafield } from "../utils/types";
-
-export interface Props {
-	slug: string;
-	metafields?: Metafield[];
-}
-
-export default async function productDetailsPageLoader(
-	props: Props,
-	url?: URL,
-): Promise<ProductDetailsPage | null> {
-	const client = getShopifyClient();
-	const { slug, metafields = [] } = props;
-
-	const splitted = slug?.split("-") ?? [];
-	const maybeSkuId = Number(splitted[splitted.length - 1]);
-	const handle = splitted.slice(0, maybeSkuId ? -1 : undefined).join("-");
-
-	const data = await client.query<{ product?: ProductShopify }>(GetProduct, {
-		handle,
-		identifiers: metafields,
-	});
-
-	if (!data?.product) return null;
-
-	return toProductPage(data.product, url ?? new URL("https://localhost"), maybeSkuId || undefined);
-}