@drawbridge/drawbridge-utils 0.0.176 → 0.0.177

package/dist/storefront-C8FKOGeD.d.cts

@@ -0,0 +1,659 @@
+import { request } from './http.cjs';
+import { SHOPIFY_STOREFRONT_API_VERSION } from './shopify/constants.cjs';
+
+const SORT_KEY_MAP = {
+	bestSelling : 'BEST_SELLING',
+	createdAt : 'CREATED_AT',
+	id : 'ID',
+	price : 'PRICE',
+	productType : 'PRODUCT_TYPE',
+	title : 'TITLE',
+	updatedAt : 'UPDATED_AT',
+	vendor : 'VENDOR'
+};
+
+const resolveProductSort = ( sort ) => {
+
+	const entry = sort && Object.entries( sort )[ 0 ];
+
+	if( ! entry ) return null;
+
+	const [ field, direction ] = entry;
+	const sortKey = SORT_KEY_MAP[ field ];
+
+	if( ! sortKey ) return null;
+
+	return {
+		sortKey,
+		reverse : Number( direction ) < 0
+	};
+
+};
+
+const storefrontUrl = ( domain ) =>
+	`https://${ domain }/api/${ SHOPIFY_STOREFRONT_API_VERSION }/graphql.json`;
+
+const storefrontFetch = async ({ fetcher, domain, storefrontAccessToken, query, variables }) => {
+
+	return request({
+		method : 'POST',
+		url : storefrontUrl( domain ),
+		headers : {
+			'X-Shopify-Storefront-Access-Token' : storefrontAccessToken
+		},
+		body : {
+			query,
+			...( variables && { variables } )
+		}
+	});
+
+};
+
+// Shop's primary country, memoized per domain. Needed as buyer context for the
+// out-of-stock probe below: cart warnings only surface when the cart carries a
+// buyer country.
+const shopCountryCache = {};
+
+const getShopCountry = async ({ domain, fetcher, storefrontAccessToken }) => {
+
+	if( shopCountryCache[ domain ] ) return shopCountryCache[ domain ];
+
+	const { data } = await storefrontFetch({
+		fetcher,
+		domain,
+		storefrontAccessToken,
+		query : `{
+			shop {
+				paymentSettings {
+					countryCode
+				}
+			}
+		}`
+	});
+
+	const countryCode = data?.shop?.paymentSettings?.countryCode || null;
+
+	if( countryCode ) shopCountryCache[ domain ] = countryCode;
+
+	return countryCode;
+
+};
+
+// Cart warning codes that mean a line is not actually purchasable, even when
+// merchandise.availableForSale / quantityAvailable report it as available (e.g.
+// stock at a fulfillment-service location that cannot fulfill the online order).
+const OUT_OF_STOCK_WARNING_CODES = [
+	'MERCHANDISE_OUT_OF_STOCK',
+	'MERCHANDISE_NOT_ENOUGH_STOCK'
+];
+
+// Probe real purchasability for a set of variants by creating a throwaway cart
+// (with the shop's country as buyer context) and reading the out-of-stock
+// warnings the availability fields miss. Returns the variant ids Shopify reports
+// as out of stock. One cart call covers all variants.
+const probeVariantsOutOfStock = async ({ fetcher, domain, storefrontAccessToken, variantIds, countryCode }) => {
+
+	if( ! variantIds?.length ) return [];
+
+	const resolvedCountry = countryCode || await getShopCountry({ domain, fetcher, storefrontAccessToken });
+
+	const { data, errors } = await storefrontFetch({
+		fetcher,
+		domain,
+		storefrontAccessToken,
+		query : `
+			mutation probe( $input : CartInput! ){
+				cartCreate( input : $input ){
+					cart {
+						lines( first : 250 ){
+							edges {
+								node {
+									id
+									merchandise {
+										... on ProductVariant {
+											id
+										}
+									}
+								}
+							}
+						}
+					}
+					warnings {
+						code
+						message
+						target
+					}
+				}
+			}
+		`,
+		variables : {
+			input : {
+				lines : variantIds.map( ( merchandiseId ) => ({
+					merchandiseId,
+					quantity : 1
+				}) ),
+				...( resolvedCountry && {
+					buyerIdentity : {
+						countryCode : resolvedCountry
+					}
+				})
+			}
+		}
+	});
+
+	if( errors ) return [];
+
+	const payload = data?.cartCreate;
+
+	const soldOut = new Set(
+		( payload?.warnings || [] )
+			.filter( ( warning ) => OUT_OF_STOCK_WARNING_CODES.includes( warning?.code ) && warning?.target )
+			.map( ( warning ) => warning.target )
+	);
+
+	return ( payload?.cart?.lines?.edges || [] )
+		.filter( ( { node } ) => soldOut.has( node.id ) )
+		.map( ( { node } ) => node?.merchandise?.id )
+		.filter( Boolean );
+
+};
+
+const productsQuery = ( search, cursor, limit, sort ) => {
+
+	const resolved = resolveProductSort( sort );
+	const sortArgs = resolved ? `, sortKey: ${ resolved.sortKey }, reverse: ${ resolved.reverse }` : '';
+
+	return `{
+	products(first: ${ limit }${ search ? `, query: "title:*${ search }*"` : '' }${ cursor ? `, after: "${ cursor }"` : '' }${ sortArgs }) {
+		edges {
+			node {
+				id
+				title
+				description
+				handle
+				productType
+				featuredImage {
+					url
+				}
+				variants(first: 10) {
+					edges {
+						node {
+							id
+							title
+							image {
+								url
+							}
+							price {
+								amount
+								currencyCode
+							}
+							compareAtPrice {
+								amount
+								currencyCode
+							}
+							availableForSale
+							requiresShipping
+						}
+					}
+				}
+			}
+		}
+		pageInfo {
+			endCursor
+			hasNextPage
+			hasPreviousPage
+			startCursor
+		}
+	}
+}`;
+
+};
+
+const productQuery = ( productId ) => `{
+	product(id: "${ productId }") {
+		id
+		title
+		description
+		handle
+		productType
+		featuredImage {
+			url
+		}
+		variants(first: 10) {
+			edges {
+				node {
+					id
+					title
+					image {
+						url
+					}
+					price {
+						amount
+						currencyCode
+					}
+					compareAtPrice {
+						amount
+						currencyCode
+					}
+					availableForSale
+					requiresShipping
+				}
+			}
+		}
+	}
+}`;
+
+// Storefront API caps variants per page at 250. Products with more than
+// that need cursor-based pagination — variants past `first:` are silently
+// dropped without a `pageInfo` hint, so we always request it and loop
+// until `hasNextPage` is false. Returns the flat list of edges from every
+// page concatenated.
+const variantsQuery = ( productId, cursor ) => `{
+	product(id: "${ productId }") {
+		variants(first: 250${ cursor ? `, after: "${ cursor }"` : '' }) {
+			edges {
+				node {
+					id
+					title
+					image {
+						url
+					}
+					price {
+						amount
+						currencyCode
+					}
+					compareAtPrice {
+						amount
+						currencyCode
+					}
+					availableForSale
+					requiresShipping
+				}
+			}
+			pageInfo {
+				hasNextPage
+				endCursor
+			}
+		}
+	}
+}`;
+
+const getProducts = async ({ fetcher, domain, storefrontAccessToken, search, cursor, limit, sort }) => {
+
+	const { data, errors } = await storefrontFetch({
+		fetcher,
+		domain,
+		storefrontAccessToken,
+		query : productsQuery( search, cursor, limit, sort )
+	});
+
+	if( errors ){
+
+		throw new Error( 'Failed to fetch Shopify products' );
+
+	}
+	return data?.products;
+
+};
+
+const getProduct = async ({ fetcher, domain, storefrontAccessToken, productId }) => {
+
+	const { data, errors } = await storefrontFetch({
+		fetcher,
+		domain,
+		storefrontAccessToken,
+		query : productQuery( productId )
+	});
+
+	if( errors ){
+
+		throw new Error( 'Shopify storefront error: ' + errors[ 0 ]?.message );
+
+	}
+	// The exact 'Shopify product not found' message is a contract: it's how a
+	// null product (not published to this channel, or deleted) stays
+	// distinguishable from transport/GraphQL failures. drawbridge-sync's
+	// product worker matches on it to send publish-this-product feedback
+	// instead of retrying the job.
+	if( ! data?.product ){
+
+		throw new Error( 'Shopify product not found' );
+
+	}
+	return data.product;
+
+};
+
+// Returns ONE page of variants — `{ edges, pageInfo }`. Callers drive the
+// cursor loop themselves. This shape exists (instead of a built-in loop)
+// so a BullMQ worker can persist each page and self-enqueue the next,
+// keeping per-job wall-clock under the worker's lock duration regardless
+// of how many variants the product has.
+const getProductVariantsPage = async ({ fetcher, domain, storefrontAccessToken, productId, cursor }) => {
+
+	const { data, errors } = await storefrontFetch({
+		fetcher,
+		domain,
+		storefrontAccessToken,
+		query : variantsQuery( productId, cursor )
+	});
+
+	if( errors ){
+
+		throw new Error( 'Shopify storefront error: ' + errors[ 0 ]?.message );
+
+	}
+	// Same not-found contract as getProduct above.
+	if( ! data?.product ){
+
+		throw new Error( 'Shopify product not found' );
+
+	}
+	return data.product.variants;
+
+};
+
+const CART_FIELDS = `
+	id
+	checkoutUrl
+	lines(first: 100) {
+		edges {
+			node {
+				id
+				quantity
+				merchandise {
+					... on ProductVariant {
+						id
+						title
+						availableForSale
+						image {
+							url
+						}
+						price {
+							amount
+							currencyCode
+						}
+						product {
+							title
+						}
+					}
+				}
+			}
+		}
+	}
+`;
+
+const mapCart = ( cart ) => {
+
+	if( ! cart ) return null;
+
+	return {
+		checkoutUrl : cart.checkoutUrl,
+		id : cart.id,
+		lines : ( cart.lines?.edges || [] ).map( ( { node } ) => ({
+			availableForSale : node?.merchandise?.availableForSale ?? true,
+			currency : node?.merchandise?.price?.currencyCode || null,
+			id : node.id,
+			image : node?.merchandise?.image?.url || null,
+			price : node?.merchandise?.price?.amount || null,
+			productTitle : node?.merchandise?.product?.title || null,
+			quantity : node.quantity,
+			variantId : node?.merchandise?.id,
+			variantTitle : node?.merchandise?.title || null
+		}))
+	};
+
+};
+
+const firstUserError = ( userErrors ) => {
+
+	const error = userErrors?.[ 0 ];
+
+	if( ! error ) return null;
+
+	const message = new Error( error.message || 'Shopify cart error' );
+
+	message.userError = true;
+
+	return message;
+
+};
+
+// Mints the JWT required by Checkout Kit's inline (embedded) checkout — passed
+// as the `auth` attribute on <shopify-checkout target="inline">. This is a
+// client-credentials grant against Shopify's auth service, NOT a Storefront/
+// Admin GraphQL call, so it takes app credentials rather than the per-shop
+// storefront token.
+//
+// NOTE: Shopify's docs are thin here — they say the client_id/client_secret are
+// "provided by Shopify" for authenticated checkouts. Callers pass the app's own
+// credentials; verify against a real store before this ships and swap to
+// dedicated checkout credentials if Shopify requires them.
+const createCheckoutToken = async ({ fetcher, clientId, clientSecret } = {}) => {
+
+	// Throw rather than grant with a missing half: Shopify answers a bad
+	// client_credentials pair with a generic rejection, so the resulting
+	// 'Failed to create Shopify checkout token' would say nothing about the
+	// credential actually being absent.
+	if( ! clientId || ! clientSecret ){
+
+		throw new Error( 'createCheckoutToken requires clientId and clientSecret' );
+
+	}
+	const response = await request({
+		fetcher,
+		method : 'POST',
+		url : 'https://api.shopify.com/auth/access_token',
+		body : {
+			client_id : clientId,
+			client_secret : clientSecret,
+			grant_type : 'client_credentials'
+		}
+	});
+
+	const token = response?.access_token;
+
+	if( ! token ){
+
+		throw new Error( 'Failed to create Shopify checkout token' );
+
+	}
+	return token;
+
+};
+
+const cartCreate = async ({ fetcher, domain, storefrontAccessToken, lines }) => {
+
+	const { data, errors } = await storefrontFetch({
+		fetcher,
+		domain,
+		storefrontAccessToken,
+		query : `
+			mutation cartCreate($input: CartInput!) {
+				cartCreate(input: $input) {
+					cart {
+						${ CART_FIELDS }
+					}
+					userErrors {
+						field
+						message
+					}
+				}
+			}
+		`,
+		variables : {
+			input : {
+				lines
+			}
+		}
+	});
+
+	if( errors ){
+
+		throw new Error( 'Failed to create Shopify cart' );
+
+	}
+	const userError = firstUserError( data?.cartCreate?.userErrors );
+
+	if( userError ) throw userError;
+
+	return mapCart( data?.cartCreate?.cart );
+
+};
+
+const cartGet = async ({ fetcher, domain, storefrontAccessToken, cartId }) => {
+
+	const { data, errors } = await storefrontFetch({
+		fetcher,
+		domain,
+		storefrontAccessToken,
+		query : `
+			query cart($id: ID!) {
+				cart(id: $id) {
+					${ CART_FIELDS }
+				}
+			}
+		`,
+		variables : {
+			id : cartId
+		}
+	});
+
+	if( errors ){
+
+		throw new Error( 'Failed to fetch Shopify cart' );
+
+	}
+	return mapCart( data?.cart );
+
+};
+
+const cartLinesAdd = async ({ fetcher, domain, storefrontAccessToken, cartId, lines }) => {
+
+	const { data, errors } = await storefrontFetch({
+		fetcher,
+		domain,
+		storefrontAccessToken,
+		query : `
+			mutation cartLinesAdd($cartId: ID!, $lines: [CartLineInput!]!) {
+				cartLinesAdd(cartId: $cartId, lines: $lines) {
+					cart {
+						${ CART_FIELDS }
+					}
+					userErrors {
+						field
+						message
+					}
+				}
+			}
+		`,
+		variables : {
+			cartId,
+			lines
+		}
+	});
+
+	if( errors ){
+
+		throw new Error( 'Failed to add Shopify cart lines' );
+
+	}
+	const userError = firstUserError( data?.cartLinesAdd?.userErrors );
+
+	if( userError ) throw userError;
+
+	return mapCart( data?.cartLinesAdd?.cart );
+
+};
+
+const cartLinesRemove = async ({ fetcher, domain, storefrontAccessToken, cartId, lineIds }) => {
+
+	const { data, errors } = await storefrontFetch({
+		fetcher,
+		domain,
+		storefrontAccessToken,
+		query : `
+			mutation cartLinesRemove($cartId: ID!, $lineIds: [ID!]!) {
+				cartLinesRemove(cartId: $cartId, lineIds: $lineIds) {
+					cart {
+						${ CART_FIELDS }
+					}
+					userErrors {
+						field
+						message
+					}
+				}
+			}
+		`,
+		variables : {
+			cartId,
+			lineIds
+		}
+	});
+
+	if( errors ){
+
+		throw new Error( 'Failed to remove Shopify cart lines' );
+
+	}
+	const userError = firstUserError( data?.cartLinesRemove?.userErrors );
+
+	if( userError ) throw userError;
+
+	return mapCart( data?.cartLinesRemove?.cart );
+
+};
+
+const cartLinesUpdate = async ({ fetcher, domain, storefrontAccessToken, cartId, lines }) => {
+
+	const { data, errors } = await storefrontFetch({
+		fetcher,
+		domain,
+		storefrontAccessToken,
+		query : `
+			mutation cartLinesUpdate($cartId: ID!, $lines: [CartLineUpdateInput!]!) {
+				cartLinesUpdate(cartId: $cartId, lines: $lines) {
+					cart {
+						${ CART_FIELDS }
+					}
+					userErrors {
+						field
+						message
+					}
+				}
+			}
+		`,
+		variables : {
+			cartId,
+			lines
+		}
+	});
+
+	if( errors ){
+
+		throw new Error( 'Failed to update Shopify cart lines' );
+
+	}
+	const userError = firstUserError( data?.cartLinesUpdate?.userErrors );
+
+	if( userError ) throw userError;
+
+	return mapCart( data?.cartLinesUpdate?.cart );
+
+};
+
+declare const shopifyStorefront_cartCreate: typeof cartCreate;
+declare const shopifyStorefront_cartGet: typeof cartGet;
+declare const shopifyStorefront_cartLinesAdd: typeof cartLinesAdd;
+declare const shopifyStorefront_cartLinesRemove: typeof cartLinesRemove;
+declare const shopifyStorefront_cartLinesUpdate: typeof cartLinesUpdate;
+declare const shopifyStorefront_createCheckoutToken: typeof createCheckoutToken;
+declare const shopifyStorefront_getProduct: typeof getProduct;
+declare const shopifyStorefront_getProductVariantsPage: typeof getProductVariantsPage;
+declare const shopifyStorefront_getProducts: typeof getProducts;
+declare const shopifyStorefront_probeVariantsOutOfStock: typeof probeVariantsOutOfStock;
+declare namespace shopifyStorefront {
+  export { shopifyStorefront_cartCreate as cartCreate, shopifyStorefront_cartGet as cartGet, shopifyStorefront_cartLinesAdd as cartLinesAdd, shopifyStorefront_cartLinesRemove as cartLinesRemove, shopifyStorefront_cartLinesUpdate as cartLinesUpdate, shopifyStorefront_createCheckoutToken as createCheckoutToken, shopifyStorefront_getProduct as getProduct, shopifyStorefront_getProductVariantsPage as getProductVariantsPage, shopifyStorefront_getProducts as getProducts, shopifyStorefront_probeVariantsOutOfStock as probeVariantsOutOfStock };
+}
+
+export { cartGet as a, cartLinesAdd as b, cartCreate as c, cartLinesRemove as d, cartLinesUpdate as e, createCheckoutToken as f, getProduct as g, getProductVariantsPage as h, getProducts as i, probeVariantsOutOfStock as p, shopifyStorefront as s };