@porulle/adapter-shopify 0.65.0 → 0.66.0

package/dist/catalog.d.ts

@@ -0,0 +1,198 @@
+import type { ChannelCatalogItem, ChannelConnectorError, Result } from "@porulle/core";
+import { z } from "zod";
+import type { ShopifyGraphqlTarget } from "./graphql.js";
+/**
+ * Products per catalogue page. Measured against Shopify's own demo store through its public GraphQL
+ * proxy on 2026-10-03: 25 products with 25 variants and 10 media each requested 320 cost points
+ * against a 2,000-point bucket restoring 100/s. 50 keeps a page well under the 1,000-point
+ * single-query ceiling while halving the number of calls a large catalogue takes.
+ */
+export declare const CATALOG_PAGE_PRODUCTS = 50;
+export declare const CATALOG_PAGE_QUERY = "query PorulleCatalogPage($first: Int!, $after: String) {\n  shop { currencyCode }\n  products(first: $first, after: $after, sortKey: ID) { pageInfo { hasNextPage endCursor } nodes { \n  legacyResourceId title handle status descriptionHtml vendor productType tags onlineStoreUrl\n  category { name }\n  options { name position optionValues { name } }\n  media(first: 20) { nodes { id alt mediaContentType ... on MediaImage { image { url } } } }\n  variants(first: 25) { pageInfo { hasNextPage endCursor } nodes { \n  legacyResourceId sku price compareAtPrice inventoryQuantity\n  barcodes(first: 1) { nodes { value } }\n  selectedOptions { name value }\n  media(first: 1) { nodes { id } }\n  inventoryItem { legacyResourceId measurement { weight { unit value } } } } } } }\n}";
+export declare const VARIANTS_PAGE_QUERY = "query PorulleProductVariants($id: ID!, $after: String) {\n  product(id: $id) { variants(first: 250, after: $after) { pageInfo { hasNextPage endCursor } nodes { \n  legacyResourceId sku price compareAtPrice inventoryQuantity\n  barcodes(first: 1) { nodes { value } }\n  selectedOptions { name value }\n  media(first: 1) { nodes { id } }\n  inventoryItem { legacyResourceId measurement { weight { unit value } } } } } }\n}";
+export declare const CATALOG_ITEMS_QUERY = "query PorulleCatalogItems($ids: [ID!]!) {\n  shop { currencyCode }\n  nodes(ids: $ids) { ... on Product { \n  legacyResourceId title handle status descriptionHtml vendor productType tags onlineStoreUrl\n  category { name }\n  options { name position optionValues { name } }\n  media(first: 20) { nodes { id alt mediaContentType ... on MediaImage { image { url } } } }\n  variants(first: 25) { pageInfo { hasNextPage endCursor } nodes { \n  legacyResourceId sku price compareAtPrice inventoryQuantity\n  barcodes(first: 1) { nodes { value } }\n  selectedOptions { name value }\n  media(first: 1) { nodes { id } }\n  inventoryItem { legacyResourceId measurement { weight { unit value } } } } } } }\n}";
+declare const variantSchema: z.ZodObject<{
+    legacyResourceId: z.ZodString;
+    sku: z.ZodNullable<z.ZodString>;
+    price: z.ZodString;
+    compareAtPrice: z.ZodNullable<z.ZodString>;
+    inventoryQuantity: z.ZodNullable<z.ZodNumber>;
+    barcodes: z.ZodObject<{
+        nodes: z.ZodArray<z.ZodObject<{
+            value: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+    selectedOptions: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        value: z.ZodString;
+    }, z.core.$strip>>;
+    media: z.ZodObject<{
+        nodes: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+    inventoryItem: z.ZodObject<{
+        legacyResourceId: z.ZodString;
+        measurement: z.ZodObject<{
+            weight: z.ZodNullable<z.ZodObject<{
+                unit: z.ZodString;
+                value: z.ZodNumber;
+            }, z.core.$strip>>;
+        }, z.core.$strip>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+type ShopifyVariant = z.infer<typeof variantSchema>;
+declare const productSchema: z.ZodObject<{
+    legacyResourceId: z.ZodString;
+    title: z.ZodString;
+    handle: z.ZodString;
+    status: z.ZodString;
+    descriptionHtml: z.ZodString;
+    vendor: z.ZodString;
+    productType: z.ZodString;
+    tags: z.ZodArray<z.ZodString>;
+    onlineStoreUrl: z.ZodNullable<z.ZodString>;
+    category: z.ZodNullable<z.ZodObject<{
+        name: z.ZodString;
+    }, z.core.$strip>>;
+    options: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        position: z.ZodNumber;
+        optionValues: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    media: z.ZodObject<{
+        nodes: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            alt: z.ZodNullable<z.ZodString>;
+            mediaContentType: z.ZodString;
+            image: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+                url: z.ZodString;
+            }, z.core.$strip>>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+    variants: z.ZodObject<{
+        pageInfo: z.ZodObject<{
+            hasNextPage: z.ZodBoolean;
+            endCursor: z.ZodNullable<z.ZodString>;
+        }, z.core.$strip>;
+        nodes: z.ZodArray<z.ZodObject<{
+            legacyResourceId: z.ZodString;
+            sku: z.ZodNullable<z.ZodString>;
+            price: z.ZodString;
+            compareAtPrice: z.ZodNullable<z.ZodString>;
+            inventoryQuantity: z.ZodNullable<z.ZodNumber>;
+            barcodes: z.ZodObject<{
+                nodes: z.ZodArray<z.ZodObject<{
+                    value: z.ZodString;
+                }, z.core.$strip>>;
+            }, z.core.$strip>;
+            selectedOptions: z.ZodArray<z.ZodObject<{
+                name: z.ZodString;
+                value: z.ZodString;
+            }, z.core.$strip>>;
+            media: z.ZodObject<{
+                nodes: z.ZodArray<z.ZodObject<{
+                    id: z.ZodString;
+                }, z.core.$strip>>;
+            }, z.core.$strip>;
+            inventoryItem: z.ZodObject<{
+                legacyResourceId: z.ZodString;
+                measurement: z.ZodObject<{
+                    weight: z.ZodNullable<z.ZodObject<{
+                        unit: z.ZodString;
+                        value: z.ZodNumber;
+                    }, z.core.$strip>>;
+                }, z.core.$strip>;
+            }, z.core.$strip>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+type ShopifyProduct = z.infer<typeof productSchema>;
+export declare const catalogPageSchema: z.ZodObject<{
+    shop: z.ZodObject<{
+        currencyCode: z.ZodString;
+    }, z.core.$strip>;
+    products: z.ZodObject<{
+        pageInfo: z.ZodObject<{
+            hasNextPage: z.ZodBoolean;
+            endCursor: z.ZodNullable<z.ZodString>;
+        }, z.core.$strip>;
+        nodes: z.ZodArray<z.ZodObject<{
+            legacyResourceId: z.ZodString;
+            title: z.ZodString;
+            handle: z.ZodString;
+            status: z.ZodString;
+            descriptionHtml: z.ZodString;
+            vendor: z.ZodString;
+            productType: z.ZodString;
+            tags: z.ZodArray<z.ZodString>;
+            onlineStoreUrl: z.ZodNullable<z.ZodString>;
+            category: z.ZodNullable<z.ZodObject<{
+                name: z.ZodString;
+            }, z.core.$strip>>;
+            options: z.ZodArray<z.ZodObject<{
+                name: z.ZodString;
+                position: z.ZodNumber;
+                optionValues: z.ZodArray<z.ZodObject<{
+                    name: z.ZodString;
+                }, z.core.$strip>>;
+            }, z.core.$strip>>;
+            media: z.ZodObject<{
+                nodes: z.ZodArray<z.ZodObject<{
+                    id: z.ZodString;
+                    alt: z.ZodNullable<z.ZodString>;
+                    mediaContentType: z.ZodString;
+                    image: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+                        url: z.ZodString;
+                    }, z.core.$strip>>>;
+                }, z.core.$strip>>;
+            }, z.core.$strip>;
+            variants: z.ZodObject<{
+                pageInfo: z.ZodObject<{
+                    hasNextPage: z.ZodBoolean;
+                    endCursor: z.ZodNullable<z.ZodString>;
+                }, z.core.$strip>;
+                nodes: z.ZodArray<z.ZodObject<{
+                    legacyResourceId: z.ZodString;
+                    sku: z.ZodNullable<z.ZodString>;
+                    price: z.ZodString;
+                    compareAtPrice: z.ZodNullable<z.ZodString>;
+                    inventoryQuantity: z.ZodNullable<z.ZodNumber>;
+                    barcodes: z.ZodObject<{
+                        nodes: z.ZodArray<z.ZodObject<{
+                            value: z.ZodString;
+                        }, z.core.$strip>>;
+                    }, z.core.$strip>;
+                    selectedOptions: z.ZodArray<z.ZodObject<{
+                        name: z.ZodString;
+                        value: z.ZodString;
+                    }, z.core.$strip>>;
+                    media: z.ZodObject<{
+                        nodes: z.ZodArray<z.ZodObject<{
+                            id: z.ZodString;
+                        }, z.core.$strip>>;
+                    }, z.core.$strip>;
+                    inventoryItem: z.ZodObject<{
+                        legacyResourceId: z.ZodString;
+                        measurement: z.ZodObject<{
+                            weight: z.ZodNullable<z.ZodObject<{
+                                unit: z.ZodString;
+                                value: z.ZodNumber;
+                            }, z.core.$strip>>;
+                        }, z.core.$strip>;
+                    }, z.core.$strip>;
+                }, z.core.$strip>>;
+            }, z.core.$strip>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export declare function toCatalogItem(product: ShopifyProduct, variants: readonly ShopifyVariant[], currency: string): ChannelCatalogItem;
+export declare function readCatalogPage(target: ShopifyGraphqlTarget, cursor: string | undefined): Promise<Result<{
+    items: ChannelCatalogItem[];
+    nextCursor: string | null;
+}, ChannelConnectorError>>;
+/** The current state of the named products. An id Shopify no longer has is simply absent. */
+export declare function readCatalogItems(target: ShopifyGraphqlTarget, externalIds: readonly string[]): Promise<Result<ChannelCatalogItem[], ChannelConnectorError>>;
+export {};

package/dist/catalog.js

@@ -0,0 +1,226 @@
+import { Err, Ok, toMinorUnits } from "@porulle/core";
+import { z } from "zod";
+import { shopifyGid, shopifyGraphql } from "./graphql.js";
+/**
+ * Products per catalogue page. Measured against Shopify's own demo store through its public GraphQL
+ * proxy on 2026-10-03: 25 products with 25 variants and 10 media each requested 320 cost points
+ * against a 2,000-point bucket restoring 100/s. 50 keeps a page well under the 1,000-point
+ * single-query ceiling while halving the number of calls a large catalogue takes.
+ */
+export const CATALOG_PAGE_PRODUCTS = 50;
+/** Variants read with the product; a product with more is completed by `VARIANTS_PAGE`. */
+const VARIANTS_WITH_PRODUCT = 25;
+/** Images read per product. Import selects a hero and a few gallery images from these. */
+const MEDIA_PER_PRODUCT = 20;
+const VARIANT_FIELDS = `
+  legacyResourceId sku price compareAtPrice inventoryQuantity
+  barcodes(first: 1) { nodes { value } }
+  selectedOptions { name value }
+  media(first: 1) { nodes { id } }
+  inventoryItem { legacyResourceId measurement { weight { unit value } } }`;
+const PRODUCT_FIELDS = `
+  legacyResourceId title handle status descriptionHtml vendor productType tags onlineStoreUrl
+  category { name }
+  options { name position optionValues { name } }
+  media(first: ${MEDIA_PER_PRODUCT}) { nodes { id alt mediaContentType ... on MediaImage { image { url } } } }
+  variants(first: ${VARIANTS_WITH_PRODUCT}) { pageInfo { hasNextPage endCursor } nodes { ${VARIANT_FIELDS} } }`;
+export const CATALOG_PAGE_QUERY = `query PorulleCatalogPage($first: Int!, $after: String) {
+  shop { currencyCode }
+  products(first: $first, after: $after, sortKey: ID) { pageInfo { hasNextPage endCursor } nodes { ${PRODUCT_FIELDS} } }
+}`;
+export const VARIANTS_PAGE_QUERY = `query PorulleProductVariants($id: ID!, $after: String) {
+  product(id: $id) { variants(first: 250, after: $after) { pageInfo { hasNextPage endCursor } nodes { ${VARIANT_FIELDS} } } }
+}`;
+export const CATALOG_ITEMS_QUERY = `query PorulleCatalogItems($ids: [ID!]!) {
+  shop { currencyCode }
+  nodes(ids: $ids) { ... on Product { ${PRODUCT_FIELDS} } }
+}`;
+const pageInfoSchema = z.object({ hasNextPage: z.boolean(), endCursor: z.string().nullable() });
+const variantSchema = z.object({
+    legacyResourceId: z.string(),
+    sku: z.string().nullable(),
+    price: z.string(),
+    compareAtPrice: z.string().nullable(),
+    inventoryQuantity: z.number().nullable(),
+    barcodes: z.object({ nodes: z.array(z.object({ value: z.string() })) }),
+    selectedOptions: z.array(z.object({ name: z.string(), value: z.string() })),
+    media: z.object({ nodes: z.array(z.object({ id: z.string() })) }),
+    inventoryItem: z.object({
+        legacyResourceId: z.string(),
+        measurement: z.object({ weight: z.object({ unit: z.string(), value: z.number() }).nullable() }),
+    }),
+});
+const variantConnectionSchema = z.object({ pageInfo: pageInfoSchema, nodes: z.array(variantSchema) });
+const productSchema = z.object({
+    legacyResourceId: z.string(),
+    title: z.string(),
+    handle: z.string(),
+    status: z.string(),
+    descriptionHtml: z.string(),
+    vendor: z.string(),
+    productType: z.string(),
+    tags: z.array(z.string()),
+    onlineStoreUrl: z.string().nullable(),
+    category: z.object({ name: z.string() }).nullable(),
+    options: z.array(z.object({ name: z.string(), position: z.number(), optionValues: z.array(z.object({ name: z.string() })) })),
+    media: z.object({
+        nodes: z.array(z.object({
+            id: z.string(),
+            alt: z.string().nullable(),
+            mediaContentType: z.string(),
+            image: z.object({ url: z.string() }).nullable().optional(),
+        })),
+    }),
+    variants: variantConnectionSchema,
+});
+const shopCurrencySchema = z.object({ currencyCode: z.string() });
+export const catalogPageSchema = z.object({
+    shop: shopCurrencySchema,
+    products: z.object({ pageInfo: pageInfoSchema, nodes: z.array(productSchema) }),
+});
+const variantsPageSchema = z.object({ product: z.object({ variants: variantConnectionSchema }).nullable() });
+const catalogItemsSchema = z.object({
+    shop: shopCurrencySchema,
+    // `nodes` answers null for an id that no longer exists, and `{}` for one that is not a Product.
+    nodes: z.array(z.union([productSchema, z.object({}).strict(), z.null()])),
+});
+const GRAMS_PER_UNIT = { GRAMS: 1, KILOGRAMS: 1000, OUNCES: 28.349523125, POUNDS: 453.59237 };
+/**
+ * Grams, or undefined — never 0 — when no weight is known, so the caller omits the key. A written
+ * 0 is indistinguishable from a weightless item and would defeat a default-parcel substitution. An
+ * unknown unit is refused rather than assumed to be grams.
+ */
+function weightGrams(variant) {
+    const weight = variant.inventoryItem.measurement.weight;
+    if (!weight || !Number.isFinite(weight.value) || weight.value <= 0)
+        return undefined;
+    const factor = GRAMS_PER_UNIT[weight.unit];
+    return factor === undefined ? undefined : Math.round(weight.value * factor);
+}
+function prices(variant, currency) {
+    const amount = toMinorUnits(variant.price, currency);
+    if (amount === undefined)
+        return undefined;
+    const compareAtAmount = variant.compareAtPrice === null ? undefined : toMinorUnits(variant.compareAtPrice, currency);
+    return [{ currency, amount, ...(compareAtAmount !== undefined && compareAtAmount !== amount ? { compareAtAmount } : {}) }];
+}
+/**
+ * UNLISTED is live but hidden from the shop's own search and collections — the merchant chose not to
+ * surface it, so it is not surfaced here either. Any status this version does not know is a draft:
+ * the safe direction for a value that decides whether a product is shown.
+ */
+function catalogStatus(status) {
+    if (status === "ACTIVE")
+        return "active";
+    if (status === "ARCHIVED")
+        return "archived";
+    return "draft";
+}
+function slugify(value) {
+    return value.toLowerCase().trim().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+}
+export function toCatalogItem(product, variants, currency) {
+    const images = product.media.nodes.flatMap((media) => (media.mediaContentType === "IMAGE" && media.image ? [{ id: media.id, url: media.image.url, alt: media.alt }] : []));
+    const category = product.productType ? slugify(product.productType) : product.category ? slugify(product.category.name) : "";
+    const storefrontUrl = product.onlineStoreUrl;
+    return {
+        externalId: product.legacyResourceId,
+        slug: product.handle,
+        title: product.title,
+        attributes: [{ locale: "en", title: product.title, ...(product.descriptionHtml ? { description: product.descriptionHtml } : {}) }],
+        variants: variants.map((variant) => {
+            const optionValues = Object.fromEntries(variant.selectedOptions.map((option) => [option.name, option.value]));
+            const variantPrices = prices(variant, currency);
+            const grams = weightGrams(variant);
+            const barcode = variant.barcodes.nodes[0]?.value;
+            return {
+                externalId: variant.legacyResourceId,
+                ...(variant.sku ? { sku: variant.sku } : {}),
+                ...(barcode ? { barcode } : {}),
+                ...(Object.keys(optionValues).length > 0 ? { optionValues } : {}),
+                ...(variantPrices ? { prices: variantPrices } : {}),
+                // The inventory item id lets a stock webhook, which names only the item, find this variant.
+                metadata: { inventoryItemId: variant.inventoryItem.legacyResourceId, ...(grams !== undefined ? { weightGrams: grams } : {}) },
+            };
+        }),
+        images: images.map((image, index) => ({
+            externalId: image.id,
+            url: image.url,
+            ...(image.alt ? { alt: image.alt } : {}),
+            role: index === 0 ? "primary" : "gallery",
+            sortOrder: index + 1,
+            variantExternalIds: variants.filter((variant) => variant.media.nodes.some((media) => media.id === image.id)).map((variant) => variant.legacyResourceId),
+        })),
+        options: product.options.map((option) => ({
+            name: option.name,
+            displayName: option.name,
+            sortOrder: option.position,
+            values: option.optionValues.map((value, index) => ({ value: value.name, displayValue: value.name, sortOrder: index })),
+        })),
+        tags: product.tags,
+        ...(product.vendor ? { brand: product.vendor } : {}),
+        ...(category ? { categories: [category] } : {}),
+        status: catalogStatus(product.status),
+        // Only Shopify's own answer. Null means the product is not on the Online Store channel; a URL
+        // assembled from the handle would be a guess that 404s on any shop with a custom route.
+        ...(storefrontUrl ? { storefrontUrl } : {}),
+    };
+}
+/** Every variant of `product`: the ones read with it, then the rest a page at a time. */
+async function allVariants(target, product) {
+    const variants = [...product.variants.nodes];
+    let pageInfo = product.variants.pageInfo;
+    const seen = new Set();
+    while (pageInfo.hasNextPage && pageInfo.endCursor) {
+        if (seen.has(pageInfo.endCursor))
+            return Err({ code: "SHOPIFY_PAGINATION_STUCK", message: `Shopify repeated a variant page for product ${product.legacyResourceId}.` });
+        seen.add(pageInfo.endCursor);
+        const page = await shopifyGraphql(target, VARIANTS_PAGE_QUERY, { id: shopifyGid("Product", product.legacyResourceId), after: pageInfo.endCursor }, variantsPageSchema);
+        if (!page.ok)
+            return page;
+        if (!page.value.product)
+            break;
+        variants.push(...page.value.product.variants.nodes);
+        pageInfo = page.value.product.variants.pageInfo;
+    }
+    return Ok(variants);
+}
+async function toItems(target, products, currency) {
+    const items = [];
+    for (const product of products) {
+        const variants = await allVariants(target, product);
+        if (!variants.ok)
+            return variants;
+        items.push(toCatalogItem(product, variants.value, currency));
+    }
+    return Ok(items);
+}
+export async function readCatalogPage(target, cursor) {
+    const page = await shopifyGraphql(target, CATALOG_PAGE_QUERY, { first: CATALOG_PAGE_PRODUCTS, after: cursor ?? null }, catalogPageSchema);
+    if (!page.ok)
+        return page;
+    const { pageInfo, nodes } = page.value.products;
+    if (pageInfo.hasNextPage && (!pageInfo.endCursor || pageInfo.endCursor === cursor)) {
+        return Err({ code: "SHOPIFY_PAGINATION_STUCK", message: "Shopify answered a product page that does not advance." });
+    }
+    const items = await toItems(target, nodes, page.value.shop.currencyCode);
+    if (!items.ok)
+        return items;
+    return Ok({ items: items.value, nextCursor: pageInfo.hasNextPage ? pageInfo.endCursor : null });
+}
+/** The current state of the named products. An id Shopify no longer has is simply absent. */
+export async function readCatalogItems(target, externalIds) {
+    const items = [];
+    for (let offset = 0; offset < externalIds.length; offset += CATALOG_PAGE_PRODUCTS) {
+        const ids = externalIds.slice(offset, offset + CATALOG_PAGE_PRODUCTS).map((id) => shopifyGid("Product", id));
+        const page = await shopifyGraphql(target, CATALOG_ITEMS_QUERY, { ids }, catalogItemsSchema);
+        if (!page.ok)
+            return page;
+        const products = page.value.nodes.filter((node) => node !== null && "legacyResourceId" in node);
+        const converted = await toItems(target, products, page.value.shop.currencyCode);
+        if (!converted.ok)
+            return converted;
+        items.push(...converted.value);
+    }
+    return Ok(items);
+}

package/dist/graphql.d.ts

@@ -0,0 +1,31 @@
+import type { ChannelConnectorError, Result } from "@porulle/core";
+import { z } from "zod";
+/**
+ * The one way this adapter talks to a store: the GraphQL Admin API.
+ *
+ * Shopify made the REST Admin API legacy on 2024-10-01, deprecated its product and variant endpoints
+ * in 2024-04, and requires public apps to use GraphQL only — so there is no REST path left here to
+ * drift out of date. Every document this adapter sends is validated against Shopify's published
+ * schema for `SHOPIFY_API_VERSION` by `scripts/validate-shopify-documents.mjs`.
+ */
+export declare const SHOPIFY_API_VERSION = "2026-10";
+export interface ShopifyGraphqlTarget {
+    fetchImpl: typeof fetch;
+    /** `https://{shop}` in production; the stand-in's per-shop origin under test. */
+    origin: string;
+    accessToken: string;
+    /** Overridable for tests only; production always waits on the real clock. */
+    sleep?: (ms: number) => Promise<void>;
+}
+/**
+ * POST one document and parse its `data` with `schema`.
+ *
+ * Throttling (`THROTTLED` in `errors`, or HTTP 429) waits for the bucket Shopify reports and
+ * retries. Anything else not-ok is an error: a GraphQL `errors` array is never read as an empty
+ * answer, because "the store has no products" and "the query failed" must not look alike. A `data`
+ * the schema rejects is an error too — that is Shopify's schema moving under a pinned version, and
+ * the right response is to stop rather than import a half-read product.
+ */
+export declare function shopifyGraphql<T>(target: ShopifyGraphqlTarget, query: string, variables: Record<string, unknown>, schema: z.ZodType<T>): Promise<Result<T, ChannelConnectorError>>;
+/** `gid://shopify/<Type>/<id>` for a numeric id; the adapter keys everything by the numeric id. */
+export declare function shopifyGid(type: "Product" | "ProductVariant", id: string): string;

package/dist/graphql.js

@@ -0,0 +1,106 @@
+import { Err, Ok } from "@porulle/core";
+import { z } from "zod";
+/**
+ * The one way this adapter talks to a store: the GraphQL Admin API.
+ *
+ * Shopify made the REST Admin API legacy on 2024-10-01, deprecated its product and variant endpoints
+ * in 2024-04, and requires public apps to use GraphQL only — so there is no REST path left here to
+ * drift out of date. Every document this adapter sends is validated against Shopify's published
+ * schema for `SHOPIFY_API_VERSION` by `scripts/validate-shopify-documents.mjs`.
+ */
+export const SHOPIFY_API_VERSION = "2026-10";
+/** How long one call may wait for the cost bucket to refill before reporting a retriable failure. */
+const MAX_THROTTLE_WAIT_MS = 10_000;
+const MAX_THROTTLE_RETRIES = 3;
+const envelopeSchema = z.object({
+    data: z.unknown().optional(),
+    errors: z.array(z.object({
+        message: z.string().optional(),
+        extensions: z.object({ code: z.string().optional() }).partial().optional(),
+    })).optional(),
+    extensions: z.object({
+        cost: z.object({
+            requestedQueryCost: z.number().optional(),
+            throttleStatus: z.object({ currentlyAvailable: z.number(), restoreRate: z.number() }).optional(),
+        }).optional(),
+    }).optional(),
+});
+/** Milliseconds until the bucket holds the query's cost again, from Shopify's own report of it. */
+function throttleWaitMs(envelope) {
+    const cost = envelope.extensions?.cost;
+    const status = cost?.throttleStatus;
+    if (!status || cost?.requestedQueryCost === undefined || status.restoreRate <= 0)
+        return 1_000;
+    const deficit = Math.max(0, cost.requestedQueryCost - status.currentlyAvailable);
+    return Math.ceil((deficit / status.restoreRate) * 1_000);
+}
+const defaultSleep = (ms) => new Promise((resolve) => { setTimeout(resolve, ms); });
+async function readEnvelope(response) {
+    const body = await response.json().catch(() => undefined);
+    const parsed = envelopeSchema.safeParse(body);
+    return parsed.success ? parsed.data : undefined;
+}
+/**
+ * POST one document and parse its `data` with `schema`.
+ *
+ * Throttling (`THROTTLED` in `errors`, or HTTP 429) waits for the bucket Shopify reports and
+ * retries. Anything else not-ok is an error: a GraphQL `errors` array is never read as an empty
+ * answer, because "the store has no products" and "the query failed" must not look alike. A `data`
+ * the schema rejects is an error too — that is Shopify's schema moving under a pinned version, and
+ * the right response is to stop rather than import a half-read product.
+ */
+export async function shopifyGraphql(target, query, variables, schema) {
+    const sleep = target.sleep ?? defaultSleep;
+    const url = `${target.origin}/admin/api/${SHOPIFY_API_VERSION}/graphql.json`;
+    let waited = 0;
+    for (let attempt = 0;; attempt += 1) {
+        let response;
+        try {
+            // `manual`, never `error`: workerd implements only `follow` and `manual` and throws on `error`
+            // from the Request constructor. A 3xx is then simply not ok, which refuses the redirect.
+            response = await target.fetchImpl(url, {
+                method: "POST",
+                redirect: "manual",
+                headers: { accept: "application/json", "content-type": "application/json", "x-shopify-access-token": target.accessToken },
+                body: JSON.stringify({ query, variables }),
+            });
+        }
+        catch (error) {
+            return Err({ code: "SHOPIFY_API_FAILED", message: error instanceof Error ? error.message : "Shopify API request failed.", retriable: true });
+        }
+        if (response.status === 401 || response.status === 403) {
+            return Err({ code: "SHOPIFY_UNAUTHORIZED", message: `Shopify refused the access token (${response.status}); the store must be reconnected.`, retriable: false });
+        }
+        if (response.status !== 429 && !response.ok) {
+            return Err({ code: "SHOPIFY_API_FAILED", message: `Shopify API request failed (${response.status}).`, retriable: response.status >= 500 });
+        }
+        const envelope = await readEnvelope(response);
+        if (envelope === undefined && response.status !== 429) {
+            return Err({ code: "SHOPIFY_API_FAILED", message: "Shopify answered a body that is not a GraphQL response.", retriable: true });
+        }
+        const errors = envelope?.errors ?? [];
+        if (response.status === 429 || errors.some((error) => error.extensions?.code === "THROTTLED")) {
+            const wait = envelope === undefined ? 1_000 : throttleWaitMs(envelope);
+            if (attempt >= MAX_THROTTLE_RETRIES || waited + wait > MAX_THROTTLE_WAIT_MS) {
+                return Err({ code: "SHOPIFY_THROTTLED", message: "Shopify's API cost bucket is exhausted; retry later.", retriable: true });
+            }
+            waited += wait;
+            await sleep(wait);
+            continue;
+        }
+        if (errors.length > 0) {
+            const message = errors.map((error) => error.message ?? "unknown error").join("; ");
+            const denied = errors.some((error) => error.extensions?.code === "ACCESS_DENIED");
+            return Err({ code: denied ? "SHOPIFY_ACCESS_DENIED" : "SHOPIFY_GRAPHQL_ERROR", message: `Shopify GraphQL error: ${message}`, retriable: false });
+        }
+        const data = schema.safeParse(envelope?.data);
+        if (!data.success) {
+            return Err({ code: "SHOPIFY_RESPONSE_INVALID", message: `Shopify answered data this adapter cannot read: ${data.error.issues[0]?.message ?? "invalid shape"}.`, retriable: false });
+        }
+        return Ok(data.data);
+    }
+}
+/** `gid://shopify/<Type>/<id>` for a numeric id; the adapter keys everything by the numeric id. */
+export function shopifyGid(type, id) {
+    return `gid://shopify/${type}/${id}`;
+}

package/dist/index.d.ts

@@ -1,38 +1,24 @@
-import type { ChannelConnector, ChannelConnectorError, Result } from "@porulle/core";
-export { PORULLE_METAFIELD_NAMESPACE, PUSH_CATALOG_SCOPE, SHOPIFY_NATIVE_PRODUCT_FIELDS, SHOPIFY_NATIVE_VARIANT_FIELDS, shopifyGrantedScopes, shopifyPushCatalogEnabled, shopifyWriteProductsScopeMissingError, } from "./push-catalog.js";
+import type { ChannelConnector } from "@porulle/core";
+export { SHOPIFY_API_VERSION } from "./graphql.js";
+export { CATALOG_ITEMS_QUERY, CATALOG_PAGE_QUERY, VARIANTS_PAGE_QUERY } from "./catalog.js";
+export { REQUIRED_SCOPES, normalizeShopDomain, parseShopifyCredentials } from "./oauth.js";
+export type { ShopifyCredentials } from "./oauth.js";
 export interface ShopifyConnectorOptions {
+    clientId: string;
+    clientSecret: string;
     fetchImpl?: typeof fetch;
-    apiVersion?: string;
-    clientId?: string;
-    clientSecret?: string;
-    appUrl?: string;
-    scopes?: string[];
     /**
-     * Origin override for every Shopify call — the Admin API and both OAuth endpoints.
-     *
-     * ABSENT IN PRODUCTION, where it resolves to `https://{store.storeDomain}` and the request is
-     * byte-identical to the one this adapter has always made. Present, it points the same code at a
-     * local stand-in built from Shopify's documentation, so that a missing app credential stops
-     * blocking development.
-     *
-     * It is an ORIGIN and not a base URL because Shopify's host is per-store: the shop still rides
-     * inside the path the adapter appends. A caller pointing at a mock passes
-     * `http://127.0.0.1:<port>/shopify`, the adapter appends `/admin/api/{version}/products.json`,
-     * and the stand-in serves Shopify's own address table unprefixed.
-     *
-     * There is deliberately NO `mock` flag and no URL rewriting inside `fetchImpl`. The shipped path
-     * must be the tested path; a branch inside the adapter means the code exercised by a test is not
-     * the code that runs, and reaching a stand-in by rewriting URLs inside an injected fetch is the
-     * same failure wearing a hook.
+     * Where a shop's Admin API lives. Production omits it: `https://{shop}`. A test points it at a
+     * stand-in that serves every shop under its own path — `(shop) => \`${mock}/shopify/${shop}\`` —
+     * so the shop's identity still rides in the request exactly as it does in production, and the
+     * code exercised by a test is the code that runs. There is no mock flag inside this adapter.
      */
-    baseUrl?: string;
+    shopOrigin?: (shopDomain: string) => string;
 }
-export declare const REQUIRED_SCOPES: readonly ["read_products", "read_inventory", "read_orders", "write_orders", "read_fulfillments", "write_products"];
-export declare function shopifyReauthorizeUrl(options: ShopifyConnectorOptions, params: {
-    storeDomain: string;
-    state: string;
-    redirectUri: string;
-    callbackUri: string;
-    scopes?: string[];
-}): Result<string, ChannelConnectorError>;
-export declare function shopifyConnector(options?: ShopifyConnectorOptions): ChannelConnector;
+export declare const INVENTORY_QUERY = "query PorulleInventoryPage($after: String) {\n  productVariants(first: 250, after: $after, sortKey: ID) { pageInfo { hasNextPage endCursor } nodes { legacyResourceId inventoryQuantity } }\n}";
+export declare const VARIANT_INVENTORY_QUERY = "query PorulleVariantInventory($ids: [ID!]!) {\n  nodes(ids: $ids) { ... on ProductVariant { legacyResourceId inventoryQuantity } }\n}";
+export declare const STORE_PROFILE_QUERY = "query PorulleStoreProfile {\n  shop { name currencyCode myshopifyDomain primaryDomain { host } }\n}";
+export declare const ORDER_CREATE_MUTATION = "mutation PorulleOrderCreate($order: OrderCreateOrderInput!, $options: OrderCreateOptionsInput) {\n  orderCreate(order: $order, options: $options) { order { legacyResourceId } userErrors { field message } }\n}";
+export declare const ORDER_BY_SOURCE_QUERY = "query PorulleOrderBySource($query: String!) {\n  orders(first: 1, query: $query) { nodes { legacyResourceId } }\n}";
+export declare const ORDER_STATUS_QUERY = "query PorulleOrderStatus($id: ID!) {\n  order(id: $id) { cancelledAt displayFinancialStatus displayFulfillmentStatus }\n}";
+export declare function shopifyConnector(options: ShopifyConnectorOptions): ChannelConnector;