@porulle/adapter-woocommerce 0.11.0 → 0.13.0

package/dist/index.js

@@ -1,5 +1,71 @@
 import { defineChannelConnector, Err, Ok } from "@porulle/core";
 import { createHmac, timingSafeEqual } from "node:crypto";
+const PORULLE_META_PREFIX = "porulle_";
+const WOO_BATCH_LIMIT = 100;
+const catalogRequestOptions = { retryableClientErrors: true };
+const wooProductNativeFields = new Set([
+    "name",
+    "slug",
+    "type",
+    "status",
+    "featured",
+    "catalog_visibility",
+    "description",
+    "short_description",
+    "sku",
+    "regular_price",
+    "sale_price",
+    "date_on_sale_from",
+    "date_on_sale_to",
+    "virtual",
+    "downloadable",
+    "downloads",
+    "download_limit",
+    "download_expiry",
+    "external_url",
+    "button_text",
+    "tax_status",
+    "tax_class",
+    "manage_stock",
+    "stock_quantity",
+    "backorders",
+    "sold_individually",
+    "weight",
+    "dimensions",
+    "shipping_class",
+    "reviews_allowed",
+    "upsell_ids",
+    "cross_sell_ids",
+    "parent_id",
+    "purchase_note",
+    "menu_order",
+    "images",
+]);
+const wooVariationNativeFields = new Set([
+    "description",
+    "sku",
+    "regular_price",
+    "sale_price",
+    "date_on_sale_from",
+    "date_on_sale_to",
+    "status",
+    "virtual",
+    "downloadable",
+    "downloads",
+    "download_limit",
+    "download_expiry",
+    "tax_status",
+    "tax_class",
+    "manage_stock",
+    "stock_quantity",
+    "backorders",
+    "weight",
+    "dimensions",
+    "shipping_class",
+    "shipping_class_id",
+    "image",
+    "menu_order",
+]);
 const zeroDecimalCurrencies = new Set([
     "BIF",
     "CLP",
@@ -108,17 +174,380 @@ function mergeProductVariations(references, details) {
     });
     return [...merged, ...details.filter((variation) => !referencedIds.has(String(variation.id)))];
 }
-async function request(fetchImpl, url, init) {
+function isRetriableStatus(status, options) {
+    return status !== undefined && (status >= 500 || (options?.retryableClientErrors === true && (status === 408 || status === 429)));
+}
+async function request(fetchImpl, url, init, options) {
     try {
         const response = await fetchImpl(url, { ...init, headers: { accept: "application/json", ...(init?.headers ?? {}) } });
         if (!response.ok)
-            return Err({ code: "WOO_API_FAILED", message: `WooCommerce request failed (${response.status}) for ${url}.`, retriable: response.status >= 500 });
+            return Err({ code: "WOO_API_FAILED", message: `WooCommerce request failed (${response.status}) for ${url}.`, retriable: isRetriableStatus(response.status, options) });
         return Ok({ data: await response.json(), response });
     }
     catch (error) {
         return Err({ code: "WOO_API_FAILED", message: error instanceof Error ? error.message : "WooCommerce request failed.", retriable: true });
     }
 }
+function connectorError(error) {
+    return {
+        code: error.code,
+        message: error.message,
+        ...(error.retriable !== undefined ? { retriable: error.retriable } : {}),
+    };
+}
+function batchErrorMessage(error) {
+    const record = asRecord(error);
+    return typeof record?.message === "string" && record.message.trim() !== ""
+        ? record.message
+        : typeof error === "string" && error.trim() !== ""
+            ? error
+            : "WooCommerce batch update failed.";
+}
+function batchErrorStatus(error) {
+    const record = asRecord(error);
+    const data = asRecord(record?.data);
+    return typeof data?.status === "number" ? data.status : undefined;
+}
+function batchItemError(error) {
+    return {
+        code: "WOO_API_FAILED",
+        message: batchErrorMessage(error),
+        retriable: isRetriableStatus(batchErrorStatus(error), { retryableClientErrors: true }),
+    };
+}
+function catalogPushError(code, message) {
+    return Err({ code, message, retriable: false });
+}
+function remoteKey(field) {
+    if (typeof field.remoteKey !== "string" || field.remoteKey.trim() === "") {
+        return catalogPushError("WOO_REMOTE_KEY_REQUIRED", `WooCommerce remoteKey is required for catalog field "${field.fieldPath}".`);
+    }
+    return Ok(field.remoteKey.trim());
+}
+function porulleMetaKey(key) {
+    const normalized = key.trim();
+    return normalized.startsWith(PORULLE_META_PREFIX) ? normalized : `${PORULLE_META_PREFIX}${normalized}`;
+}
+function tagValues(value) {
+    const values = Array.isArray(value) ? value : [value];
+    return values.flatMap((entry) => {
+        if (typeof entry === "string" && entry.trim() !== "")
+            return [entry.trim()];
+        if (typeof entry === "number" && Number.isFinite(entry))
+            return [String(entry)];
+        const object = asRecord(entry);
+        return typeof object?.name === "string" && object.name.trim() !== "" ? [object.name.trim()] : [];
+    });
+}
+function filterableTerms(value) {
+    const values = Array.isArray(value) ? value : [value];
+    return [...new Set(values.flatMap((entry) => {
+            if (typeof entry === "string" && entry.trim() !== "")
+                return [entry.trim()];
+            if (typeof entry === "number" && Number.isFinite(entry))
+                return [String(entry)];
+            return [];
+        }))];
+}
+function addNativeField(body, locales, field, key) {
+    const currentLocale = locales.get(key);
+    if (!Object.prototype.hasOwnProperty.call(body, key) || (field.locale === "en" && currentLocale !== "en")) {
+        body[key] = field.value;
+        locales.set(key, field.locale);
+    }
+}
+function addMetaField(metaData, locales, field, key) {
+    const currentLocale = locales.get(key);
+    const existingIndex = metaData.findIndex((entry) => entry.key === key);
+    if (existingIndex === -1 || (field.locale === "en" && currentLocale !== "en")) {
+        const entry = { key, value: field.value };
+        if (existingIndex === -1)
+            metaData.push(entry);
+        else
+            metaData[existingIndex] = entry;
+        locales.set(key, field.locale);
+    }
+}
+function appendCatalogFields(fields, nativeFields, body, filterableFields, metaData, tags) {
+    const locales = new Map();
+    const metaLocales = new Map();
+    let hasTagField = false;
+    for (const field of fields) {
+        if (field.intent === "filterable") {
+            const key = remoteKey(field);
+            if (!key.ok)
+                return key;
+            filterableFields.push(field);
+            continue;
+        }
+        if (field.intent === "tag") {
+            hasTagField = true;
+            for (const tag of tagValues(field.value))
+                tags.add(tag);
+            continue;
+        }
+        const key = remoteKey(field);
+        if (!key.ok)
+            return key;
+        if (nativeFields.has(key.value)) {
+            addNativeField(body, locales, field, key.value);
+        }
+        else {
+            addMetaField(metaData, metaLocales, field, porulleMetaKey(key.value));
+        }
+    }
+    return Ok({ hasTagField });
+}
+function wooImages(images) {
+    return images.map((image, index) => ({
+        ...(image.externalId?.trim() ? { id: batchId(image.externalId.trim()) } : { src: image.url }),
+        ...(image.alt !== undefined ? { alt: image.alt } : {}),
+        position: image.sortOrder ?? index,
+    }));
+}
+function mergeWooImages(current, incoming) {
+    const incomingById = new Map();
+    for (const image of incoming) {
+        if (typeof image.id === "number" || typeof image.id === "string")
+            incomingById.set(String(image.id), image);
+    }
+    const currentIds = new Set(current.map((image) => String(image.id)));
+    const merged = current.map((image, index) => {
+        const replacement = incomingById.get(String(image.id));
+        return replacement ?? {
+            id: image.id,
+            ...(image.alt !== undefined ? { alt: image.alt } : {}),
+            position: image.position ?? index,
+        };
+    });
+    const appendedIds = new Set();
+    for (const image of incoming) {
+        if (typeof image.id === "number" || typeof image.id === "string") {
+            const id = String(image.id);
+            if (currentIds.has(id) || appendedIds.has(id))
+                continue;
+            appendedIds.add(id);
+        }
+        merged.push(image);
+    }
+    return merged;
+}
+function batchId(externalId) {
+    return /^\d+$/.test(externalId) ? Number(externalId) : externalId;
+}
+function buildCatalogPlan(item) {
+    const productBody = {};
+    const productFilterableFields = [];
+    const productMetaData = [];
+    const productTags = new Set();
+    const productFields = appendCatalogFields(item.fields, wooProductNativeFields, productBody, productFilterableFields, productMetaData, productTags);
+    if (!productFields.ok)
+        return productFields;
+    if (productMetaData.length > 0)
+        productBody.meta_data = productMetaData;
+    if (productFields.value.hasTagField)
+        productBody.tags = [...productTags].map((name) => ({ name }));
+    if (item.images !== undefined)
+        productBody.images = wooImages(item.images);
+    const variants = [];
+    for (const variant of item.variants ?? []) {
+        const variantBody = {};
+        const filterableFields = [];
+        const metaData = [];
+        const tags = new Set();
+        const variantFields = appendCatalogFields(variant.fields, wooVariationNativeFields, variantBody, filterableFields, metaData, tags);
+        if (!variantFields.ok)
+            return variantFields;
+        if (filterableFields.length > 0) {
+            return catalogPushError("WOO_VARIANT_FILTERABLE_UNSUPPORTED", `WooCommerce filterable fields must be assigned on product "${item.externalId}", not variation "${variant.externalId}".`);
+        }
+        if (variantFields.value.hasTagField) {
+            return catalogPushError("WOO_VARIANT_TAG_UNSUPPORTED", `WooCommerce tags must be assigned on product "${item.externalId}", not variation "${variant.externalId}".`);
+        }
+        if (metaData.length > 0)
+            variantBody.meta_data = metaData;
+        variants.push({ variant, body: variantBody });
+    }
+    return Ok({ productBody, filterableFields: productFilterableFields, variants });
+}
+function queryUrl(storeDomain, path, key, secret, params) {
+    const url = new URL(buildWooUrl(storeDomain, path, key, secret, 1));
+    for (const [name, value] of Object.entries(params))
+        url.searchParams.set(name, value);
+    return url.toString();
+}
+function taxonomyParts(remoteName) {
+    const withoutPrefix = remoteName.trim().toLowerCase().replace(/^pa[_-]/, "");
+    const base = withoutPrefix.replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+    return {
+        base,
+        taxonomy: `pa_${base}`,
+        name: withoutPrefix.replace(/[-_]+/g, " ").trim(),
+    };
+}
+async function ensureGlobalAttribute(fetchImpl, store, auth, remoteName) {
+    const parts = taxonomyParts(remoteName);
+    const existing = await request(fetchImpl, queryUrl(store.storeDomain, "/wp-json/wc/v3/products/attributes", auth.key, auth.secret, { search: parts.name }), undefined, catalogRequestOptions);
+    if (!existing.ok)
+        return Err(connectorError(existing.error));
+    const found = existing.value.data.find((attribute) => {
+        const slug = attribute.slug?.toLowerCase();
+        return slug === parts.taxonomy || slug === parts.base || attribute.name.toLowerCase() === parts.name;
+    });
+    if (found)
+        return Ok(found);
+    const created = await request(fetchImpl, buildWooUrl(store.storeDomain, "/wp-json/wc/v3/products/attributes", auth.key, auth.secret, 1), {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ name: parts.name, slug: parts.base }),
+    }, catalogRequestOptions);
+    return created.ok ? Ok(created.value.data) : Err(connectorError(created.error));
+}
+async function ensureTerm(fetchImpl, store, auth, attributeId, termName) {
+    const path = `/wp-json/wc/v3/products/attributes/${encodeURIComponent(String(attributeId))}/terms`;
+    const existing = await request(fetchImpl, queryUrl(store.storeDomain, path, auth.key, auth.secret, { search: termName }), undefined, catalogRequestOptions);
+    if (!existing.ok)
+        return Err(connectorError(existing.error));
+    const found = existing.value.data.find((term) => term.name.toLowerCase() === termName.toLowerCase());
+    if (found)
+        return Ok(found);
+    const created = await request(fetchImpl, buildWooUrl(store.storeDomain, path, auth.key, auth.secret, 1), {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ name: termName }),
+    }, catalogRequestOptions);
+    return created.ok ? Ok(created.value.data) : Err(connectorError(created.error));
+}
+async function mergedFilterableAttributes(fetchImpl, store, auth, productId, fields, attributeCache, termCache) {
+    const termsByRemoteName = new Map();
+    for (const field of fields) {
+        const key = remoteKey(field);
+        if (!key.ok)
+            return key;
+        const terms = termsByRemoteName.get(key.value) ?? new Set();
+        for (const term of filterableTerms(field.value))
+            terms.add(term);
+        termsByRemoteName.set(key.value, terms);
+    }
+    const assignments = [];
+    for (const [remoteName, termNames] of termsByRemoteName) {
+        const parts = taxonomyParts(remoteName);
+        const attributeKey = `${store.storeDomain}|${parts.taxonomy}`;
+        let attributePromise = attributeCache.get(attributeKey);
+        if (!attributePromise) {
+            attributePromise = ensureGlobalAttribute(fetchImpl, store, auth, remoteName);
+            attributeCache.set(attributeKey, attributePromise);
+        }
+        const attribute = await attributePromise;
+        if (!attribute.ok) {
+            attributeCache.delete(attributeKey);
+            return attribute;
+        }
+        const terms = [];
+        for (const termName of termNames) {
+            const termKey = `${store.storeDomain}|${String(attribute.value.id)}|${termName.toLowerCase()}`;
+            let termPromise = termCache.get(termKey);
+            if (!termPromise) {
+                termPromise = ensureTerm(fetchImpl, store, auth, attribute.value.id, termName);
+                termCache.set(termKey, termPromise);
+            }
+            const term = await termPromise;
+            if (!term.ok) {
+                termCache.delete(termKey);
+                return term;
+            }
+            terms.push(term.value.name);
+        }
+        assignments.push({ attribute: attribute.value, terms });
+    }
+    const current = await request(fetchImpl, buildWooUrl(store.storeDomain, `/wp-json/wc/v3/products/${encodeURIComponent(productId)}`, auth.key, auth.secret, 1), undefined, catalogRequestOptions);
+    if (!current.ok)
+        return Err(connectorError(current.error));
+    const merged = (current.value.data.attributes ?? []).map((attribute) => ({
+        ...attribute,
+        ...(attribute.options ? { options: [...attribute.options] } : {}),
+    }));
+    for (const assignment of assignments) {
+        const existing = merged.find((attribute) => attribute.id !== undefined && String(attribute.id) === String(assignment.attribute.id));
+        if (existing) {
+            existing.visible = existing.visible ?? true;
+            existing.variation = existing.variation ?? false;
+            existing.options = [...new Set([...(existing.options ?? []), ...assignment.terms])];
+        }
+        else {
+            merged.push({
+                id: assignment.attribute.id,
+                name: assignment.attribute.name,
+                visible: true,
+                variation: false,
+                options: assignment.terms,
+            });
+        }
+    }
+    return Ok(merged);
+}
+async function updateProduct(fetchImpl, store, auth, item, plan, attributeCache, termCache) {
+    const body = { ...plan.productBody };
+    if (Array.isArray(body.images)) {
+        const current = await request(fetchImpl, buildWooUrl(store.storeDomain, `/wp-json/wc/v3/products/${encodeURIComponent(item.externalId)}`, auth.key, auth.secret, 1), undefined, catalogRequestOptions);
+        if (!current.ok)
+            return Err(connectorError(current.error));
+        body.images = mergeWooImages(current.value.data.images ?? [], body.images);
+    }
+    if (plan.filterableFields.length > 0) {
+        const attributes = await mergedFilterableAttributes(fetchImpl, store, auth, item.externalId, plan.filterableFields, attributeCache, termCache);
+        if (!attributes.ok)
+            return attributes;
+        body.attributes = attributes.value;
+    }
+    if (Object.keys(body).length === 0)
+        return Ok(undefined);
+    const result = await request(fetchImpl, buildWooUrl(store.storeDomain, `/wp-json/wc/v3/products/${encodeURIComponent(item.externalId)}`, auth.key, auth.secret, 1), {
+        method: "PUT",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(body),
+    }, catalogRequestOptions);
+    return result.ok ? Ok(undefined) : Err(connectorError(result.error));
+}
+async function updateVariant(fetchImpl, store, auth, productId, variant, body) {
+    if (Object.keys(body).length === 0)
+        return Ok(undefined);
+    const result = await request(fetchImpl, buildWooUrl(store.storeDomain, `/wp-json/wc/v3/products/${encodeURIComponent(productId)}/variations/${encodeURIComponent(variant.externalId)}`, auth.key, auth.secret, 1), {
+        method: "PUT",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(body),
+    }, catalogRequestOptions);
+    return result.ok ? Ok(undefined) : Err(connectorError(result.error));
+}
+async function pushCatalogItem(fetchImpl, store, auth, item, plan, attributeCache, termCache) {
+    const product = await updateProduct(fetchImpl, store, auth, item, plan, attributeCache, termCache);
+    if (!product.ok)
+        return product;
+    for (const variant of plan.variants) {
+        const updated = await updateVariant(fetchImpl, store, auth, item.externalId, variant.variant, variant.body);
+        if (!updated.ok)
+            return updated;
+    }
+    return Ok(undefined);
+}
+async function pushCatalogBatch(fetchImpl, store, auth, entries) {
+    const update = entries.map(({ item, plan }) => ({ id: batchId(item.externalId), ...plan.productBody }));
+    const result = await request(fetchImpl, buildWooUrl(store.storeDomain, "/wp-json/wc/v3/products/batch", auth.key, auth.secret, 1), {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ update }),
+    }, { retryableClientErrors: true });
+    if (!result.ok)
+        return Err(connectorError(result.error));
+    const responseById = new Map((result.value.data.update ?? []).map((entry) => [String(entry.id), entry]));
+    return Ok(entries.map((entry) => {
+        const responseEntry = responseById.get(String(batchId(entry.item.externalId)));
+        if (!responseEntry) {
+            return { index: entry.index, error: { code: "WOO_API_FAILED", message: "WooCommerce batch response omitted this product.", retriable: false } };
+        }
+        return responseEntry.error === undefined ? { index: entry.index } : { index: entry.index, error: batchItemError(responseEntry.error) };
+    }));
+}
 function wooStatus(status) {
     if (status === "completed")
         return { status: "fulfilled" };
@@ -157,9 +586,11 @@ function storeUrl(domain) {
 export function wooConnector(options = {}) {
     const fetchImpl = options.fetchImpl ?? fetch;
     const currencyCache = new Map();
+    const attributeCache = new Map();
+    const termCache = new Map();
     return defineChannelConnector({
         providerId: "woocommerce",
-        capabilities: { importCatalog: true, importInventory: true, pushOrder: true, receiveWebhooks: true },
+        capabilities: { importCatalog: true, importInventory: true, pushOrder: true, pushCatalog: true, receiveWebhooks: true },
         buildAuthUrl(params) {
             const store = storeUrl(params.storeDomain);
             if (!store)
@@ -301,6 +732,60 @@ export function wooConnector(options = {}) {
             const id = String(result.value.data.id);
             return Ok({ remoteOrderId: id, remoteUrl: `${store.storeDomain.replace(/\/$/, "")}/wp-admin/post.php?post=${id}&action=edit` });
         },
+        async pushCatalog(store, items, opts) {
+            if (store.provider !== "woocommerce") {
+                return Err({ code: "WOO_INVALID_STORE_PROVIDER", message: "WooCommerce catalog pushes require a WooCommerce store.", retriable: false });
+            }
+            const auth = credentials(store);
+            if (!auth)
+                return Err({ code: "WOO_CREDENTIALS_REQUIRED", message: "WooCommerce consumerKey and consumerSecret are required.", retriable: false });
+            const outcomes = items.map((item) => ({ externalId: item.externalId, ok: true }));
+            const planned = [];
+            for (const [index, item] of items.entries()) {
+                const plan = buildCatalogPlan(item);
+                if (!plan.ok) {
+                    outcomes[index] = { externalId: item.externalId, ok: false, error: plan.error };
+                }
+                else {
+                    planned.push({ index, item, plan: plan.value });
+                }
+            }
+            if (opts?.dryRun)
+                return Ok({ outcomes });
+            const batchable = planned.filter(({ plan }) => plan.filterableFields.length === 0 && plan.variants.length === 0 && !Object.prototype.hasOwnProperty.call(plan.productBody, "images") && Object.keys(plan.productBody).length > 0);
+            const batched = new Set();
+            if (batchable.length > 1) {
+                for (let offset = 0; offset < batchable.length; offset += WOO_BATCH_LIMIT) {
+                    const chunk = batchable.slice(offset, offset + WOO_BATCH_LIMIT);
+                    const batchResult = await pushCatalogBatch(fetchImpl, store, auth, chunk);
+                    for (const entry of chunk) {
+                        batched.add(entry.index);
+                    }
+                    if (!batchResult.ok) {
+                        for (const entry of chunk)
+                            outcomes[entry.index] = { externalId: entry.item.externalId, ok: false, error: batchResult.error };
+                    }
+                    else {
+                        const entryByIndex = new Map(chunk.map((entry) => [entry.index, entry.item]));
+                        for (const entry of batchResult.value) {
+                            if (entry.error) {
+                                const item = entryByIndex.get(entry.index);
+                                if (item)
+                                    outcomes[entry.index] = { externalId: item.externalId, ok: false, error: entry.error };
+                            }
+                        }
+                    }
+                }
+            }
+            for (const entry of planned) {
+                if (batched.has(entry.index))
+                    continue;
+                const pushed = await pushCatalogItem(fetchImpl, store, auth, entry.item, entry.plan, attributeCache, termCache);
+                if (!pushed.ok)
+                    outcomes[entry.index] = { externalId: entry.item.externalId, ok: false, error: pushed.error };
+            }
+            return Ok({ outcomes });
+        },
         async fetchOrderStatus(store, remoteId) {
             const auth = credentials(store);
             if (!auth)