@porulle/adapter-woocommerce 0.73.2 → 0.74.0

package/dist/index.js

@@ -1,815 +1,170 @@
-import { defineChannelConnector, Err, Ok, toMinorUnits } 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",
-]);
-function buildWooUrl(base, path, key, secret, page, cursor) {
-    const url = new URL(path, base.replace(/\/$/, "/"));
-    url.searchParams.set("consumer_key", key);
-    url.searchParams.set("consumer_secret", secret);
-    url.searchParams.set("per_page", "100");
-    url.searchParams.set("page", String(page));
-    if (cursor)
-        url.searchParams.set("modified_after", cursor);
-    return url.toString();
-}
-function normalizeCurrency(value) {
-    if (typeof value !== "string" || value.trim() === "")
-        return undefined;
-    return value.trim().toUpperCase();
-}
-function pricesForVariation(variation, currency) {
-    if (!currency)
-        return undefined;
-    const amount = toMinorUnits(variation.price, currency);
-    return amount === undefined ? undefined : [{ currency, amount }];
-}
-function catalogStatus(value) {
-    if (value === "publish")
-        return "active";
-    if (value === "draft" || value === "private")
-        return "draft";
-    return undefined;
-}
-function asRecord(value) {
-    return typeof value === "object" && value !== null ? value : undefined;
-}
-function settingCurrency(data) {
-    if (Array.isArray(data)) {
-        for (const entry of data) {
-            const setting = asRecord(entry);
-            if (setting?.id === "woocommerce_currency")
-                return normalizeCurrency(setting.value);
-        }
-    }
-    const object = asRecord(data);
-    if (!object)
-        return undefined;
-    const direct = normalizeCurrency(object.woocommerce_currency);
-    if (direct)
-        return direct;
-    const systemStatus = asRecord(object.system_status);
-    return normalizeCurrency(systemStatus?.woocommerce_currency);
-}
-async function fetchWooCurrency(fetchImpl, url) {
-    const result = await request(fetchImpl, url);
-    return result.ok ? settingCurrency(result.value.data) : undefined;
-}
-async function fetchProductVariations(fetchImpl, storeDomain, auth, productId, modifiedAfter) {
-    const variations = [];
-    let page = 1;
-    while (true) {
-        const result = await request(fetchImpl, buildWooUrl(storeDomain, `/wp-json/wc/v3/products/${encodeURIComponent(productId)}/variations`, auth.key, auth.secret, page, modifiedAfter));
-        if (!result.ok)
-            return result;
-        variations.push(...result.value.data);
-        const totalPages = Number.parseInt(result.value.response.headers.get("x-wp-totalpages") ?? "1", 10);
-        if (!Number.isFinite(totalPages) || page >= totalPages)
-            break;
-        page += 1;
-    }
-    return Ok(variations);
-}
-function variationFromReference(reference) {
-    return typeof reference === "object" && reference !== null ? reference : { id: reference };
-}
-function mergeProductVariations(references, details) {
-    const detailById = new Map(details.map((variation) => [String(variation.id), variation]));
-    const referencedIds = new Set();
-    const merged = references.map((reference) => {
-        const fallback = variationFromReference(reference);
-        const id = String(fallback.id);
-        referencedIds.add(id);
-        return detailById.get(id) ?? fallback;
-    });
-    return [...merged, ...details.filter((variation) => !referencedIds.has(String(variation.id)))];
-}
-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: 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 } : {}),
+import { defineChannelConnector, Err, Ok } from "@porulle/core";
+import { z } from "zod";
+import { catalogItems, importPage, storeProfile } from "./catalog.js";
+import { pushCatalog, pushCaches } from "./catalog-push.js";
+import { discoverStore, normalizeStoreDomain, wooClient, wooCredentialsSchema } from "./client.js";
+import { inventoryFor, inventoryPage } from "./inventory.js";
+import { cancelOrder, orderStatus, pushOrder } from "./orders.js";
+import { decodeDelivery, orderEvents, registerWebhooks, unregisterWebhooks, verifyDelivery, webhookHealth, WOO_WEBHOOK_TOPICS } from "./webhooks.js";
+export { normalizeStoreDomain, probeStore, refusedStoreUrl, WOO_BLOCKED_BY_FIREWALL } from "./client.js";
+export { ORDER_META_KEY } from "./orders.js";
+export { WOO_WEBHOOK_TOPICS } from "./webhooks.js";
+/** What WooCommerce posts to the callback when the merchant approves: keys, and our own `user_id` back. */
+const authCallbackSchema = z.object({
+    key_id: z.union([z.number(), z.string()]).optional(),
+    user_id: z.union([z.string(), z.number()]).transform(String),
+    consumer_key: z.string(),
+    consumer_secret: z.string(),
+    key_permissions: z.string(),
+});
+const refused = (code, message) => Err({ code, message, retriable: false });
+export function wooConnector(options = {}) {
+    const transport = {
+        fetchImpl: options.fetchImpl ?? ((input, init) => fetch(input, init)),
+        userAgent: options.userAgent ?? "Porulle-WooCommerce/1.0",
+        allowPrivateHosts: options.allowPrivateHosts === true,
     };
-}
-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 }),
+    const untracked = options.untrackedStockQuantity ?? 99;
+    const caches = pushCaches();
+    const withClient = async (store, call) => {
+        const client = wooClient(store, transport);
+        return client.ok ? call(client.value) : client;
     };
-}
-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" };
-    if (status === "processing" || status === "on-hold")
-        return { status: "confirmed" };
-    if (status === "cancelled")
-        return { status: "cancelled" };
-    if (status === "failed" || status === "refunded")
-        return { status: "failed" };
-    return { status: "pending" };
-}
-function credentials(store) {
-    const key = store.credentials.consumerKey;
-    const secret = store.credentials.consumerSecret;
-    return typeof key === "string" && typeof secret === "string" && key && secret ? { key, secret } : undefined;
-}
-function validBase64Hmac(secret, body, signature) {
-    if (!signature)
-        return false;
-    const expected = createHmac("sha256", secret).update(body).digest();
-    const actual = Buffer.from(signature, "base64");
-    return actual.length === expected.length && timingSafeEqual(actual, expected);
-}
-function oauthError(code, message) {
-    return Err({ code, message, retriable: false });
-}
-function storeUrl(domain) {
-    try {
-        const url = new URL(/^https?:\/\//i.test(domain) ? domain : `https://${domain}`);
-        return url.protocol === "http:" || url.protocol === "https:" ? url : undefined;
-    }
-    catch {
-        return undefined;
-    }
-}
-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, pushCatalog: true, receiveWebhooks: true },
+        webhookTopics: WOO_WEBHOOK_TOPICS,
+        normalizeStoreDomain: (input) => normalizeStoreDomain(input, { allowPrivateHosts: transport.allowPrivateHosts }),
         buildAuthUrl(params) {
-            const store = storeUrl(params.storeDomain);
+            const store = normalizeStoreDomain(params.storeDomain, { allowPrivateHosts: transport.allowPrivateHosts });
             if (!store)
-                return oauthError("WOO_INVALID_STORE_DOMAIN", "WooCommerce storeDomain must be an HTTP(S) URL.");
+                return refused("WOO_INVALID_STORE_DOMAIN", "A WooCommerce store is named by its https address.");
             let callback;
             try {
                 callback = new URL(params.callbackUri);
             }
             catch {
-                return oauthError("WOO_INVALID_CALLBACK_URL", "WooCommerce callbackUri must be an HTTPS URL.");
+                return refused("WOO_INVALID_CALLBACK_URL", "WooCommerce needs an https callback address.");
             }
             if (callback.protocol !== "https:")
-                return oauthError("WOO_INVALID_CALLBACK_URL", "WooCommerce callbackUri must be an HTTPS URL.");
+                return refused("WOO_INVALID_CALLBACK_URL", "WooCommerce needs an https callback address.");
             callback.searchParams.set("state", params.state);
             const returnUrl = new URL(params.callbackUri);
             returnUrl.searchParams.set("state", params.state);
             returnUrl.searchParams.set("return", "1");
-            const url = new URL("/wc-auth/v1/authorize", store.origin);
-            url.searchParams.set("app_name", "Porulle");
+            const url = new URL(`${store}/wc-auth/v1/authorize`);
+            url.searchParams.set("app_name", options.appName ?? "Runvae");
             url.searchParams.set("scope", "read_write");
-            url.searchParams.set("user_id", "porulle");
+            // Echoed back in the posted keys: the keys are bound to the connection this state started.
+            url.searchParams.set("user_id", params.state);
             url.searchParams.set("return_url", returnUrl.toString());
             url.searchParams.set("callback_url", callback.toString());
             return Ok(url.toString());
         },
+        /**
+         * The keys WooCommerce posts. They carry no store address and no signature, so they are accepted
+         * only for the connection they were issued for (`user_id` is our state), only read-write, only
+         * in WooCommerce's key format. Any refusal answers non-200, and WooCommerce deletes the key.
+         */
         async completeAuth(request, ctx) {
             if (request.method !== "POST")
-                return oauthError("WOO_AUTH_METHOD_REQUIRED", "WooCommerce auth credentials must be posted.");
-            const store = storeUrl(ctx.storeDomain);
-            if (!store)
-                return oauthError("WOO_INVALID_STORE_DOMAIN", "WooCommerce storeDomain must be an HTTP(S) URL.");
+                return refused("WOO_AUTH_METHOD_REQUIRED", "WooCommerce posts the keys.");
+            let raw;
             try {
-                const body = await request.json();
-                const consumerKey = body.consumer_key;
-                const consumerSecret = body.consumer_secret;
-                if (typeof consumerKey !== "string" || !consumerKey || typeof consumerSecret !== "string" || !consumerSecret) {
-                    return oauthError("WOO_AUTH_CREDENTIALS_INVALID", "WooCommerce auth response must include consumer_key and consumer_secret.");
-                }
-                return Ok({ credentials: { consumerKey, consumerSecret }, storeDomain: ctx.storeDomain });
+                raw = await request.json();
             }
             catch {
-                return oauthError("WOO_AUTH_RESPONSE_INVALID", "WooCommerce auth response must be valid JSON.");
-            }
+                return refused("WOO_AUTH_RESPONSE_INVALID", "WooCommerce's callback body was not JSON.");
+            }
+            const body = authCallbackSchema.safeParse(raw);
+            if (!body.success)
+                return refused("WOO_AUTH_RESPONSE_INVALID", "WooCommerce's callback did not carry keys.");
+            if (body.data.user_id !== ctx.state)
+                return refused("WOO_AUTH_STATE_MISMATCH", "The keys were issued for another connection.");
+            if (body.data.key_permissions !== "read_write")
+                return refused("WOO_AUTH_READ_ONLY", "The store granted read-only access; we need read and write to send orders.");
+            const credentials = wooCredentialsSchema.safeParse({ consumerKey: body.data.consumer_key, consumerSecret: body.data.consumer_secret });
+            if (!credentials.success)
+                return refused("WOO_AUTH_CREDENTIALS_INVALID", "The keys WooCommerce sent are not in its key format.");
+            return Ok({ credentials: { ...credentials.data }, storeDomain: ctx.storeDomain });
+        },
+        /**
+         * Learns, once, how to call the store (where its REST API answers, how it accepts our keys, how it
+         * prices) and hands it to the plugin to persist. Forced after a rejected key: a host that began
+         * stripping the Authorization header is met in query mode; a key both modes refuse is gone.
+         */
+        async liveCredentials(store, refresh) {
+            const credentials = wooCredentialsSchema.safeParse(store.credentials);
+            if (!credentials.success)
+                return refused("WOO_CREDENTIALS_REQUIRED", "The store holds no valid WooCommerce keys; it must be reconnected.");
+            const known = credentials.data;
+            if (refresh?.force !== true && known.authMode && known.restRoute && known.currency && known.priceDecimals !== undefined)
+                return Ok(null);
+            const discovered = await discoverStore(transport, store.storeDomain, known);
+            if (!discovered.ok)
+                return discovered;
+            return Ok({ ...store.credentials, ...discovered.value });
+        },
+        async fetchStoreProfile(store) {
+            return withClient(store, storeProfile);
         },
         async importCatalog(store, cursor) {
-            const auth = credentials(store);
-            if (!auth)
-                return Err({ code: "WOO_CREDENTIALS_REQUIRED", message: "WooCommerce consumerKey and consumerSecret are required." });
-            const [pagePart, ...afterParts] = cursor?.split("|") ?? [];
-            const isPage = pagePart === undefined || /^\d+$/.test(pagePart);
-            const parsedPage = isPage && pagePart ? Number.parseInt(pagePart, 10) : 1;
-            const page = Number.isFinite(parsedPage) && parsedPage > 0 ? parsedPage : 1;
-            const modifiedAfter = afterParts.length > 0 ? afterParts.join("|") : (!isPage ? cursor : undefined);
-            const currencyKey = store.storeDomain.replace(/\/$/, "");
-            let currencyPromise = currencyCache.get(currencyKey);
-            if (!currencyPromise) {
-                currencyPromise = fetchWooCurrency(fetchImpl, buildWooUrl(store.storeDomain, "/wp-json/wc/v3/settings/general", auth.key, auth.secret, 1));
-                currencyCache.set(currencyKey, currencyPromise);
-            }
-            const currency = await currencyPromise;
-            const result = await request(fetchImpl, buildWooUrl(store.storeDomain, "/wp-json/wc/v3/products", auth.key, auth.secret, page, modifiedAfter));
-            if (!result.ok)
-                return result;
-            const totalPages = Number.parseInt(result.value.response.headers.get("x-wp-totalpages") ?? "1", 10);
-            const nextCursor = page < totalPages ? (modifiedAfter ? `${page + 1}|${modifiedAfter}` : String(page + 1)) : null;
-            const items = [];
-            for (const product of result.value.data) {
-                const references = product.variations ?? [];
-                const details = references.length > 0
-                    ? await fetchProductVariations(fetchImpl, store.storeDomain, auth, String(product.id), modifiedAfter)
-                    : Ok([]);
-                if (!details.ok)
-                    return details;
-                const variants = mergeProductVariations(references, details.value).map((variant) => {
-                    const optionValues = Object.fromEntries((variant.attributes ?? []).flatMap((attribute) => (attribute.option != null && attribute.option !== "" ? [[attribute.name, attribute.option]] : [])));
-                    const prices = pricesForVariation(variant, currency);
-                    return {
-                        externalId: String(variant.id),
-                        ...(variant.sku ? { sku: variant.sku } : {}),
-                        ...(Object.keys(optionValues).length > 0 ? { optionValues } : {}),
-                        ...(prices ? { prices } : {}),
-                    };
-                });
-                const options = product.attributes?.filter((attribute) => attribute.variation === true).map((attribute, index) => ({
-                    name: attribute.name,
-                    displayName: attribute.name,
-                    ...(attribute.position != null ? { sortOrder: attribute.position } : { sortOrder: index }),
-                    values: (attribute.options ?? []).map((value, valueIndex) => ({ value, displayValue: value, sortOrder: valueIndex })),
-                }));
-                const status = catalogStatus(product.status);
-                items.push({
-                    externalId: String(product.id),
-                    slug: product.slug ?? String(product.id),
-                    title: product.name,
-                    attributes: [{ locale: "en", title: product.name, ...(product.description != null ? { description: product.description } : {}) }],
-                    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 } : {}),
-                        })),
-                    } : {}),
-                    ...(options ? { options } : {}),
-                    ...(product.tags ? { tags: product.tags.flatMap((tag) => tag.slug ? [tag.slug] : []) } : {}),
-                    ...(product.categories ? { categories: product.categories.flatMap((category) => category.slug ? [category.slug] : []) } : {}),
-                    ...(status ? { status } : {}),
-                });
-            }
-            return Ok({ items, nextCursor });
+            return withClient(store, (client) => importPage(client, cursor));
         },
-        async fetchInventory(store, ids) {
-            const auth = credentials(store);
-            if (!auth)
-                return Err({ code: "WOO_CREDENTIALS_REQUIRED", message: "WooCommerce consumerKey and consumerSecret are required." });
-            const page = await request(fetchImpl, buildWooUrl(store.storeDomain, "/wp-json/wc/v3/products", auth.key, auth.secret, 1));
-            if (!page.ok)
-                return page;
-            const requested = ids ? new Set(ids) : undefined;
-            return Ok(page.value.data.filter((product) => !requested || requested.has(String(product.id))).map((product) => ({ externalId: String(product.id), available: product.stock_quantity ?? 0 })));
+        async fetchCatalogItems(store, externalIds) {
+            return withClient(store, (client) => catalogItems(client, externalIds));
         },
-        async pushOrder(store, slice) {
-            const auth = credentials(store);
-            if (!auth)
-                return Err({ code: "WOO_CREDENTIALS_REQUIRED", message: "WooCommerce consumerKey and consumerSecret are required.", retriable: false });
-            const url = buildWooUrl(store.storeDomain, "/wp-json/wc/v3/orders", auth.key, auth.secret, 1);
-            const [firstName, ...lastParts] = slice.customer.name.trim().split(/\s+/);
-            const source = slice.customer.shippingAddress;
-            // WooCommerce's order address spelling (REST v3 `shipping`/`billing`).
-            const address = {
-                first_name: source.firstName,
-                last_name: source.lastName,
-                address_1: source.line1,
-                ...(source.line2 ? { address_2: source.line2 } : {}),
-                city: source.city,
-                ...(source.region ? { state: source.region } : {}),
-                ...(source.postalCode ? { postcode: source.postalCode } : {}),
-                country: source.countryCode,
-                ...(source.phone ? { phone: source.phone } : {}),
-            };
-            const billing = { ...address, first_name: firstName ?? source.firstName, last_name: lastParts.join(" ") || source.lastName, email: slice.customer.email };
-            const result = await request(fetchImpl, url, {
-                method: "POST",
-                headers: { "content-type": "application/json", "idempotency-key": `porulle:${slice.orderId}` },
-                body: JSON.stringify({ set_paid: true, line_items: slice.lines.map((line) => ({ variation_id: line.externalVariantId, quantity: line.quantity, total: line.totalPrice / 100 })), billing, shipping: address }),
+        async fetchInventory(store, ids) {
+            return withClient(store, async (client) => {
+                if (ids !== undefined)
+                    return inventoryFor(client, ids, untracked);
+                const levels = [];
+                let cursor = null;
+                do {
+                    const page = await inventoryPage(client, cursor, untracked);
+                    if (!page.ok)
+                        return page;
+                    levels.push(...page.value.levels);
+                    cursor = page.value.nextCursor;
+                } while (cursor !== null);
+                return Ok(levels);
             });
-            if (!result.ok)
-                return result;
-            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 fetchInventoryPage(store, cursor) {
+            return withClient(store, (client) => inventoryPage(client, cursor, untracked));
+        },
+        async pushOrder(store, slice) {
+            return withClient(store, (client) => pushOrder(client, slice, { paymentMethodTitle: options.paymentMethodTitle ?? "Paid on Runvae", untrackedStockQuantity: untracked }));
         },
         async fetchOrderStatus(store, remoteId) {
-            const auth = credentials(store);
-            if (!auth)
-                return Err({ code: "WOO_CREDENTIALS_REQUIRED", message: "WooCommerce consumerKey and consumerSecret are required.", retriable: false });
-            const result = await request(fetchImpl, buildWooUrl(store.storeDomain, `/wp-json/wc/v3/orders/${encodeURIComponent(remoteId)}`, auth.key, auth.secret, 1));
-            return result.ok ? Ok(wooStatus(result.value.data.status)) : result;
+            return withClient(store, (client) => orderStatus(client, remoteId));
+        },
+        async cancelOrder(store, remoteId, input) {
+            return withClient(store, (client) => cancelOrder(client, remoteId, input));
+        },
+        async pushCatalog(store, items, opts) {
+            return withClient(store, (client) => pushCatalog(client, store, items, opts, caches));
         },
         async verifyWebhook(store, request) {
-            const body = await request.text();
-            if (!validBase64Hmac(store.webhookSecret ?? "", body, request.headers.get("x-wc-webhook-signature"))) {
-                return Err({ code: "INVALID_WEBHOOK_SIGNATURE", message: "Invalid WooCommerce webhook signature." });
-            }
-            try {
-                const data = JSON.parse(body);
-                const id = request.headers.get("x-wc-webhook-id");
-                const type = request.headers.get("x-wc-webhook-topic");
-                if (!id || !type)
-                    return Err({ code: "INVALID_WEBHOOK", message: "WooCommerce webhook headers are incomplete." });
-                return Ok({ id, type, data });
-            }
-            catch {
-                return Err({ code: "INVALID_WEBHOOK", message: "WooCommerce webhook body must be valid JSON." });
-            }
+            return verifyDelivery(store, request);
+        },
+        async decodeWebhook(store, event) {
+            return withClient(store, (client) => decodeDelivery(client, event, untracked));
         },
         async registerWebhooks(store, topics, callbackUrl) {
-            const auth = credentials(store);
-            if (!auth)
-                return Err({ code: "WOO_CREDENTIALS_REQUIRED", message: "WooCommerce consumerKey and consumerSecret are required." });
-            for (const topic of topics) {
-                const result = await request(fetchImpl, buildWooUrl(store.storeDomain, "/wp-json/wc/v3/webhooks", auth.key, auth.secret, 1), {
-                    method: "POST",
-                    headers: { "content-type": "application/json" },
-                    body: JSON.stringify({ name: `Porulle ${topic}`, topic, delivery_url: callbackUrl, secret: store.webhookSecret }),
-                });
-                if (!result.ok)
-                    return result;
-            }
-            return Ok({ registered: topics.length });
+            return withClient(store, (client) => registerWebhooks(client, store, topics, callbackUrl));
+        },
+        async unregisterWebhooks(store, callbackUrl) {
+            return withClient(store, (client) => unregisterWebhooks(client, callbackUrl));
+        },
+        async orderEvents(store, remoteOrderId) {
+            return withClient(store, (client) => orderEvents(client, remoteOrderId));
+        },
+        async webhookHealth(store, callbackUrl) {
+            return withClient(store, (client) => webhookHealth(client, store, WOO_WEBHOOK_TOPICS, callbackUrl));
+        },
+        async refundExecute() {
+            return refused("NOT_IMPLEMENTED", "Refunds are issued by the platform, not executed in the WooCommerce store.");
         },
-        async refundExecute() { return Err({ code: "NOT_IMPLEMENTED", message: "WooCommerce refund execution is not implemented in this slice." }); },
     });
 }