@porulle/adapter-shopify 0.11.0 → 0.13.0

package/README.md

@@ -1,3 +1,24 @@
 # @porulle/adapter-shopify
 
 Shopify ingress channel connector for Porulle.
+
+## Catalog push and re-authorisation
+
+Catalog push requires the `write_products` OAuth scope. The adapter advertises
+`capabilities.pushCatalog: true`, but effective push access is resolved per
+store from `credentials.grantedScopes` recorded during OAuth (`completeAuth`).
+
+Stores connected before `write_products` was added to `REQUIRED_SCOPES` hold
+tokens without that scope. When push is attempted, the adapter returns
+`SHOPIFY_WRITE_PRODUCTS_SCOPE_MISSING` with `retriable: false` and a link to
+Porulle's OAuth start route (when `appUrl` is configured).
+
+Operators can recover without disconnecting the store:
+
+1. Start Shopify OAuth again for the same store (`/api/channels/oauth/shopify/start` in a Porulle app with this adapter configured).
+2. Approve the updated scope list, which now includes `write_products`.
+3. Retry the catalog push job.
+
+Use `shopifyReauthorizeUrl(options, params)` to build the authorize URL outside
+the push error path, or `shopifyPushCatalogEnabled(store)` to check scope
+coverage before enqueueing work.

package/dist/index.d.ts

@@ -1,4 +1,5 @@
-import type { ChannelConnector } from "@porulle/core";
+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";
 export interface ShopifyConnectorOptions {
     fetchImpl?: typeof fetch;
     apiVersion?: string;
@@ -7,5 +8,12 @@ export interface ShopifyConnectorOptions {
     appUrl?: string;
     scopes?: string[];
 }
-export declare const REQUIRED_SCOPES: readonly ["read_products", "read_inventory", "read_orders", "write_orders", "read_fulfillments"];
+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;

package/dist/index.js

@@ -1,11 +1,14 @@
 import { defineChannelConnector, Err, Ok } from "@porulle/core";
 import { createHmac, timingSafeEqual } from "node:crypto";
+import { pushCatalog as executePushCatalog, } from "./push-catalog.js";
+export { PORULLE_METAFIELD_NAMESPACE, PUSH_CATALOG_SCOPE, SHOPIFY_NATIVE_PRODUCT_FIELDS, SHOPIFY_NATIVE_VARIANT_FIELDS, shopifyGrantedScopes, shopifyPushCatalogEnabled, shopifyWriteProductsScopeMissingError, } from "./push-catalog.js";
 export const REQUIRED_SCOPES = [
     "read_products",
     "read_inventory",
     "read_orders",
     "write_orders",
     "read_fulfillments",
+    "write_products",
 ];
 const zeroDecimalCurrencies = new Set([
     "BIF",
@@ -65,6 +68,16 @@ async function fetchShopCurrency(fetchImpl, url, accessToken) {
 function apiBase(store, version) {
     return `https://${store.storeDomain.replace(/^https?:\/\//, "").replace(/\/$/, "")}/admin/api/${version}`;
 }
+function shopifyOAuthStartUrl(appUrl, storeDomain) {
+    try {
+        const url = new URL("/api/channels/oauth/shopify/start", appUrl);
+        url.searchParams.set("shop", storeDomain);
+        return url.toString();
+    }
+    catch {
+        return undefined;
+    }
+}
 async function request(fetchImpl, url, accessToken, init) {
     try {
         const response = await fetchImpl(url, {
@@ -122,13 +135,19 @@ function validOAuthHmac(searchParams, secret) {
 function oauthError(code, message) {
     return Err({ code, message, retriable: false });
 }
+export function shopifyReauthorizeUrl(options, params) {
+    return shopifyConnector(options).buildAuthUrl({
+        ...params,
+        scopes: params.scopes ?? [],
+    });
+}
 export function shopifyConnector(options = {}) {
     const fetchImpl = options.fetchImpl ?? fetch;
     const version = options.apiVersion ?? "2024-10";
     const currencyCache = new Map();
     return defineChannelConnector({
         providerId: "shopify",
-        capabilities: { importCatalog: true, importInventory: true, pushOrder: true, receiveWebhooks: true },
+        capabilities: { importCatalog: true, importInventory: true, pushOrder: true, pushCatalog: true, receiveWebhooks: true },
         buildAuthUrl(params) {
             if (!options.clientId || !options.clientSecret || !options.appUrl) {
                 return oauthError("SHOPIFY_OAUTH_NOT_CONFIGURED", "Shopify OAuth requires clientId, clientSecret, and appUrl.");
@@ -175,7 +194,10 @@ export function shopifyConnector(options = {}) {
                 const body = await response.json();
                 if (typeof body.access_token !== "string" || !body.access_token)
                     return oauthError("SHOPIFY_TOKEN_INVALID", "Shopify token exchange did not return an access token.");
-                return Ok({ credentials: { accessToken: body.access_token }, storeDomain: shopDomain });
+                const grantedScopes = typeof body.scope === "string"
+                    ? body.scope.split(",").map((scope) => scope.trim()).filter(Boolean)
+                    : [];
+                return Ok({ credentials: { accessToken: body.access_token, grantedScopes }, storeDomain: shopDomain });
             }
             catch (error) {
                 return Err({ code: "SHOPIFY_TOKEN_EXCHANGE_FAILED", message: error instanceof Error ? error.message : "Shopify token exchange failed.", retriable: true });
@@ -262,6 +284,17 @@ export function shopifyConnector(options = {}) {
                 return result;
             return Ok(result.value.data.inventory_levels.map((level) => ({ externalId: String(level.inventory_item_id), available: level.available ?? 0 })));
         },
+        async pushCatalog(store, items, opts) {
+            const oauthStartUrl = options.appUrl ? shopifyOAuthStartUrl(options.appUrl, store.storeDomain) : undefined;
+            return executePushCatalog({
+                fetchImpl,
+                apiBase: (target) => apiBase(target, version),
+                credentials,
+            }, store, items, {
+                ...(opts?.dryRun === true ? { dryRun: true } : {}),
+                ...(oauthStartUrl ? { reauthorizeUrl: oauthStartUrl } : {}),
+            });
+        },
         async pushOrder(store, slice) {
             const token = credentials(store);
             if (!token)

package/dist/push-catalog.d.ts

@@ -0,0 +1,18 @@
+import type { ChannelConnectorError, ChannelPushCatalogItem, ChannelPushCatalogResult, ChannelStore, Result } from "@porulle/core";
+export declare const PUSH_CATALOG_SCOPE = "write_products";
+export declare const PORULLE_METAFIELD_NAMESPACE = "porulle";
+export declare const SHOPIFY_NATIVE_PRODUCT_FIELDS: Set<string>;
+export declare const SHOPIFY_NATIVE_VARIANT_FIELDS: Set<string>;
+export interface PushCatalogDeps {
+    fetchImpl: typeof fetch;
+    apiBase: (store: ChannelStore) => string;
+    credentials: (store: ChannelStore) => string | undefined;
+    sleep?: (ms: number) => Promise<void>;
+}
+export declare function shopifyGrantedScopes(store: ChannelStore): string[];
+export declare function shopifyPushCatalogEnabled(store: ChannelStore): boolean;
+export declare function shopifyWriteProductsScopeMissingError(reauthorizeUrl?: string): ChannelConnectorError;
+export declare function pushCatalog(deps: PushCatalogDeps, store: ChannelStore, items: ChannelPushCatalogItem[], opts?: {
+    dryRun?: boolean;
+    reauthorizeUrl?: string;
+}): Promise<Result<ChannelPushCatalogResult, ChannelConnectorError>>;

package/dist/push-catalog.js

@@ -0,0 +1,401 @@
+import { Err, Ok } from "@porulle/core";
+export const PUSH_CATALOG_SCOPE = "write_products";
+export const PORULLE_METAFIELD_NAMESPACE = "porulle";
+export const SHOPIFY_NATIVE_PRODUCT_FIELDS = new Set([
+    "title",
+    "body_html",
+    "vendor",
+    "product_type",
+    "handle",
+    "status",
+]);
+export const SHOPIFY_NATIVE_VARIANT_FIELDS = new Set([
+    "sku",
+    "barcode",
+]);
+export function shopifyGrantedScopes(store) {
+    const raw = store.credentials.grantedScopes;
+    if (Array.isArray(raw)) {
+        return raw.filter((scope) => typeof scope === "string" && scope.length > 0);
+    }
+    if (typeof raw === "string" && raw.length > 0) {
+        return raw.split(",").map((scope) => scope.trim()).filter(Boolean);
+    }
+    return [];
+}
+export function shopifyPushCatalogEnabled(store) {
+    return shopifyGrantedScopes(store).includes(PUSH_CATALOG_SCOPE);
+}
+export function shopifyWriteProductsScopeMissingError(reauthorizeUrl) {
+    const suffix = reauthorizeUrl
+        ? ` Re-authorize at ${reauthorizeUrl}.`
+        : " Re-authorize the store through the Shopify OAuth start route.";
+    return {
+        code: "SHOPIFY_WRITE_PRODUCTS_SCOPE_MISSING",
+        message: `Shopify store is missing the ${PUSH_CATALOG_SCOPE} scope.${suffix}`,
+        retriable: false,
+    };
+}
+function parseCallLimit(header) {
+    const match = header?.match(/^(\d+)\/(\d+)$/);
+    if (!match)
+        return undefined;
+    return { current: Number(match[1]), max: Number(match[2]) };
+}
+function metafieldType(value) {
+    if (typeof value === "boolean")
+        return "boolean";
+    if (typeof value === "number")
+        return Number.isInteger(value) ? "number_integer" : "number_decimal";
+    if (typeof value === "object" && value !== null)
+        return "json";
+    return "single_line_text_field";
+}
+function metafieldValue(value) {
+    if (typeof value === "string")
+        return value;
+    if (typeof value === "number" || typeof value === "boolean")
+        return String(value);
+    return JSON.stringify(value);
+}
+function remoteKey(field) {
+    if (typeof field.remoteKey === "string" && field.remoteKey.length > 0)
+        return field.remoteKey;
+    return undefined;
+}
+function missingRemoteKeyError(field) {
+    return {
+        code: "SHOPIFY_REMOTE_KEY_REQUIRED",
+        message: `Shopify catalog field ${field.fieldPath} requires a remoteKey.`,
+        retriable: false,
+    };
+}
+function isNativeProductField(field) {
+    const key = remoteKey(field);
+    return field.intent === "display" && key !== undefined && SHOPIFY_NATIVE_PRODUCT_FIELDS.has(key);
+}
+function isNativeVariantField(field) {
+    const key = remoteKey(field);
+    return field.intent === "display" && key !== undefined && SHOPIFY_NATIVE_VARIANT_FIELDS.has(key);
+}
+function isMetafieldField(field) {
+    if (field.intent === "filterable")
+        return true;
+    if (field.intent === "tag")
+        return false;
+    return field.intent === "display" && remoteKey(field) !== undefined && !isNativeProductField(field) && !isNativeVariantField(field);
+}
+function parseTags(value) {
+    if (!value)
+        return [];
+    return value.split(",").map((tag) => tag.trim()).filter(Boolean);
+}
+function mergeTags(existing, pushed) {
+    return [...new Set([...existing, ...pushed])].join(", ");
+}
+function collectPreviousFields(product, metafields, variantMetafields, item) {
+    const previous = [];
+    const metafieldByKey = new Map(metafields
+        .filter((entry) => entry.namespace === PORULLE_METAFIELD_NAMESPACE)
+        .map((entry) => [entry.key, entry]));
+    for (const field of item.fields) {
+        if (field.intent === "tag") {
+            const tag = field.value == null ? "" : String(field.value);
+            previous.push({
+                fieldPath: field.fieldPath,
+                value: tag.length > 0 && parseTags(product.tags).includes(tag) ? tag : null,
+            });
+            continue;
+        }
+        if (isNativeProductField(field)) {
+            const key = remoteKey(field);
+            if (key !== undefined)
+                previous.push({ fieldPath: field.fieldPath, value: product[key] ?? null });
+            continue;
+        }
+        if (isMetafieldField(field)) {
+            const key = remoteKey(field);
+            if (key !== undefined) {
+                const existing = metafieldByKey.get(key);
+                previous.push({ fieldPath: field.fieldPath, value: existing?.value ?? null });
+            }
+        }
+    }
+    for (const variant of item.variants ?? []) {
+        for (const field of variant.fields) {
+            if (isNativeVariantField(field)) {
+                const key = remoteKey(field);
+                const snapshot = product.variants?.find((entry) => String(entry.id) === variant.externalId);
+                previous.push({ fieldPath: field.fieldPath, value: key !== undefined ? snapshot?.[key] ?? null : null });
+            }
+            else if (isMetafieldField(field)) {
+                const key = remoteKey(field);
+                if (key !== undefined) {
+                    const existing = new Map((variantMetafields.get(variant.externalId) ?? [])
+                        .filter((entry) => entry.namespace === PORULLE_METAFIELD_NAMESPACE)
+                        .map((entry) => [entry.key, entry])).get(key);
+                    previous.push({ fieldPath: field.fieldPath, value: existing?.value ?? null });
+                }
+            }
+        }
+    }
+    return previous;
+}
+async function pushRequest(deps, url, token, init) {
+    const sleep = deps.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    try {
+        const response = await deps.fetchImpl(url, {
+            ...init,
+            headers: {
+                accept: "application/json",
+                ...(init?.headers ?? {}),
+                "x-shopify-access-token": token,
+            },
+        });
+        const limit = parseCallLimit(response.headers.get("x-shopify-shop-api-call-limit"));
+        if (limit && limit.current >= Math.max(1, limit.max - 2)) {
+            await sleep(500);
+        }
+        if (response.status === 429) {
+            return {
+                ok: false,
+                status: 429,
+                response,
+                error: {
+                    code: "SHOPIFY_RATE_LIMITED",
+                    message: "Shopify API rate limit exceeded.",
+                    retriable: true,
+                },
+            };
+        }
+        const method = (init?.method ?? "GET").toUpperCase();
+        if (response.status === 403 && method !== "GET") {
+            return {
+                ok: false,
+                status: 403,
+                response,
+                error: shopifyWriteProductsScopeMissingError(),
+            };
+        }
+        if (!response.ok) {
+            return {
+                ok: false,
+                status: response.status,
+                response,
+                error: {
+                    code: "SHOPIFY_API_FAILED",
+                    message: `Shopify API request failed (${response.status}) for ${url}.`,
+                    retriable: response.status >= 500,
+                },
+            };
+        }
+        const text = await response.text();
+        const data = text.length > 0 ? JSON.parse(text) : {};
+        return { ok: true, data, response };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            error: {
+                code: "SHOPIFY_API_FAILED",
+                message: error instanceof Error ? error.message : "Shopify API request failed.",
+                retriable: true,
+            },
+        };
+    }
+}
+async function loadProductSnapshot(deps, store, token, externalId, variantIds) {
+    const base = deps.apiBase(store);
+    const productResult = await pushRequest(deps, `${base}/products/${encodeURIComponent(externalId)}.json`, token);
+    if (!productResult.ok)
+        return productResult;
+    const metafieldsResult = await pushRequest(deps, `${base}/products/${encodeURIComponent(externalId)}/metafields.json?namespace=${encodeURIComponent(PORULLE_METAFIELD_NAMESPACE)}`, token);
+    if (!metafieldsResult.ok)
+        return metafieldsResult;
+    const variantMetafields = new Map();
+    for (const variantId of variantIds) {
+        const variantResult = await pushRequest(deps, `${base}/variants/${encodeURIComponent(variantId)}/metafields.json?namespace=${encodeURIComponent(PORULLE_METAFIELD_NAMESPACE)}`, token);
+        if (!variantResult.ok)
+            return variantResult;
+        variantMetafields.set(variantId, variantResult.data.metafields ?? []);
+    }
+    return Ok({
+        product: productResult.data.product,
+        metafields: metafieldsResult.data.metafields ?? [],
+        variantMetafields,
+    });
+}
+async function writeNativeProduct(deps, store, token, externalId, fields, tagValues, existingTags) {
+    const product = { id: externalId };
+    for (const field of fields) {
+        if (!isNativeProductField(field))
+            continue;
+        const key = remoteKey(field);
+        if (key !== undefined)
+            product[key] = field.value;
+    }
+    if (tagValues.length > 0) {
+        product.tags = mergeTags(existingTags, tagValues);
+    }
+    if (Object.keys(product).length <= 1) {
+        return {
+            ok: true,
+            data: { product: { id: externalId } },
+            response: new Response(null, { status: 200 }),
+        };
+    }
+    return pushRequest(deps, `${deps.apiBase(store)}/products/${encodeURIComponent(externalId)}.json`, token, {
+        method: "PUT",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ product }),
+    });
+}
+async function writeVariantFields(deps, store, token, variantExternalId, fields) {
+    const variant = { id: variantExternalId };
+    for (const field of fields) {
+        if (!isNativeVariantField(field))
+            continue;
+        const key = remoteKey(field);
+        if (key !== undefined)
+            variant[key] = field.value;
+    }
+    if (Object.keys(variant).length <= 1) {
+        return {
+            ok: true,
+            data: { variant: { id: variantExternalId } },
+            response: new Response(null, { status: 200 }),
+        };
+    }
+    return pushRequest(deps, `${deps.apiBase(store)}/variants/${encodeURIComponent(variantExternalId)}.json`, token, {
+        method: "PUT",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ variant }),
+    });
+}
+async function writeMetafield(deps, store, token, externalId, field, existing, resource) {
+    const key = remoteKey(field);
+    if (key === undefined)
+        return { ok: false, error: missingRemoteKeyError(field) };
+    const payload = {
+        metafield: {
+            namespace: PORULLE_METAFIELD_NAMESPACE,
+            key,
+            value: metafieldValue(field.value),
+            type: metafieldType(field.value),
+        },
+    };
+    if (existing) {
+        return pushRequest(deps, `${deps.apiBase(store)}/metafields/${encodeURIComponent(String(existing.id))}.json`, token, {
+            method: "PUT",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify(payload),
+        });
+    }
+    return pushRequest(deps, `${deps.apiBase(store)}/${resource}s/${encodeURIComponent(externalId)}/metafields.json`, token, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(payload),
+    });
+}
+async function pushCatalogItem(deps, store, token, item, dryRun) {
+    const missingField = [...item.fields, ...(item.variants ?? []).flatMap((variant) => variant.fields)]
+        .find((field) => field.intent !== "tag" && remoteKey(field) === undefined);
+    if (missingField)
+        return { externalId: item.externalId, ok: false, error: missingRemoteKeyError(missingField) };
+    if (item.images && item.images.length > 0) {
+        return {
+            externalId: item.externalId,
+            ok: false,
+            error: {
+                code: "SHOPIFY_IMAGES_NOT_WRITTEN",
+                message: "Shopify catalog image pushes are not written by this adapter.",
+                retriable: false,
+            },
+        };
+    }
+    const variantIds = (item.variants ?? [])
+        .filter((variant) => variant.fields.some((field) => isMetafieldField(field)))
+        .map((variant) => variant.externalId);
+    const snapshot = await loadProductSnapshot(deps, store, token, item.externalId, variantIds);
+    if (!snapshot.ok) {
+        return { externalId: item.externalId, ok: false, error: snapshot.error };
+    }
+    const previousFields = collectPreviousFields(snapshot.value.product, snapshot.value.metafields, snapshot.value.variantMetafields, item);
+    if (dryRun) {
+        return {
+            externalId: item.externalId,
+            ok: true,
+            ...(previousFields.length > 0 ? { previousFields } : {}),
+        };
+    }
+    const metafieldByKey = new Map(snapshot.value.metafields
+        .filter((entry) => entry.namespace === PORULLE_METAFIELD_NAMESPACE)
+        .map((entry) => [entry.key, entry]));
+    const productFields = item.fields.filter((field) => field.intent !== "tag");
+    const tagValues = item.fields
+        .filter((field) => field.intent === "tag")
+        .flatMap((field) => {
+        if (typeof field.value === "string")
+            return [field.value];
+        if (Array.isArray(field.value))
+            return field.value.filter((entry) => typeof entry === "string");
+        return field.value == null ? [] : [String(field.value)];
+    });
+    const nativeResult = await writeNativeProduct(deps, store, token, item.externalId, productFields, tagValues, parseTags(snapshot.value.product.tags));
+    if (!nativeResult.ok) {
+        return { externalId: item.externalId, ok: false, error: nativeResult.error };
+    }
+    for (const field of productFields) {
+        if (!isMetafieldField(field))
+            continue;
+        const key = remoteKey(field);
+        const metafieldResult = await writeMetafield(deps, store, token, item.externalId, field, key !== undefined ? metafieldByKey.get(key) : undefined, "product");
+        if (!metafieldResult.ok) {
+            return { externalId: item.externalId, ok: false, error: metafieldResult.error };
+        }
+        if (metafieldResult.data.metafield) {
+            metafieldByKey.set(metafieldResult.data.metafield.key, metafieldResult.data.metafield);
+        }
+    }
+    for (const variant of item.variants ?? []) {
+        const variantMetafieldByKey = new Map((snapshot.value.variantMetafields.get(variant.externalId) ?? [])
+            .filter((entry) => entry.namespace === PORULLE_METAFIELD_NAMESPACE)
+            .map((entry) => [entry.key, entry]));
+        for (const field of variant.fields) {
+            if (!isMetafieldField(field))
+                continue;
+            const key = remoteKey(field);
+            const metafieldResult = await writeMetafield(deps, store, token, variant.externalId, field, key !== undefined ? variantMetafieldByKey.get(key) : undefined, "variant");
+            if (!metafieldResult.ok) {
+                return { externalId: item.externalId, ok: false, error: metafieldResult.error };
+            }
+            if (metafieldResult.data.metafield) {
+                variantMetafieldByKey.set(metafieldResult.data.metafield.key, metafieldResult.data.metafield);
+            }
+        }
+        const variantResult = await writeVariantFields(deps, store, token, variant.externalId, variant.fields);
+        if (!variantResult.ok) {
+            return { externalId: item.externalId, ok: false, error: variantResult.error };
+        }
+    }
+    return {
+        externalId: item.externalId,
+        ok: true,
+        ...(nativeResult.data.product.updated_at ? { remoteUpdatedAt: nativeResult.data.product.updated_at } : {}),
+        ...(previousFields.length > 0 ? { previousFields } : {}),
+    };
+}
+export async function pushCatalog(deps, store, items, opts) {
+    const token = deps.credentials(store);
+    if (!token) {
+        return Err({ code: "SHOPIFY_CREDENTIALS_REQUIRED", message: "Shopify accessToken is required.", retriable: false });
+    }
+    if (!shopifyPushCatalogEnabled(store)) {
+        return Err(shopifyWriteProductsScopeMissingError(opts?.reauthorizeUrl));
+    }
+    const outcomes = [];
+    for (const item of items) {
+        outcomes.push(await pushCatalogItem(deps, store, token, item, opts?.dryRun === true));
+    }
+    return Ok({ outcomes });
+}