@decocms/apps-shopify 7.2.0

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@decocms/apps-shopify",
+  "version": "7.2.0",
+  "type": "module",
+  "description": "Deco commerce app: Shopify integration",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/decocms/blocks.git",
+    "directory": "packages/apps-shopify"
+  },
+  "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"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run --root ../.. packages/apps-shopify/",
+    "typecheck": "tsc --noEmit",
+    "lint:unused": "knip"
+  },
+  "dependencies": {
+    "@decocms/blocks": "7.2.0",
+    "@decocms/apps-commerce": "7.2.0",
+    "@decocms/tanstack": "7.2.0"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "knip": "^5.86.0",
+    "typescript": "^5.9.0"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  }
+}

package/src/actions/cart/addItems.ts

@@ -0,0 +1,36 @@
+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

@@ -0,0 +1,31 @@
+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

@@ -0,0 +1,31 @@
+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

@@ -0,0 +1,40 @@
+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

@@ -0,0 +1,31 @@
+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/client.ts

@@ -0,0 +1,58 @@
+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.
+ *
+ * @example
+ * ```ts
+ * import { createInstrumentedFetch } from "@decocms/blocks/sdk/instrumentedFetch";
+ * import { setShopifyFetch } from "@decocms/apps/shopify";
+ * setShopifyFetch(createInstrumentedFetch("shopify"));
+ * ```
+ */
+export function setShopifyFetch(fetchFn: typeof fetch) {
+	_fetch = fetchFn;
+	if (_config) configureShopify(_config);
+}
+
+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,
+	);
+}
+
+export function getShopifyClient(): GraphQLClient {
+	if (!_client || !_config) {
+		throw new Error(
+			"Shopify not configured. Call configureShopify() first or check deco-shopify.json block.",
+		);
+	}
+	return _client;
+}
+
+export function getShopifyConfig(): ShopifyConfig {
+	if (!_config) {
+		throw new Error("Shopify not configured.");
+	}
+	return _config;
+}
+
+export function getBaseUrl(): string {
+	return _config?.publicUrl || "";
+}

package/src/index.ts

@@ -0,0 +1,43 @@
+// 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";
+export {
+	configureShopify,
+	getBaseUrl,
+	getShopifyClient,
+	getShopifyConfig,
+	setShopifyFetch,
+} 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/init.ts

@@ -0,0 +1,39 @@
+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

@@ -0,0 +1,31 @@
+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);
+}

package/src/loaders/ProductList.ts

@@ -0,0 +1,102 @@
+import type { Product } from "@decocms/apps-commerce/types";
+import { getShopifyClient } from "../client";
+import { ProductsByCollection, SearchProducts } from "../utils/storefront/queries";
+import { type ProductShopify, toProduct } from "../utils/transform";
+import type { Metafield } from "../utils/types";
+import {
+	type CollectionSortKeys,
+	type SearchSortKeys,
+	searchSortShopify,
+	sortShopify,
+} from "../utils/utils";
+
+export interface QueryProps {
+	query: string;
+	count: number;
+	sort?: SearchSortKeys;
+}
+
+export interface CollectionProps {
+	collection: string;
+	count: number;
+	sort?: CollectionSortKeys;
+}
+
+export interface FilterProps {
+	tags?: string[];
+	productTypes?: string[];
+	productVendors?: string[];
+	priceMin?: number;
+	priceMax?: number;
+	variantOptions?: { name: string; value: string }[];
+}
+
+export type Props = {
+	props: QueryProps | CollectionProps;
+	filters?: FilterProps;
+	metafields?: Metafield[];
+};
+
+const isQueryList = (p: QueryProps | CollectionProps): p is QueryProps =>
+	"query" in p && typeof p.query === "string" && typeof p.count === "number";
+
+export default async function productListLoader(
+	expandedProps: Props,
+	url?: URL,
+): Promise<Product[] | null> {
+	const client = getShopifyClient();
+
+	const props = expandedProps.props ?? (expandedProps as unknown as Props["props"]);
+
+	const count = props.count ?? 12;
+	const metafields = expandedProps.metafields || [];
+	const sort = props.sort ?? "";
+
+	const filters: Record<string, unknown>[] = [];
+	for (const tag of expandedProps.filters?.tags ?? []) {
+		filters.push({ tag });
+	}
+	for (const productType of expandedProps.filters?.productTypes ?? []) {
+		filters.push({ productType });
+	}
+	for (const productVendor of expandedProps.filters?.productVendors ?? []) {
+		filters.push({ productVendor });
+	}
+	if (expandedProps.filters?.priceMin != null)
+		filters.push({ price: { min: expandedProps.filters.priceMin } });
+	if (expandedProps.filters?.priceMax != null)
+		filters.push({ price: { max: expandedProps.filters.priceMax } });
+	for (const variantOption of expandedProps.filters?.variantOptions ?? []) {
+		filters.push({ variantOption });
+	}
+
+	let shopifyProducts: { nodes: ProductShopify[] } | undefined;
+
+	if (isQueryList(props)) {
+		const data = await client.query<{ search: { nodes: ProductShopify[] } }>(SearchProducts, {
+			first: count,
+			query: props.query,
+			productFilters: filters,
+			identifiers: metafields,
+			...searchSortShopify[sort],
+		});
+		shopifyProducts = data.search;
+	} else {
+		const data = await client.query<{
+			collection?: { products: { nodes: ProductShopify[] } };
+		}>(ProductsByCollection, {
+			first: count,
+			handle: (props as CollectionProps).collection,
+			filters,
+			identifiers: metafields,
+			...sortShopify[sort],
+		});
+		shopifyProducts = data.collection?.products;
+	}
+
+	const baseUrl = url ?? new URL("https://localhost");
+
+	const products = shopifyProducts?.nodes.map((p) => toProduct(p, p.variants.nodes[0], baseUrl));
+
+	return products ?? [];
+}

package/src/loaders/ProductListingPage.ts

@@ -0,0 +1,172 @@
+import type { ProductListingPage } from "@decocms/apps-commerce/types";
+import { getShopifyClient } from "../client";
+import { ProductsByCollection, SearchProducts } from "../utils/storefront/queries";
+import { type ProductShopify, toFilter, toProduct } from "../utils/transform";
+import type { Metafield } from "../utils/types";
+import {
+	getFiltersByUrl,
+	searchSortOptions,
+	searchSortShopify,
+	sortOptions,
+	sortShopify,
+} from "../utils/utils";
+
+interface PageInfo {
+	hasNextPage: boolean;
+	hasPreviousPage: boolean;
+	endCursor?: string;
+	startCursor?: string;
+}
+
+interface FilterNode {
+	id: string;
+	label: string;
+	type: string;
+	values: Array<{ id: string; label: string; count: number; input: string }>;
+}
+
+interface ProductConnection {
+	nodes: ProductShopify[];
+	pageInfo: PageInfo;
+	filters?: FilterNode[];
+}
+
+export interface Props {
+	query?: string;
+	collectionName?: string;
+	count: number;
+	metafields?: Metafield[];
+	pageOffset?: number;
+	page?: number;
+	startCursor?: string;
+	endCursor?: string;
+	pageHref?: string;
+}
+
+export default async function productListingPageLoader(
+	props: Props,
+	url?: URL,
+): Promise<ProductListingPage | null> {
+	const pageUrl = url ?? new URL(props.pageHref || "https://localhost");
+	const client = getShopifyClient();
+
+	const count = props.count ?? 12;
+	const query = props.query || pageUrl.searchParams.get("q") || "";
+	const currentPageoffset = props.pageOffset ?? 1;
+	const pageParam = pageUrl.searchParams.get("page")
+		? Number(pageUrl.searchParams.get("page")) - currentPageoffset
+		: 0;
+	const page = props.page || pageParam;
+	const endCursor = props.endCursor || pageUrl.searchParams.get("endCursor") || "";
+	const startCursor = props.startCursor || pageUrl.searchParams.get("startCursor") || "";
+	const metafields = props.metafields || [];
+
+	const isSearch = Boolean(query);
+	let hasNextPage = false;
+	let hasPreviousPage = false;
+	let shopifyProducts: ProductConnection | undefined;
+	let shopifyFilters: FilterNode[] | undefined;
+	let records: number | undefined;
+	let collectionTitle: string | undefined;
+	let collectionDescription: string | undefined;
+
+	const sort = pageUrl.searchParams.get("sort") ?? "";
+
+	if (isSearch) {
+		const data = await client.query<{
+			search: ProductConnection & { totalCount?: number; productFilters?: FilterNode[] };
+		}>(SearchProducts, {
+			...(!endCursor && { first: count }),
+			...(endCursor && { last: count }),
+			...(startCursor && { after: startCursor }),
+			...(endCursor && { before: endCursor }),
+			query,
+			productFilters: getFiltersByUrl(pageUrl),
+			identifiers: metafields,
+			...searchSortShopify[sort],
+		});
+
+		shopifyProducts = data.search;
+		shopifyFilters = data.search?.productFilters;
+		records = data.search?.totalCount;
+		hasNextPage = Boolean(data.search?.pageInfo.hasNextPage);
+		hasPreviousPage = Boolean(data.search?.pageInfo.hasPreviousPage);
+	} else {
+		const pathname = props.collectionName || pageUrl.pathname.split("/")[1];
+
+		const data = await client.query<{
+			collection?: {
+				title?: string;
+				description?: string;
+				products: ProductConnection;
+			};
+		}>(ProductsByCollection, {
+			...(!endCursor && { first: count }),
+			...(endCursor && { last: count }),
+			...(startCursor && { after: startCursor }),
+			...(endCursor && { before: endCursor }),
+			identifiers: metafields,
+			handle: pathname,
+			filters: getFiltersByUrl(pageUrl),
+			...sortShopify[sort],
+		});
+
+		shopifyProducts = data.collection?.products;
+		shopifyFilters = data.collection?.products?.filters;
+		hasNextPage = Boolean(data.collection?.products.pageInfo.hasNextPage);
+		hasPreviousPage = Boolean(data.collection?.products.pageInfo.hasPreviousPage);
+		collectionTitle = data.collection?.title;
+		collectionDescription = data.collection?.description;
+	}
+
+	const products = shopifyProducts?.nodes?.map((p) => toProduct(p, p.variants.nodes[0], pageUrl));
+
+	const nextPage = new URLSearchParams(pageUrl.searchParams);
+	const previousPage = new URLSearchParams(pageUrl.searchParams);
+
+	if (hasNextPage) {
+		nextPage.set("page", (page + currentPageoffset + 1).toString());
+		nextPage.set("startCursor", shopifyProducts?.pageInfo.endCursor ?? "");
+		nextPage.delete("endCursor");
+	}
+
+	if (hasPreviousPage) {
+		previousPage.set("page", (page + currentPageoffset - 1).toString());
+		previousPage.set("endCursor", shopifyProducts?.pageInfo.startCursor ?? "");
+		previousPage.delete("startCursor");
+	}
+
+	const filters = shopifyFilters?.map((filter) => toFilter(filter, pageUrl));
+	const currentPage = page + currentPageoffset;
+
+	return {
+		"@type": "ProductListingPage",
+		breadcrumb: {
+			"@type": "BreadcrumbList",
+			itemListElement: [
+				{
+					"@type": "ListItem" as const,
+					name: isSearch ? query : pageUrl.pathname.split("/")[1],
+					item: isSearch ? pageUrl.href : pageUrl.pathname,
+					position: 2,
+				},
+			],
+			numberOfItems: 1,
+		},
+		filters: filters ?? [],
+		products: products ?? [],
+		pageInfo: {
+			nextPage: hasNextPage ? `?${nextPage}` : undefined,
+			previousPage: hasPreviousPage ? `?${previousPage}` : undefined,
+			currentPage,
+			records,
+			recordPerPage: count,
+		},
+		sortOptions: isSearch ? searchSortOptions : sortOptions,
+		seo: {
+			title: collectionTitle || "",
+			description: collectionDescription || "",
+			canonical: `${pageUrl.origin}${pageUrl.pathname}${page >= 1 ? `?page=${page}` : ""}`,
+		},
+	};
+}