@decocms/apps-shopify 7.2.0

package/src/utils/enums.ts

@@ -0,0 +1,438 @@
+export enum CurrencyCode {
+	AED = "AED",
+	AFN = "AFN",
+	ALL = "ALL",
+	AMD = "AMD",
+	ANG = "ANG",
+	AOA = "AOA",
+	ARS = "ARS",
+	AUD = "AUD",
+	AWG = "AWG",
+	AZN = "AZN",
+	BAM = "BAM",
+	BBD = "BBD",
+	BDT = "BDT",
+	BGN = "BGN",
+	BHD = "BHD",
+	BIF = "BIF",
+	BMD = "BMD",
+	BND = "BND",
+	BOB = "BOB",
+	BRL = "BRL",
+	BSD = "BSD",
+	BTN = "BTN",
+	BWP = "BWP",
+	BYN = "BYN",
+	BZD = "BZD",
+	CAD = "CAD",
+	CDF = "CDF",
+	CHF = "CHF",
+	CLP = "CLP",
+	CNY = "CNY",
+	COP = "COP",
+	CRC = "CRC",
+	CVE = "CVE",
+	CZK = "CZK",
+	DJF = "DJF",
+	DKK = "DKK",
+	DOP = "DOP",
+	DZD = "DZD",
+	EGP = "EGP",
+	ERN = "ERN",
+	ETB = "ETB",
+	EUR = "EUR",
+	FJD = "FJD",
+	FKP = "FKP",
+	GBP = "GBP",
+	GEL = "GEL",
+	GHS = "GHS",
+	GIP = "GIP",
+	GMD = "GMD",
+	GNF = "GNF",
+	GTQ = "GTQ",
+	GYD = "GYD",
+	HKD = "HKD",
+	HNL = "HNL",
+	HRK = "HRK",
+	HTG = "HTG",
+	HUF = "HUF",
+	IDR = "IDR",
+	ILS = "ILS",
+	INR = "INR",
+	IQD = "IQD",
+	IRR = "IRR",
+	ISK = "ISK",
+	JEP = "JEP",
+	JMD = "JMD",
+	JOD = "JOD",
+	JPY = "JPY",
+	KES = "KES",
+	KGS = "KGS",
+	KHR = "KHR",
+	KID = "KID",
+	KMF = "KMF",
+	KRW = "KRW",
+	KWD = "KWD",
+	KYD = "KYD",
+	KZT = "KZT",
+	LAK = "LAK",
+	LBP = "LBP",
+	LKR = "LKR",
+	LRD = "LRD",
+	LSL = "LSL",
+	LTL = "LTL",
+	LVL = "LVL",
+	LYD = "LYD",
+	MAD = "MAD",
+	MDL = "MDL",
+	MGA = "MGA",
+	MKD = "MKD",
+	MMK = "MMK",
+	MNT = "MNT",
+	MOP = "MOP",
+	MRU = "MRU",
+	MUR = "MUR",
+	MVR = "MVR",
+	MWK = "MWK",
+	MXN = "MXN",
+	MYR = "MYR",
+	MZN = "MZN",
+	NAD = "NAD",
+	NGN = "NGN",
+	NIO = "NIO",
+	NOK = "NOK",
+	NPR = "NPR",
+	NZD = "NZD",
+	OMR = "OMR",
+	PAB = "PAB",
+	PEN = "PEN",
+	PGK = "PGK",
+	PHP = "PHP",
+	PKR = "PKR",
+	PLN = "PLN",
+	PYG = "PYG",
+	QAR = "QAR",
+	RON = "RON",
+	RSD = "RSD",
+	RUB = "RUB",
+	RWF = "RWF",
+	SAR = "SAR",
+	SBD = "SBD",
+	SCR = "SCR",
+	SDG = "SDG",
+	SEK = "SEK",
+	SGD = "SGD",
+	SHP = "SHP",
+	SLL = "SLL",
+	SOS = "SOS",
+	SRD = "SRD",
+	SSP = "SSP",
+	STN = "STN",
+	SYP = "SYP",
+	SZL = "SZL",
+	THB = "THB",
+	TJS = "TJS",
+	TMT = "TMT",
+	TND = "TND",
+	TOP = "TOP",
+	TRY = "TRY",
+	TTD = "TTD",
+	TWD = "TWD",
+	TZS = "TZS",
+	UAH = "UAH",
+	UGX = "UGX",
+	USD = "USD",
+	UYU = "UYU",
+	UZS = "UZS",
+	VED = "VED",
+	VES = "VES",
+	VND = "VND",
+	VUV = "VUV",
+	WST = "WST",
+	XAF = "XAF",
+	XCD = "XCD",
+	XOF = "XOF",
+	XPF = "XPF",
+	XXX = "XXX",
+	YER = "YER",
+	ZAR = "ZAR",
+	ZMW = "ZMW",
+}
+
+export enum CountryCode {
+	AC = "AC",
+	AD = "AD",
+	AE = "AE",
+	AF = "AF",
+	AG = "AG",
+	AI = "AI",
+	AL = "AL",
+	AM = "AM",
+	AN = "AN",
+	AO = "AO",
+	AR = "AR",
+	AT = "AT",
+	AU = "AU",
+	AW = "AW",
+	AX = "AX",
+	AZ = "AZ",
+	BA = "BA",
+	BB = "BB",
+	BD = "BD",
+	BE = "BE",
+	BF = "BF",
+	BG = "BG",
+	BH = "BH",
+	BI = "BI",
+	BJ = "BJ",
+	BL = "BL",
+	BM = "BM",
+	BN = "BN",
+	BO = "BO",
+	BQ = "BQ",
+	BR = "BR",
+	BS = "BS",
+	BT = "BT",
+	BV = "BV",
+	BW = "BW",
+	BY = "BY",
+	BZ = "BZ",
+	CA = "CA",
+	CC = "CC",
+	CD = "CD",
+	CF = "CF",
+	CG = "CG",
+	CH = "CH",
+	CI = "CI",
+	CK = "CK",
+	CL = "CL",
+	CM = "CM",
+	CN = "CN",
+	CO = "CO",
+	CR = "CR",
+	CU = "CU",
+	CV = "CV",
+	CW = "CW",
+	CX = "CX",
+	CY = "CY",
+	CZ = "CZ",
+	DE = "DE",
+	DJ = "DJ",
+	DK = "DK",
+	DM = "DM",
+	DO = "DO",
+	DZ = "DZ",
+	EC = "EC",
+	EE = "EE",
+	EG = "EG",
+	EH = "EH",
+	ER = "ER",
+	ES = "ES",
+	ET = "ET",
+	FI = "FI",
+	FJ = "FJ",
+	FK = "FK",
+	FO = "FO",
+	FR = "FR",
+	GA = "GA",
+	GB = "GB",
+	GD = "GD",
+	GE = "GE",
+	GF = "GF",
+	GG = "GG",
+	GH = "GH",
+	GI = "GI",
+	GL = "GL",
+	GM = "GM",
+	GN = "GN",
+	GP = "GP",
+	GQ = "GQ",
+	GR = "GR",
+	GS = "GS",
+	GT = "GT",
+	GW = "GW",
+	GY = "GY",
+	HK = "HK",
+	HM = "HM",
+	HN = "HN",
+	HR = "HR",
+	HT = "HT",
+	HU = "HU",
+	ID = "ID",
+	IE = "IE",
+	IL = "IL",
+	IM = "IM",
+	IN = "IN",
+	IO = "IO",
+	IQ = "IQ",
+	IR = "IR",
+	IS = "IS",
+	IT = "IT",
+	JE = "JE",
+	JM = "JM",
+	JO = "JO",
+	JP = "JP",
+	KE = "KE",
+	KG = "KG",
+	KH = "KH",
+	KI = "KI",
+	KM = "KM",
+	KN = "KN",
+	KP = "KP",
+	KR = "KR",
+	KW = "KW",
+	KY = "KY",
+	KZ = "KZ",
+	LA = "LA",
+	LB = "LB",
+	LC = "LC",
+	LI = "LI",
+	LK = "LK",
+	LR = "LR",
+	LS = "LS",
+	LT = "LT",
+	LU = "LU",
+	LV = "LV",
+	LY = "LY",
+	MA = "MA",
+	MC = "MC",
+	MD = "MD",
+	ME = "ME",
+	MF = "MF",
+	MG = "MG",
+	MK = "MK",
+	ML = "ML",
+	MM = "MM",
+	MN = "MN",
+	MO = "MO",
+	MQ = "MQ",
+	MR = "MR",
+	MS = "MS",
+	MT = "MT",
+	MU = "MU",
+	MV = "MV",
+	MW = "MW",
+	MX = "MX",
+	MY = "MY",
+	MZ = "MZ",
+	NA = "NA",
+	NC = "NC",
+	NE = "NE",
+	NF = "NF",
+	NG = "NG",
+	NI = "NI",
+	NL = "NL",
+	NO = "NO",
+	NP = "NP",
+	NR = "NR",
+	NU = "NU",
+	NZ = "NZ",
+	OM = "OM",
+	PA = "PA",
+	PE = "PE",
+	PF = "PF",
+	PG = "PG",
+	PH = "PH",
+	PK = "PK",
+	PL = "PL",
+	PM = "PM",
+	PN = "PN",
+	PS = "PS",
+	PT = "PT",
+	PY = "PY",
+	QA = "QA",
+	RE = "RE",
+	RO = "RO",
+	RS = "RS",
+	RU = "RU",
+	RW = "RW",
+	SA = "SA",
+	SB = "SB",
+	SC = "SC",
+	SD = "SD",
+	SE = "SE",
+	SG = "SG",
+	SH = "SH",
+	SI = "SI",
+	SJ = "SJ",
+	SK = "SK",
+	SL = "SL",
+	SM = "SM",
+	SN = "SN",
+	SO = "SO",
+	SR = "SR",
+	SS = "SS",
+	ST = "ST",
+	SV = "SV",
+	SX = "SX",
+	SY = "SY",
+	SZ = "SZ",
+	TA = "TA",
+	TC = "TC",
+	TD = "TD",
+	TF = "TF",
+	TG = "TG",
+	TH = "TH",
+	TJ = "TJ",
+	TK = "TK",
+	TL = "TL",
+	TM = "TM",
+	TN = "TN",
+	TO = "TO",
+	TR = "TR",
+	TT = "TT",
+	TV = "TV",
+	TW = "TW",
+	TZ = "TZ",
+	UA = "UA",
+	UG = "UG",
+	UM = "UM",
+	US = "US",
+	UY = "UY",
+	UZ = "UZ",
+	VA = "VA",
+	VC = "VC",
+	VE = "VE",
+	VG = "VG",
+	VN = "VN",
+	VU = "VU",
+	WF = "WF",
+	WS = "WS",
+	XK = "XK",
+	YE = "YE",
+	YT = "YT",
+	ZA = "ZA",
+	ZM = "ZM",
+	ZW = "ZW",
+	ZZ = "ZZ",
+}
+
+export enum OrderCancelReason {
+	CUSTOMER = "CUSTOMER",
+	DECLINED = "DECLINED",
+	FRAUD = "FRAUD",
+	INVENTORY = "INVENTORY",
+	OTHER = "OTHER",
+}
+
+export enum OrderFinancialStatus {
+	AUTHORIZED = "AUTHORIZED",
+	PAID = "PAID",
+	PARTIALLY_PAID = "PARTIALLY_PAID",
+	PARTIALLY_REFUNDED = "PARTIALLY_REFUNDED",
+	PENDING = "PENDING",
+	REFUNDED = "REFUNDED",
+	VOIDED = "VOIDED",
+}
+
+export enum OrderFulfillmentStatus {
+	FULFILLED = "FULFILLED",
+	IN_PROGRESS = "IN_PROGRESS",
+	ON_HOLD = "ON_HOLD",
+	OPEN = "OPEN",
+	PARTIALLY_FULFILLED = "PARTIALLY_FULFILLED",
+	PENDING_FULFILLMENT = "PENDING_FULFILLMENT",
+	RESTOCKED = "RESTOCKED",
+	SCHEDULED = "SCHEDULED",
+	UNFULFILLED = "UNFULFILLED",
+}

package/src/utils/graphql.ts

@@ -0,0 +1,69 @@
+import type { InstrumentedFetchInit } from "@decocms/blocks/sdk/instrumentedFetch";
+import { extractGraphqlOperationName } from "./graphqlOperationName";
+
+export function gql(strings: TemplateStringsArray, ...values: unknown[]): string {
+	return strings.reduce((acc, str, i) => acc + str + (values[i] ?? ""), "");
+}
+
+export interface QueryDefinition {
+	fragments?: string[];
+	query: string;
+}
+
+export function buildQuery(def: QueryDefinition): string {
+	const fragments = def.fragments?.join("\n") ?? "";
+	return fragments ? `${fragments}\n${def.query}` : def.query;
+}
+
+export interface GraphQLClient {
+	query<T>(query: string | QueryDefinition, variables?: Record<string, unknown>): Promise<T>;
+}
+
+export function createGraphqlClient(
+	endpoint: string,
+	headers: Record<string, string>,
+	fetchFn?: typeof fetch,
+): GraphQLClient {
+	const _fetch = fetchFn ?? globalThis.fetch;
+	return {
+		async query<T>(
+			queryOrDef: string | QueryDefinition,
+			variables?: Record<string, unknown>,
+		): Promise<T> {
+			const query = typeof queryOrDef === "string" ? queryOrDef : buildQuery(queryOrDef);
+
+			// Stamp the GraphQL operation as init.operation so the framework's
+			// span name becomes `shopify.<OperationName>` instead of the
+			// generic `shopify.storefront.graphql` from the URL router. The
+			// extra field is silently dropped by plain `fetch` and read by
+			// any `InstrumentedFetch` configured via `setShopifyFetch`.
+			const operation = extractGraphqlOperationName(query);
+			const init: InstrumentedFetchInit = {
+				method: "POST",
+				headers: {
+					"Content-Type": "application/json",
+					...headers,
+				},
+				body: JSON.stringify({ query, variables }),
+				...(operation ? { operation } : {}),
+			};
+			const response = await _fetch(endpoint, init);
+
+			if (!response.ok) {
+				throw new Error(`Shopify GraphQL error: ${response.status} ${response.statusText}`);
+			}
+
+			const json = (await response.json()) as { data?: T; errors?: Array<{ message: string }> };
+
+			if (json.errors?.length) {
+				throw new Error(`Shopify GraphQL errors: ${json.errors.map((e) => e.message).join(", ")}`);
+			}
+
+			if (json.data === undefined) {
+				throw new Error("Shopify GraphQL response missing data");
+			}
+
+			return json.data;
+		},
+	};
+}

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

@@ -0,0 +1,55 @@
+/**
+ * Pre-wired instrumented fetch factory for Shopify.
+ *
+ * Mirrors `vtex/utils/instrumentedFetch.ts`. Bundles:
+ *
+ *   1. `createInstrumentedFetch` from `@decocms/start` (spans,
+ *      traceparent, URL redaction).
+ *   2. `shopifyOperationRouter` as the URL fallback for non-GraphQL
+ *      and unnamed-GraphQL calls.
+ *   3. An `onComplete` that records the canonical
+ *      `http.client.request.duration` histogram (via the framework's
+ *      `recordCommerceMetric(...)` helper) with `provider: "shopify"`.
+ *
+ * Sites do:
+ *
+ *   ```ts
+ *   import { setShopifyFetch, createShopifyFetch } from "@decocms/apps/shopify";
+ *   setShopifyFetch(createShopifyFetch());
+ *   ```
+ *
+ * Per-call operation names come from `extractGraphqlOperationName`
+ * (wired in `./graphql.ts`); the URL router fires only when the
+ * extractor returns `undefined`.
+ */
+
+import {
+	createInstrumentedFetch,
+	type InstrumentedFetch,
+} from "@decocms/blocks/sdk/instrumentedFetch";
+import { recordCommerceMetric } from "@decocms/blocks/sdk/observability";
+import { shopifyOperationRouter } from "./operationRouter";
+
+export interface CreateShopifyFetchOptions {
+	baseFetch?: typeof fetch;
+	disableHistogram?: boolean;
+}
+
+export function createShopifyFetch(options: CreateShopifyFetchOptions = {}): InstrumentedFetch {
+	const { baseFetch, disableHistogram = false } = options;
+	return createInstrumentedFetch({
+		name: "shopify",
+		baseFetch,
+		resolveOperation: shopifyOperationRouter,
+		onComplete: disableHistogram
+			? undefined
+			: ({ operation, status, durationMs, cached }) => {
+					recordCommerceMetric(durationMs, {
+						provider: "shopify",
+						operation,
+						status_class: `${Math.floor(status / 100)}xx`,
+						cached,
+					});
+				},
+	});
+}

package/src/utils/operationRouter.ts

@@ -0,0 +1,70 @@
+/**
+ * URL-derived operation name router for Shopify API calls.
+ *
+ * Plugged into `@decocms/start`'s `createInstrumentedFetch` via the
+ * `resolveOperation(url, method)` option. Mirrors the shape of the
+ * VTEX router in `../../vtex/utils/operationRouter.ts`.
+ *
+ * Shopify's API surface from this repo is overwhelmingly GraphQL —
+ * a single endpoint per environment (storefront vs admin). That means
+ * the URL alone can only tell us *which GraphQL surface* a call is
+ * 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
+ * `init.operation`, which always wins over this router.
+ *
+ * So this router exists for:
+ *
+ *   - non-GraphQL Shopify REST endpoints we may add later
+ *     (cart API, customer accounts, billing, etc.);
+ *   - giving the GraphQL endpoints a *fallback* operation when the
+ *     extractor can't parse a name (anonymous queries, missing body).
+ */
+
+type OperationResolver = string | ((match: RegExpMatchArray, method: string) => string);
+
+interface Matcher {
+	pattern: RegExp;
+	operation: OperationResolver;
+}
+
+const m = (pattern: RegExp, operation: OperationResolver): Matcher => ({ pattern, operation });
+
+const MATCHERS: ReadonlyArray<Matcher> = [
+	m(/^\/admin\/api\/[0-9]{4}-[0-9]{2}\/graphql\.json/, "admin.graphql"),
+	m(/^\/api\/[0-9]{4}-[0-9]{2}\/graphql\.json/, "storefront.graphql"),
+
+	m(/^\/admin\/api\/[0-9]{4}-[0-9]{2}\/products/, "admin.products"),
+	m(/^\/admin\/api\/[0-9]{4}-[0-9]{2}\/orders/, "admin.orders"),
+	m(/^\/admin\/api\/[0-9]{4}-[0-9]{2}\/customers/, "admin.customers"),
+	m(/^\/admin\/api\/[0-9]{4}-[0-9]{2}\/inventory/, "admin.inventory"),
+
+	m(/^\/api\/[0-9]{4}-[0-9]{2}\/checkouts/, "storefront.checkout"),
+	m(/^\/cart(?:\/|\.js|$)/, "storefront.cart"),
+];
+
+/**
+ * Resolve an operation name for a Shopify URL. Returns `undefined`
+ * if no matcher fires, which causes the framework to fall back to
+ * `shopify.fetch`.
+ */
+export function shopifyOperationRouter(url: string, method: string): string | undefined {
+	let pathname: string;
+	try {
+		pathname = new URL(url).pathname;
+	} catch {
+		const qs = url.indexOf("?");
+		const hash = url.indexOf("#");
+		const end = [qs, hash].filter((i) => i >= 0).sort((a, b) => a - b)[0];
+		pathname = end === undefined ? url : url.slice(0, end);
+	}
+
+	const upperMethod = method.toUpperCase();
+	for (const { pattern, operation } of MATCHERS) {
+		const match = pathname.match(pattern);
+		if (!match) continue;
+		return typeof operation === "function" ? operation(match, upperMethod) : operation;
+	}
+	return undefined;
+}