@porulle/adapter-shopify 0.10.8 → 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,21 +1,83 @@
 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",
 ];
-function parseMoney(value) {
-    if (!value)
-        return 0;
-    const parsed = Number.parseFloat(value);
-    return Number.isFinite(parsed) ? Math.round(parsed * 100) : 0;
+const zeroDecimalCurrencies = new Set([
+    "BIF",
+    "CLP",
+    "DJF",
+    "GNF",
+    "ISK",
+    "JPY",
+    "KMF",
+    "KRW",
+    "PYG",
+    "RWF",
+    "UGX",
+    "VND",
+    "VUV",
+    "XAF",
+    "XOF",
+    "XPF",
+]);
+function normalizeCurrency(value) {
+    if (typeof value !== "string" || value.trim() === "")
+        return undefined;
+    return value.trim().toUpperCase();
+}
+function parseMoney(value, currency) {
+    if (value == null || value.trim() === "")
+        return undefined;
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed))
+        return undefined;
+    const exponent = zeroDecimalCurrencies.has(currency) ? 0 : 2;
+    return Math.round(parsed * (10 ** exponent));
+}
+function pricesForVariant(variant, currency) {
+    if (!currency)
+        return undefined;
+    const amount = parseMoney(variant.price, currency);
+    if (amount === undefined)
+        return undefined;
+    const compareAtAmount = parseMoney(variant.compare_at_price, currency);
+    return [{
+            currency,
+            amount,
+            ...(compareAtAmount !== undefined && compareAtAmount !== amount ? { compareAtAmount } : {}),
+        }];
+}
+function catalogStatus(value) {
+    return value === "draft" || value === "active" || value === "archived" ? value : undefined;
+}
+function slugify(value) {
+    return value.toLowerCase().trim().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+}
+async function fetchShopCurrency(fetchImpl, url, accessToken) {
+    const result = await request(fetchImpl, url, accessToken);
+    return result.ok ? normalizeCurrency(result.value.data.shop?.currency) : undefined;
 }
 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, {
@@ -73,12 +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.");
@@ -125,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 });
@@ -135,6 +207,14 @@ export function shopifyConnector(options = {}) {
             const token = credentials(store);
             if (!token)
                 return Err({ code: "SHOPIFY_CREDENTIALS_REQUIRED", message: "Shopify accessToken is required." });
+            const currencyUrl = `${apiBase(store, version)}/shop.json`;
+            const currencyKey = apiBase(store, version);
+            let currencyPromise = currencyCache.get(currencyKey);
+            if (!currencyPromise) {
+                currencyPromise = fetchShopCurrency(fetchImpl, currencyUrl, token);
+                currencyCache.set(currencyKey, currencyPromise);
+            }
+            const currency = await currencyPromise;
             const url = cursor ?? `${apiBase(store, version)}/products.json?limit=250`;
             const result = await request(fetchImpl, url, token);
             if (!result.ok)
@@ -142,18 +222,53 @@ export function shopifyConnector(options = {}) {
             const link = result.value.response.headers.get("link") ?? "";
             const next = link.match(/<([^>]+)>;\s*rel="next"/)?.[1] ?? null;
             return Ok({
-                items: result.value.data.products.map((product) => ({
-                    externalId: String(product.id),
-                    slug: product.handle ?? String(product.id),
-                    title: product.title,
-                    ...(product.body_html ? { description: product.body_html } : {}),
-                    variants: (product.variants ?? []).map((variant) => ({
-                        externalId: String(variant.id),
-                        ...(variant.sku ? { sku: variant.sku } : {}),
-                        ...(variant.barcode ? { barcode: variant.barcode } : {}),
-                        metadata: { price: parseMoney(variant.price) },
-                    })),
-                })),
+                items: result.value.data.products.map((product) => {
+                    const options = product.options?.map((option, index) => ({
+                        name: option.name,
+                        displayName: option.name,
+                        ...(option.position != null ? { sortOrder: option.position } : { sortOrder: index }),
+                        values: (option.values ?? []).map((value, valueIndex) => ({ value, displayValue: value, sortOrder: valueIndex })),
+                    }));
+                    const variants = (product.variants ?? []).map((variant) => {
+                        const selectors = [variant.option1, variant.option2, variant.option3];
+                        const optionValues = Object.fromEntries((product.options ?? []).slice(0, 3).flatMap((option, index) => {
+                            const value = selectors[index];
+                            return value != null && value !== "" ? [[option.name, value]] : [];
+                        }));
+                        const prices = pricesForVariant(variant, currency);
+                        return {
+                            externalId: String(variant.id),
+                            ...(variant.sku ? { sku: variant.sku } : {}),
+                            ...(variant.barcode ? { barcode: variant.barcode } : {}),
+                            ...(Object.keys(optionValues).length > 0 ? { optionValues } : {}),
+                            ...(prices ? { prices } : {}),
+                        };
+                    });
+                    const category = product.product_type ? slugify(product.product_type) : "";
+                    const status = catalogStatus(product.status);
+                    return {
+                        externalId: String(product.id),
+                        slug: product.handle ?? String(product.id),
+                        title: product.title,
+                        attributes: [{ locale: "en", title: product.title, ...(product.body_html != null ? { description: product.body_html } : {}) }],
+                        variants,
+                        ...(product.images ? {
+                            images: product.images.map((image, index) => ({
+                                externalId: String(image.id),
+                                url: image.src,
+                                ...(image.alt != null ? { alt: image.alt } : {}),
+                                role: index === 0 ? "primary" : "gallery",
+                                ...(image.position != null ? { sortOrder: image.position } : {}),
+                                ...(image.variant_ids != null ? { variantExternalIds: image.variant_ids.map(String) } : {}),
+                            })),
+                        } : {}),
+                        ...(options ? { options } : {}),
+                        ...(product.tags != null ? { tags: product.tags.split(",").map((tag) => tag.trim()).filter(Boolean) } : {}),
+                        ...(product.vendor ? { brand: product.vendor } : {}),
+                        ...(category ? { categories: [category] } : {}),
+                        ...(status ? { status } : {}),
+                    };
+                }),
                 nextCursor: next,
             });
         },
@@ -169,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>>;