@porulle/adapter-shopify 0.16.0 → 0.17.0

package/README.md

@@ -22,3 +22,19 @@ Operators can recover without disconnecting the store:
 Use `shopifyReauthorizeUrl(options, params)` to build the authorize URL outside
 the push error path, or `shopifyPushCatalogEnabled(store)` to check scope
 coverage before enqueueing work.
+
+## Product images
+
+`pushCatalog` writes `item.images` to the product's images through the Admin
+REST API (`/products/{id}/images.json`). Roles `primary`, `gallery` and
+`thumbnail` are written as images; `video` and `document` fail the item with
+`SHOPIFY_IMAGE_ROLE_UNSUPPORTED`. The `primary` image is written first and
+takes position 1, the rest follow `sortOrder`; `alt` and `variantExternalIds`
+map to the image's `alt` and `variant_ids`.
+
+Each item outcome carries `images[]` with the Shopify image id as
+`externalId`. Persist it and send it back as `image.externalId` on the next
+push so the adapter updates that image in place. Without an id the adapter
+falls back to matching the uploaded file name against the CDN path Shopify
+keeps (`boot.jpg` matches `boot.jpg` and `boot_a1b2c3.jpg`); a file name that
+matches nothing creates a new image. Dry runs do not touch images.

package/dist/push-catalog.js

@@ -13,6 +13,7 @@ export const SHOPIFY_NATIVE_VARIANT_FIELDS = new Set([
     "sku",
     "barcode",
 ]);
+const SHOPIFY_IMAGE_ROLES = new Set(["primary", "gallery", "thumbnail"]);
 export function shopifyGrantedScopes(store) {
     const raw = store.credentials.grantedScopes;
     if (Array.isArray(raw)) {
@@ -204,7 +205,7 @@ async function pushRequest(deps, url, token, init) {
         };
     }
 }
-async function loadProductSnapshot(deps, store, token, externalId, variantIds) {
+async function loadProductSnapshot(deps, store, token, externalId, variantIds, withImages) {
     const base = deps.apiBase(store);
     const productResult = await pushRequest(deps, `${base}/products/${encodeURIComponent(externalId)}.json`, token);
     if (!productResult.ok)
@@ -219,12 +220,113 @@ async function loadProductSnapshot(deps, store, token, externalId, variantIds) {
             return variantResult;
         variantMetafields.set(variantId, variantResult.data.metafields ?? []);
     }
+    let images = [];
+    if (withImages) {
+        const imagesResult = await pushRequest(deps, `${base}/products/${encodeURIComponent(externalId)}/images.json`, token);
+        if (!imagesResult.ok)
+            return imagesResult;
+        images = imagesResult.data.images ?? [];
+    }
     return Ok({
         product: productResult.data.product,
         metafields: metafieldsResult.data.metafields ?? [],
         variantMetafields,
+        images,
     });
 }
+function shopifyId(externalId) {
+    return /^\d+$/.test(externalId) ? Number(externalId) : externalId;
+}
+function imageFileName(url) {
+    try {
+        const path = new URL(url).pathname;
+        const name = path.slice(path.lastIndexOf("/") + 1).toLowerCase();
+        return name.length > 0 ? name : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function imageFileStem(name) {
+    const dot = name.lastIndexOf(".");
+    return dot > 0 ? name.slice(0, dot) : name;
+}
+// Shopify keeps the uploaded file name in the CDN path (suffixing `_<hash>` on a
+// collision) but never echoes the original source URL, so a re-push without a
+// recorded image id can only recognise its own image by that file name.
+function matchExistingImage(image, existing) {
+    const externalId = image.externalId?.trim();
+    if (externalId)
+        return existing.find((candidate) => String(candidate.id) === externalId);
+    const name = imageFileName(image.url);
+    if (name === undefined)
+        return undefined;
+    const stem = imageFileStem(name);
+    return existing.find((candidate) => {
+        const candidateName = candidate.src ? imageFileName(candidate.src) : undefined;
+        if (candidateName === undefined)
+            return false;
+        const candidateStem = imageFileStem(candidateName);
+        return candidateName === name || candidateStem === stem || candidateStem.startsWith(`${stem}_`);
+    });
+}
+function orderImages(images) {
+    const rank = (image) => (image.role === "primary" ? 0 : 1);
+    return images
+        .map((image, index) => ({ image, index }))
+        .sort((left, right) => rank(left.image) - rank(right.image)
+        || (left.image.sortOrder ?? left.index) - (right.image.sortOrder ?? right.index)
+        || left.index - right.index)
+        .map((entry) => entry.image);
+}
+async function writeImages(deps, store, token, externalId, images, existing) {
+    const outcomes = [];
+    const base = `${deps.apiBase(store)}/products/${encodeURIComponent(externalId)}/images`;
+    const claimed = new Set();
+    for (const [index, image] of orderImages(images).entries()) {
+        if (!SHOPIFY_IMAGE_ROLES.has(image.role)) {
+            const error = {
+                code: "SHOPIFY_IMAGE_ROLE_UNSUPPORTED",
+                message: `Shopify product images cannot carry the "${image.role}" role.`,
+                retriable: false,
+            };
+            outcomes.push({ url: image.url, role: image.role, ok: false, error });
+            return { outcomes, error };
+        }
+        const match = matchExistingImage(image, existing.filter((candidate) => !claimed.has(String(candidate.id))));
+        const payload = { position: index + 1 };
+        if (image.alt !== undefined)
+            payload.alt = image.alt;
+        if (image.variantExternalIds && image.variantExternalIds.length > 0) {
+            payload.variant_ids = image.variantExternalIds.map(shopifyId);
+        }
+        const result = match
+            ? await pushRequest(deps, `${base}/${encodeURIComponent(String(match.id))}.json`, token, {
+                method: "PUT",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify({ image: { id: match.id, ...payload } }),
+            })
+            : await pushRequest(deps, `${base}.json`, token, {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify({ image: { src: image.url, ...payload } }),
+            });
+        if (!result.ok) {
+            outcomes.push({ url: image.url, role: image.role, ok: false, error: result.error });
+            return { outcomes, error: result.error };
+        }
+        const written = result.data.image ?? match;
+        if (written)
+            claimed.add(String(written.id));
+        outcomes.push({
+            url: image.url,
+            role: image.role,
+            ok: true,
+            ...(written ? { externalId: String(written.id) } : {}),
+        });
+    }
+    return { outcomes };
+}
 async function writeNativeProduct(deps, store, token, externalId, fields, tagValues, existingTags) {
     const product = { id: externalId };
     for (const field of fields) {
@@ -302,21 +404,11 @@ async function pushCatalogItem(deps, store, token, item, dryRun) {
         .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 images = item.images ?? [];
     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);
+    const snapshot = await loadProductSnapshot(deps, store, token, item.externalId, variantIds, images.length > 0);
     if (!snapshot.ok) {
         return { externalId: item.externalId, ok: false, error: snapshot.error };
     }
@@ -378,11 +470,20 @@ async function pushCatalogItem(deps, store, token, item, dryRun) {
             return { externalId: item.externalId, ok: false, error: variantResult.error };
         }
     }
+    let imageOutcomes;
+    if (images.length > 0) {
+        const imageResult = await writeImages(deps, store, token, item.externalId, images, snapshot.value.images);
+        imageOutcomes = imageResult.outcomes;
+        if (imageResult.error) {
+            return { externalId: item.externalId, ok: false, error: imageResult.error, images: imageOutcomes };
+        }
+    }
     return {
         externalId: item.externalId,
         ok: true,
         ...(nativeResult.data.product.updated_at ? { remoteUpdatedAt: nativeResult.data.product.updated_at } : {}),
         ...(previousFields.length > 0 ? { previousFields } : {}),
+        ...(imageOutcomes ? { images: imageOutcomes } : {}),
     };
 }
 export async function pushCatalog(deps, store, items, opts) {