@decocms/apps-shopify 7.2.0

package/src/loaders/RelatedProducts.ts

@@ -0,0 +1,42 @@
+import type { Product } from "@decocms/apps-commerce/types";
+import { getShopifyClient } from "../client";
+import { GetProduct, ProductRecommendations } from "../utils/storefront/queries";
+import { type ProductShopify, toProduct } from "../utils/transform";
+import type { Metafield } from "../utils/types";
+
+export interface Props {
+	slug: string;
+	count?: number;
+	metafields?: Metafield[];
+}
+
+export default async function relatedProductsLoader(
+	props: Props,
+	url?: URL,
+): Promise<Product[] | null> {
+	const client = getShopifyClient();
+	const { slug, count = 10, metafields = [] } = props;
+
+	const splitted = slug?.split("-") ?? [];
+	const maybeSkuId = Number(splitted[splitted.length - 1]);
+	const handle = splitted.slice(0, maybeSkuId ? -1 : undefined).join("-");
+
+	const productData = await client.query<{ product?: ProductShopify }>(GetProduct, {
+		handle,
+		identifiers: metafields,
+	});
+
+	if (!productData?.product) return [];
+
+	const data = await client.query<{
+		productRecommendations?: ProductShopify[];
+	}>(ProductRecommendations, { productId: productData.product.id, identifiers: metafields });
+
+	if (!data?.productRecommendations) return [];
+
+	const baseUrl = url ?? new URL("https://localhost");
+
+	return data.productRecommendations
+		.map((p) => toProduct(p, p.variants.nodes[0], baseUrl))
+		.slice(0, count);
+}

package/src/loaders/cart.ts

@@ -0,0 +1,74 @@
+import { getShopifyClient } from "../client";
+import { getCartCookie, setCartCookie } from "../utils/cart";
+import { CreateCart, GetCart } from "../utils/storefront/queries";
+
+export interface CartLine {
+	id: string;
+	quantity: number;
+	merchandise: {
+		id: string;
+		title: string;
+		image?: { url: string; altText?: string | null } | null;
+		product: { title: string; handle: string; onlineStoreUrl?: string | null };
+		price: { amount: string; currencyCode: string };
+	};
+	discountAllocations?: Array<{
+		code?: string;
+		discountedAmount?: { amount: string; currencyCode: string };
+	}>;
+	cost?: {
+		totalAmount: { amount: string; currencyCode: string };
+		subtotalAmount: { amount: string; currencyCode: string };
+		amountPerQuantity?: { amount: string; currencyCode: string };
+		compareAtAmountPerQuantity?: { amount: string; currencyCode: string } | null;
+	};
+}
+
+export interface ShopifyCart {
+	id: string;
+	checkoutUrl: string;
+	totalQuantity: number;
+	lines: { nodes: CartLine[] };
+	cost: {
+		totalTaxAmount?: { amount: string; currencyCode: string };
+		subtotalAmount: { amount: string; currencyCode: string };
+		totalAmount: { amount: string; currencyCode: string };
+		checkoutChargeAmount?: { amount: string; currencyCode: string };
+	};
+	discountCodes?: Array<{ applicable: boolean; code: string }>;
+	discountAllocations?: Array<{
+		discountedAmount: { amount: string; currencyCode: string };
+	}>;
+}
+
+export async function getCart(
+	requestHeaders: Headers,
+	responseHeaders?: Headers,
+): Promise<ShopifyCart | null> {
+	const client = getShopifyClient();
+	const maybeCartId = getCartCookie(requestHeaders);
+
+	const cartId =
+		maybeCartId ??
+		(await client
+			.query<{ payload?: { cart?: { id: string } } }>(CreateCart)
+			.then((data) => data.payload?.cart?.id));
+
+	if (!cartId) throw new Error("Missing cart id");
+
+	const cart = await client
+		.query<{ cart?: ShopifyCart }>(GetCart, { id: decodeURIComponent(cartId) })
+		.then((data) => data.cart ?? null);
+
+	if (responseHeaders) {
+		setCartCookie(responseHeaders, cartId);
+	}
+
+	return cart;
+}
+
+export async function createCart(): Promise<string | null> {
+	const client = getShopifyClient();
+	const data = await client.query<{ payload?: { cart?: { id: string } } }>(CreateCart);
+	return data?.payload?.cart?.id ?? null;
+}

package/src/loaders/shop.ts

@@ -0,0 +1,35 @@
+import { getShopifyClient } from "../client";
+import { GetShopInfo } from "../utils/storefront/queries";
+import type { Metafield } from "../utils/types";
+
+export interface Shop {
+	name: string;
+	description?: string;
+	privacyPolicy?: { title: string; body: string };
+	refundPolicy?: { title: string; body: string };
+	shippingPolicy?: { title: string; body: string };
+	subscriptionPolicy?: { title: string; body: string };
+	termsOfService?: { title: string; body: string };
+	metafields?: Array<{
+		description?: string | null;
+		key: string;
+		namespace: string;
+		type: string;
+		value: string;
+		reference?: { image?: { url: string } } | null;
+		references?: { edges: Array<{ node: { image?: { url: string } } }> } | null;
+	} | null>;
+}
+
+export interface Props {
+	metafields?: Metafield[];
+}
+
+export default async function shopLoader(props?: Props): Promise<Shop> {
+	const client = getShopifyClient();
+	const metafields = props?.metafields || [];
+
+	const data = await client.query<{ shop: Shop }>(GetShopInfo, { identifiers: metafields });
+
+	return data.shop;
+}

package/src/loaders/user.ts

@@ -0,0 +1,39 @@
+import { getShopifyClient } from "../client";
+import { FetchCustomerInfo } from "../utils/storefront/queries";
+import { getUserCookie } from "../utils/user";
+
+export interface ShopifyUser {
+	"@id": string;
+	email: string;
+	givenName: string;
+	familyName: string;
+}
+
+export default async function userLoader(requestHeaders: Headers): Promise<ShopifyUser | null> {
+	const client = getShopifyClient();
+	const customerAccessToken = getUserCookie(requestHeaders);
+
+	if (!customerAccessToken) return null;
+
+	try {
+		const data = await client.query<{
+			customer?: {
+				id: string;
+				email?: string | null;
+				firstName?: string | null;
+				lastName?: string | null;
+			};
+		}>(FetchCustomerInfo, { customerAccessToken });
+
+		if (!data.customer) return null;
+
+		return {
+			"@id": data.customer.id,
+			email: data.customer.email ?? "",
+			givenName: data.customer.firstName ?? "",
+			familyName: data.customer.lastName ?? "",
+		};
+	} catch {
+		return null;
+	}
+}

package/src/mod.ts

@@ -0,0 +1,67 @@
+/**
+ * Shopify app module — standard autoconfig contract.
+ *
+ * Exports `configure` following the AppModContract pattern.
+ * The framework's `autoconfigApps()` calls these generically.
+ *
+ * @example
+ * ```ts
+ * import * as shopifyApp from "@decocms/apps/shopify/mod";
+ *
+ * const app = await shopifyApp.configure(blocks["deco-shopify"], resolveSecret);
+ * if (app) {
+ *   // app.manifest, app.state are available
+ * }
+ * ```
+ */
+
+import type { AppDefinition, ResolveSecretFn } from "@decocms/apps-commerce/app-types";
+import { configureShopify, type ShopifyConfig } from "./client";
+import manifest from "./manifest.gen";
+
+// -------------------------------------------------------------------------
+// State
+// -------------------------------------------------------------------------
+
+export interface ShopifyState {
+	config: ShopifyConfig;
+}
+
+// -------------------------------------------------------------------------
+// Configure
+// -------------------------------------------------------------------------
+
+/**
+ * Configure the Shopify app from CMS block data.
+ * Returns an AppDefinition or null if required fields are missing.
+ */
+export async function configure(
+	block: Record<string, unknown>,
+	resolveSecret: ResolveSecretFn,
+): Promise<AppDefinition<ShopifyState> | null> {
+	if (!block?.storeName) return null;
+
+	const storefrontAccessToken =
+		(await resolveSecret(block.storefrontAccessToken, "SHOPIFY_STOREFRONT_TOKEN")) ??
+		(typeof block.storefrontAccessToken === "string" ? block.storefrontAccessToken : null);
+
+	if (!storefrontAccessToken) return null;
+
+	const config: ShopifyConfig = {
+		storeName: block.storeName as string,
+		storefrontAccessToken,
+		publicUrl: block.publicUrl as string | undefined,
+	};
+
+	// Bridge: maintain global singleton for backward compat
+	configureShopify(config);
+
+	return {
+		name: "shopify",
+		manifest,
+		state: { config },
+	};
+}
+
+/** Placeholder preview for CMS editor — evolves when admin supports it. */
+export const preview = undefined;

package/src/registry.ts

@@ -0,0 +1,9 @@
+import type { AppRegistryEntry } from "@decocms/apps-commerce/registry";
+
+export const SHOPIFY_REGISTRY_ENTRY: AppRegistryEntry = {
+	blockKey: "deco-shopify",
+	module: () => import("./mod"),
+	displayName: "Shopify",
+	category: "commerce",
+	description: "Shopify Storefront API commerce integration",
+};

package/src/utils/__tests__/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/utils/__tests__/instrumentedFetch.test.ts

@@ -0,0 +1,84 @@
+/**
+ * Smoke tests for the pre-wired Shopify fetch factory. Same wiring
+ * assertions as `vtex/utils/__tests__/instrumentedFetch.test.ts`.
+ */
+
+import { configureMeter, type MeterAdapter } from "@decocms/blocks/sdk/observability";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { createShopifyFetch } from "../instrumentedFetch";
+
+type Labels = Record<string, string | number | boolean>;
+
+function captureHistogram(): {
+	calls: { name: string; value: number; attrs: Labels }[];
+	meter: MeterAdapter;
+} {
+	const calls: { name: string; value: number; attrs: Labels }[] = [];
+	const meter: MeterAdapter = {
+		counterInc: vi.fn(),
+		gaugeSet: vi.fn(),
+		histogramRecord: (name, value, attrs) => {
+			calls.push({ name, value, attrs: attrs ?? {} });
+		},
+	};
+	return { calls, meter };
+}
+
+describe("createShopifyFetch", () => {
+	afterEach(() => {
+		vi.restoreAllMocks();
+		configureMeter({
+			counterInc: () => {},
+			gaugeSet: () => {},
+			histogramRecord: () => {},
+		});
+	});
+
+	it("emits http.client.request.duration with provider=shopify on success", async () => {
+		const { calls, meter } = captureHistogram();
+		configureMeter(meter);
+
+		const baseFetch = vi.fn(async () => new Response("{}", { status: 200 }));
+		const fetchFn = createShopifyFetch({ baseFetch: baseFetch as typeof fetch });
+
+		await fetchFn("https://store.myshopify.com/api/2025-04/graphql.json", { method: "POST" });
+
+		expect(calls).toHaveLength(1);
+		expect(calls[0].name).toBe("http.client.request.duration");
+		expect(calls[0].attrs).toMatchObject({
+			provider: "shopify",
+			operation: "storefront.graphql",
+			status_class: "2xx",
+		});
+	});
+
+	it("honors init.operation (used by the GraphQL client to stamp <OperationName>)", async () => {
+		const { calls, meter } = captureHistogram();
+		configureMeter(meter);
+
+		const baseFetch = vi.fn(async () => new Response("{}", { status: 200 }));
+		const fetchFn = createShopifyFetch({ baseFetch: baseFetch as typeof fetch });
+
+		await fetchFn("https://store.myshopify.com/api/2025-04/graphql.json", {
+			method: "POST",
+			operation: "ProductBySlug",
+		});
+
+		expect(calls[0].attrs.operation).toBe("ProductBySlug");
+	});
+
+	it("skips histogram emission when disableHistogram is true", async () => {
+		const { calls, meter } = captureHistogram();
+		configureMeter(meter);
+
+		const baseFetch = vi.fn(async () => new Response("{}", { status: 200 }));
+		const fetchFn = createShopifyFetch({
+			baseFetch: baseFetch as typeof fetch,
+			disableHistogram: true,
+		});
+
+		await fetchFn("https://store.myshopify.com/api/2025-04/graphql.json", { method: "POST" });
+
+		expect(calls).toHaveLength(0);
+	});
+});

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

@@ -0,0 +1,56 @@
+import { describe, expect, it } from "vitest";
+import { shopifyOperationRouter } from "../operationRouter";
+
+describe("shopifyOperationRouter", () => {
+	const store = "https://acme.myshopify.com";
+
+	it("recognizes the storefront GraphQL endpoint", () => {
+		expect(shopifyOperationRouter(`${store}/api/2025-04/graphql.json`, "POST")).toBe(
+			"storefront.graphql",
+		);
+	});
+
+	it("recognizes the admin GraphQL endpoint", () => {
+		expect(shopifyOperationRouter(`${store}/admin/api/2025-04/graphql.json`, "POST")).toBe(
+			"admin.graphql",
+		);
+	});
+
+	it("maps admin REST product / order / customer / inventory endpoints", () => {
+		expect(shopifyOperationRouter(`${store}/admin/api/2025-04/products.json`, "GET")).toBe(
+			"admin.products",
+		);
+		expect(shopifyOperationRouter(`${store}/admin/api/2025-04/orders/123.json`, "GET")).toBe(
+			"admin.orders",
+		);
+		expect(shopifyOperationRouter(`${store}/admin/api/2025-04/customers.json`, "GET")).toBe(
+			"admin.customers",
+		);
+		expect(shopifyOperationRouter(`${store}/admin/api/2025-04/inventory_levels.json`, "GET")).toBe(
+			"admin.inventory",
+		);
+	});
+
+	it("maps storefront checkout + cart endpoints", () => {
+		expect(shopifyOperationRouter(`${store}/api/2025-04/checkouts/abc.json`, "POST")).toBe(
+			"storefront.checkout",
+		);
+		expect(shopifyOperationRouter(`${store}/cart.js`, "GET")).toBe("storefront.cart");
+		expect(shopifyOperationRouter(`${store}/cart/add.js`, "POST")).toBe("storefront.cart");
+	});
+
+	it("returns undefined for unrecognized paths", () => {
+		expect(shopifyOperationRouter(`${store}/random/path`, "GET")).toBeUndefined();
+	});
+
+	it("does not throw on unparseable URLs", () => {
+		expect(shopifyOperationRouter("not-a-url", "GET")).toBeUndefined();
+		expect(shopifyOperationRouter("/api/2025-04/graphql.json", "POST")).toBe("storefront.graphql");
+	});
+
+	it("is case-insensitive on method (no behavioral impact today; future-proofing)", () => {
+		expect(shopifyOperationRouter(`${store}/api/2025-04/graphql.json`, "post")).toBe(
+			"storefront.graphql",
+		);
+	});
+});