@porulle/adapter-woocommerce 0.73.2 → 0.74.0

package/dist/catalog.js

@@ -0,0 +1,195 @@
+import { Err, Ok, toMinorUnits } from "@porulle/core";
+import { z } from "zod";
+const id = z.union([z.number(), z.string()]).transform(String);
+const money = z.string().nullish();
+const image = z.object({ id, src: z.string(), alt: z.string().nullish() });
+export const wooVariationSchema = z.object({
+    id,
+    sku: z.string().nullish(),
+    price: money,
+    regular_price: money,
+    sale_price: money,
+    status: z.string().nullish(),
+    attributes: z.array(z.object({ name: z.string(), option: z.string().nullish() })).default([]),
+    image: image.nullish(),
+    manage_stock: z.union([z.boolean(), z.literal("parent")]).nullish(),
+    stock_quantity: z.number().nullish(),
+    stock_status: z.string().nullish(),
+});
+export const wooProductSchema = z.object({
+    id,
+    name: z.string(),
+    slug: z.string().nullish(),
+    type: z.string(),
+    status: z.string().nullish(),
+    description: z.string().nullish(),
+    permalink: z.string().nullish(),
+    sku: z.string().nullish(),
+    price: money,
+    regular_price: money,
+    sale_price: money,
+    images: z.array(image).default([]),
+    attributes: z.array(z.object({ name: z.string(), position: z.number().nullish(), variation: z.boolean().nullish(), options: z.array(z.string()).default([]) })).default([]),
+    tags: z.array(z.object({ slug: z.string().nullish() })).default([]),
+    categories: z.array(z.object({ slug: z.string().nullish() })).default([]),
+    variations: z.array(id).default([]),
+    manage_stock: z.boolean().nullish(),
+    stock_quantity: z.number().nullish(),
+    stock_status: z.string().nullish(),
+});
+/** Products a shopper can buy through us: a grouped product is a list of others; an external one is sold elsewhere. */
+export function isPurchasable(product) {
+    return product.type === "simple" || product.type === "variable";
+}
+/** The amount a shopper pays and, when on sale, the price it is reduced from. Missing price → no price. */
+function prices(row, currency) {
+    if (!currency)
+        return undefined;
+    const sale = toMinorUnits(row.sale_price, currency);
+    const regular = toMinorUnits(row.regular_price, currency);
+    const amount = sale ?? regular ?? toMinorUnits(row.price, currency);
+    if (amount === undefined)
+        return undefined;
+    return [{ currency, amount, ...(sale !== undefined && regular !== undefined && regular > sale ? { compareAtAmount: regular } : {}) }];
+}
+function status(value) {
+    if (value === "publish")
+        return "active";
+    if (value === "draft" || value === "pending" || value === "private")
+        return "draft";
+    return undefined;
+}
+function variant(row, currency) {
+    const optionValues = Object.fromEntries(row.attributes.flatMap((attribute) => (attribute.option ? [[attribute.name, attribute.option]] : [])));
+    const rowPrices = prices(row, currency);
+    return {
+        externalId: row.id,
+        ...(row.sku ? { sku: row.sku } : {}),
+        ...(Object.keys(optionValues).length > 0 ? { optionValues } : {}),
+        ...(rowPrices ? { prices: rowPrices } : {}),
+    };
+}
+/**
+ * One store product as a catalogue item. A simple product is one variant named by the product's own
+ * id (only variations carry a price otherwise, so a simple product would import unpriced).
+ */
+export function catalogItem(product, variations, currency) {
+    const images = product.images.map((entry, index) => ({
+        externalId: entry.id,
+        url: entry.src,
+        ...(entry.alt ? { alt: entry.alt } : {}),
+        role: index === 0 ? "primary" : "gallery",
+        sortOrder: index,
+    }));
+    const seen = new Set(images.map((entry) => entry.externalId));
+    for (const row of variations) {
+        if (!row.image || row.image.id === "0")
+            continue;
+        const existing = images.find((entry) => entry.externalId === row.image?.id);
+        if (existing) {
+            existing.variantExternalIds = [...(existing.variantExternalIds ?? []), row.id];
+        }
+        else if (!seen.has(row.image.id)) {
+            seen.add(row.image.id);
+            images.push({ externalId: row.image.id, url: row.image.src, ...(row.image.alt ? { alt: row.image.alt } : {}), role: "gallery", sortOrder: images.length, variantExternalIds: [row.id] });
+        }
+    }
+    const options = product.attributes.filter((attribute) => attribute.variation === true).map((attribute, index) => ({
+        name: attribute.name,
+        displayName: attribute.name,
+        sortOrder: attribute.position ?? index,
+        values: attribute.options.map((value, valueIndex) => ({ value, displayValue: value, sortOrder: valueIndex })),
+    }));
+    const variants = product.type === "simple"
+        ? [variant({ id: product.id, sku: product.sku, price: product.price, regular_price: product.regular_price, sale_price: product.sale_price, attributes: [] }, currency)]
+        : variations.filter((row) => row.status !== "private").map((row) => variant(row, currency));
+    const itemStatus = status(product.status);
+    return {
+        externalId: product.id,
+        slug: product.slug || product.id,
+        title: product.name,
+        ...(product.description ? { description: product.description } : {}),
+        attributes: [{ locale: "en", title: product.name, ...(product.description ? { description: product.description } : {}) }],
+        variants,
+        ...(images.length > 0 ? { images } : {}),
+        ...(options.length > 0 ? { options } : {}),
+        tags: product.tags.flatMap((tag) => (tag.slug ? [tag.slug] : [])),
+        categories: product.categories.flatMap((category) => (category.slug ? [category.slug] : [])),
+        ...(itemStatus ? { status: itemStatus } : {}),
+        ...(product.permalink ? { storefrontUrl: product.permalink } : {}),
+    };
+}
+/** Every variation of a variable product, whatever changed: a changed product is re-read whole. */
+export async function variationsOf(client, product) {
+    if (product.type !== "variable" || product.variations.length === 0)
+        return Ok([]);
+    return client.all(`/wc/v3/products/${encodeURIComponent(product.id)}/variations`, wooVariationSchema);
+}
+/**
+ * The import cursor, as JSON: `{ page, after? }`. `after` is the `date_modified_gmt` an incremental
+ * import resumes from; pages are walked oldest change first so a resumed walk never skips one.
+ */
+const cursorSchema = z.object({ page: z.number().int().positive(), after: z.string().optional() });
+export async function importPage(client, cursor) {
+    let position = { page: 1 };
+    if (cursor) {
+        let raw;
+        try {
+            raw = JSON.parse(cursor);
+        }
+        catch {
+            raw = undefined;
+        }
+        const parsed = cursorSchema.safeParse(raw);
+        // Anything else is an ISO time: "everything changed since".
+        position = parsed.success ? parsed.data : { page: 1, after: cursor };
+    }
+    const query = { per_page: "50", page: String(position.page), orderby: "modified", order: "asc" };
+    if (position.after) {
+        query.modified_after = position.after;
+        query.dates_are_gmt = "true";
+    }
+    const read = await client.get("/wc/v3/products", z.array(wooProductSchema), query);
+    if (!read.ok)
+        return read;
+    const items = [];
+    for (const product of read.value.data) {
+        if (!isPurchasable(product))
+            continue;
+        const variations = await variationsOf(client, product);
+        if (!variations.ok)
+            return variations;
+        items.push(catalogItem(product, variations.value, client.credentials.currency));
+    }
+    const nextCursor = position.page < read.value.totalPages ? JSON.stringify({ ...position, page: position.page + 1 }) : null;
+    return Ok({ items, nextCursor });
+}
+/** The named products as they are now; an id the store no longer has, or cannot sell through us, is absent. */
+export async function catalogItems(client, externalIds) {
+    const items = [];
+    for (let offset = 0; offset < externalIds.length; offset += 100) {
+        const ids = externalIds.slice(offset, offset + 100);
+        const read = await client.get("/wc/v3/products", z.array(wooProductSchema), { include: ids.join(","), per_page: "100", status: "any" });
+        if (!read.ok)
+            return read;
+        for (const product of read.value.data) {
+            if (!isPurchasable(product))
+                continue;
+            const variations = await variationsOf(client, product);
+            if (!variations.ok)
+                return variations;
+            items.push(catalogItem(product, variations.value, client.credentials.currency));
+        }
+    }
+    return Ok(items);
+}
+const rootSchema = z.object({ name: z.string() });
+export async function storeProfile(client) {
+    const root = await client.get("/", rootSchema);
+    if (!root.ok)
+        return root;
+    const currency = client.credentials.currency;
+    if (!currency)
+        return Err({ code: "WOO_STORE_NOT_DISCOVERED", message: "The store's currency is not known yet.", retriable: true });
+    return Ok({ name: root.value.data.name, currency, storefrontHosts: [new URL(client.base).host] });
+}

package/dist/client.d.ts

@@ -0,0 +1,85 @@
+import type { ChannelConnectorError, ChannelStore, Result } from "@porulle/core";
+import { z } from "zod";
+/**
+ * Everything the adapter learns about one store, kept in its credentials. The keys come from
+ * WooCommerce's approval screen; the rest is discovered once by `discoverStore` and persisted through
+ * the plugin's `liveCredentials` hook, so no call has to rediscover it.
+ */
+export declare const wooCredentialsSchema: z.ZodObject<{
+    consumerKey: z.ZodString;
+    consumerSecret: z.ZodString;
+    authMode: z.ZodOptional<z.ZodEnum<{
+        query: "query";
+        header: "header";
+    }>>;
+    restRoute: z.ZodOptional<z.ZodEnum<{
+        query: "query";
+        pretty: "pretty";
+    }>>;
+    currency: z.ZodOptional<z.ZodString>;
+    priceDecimals: z.ZodOptional<z.ZodNumber>;
+    hpos: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type WooCredentials = z.infer<typeof wooCredentialsSchema>;
+export interface WooTransportOptions {
+    fetchImpl: typeof fetch;
+    userAgent: string;
+    /** Tests point the adapter at a store on localhost; production never does. */
+    allowPrivateHosts: boolean;
+}
+export type WooProbeFailure = "not_json" | "rest_unavailable" | "tls" | "not_woocommerce" | "private_host" | "unreachable";
+export declare const WOO_BLOCKED_BY_FIREWALL = "WOO_BLOCKED_BY_FIREWALL";
+export declare const WOO_API_FAILED = "WOO_API_FAILED";
+/**
+ * The canonical store URL a merchant's typing names: https only, lower-case host, any sub-directory
+ * install path kept, no trailing slash or `/wp-json` suffix. Undefined when it cannot name a store.
+ */
+export declare function normalizeStoreDomain(input: string, options?: {
+    allowPrivateHosts?: boolean;
+}): string | undefined;
+/** A store URL the adapter refuses outright, for a message better than "does not name a store". */
+export declare function refusedStoreUrl(input: string): WooProbeFailure | "http" | undefined;
+/**
+ * Finds the store's REST API without credentials: `/wp-json/`, else `/?rest_route=/` for a store with
+ * plain permalinks. It must list `wc/v3`. Each failure is classified for a message the merchant can act on.
+ */
+export declare function probeStore(options: WooTransportOptions, storeUrl: string): Promise<Result<{
+    restRoute: "pretty" | "query";
+    name: string;
+}, {
+    code: WooProbeFailure;
+    message: string;
+}>>;
+export interface WooPage<T> {
+    data: T;
+    totalPages: number;
+}
+/** A store's REST client: keys sent as the store accepts them, every answer parsed, no secret in an error. */
+export interface WooClient {
+    readonly base: string;
+    readonly credentials: WooCredentials;
+    get<T>(path: string, schema: z.ZodType<T>, query?: Record<string, string>): Promise<Result<WooPage<T>, WooRequestError>>;
+    send<T>(method: "POST" | "PUT" | "DELETE", path: string, body: unknown, schema: z.ZodType<T>, query?: Record<string, string>): Promise<Result<T, WooRequestError>>;
+    /** Every page of a list endpoint, 100 at a time. */
+    all<T>(path: string, schema: z.ZodType<T>, query?: Record<string, string>): Promise<Result<T[], WooRequestError>>;
+}
+declare const wooErrorSchema: z.ZodObject<{
+    code: z.ZodString;
+    message: z.ZodOptional<z.ZodString>;
+    data: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strip>;
+export type WooErrorBody = z.infer<typeof wooErrorSchema>;
+/** The REST error WooCommerce answered, kept for callers that act on its code (e.g. a leftover draft order). */
+export interface WooRequestError extends ChannelConnectorError {
+    status?: number;
+    body?: WooErrorBody;
+}
+export declare function wooClient(store: ChannelStore, options: WooTransportOptions): Result<WooClient, ChannelConnectorError>;
+export declare function clientFor(base: string, credentials: WooCredentials, options: WooTransportOptions): WooClient;
+/**
+ * What the adapter needs to know about a store before it can call it well: where its REST API
+ * answers, how it accepts our keys, and how it prices. Read once and persisted in the credentials.
+ * A key both auth modes refuse is {@link CHANNEL_CREDENTIALS_REJECTED}.
+ */
+export declare function discoverStore(options: WooTransportOptions, storeDomain: string, credentials: WooCredentials): Promise<Result<WooCredentials, ChannelConnectorError>>;
+export {};

package/dist/client.js

@@ -0,0 +1,269 @@
+import { CHANNEL_CREDENTIALS_REJECTED, Err, Ok } from "@porulle/core";
+import { z } from "zod";
+/**
+ * Everything the adapter learns about one store, kept in its credentials. The keys come from
+ * WooCommerce's approval screen; the rest is discovered once by `discoverStore` and persisted through
+ * the plugin's `liveCredentials` hook, so no call has to rediscover it.
+ */
+export const wooCredentialsSchema = z.object({
+    consumerKey: z.string().regex(/^ck_[a-f0-9]{40}$/),
+    consumerSecret: z.string().regex(/^cs_[a-f0-9]{40}$/),
+    /** `query` when the host strips the Authorization header (some proxies and caches do). */
+    authMode: z.enum(["header", "query"]).optional(),
+    /** `query` when pretty permalinks are off and the REST API answers only at `/?rest_route=`. */
+    restRoute: z.enum(["pretty", "query"]).optional(),
+    currency: z.string().optional(),
+    priceDecimals: z.number().int().min(0).max(4).optional(),
+    hpos: z.boolean().optional(),
+});
+export const WOO_BLOCKED_BY_FIREWALL = "WOO_BLOCKED_BY_FIREWALL";
+export const WOO_API_FAILED = "WOO_API_FAILED";
+const FIREWALL_MESSAGE = "The store answered with a web page instead of its API. A firewall in front of it (Cloudflare Bot Fight Mode, Wordfence or another security plugin) is blocking us; allow requests to /wp-json/wc/ from our service.";
+function isPrivateHost(host) {
+    const h = host.replace(/^\[|\]$/g, "").toLowerCase();
+    if (h === "localhost" || h.endsWith(".localhost") || h.endsWith(".local") || h.endsWith(".internal") || h === "metadata.google.internal")
+        return true;
+    // IPv6 loopback, unique-local, link-local, IPv4-mapped.
+    if (h.includes(":"))
+        return h === "::1" || h === "::" || /^f[cd]/.test(h) || /^fe[89ab]/.test(h) || h.startsWith("::ffff:");
+    // Any all-numeric host: dotted, single integer, hex or octal encodings all name an IP.
+    if (/^[0-9.]+$/.test(h) || /^0x[0-9a-f]+$/i.test(h)) {
+        const parts = h.split(".").map((part) => Number(part));
+        if (parts.length !== 4 || parts.some((part) => !Number.isInteger(part) || part < 0 || part > 255))
+            return true;
+        const [a = 0, b = 0] = parts;
+        return a === 0 || a === 10 || a === 127 || (a === 169 && b === 254) || (a === 172 && b >= 16 && b <= 31) || (a === 192 && b === 168) || (a === 100 && b >= 64 && b <= 127) || a >= 224;
+    }
+    return false;
+}
+/**
+ * The canonical store URL a merchant's typing names: https only, lower-case host, any sub-directory
+ * install path kept, no trailing slash or `/wp-json` suffix. Undefined when it cannot name a store.
+ */
+export function normalizeStoreDomain(input, options = {}) {
+    const typed = input.trim();
+    if (typed === "")
+        return undefined;
+    let url;
+    try {
+        url = new URL(/^[a-z][a-z0-9+.-]*:\/\//i.test(typed) ? typed : `https://${typed}`);
+    }
+    catch {
+        return undefined;
+    }
+    const local = options.allowPrivateHosts === true && isPrivateHost(url.hostname);
+    if (url.protocol !== "https:" && !(local && url.protocol === "http:"))
+        return undefined;
+    if (url.username || url.password || !url.hostname.includes(".") && !local)
+        return undefined;
+    if (isPrivateHost(url.hostname) && options.allowPrivateHosts !== true)
+        return undefined;
+    const path = url.pathname.replace(/\/+$/, "").replace(/\/wp-json$/i, "").replace(/\/+$/, "");
+    return `${url.protocol}//${url.host.toLowerCase()}${path}`;
+}
+/** A store URL the adapter refuses outright, for a message better than "does not name a store". */
+export function refusedStoreUrl(input) {
+    try {
+        const url = new URL(/^[a-z][a-z0-9+.-]*:\/\//i.test(input.trim()) ? input.trim() : `https://${input.trim()}`);
+        if (url.protocol === "http:")
+            return "http";
+        if (isPrivateHost(url.hostname))
+            return "private_host";
+    }
+    catch {
+        return undefined;
+    }
+    return undefined;
+}
+const restRootSchema = z.object({ name: z.string().optional(), namespaces: z.array(z.string()).optional() });
+function stripBom(text) {
+    return text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+}
+function looksLikeJson(response) {
+    return (response.headers.get("content-type") ?? "").toLowerCase().includes("json");
+}
+/** One request with no redirect followed: a redirect to another host, or to http, must not carry our keys. */
+async function fetchOnce(options, url, init = {}) {
+    return options.fetchImpl(url, {
+        ...init,
+        redirect: "manual",
+        headers: { accept: "application/json", "user-agent": options.userAgent, ...(init.headers ?? {}) },
+    });
+}
+function restUrl(base, path, restRoute, query = {}) {
+    const url = restRoute === "pretty" ? new URL(`${base}/wp-json${path}`) : new URL(`${base}/`);
+    if (restRoute === "query")
+        url.searchParams.set("rest_route", path);
+    for (const [name, value] of Object.entries(query))
+        url.searchParams.set(name, value);
+    return url;
+}
+/**
+ * Finds the store's REST API without credentials: `/wp-json/`, else `/?rest_route=/` for a store with
+ * plain permalinks. It must list `wc/v3`. Each failure is classified for a message the merchant can act on.
+ */
+export async function probeStore(options, storeUrl) {
+    const base = normalizeStoreDomain(storeUrl, { allowPrivateHosts: options.allowPrivateHosts });
+    if (!base)
+        return Err({ code: "private_host", message: "That address cannot be a public WooCommerce store." });
+    let sawHtml = false;
+    for (const restRoute of ["pretty", "query"]) {
+        let response;
+        try {
+            response = await fetchOnce(options, restUrl(base, "/", restRoute));
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            if (/certificate|ssl|tls/i.test(message))
+                return Err({ code: "tls", message: "The store's HTTPS certificate was refused. It needs a valid certificate." });
+            return Err({ code: "unreachable", message: `The store could not be reached: ${message}` });
+        }
+        if (response.ok && looksLikeJson(response)) {
+            const root = restRootSchema.safeParse(JSON.parse(stripBom(await response.text())));
+            if (!root.success)
+                return Err({ code: "not_json", message: FIREWALL_MESSAGE });
+            if (!(root.data.namespaces ?? []).includes("wc/v3"))
+                return Err({ code: "not_woocommerce", message: "That site runs WordPress but not WooCommerce (or its REST API is turned off)." });
+            return Ok({ restRoute, name: root.data.name ?? base });
+        }
+        if (!looksLikeJson(response) && response.status !== 404)
+            sawHtml = true;
+    }
+    return sawHtml
+        ? Err({ code: "not_json", message: FIREWALL_MESSAGE })
+        : Err({ code: "rest_unavailable", message: "The store's REST API did not answer. Turn on pretty permalinks (Settings → Permalinks → Post name) and make sure no plugin disables the REST API." });
+}
+const wooErrorSchema = z.object({ code: z.string(), message: z.string().optional(), data: z.unknown().optional() });
+function classify(status, json, body, what) {
+    if (status === 401 && json) {
+        return { code: CHANNEL_CREDENTIALS_REJECTED, message: `The store refused our key for ${what}${body?.message ? `: ${body.message}` : ""}.`, retriable: false, status, ...(body ? { body } : {}) };
+    }
+    if (!json && (status === 403 || status === 429 || status === 503 || status === 406)) {
+        return { code: WOO_BLOCKED_BY_FIREWALL, message: FIREWALL_MESSAGE, retriable: true, status };
+    }
+    const retriable = status >= 500 || status === 408 || status === 429;
+    return { code: WOO_API_FAILED, message: `WooCommerce answered ${status} for ${what}${body?.message ? `: ${body.message}` : ""}.`, retriable, status, ...(body ? { body } : {}) };
+}
+export function wooClient(store, options) {
+    const credentials = wooCredentialsSchema.safeParse(store.credentials);
+    if (!credentials.success)
+        return Err({ code: "WOO_CREDENTIALS_REQUIRED", message: "The store holds no valid WooCommerce keys; it must be reconnected.", retriable: false });
+    const base = normalizeStoreDomain(store.storeDomain, { allowPrivateHosts: options.allowPrivateHosts });
+    if (!base)
+        return Err({ code: "WOO_INVALID_STORE_DOMAIN", message: "The store's address is not an https URL.", retriable: false });
+    return Ok(clientFor(base, credentials.data, options));
+}
+export function clientFor(base, credentials, options) {
+    const authMode = credentials.authMode ?? "header";
+    const restRoute = credentials.restRoute ?? "pretty";
+    const authHeader = `Basic ${btoa(`${credentials.consumerKey}:${credentials.consumerSecret}`)}`;
+    async function call(method, path, query, body) {
+        const url = restUrl(base, path, restRoute, query);
+        if (authMode === "query") {
+            url.searchParams.set("consumer_key", credentials.consumerKey);
+            url.searchParams.set("consumer_secret", credentials.consumerSecret);
+        }
+        // Named in errors without its query string, which may carry the keys.
+        const what = `${method} ${path}`;
+        let response;
+        try {
+            response = await fetchOnce(options, url, {
+                method,
+                headers: { ...(authMode === "header" ? { authorization: authHeader } : {}), ...(body !== undefined ? { "content-type": "application/json" } : {}) },
+                ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+            });
+        }
+        catch (error) {
+            return Err({ code: WOO_API_FAILED, message: `The store could not be reached for ${what}: ${error instanceof Error ? error.message : String(error)}.`, retriable: true });
+        }
+        if (response.status >= 300 && response.status < 400) {
+            return Err({ code: WOO_API_FAILED, message: `The store redirected ${what} elsewhere (${response.status}); its address may have changed. Reconnect it at its current address.`, retriable: false, status: response.status });
+        }
+        const json = looksLikeJson(response);
+        const text = stripBom(await response.text());
+        let data;
+        if (json) {
+            try {
+                data = JSON.parse(text);
+            }
+            catch {
+                return Err({ code: WOO_BLOCKED_BY_FIREWALL, message: FIREWALL_MESSAGE, retriable: true, status: response.status });
+            }
+        }
+        if (!response.ok)
+            return Err(classify(response.status, json, json ? wooErrorSchema.safeParse(data).data : undefined, what));
+        if (!json)
+            return Err({ code: WOO_BLOCKED_BY_FIREWALL, message: FIREWALL_MESSAGE, retriable: true, status: response.status });
+        return Ok({ data, response });
+    }
+    function parse(schema, data, what) {
+        const parsed = schema.safeParse(data);
+        return parsed.success ? Ok(parsed.data) : Err({ code: "WOO_UNEXPECTED_RESPONSE", message: `WooCommerce answered ${what} in a shape we do not recognise: ${parsed.error.message.slice(0, 400)}`, retriable: false });
+    }
+    const client = {
+        base,
+        credentials,
+        async get(path, schema, query = {}) {
+            const answered = await call("GET", path, query, undefined);
+            if (!answered.ok)
+                return answered;
+            const parsed = parse(schema, answered.value.data, `GET ${path}`);
+            if (!parsed.ok)
+                return parsed;
+            const totalPages = Number.parseInt(answered.value.response.headers.get("x-wp-totalpages") ?? "1", 10);
+            return Ok({ data: parsed.value, totalPages: Number.isFinite(totalPages) && totalPages > 0 ? totalPages : 1 });
+        },
+        async send(method, path, body, schema, query = {}) {
+            const answered = await call(method, path, query, body);
+            if (!answered.ok)
+                return answered;
+            return parse(schema, answered.value.data, `${method} ${path}`);
+        },
+        async all(path, schema, query = {}) {
+            const rows = [];
+            for (let page = 1;; page += 1) {
+                const read = await client.get(path, z.array(schema), { per_page: "100", ...query, page: String(page) });
+                if (!read.ok)
+                    return read;
+                rows.push(...read.value.data);
+                if (page >= read.value.totalPages || read.value.data.length === 0)
+                    return Ok(rows);
+            }
+        },
+    };
+    return client;
+}
+const systemStatusSchema = z.object({
+    settings: z.object({
+        currency: z.string(),
+        number_of_decimals: z.coerce.number().int(),
+        HPOS_enabled: z.boolean().optional(),
+    }),
+});
+/**
+ * What the adapter needs to know about a store before it can call it well: where its REST API
+ * answers, how it accepts our keys, and how it prices. Read once and persisted in the credentials.
+ * A key both auth modes refuse is {@link CHANNEL_CREDENTIALS_REJECTED}.
+ */
+export async function discoverStore(options, storeDomain, credentials) {
+    const base = normalizeStoreDomain(storeDomain, { allowPrivateHosts: options.allowPrivateHosts });
+    if (!base)
+        return Err({ code: "WOO_INVALID_STORE_DOMAIN", message: "The store's address is not an https URL.", retriable: false });
+    const probe = await probeStore(options, base);
+    if (!probe.ok)
+        return Err({ code: probe.error.code === "not_json" ? WOO_BLOCKED_BY_FIREWALL : "WOO_STORE_UNREACHABLE", message: probe.error.message, retriable: probe.error.code === "not_json" || probe.error.code === "unreachable" });
+    let firstError;
+    for (const authMode of ["header", "query"]) {
+        const client = clientFor(base, { ...credentials, authMode, restRoute: probe.value.restRoute }, options);
+        const status = await client.get("/wc/v3/system_status", systemStatusSchema);
+        if (status.ok) {
+            const { currency, number_of_decimals, HPOS_enabled } = status.value.data.settings;
+            return Ok({ ...credentials, authMode, restRoute: probe.value.restRoute, currency: currency.toUpperCase(), priceDecimals: number_of_decimals, hpos: HPOS_enabled === true });
+        }
+        firstError ??= status.error;
+        // Only a refused key is worth a second try in the other mode: a stripped header reads as no key.
+        if (status.error.code !== CHANNEL_CREDENTIALS_REJECTED)
+            return status;
+    }
+    return Err(firstError ?? { code: CHANNEL_CREDENTIALS_REJECTED, message: "The store refused our key.", retriable: false });
+}

package/dist/index.d.ts

@@ -1,5 +1,19 @@
 import type { ChannelConnector } from "@porulle/core";
+export { normalizeStoreDomain, probeStore, refusedStoreUrl, WOO_BLOCKED_BY_FIREWALL } from "./client.js";
+export type { WooCredentials, WooProbeFailure } from "./client.js";
+export { ORDER_META_KEY } from "./orders.js";
+export { WOO_WEBHOOK_TOPICS } from "./webhooks.js";
 export interface WooConnectorOptions {
     fetchImpl?: typeof fetch;
+    /** Sent on every request: a store's firewall can then allow us by name. */
+    userAgent?: string;
+    /** Only for a test store on localhost; production stores are public https sites. */
+    allowPrivateHosts?: boolean;
+    /** How many units a product the store does not count (`manage_stock: false`) can sell while in stock. */
+    untrackedStockQuantity?: number;
+    /** How the store's order (and the email it sends the shopper) names the payment. */
+    paymentMethodTitle?: string;
+    /** The application name WooCommerce shows the merchant on its approval screen. */
+    appName?: string;
 }
 export declare function wooConnector(options?: WooConnectorOptions): ChannelConnector;