@porulle/adapter-woocommerce 0.73.2 → 0.74.0

package/dist/inventory.d.ts

@@ -0,0 +1,21 @@
+import type { ChannelConnectorError, ChannelInventoryLevel, Result } from "@porulle/core";
+import type { WooVariation } from "./catalog.js";
+import type { WooClient } from "./client.js";
+/**
+ * Sellable stock of one product or variation. A store that tracks quantity says how many (a variation
+ * whose stock is its parent's, `manage_stock: "parent"`, already reports the parent's count); one that
+ * does not (`manage_stock: false`) only says in or out of stock, and "in stock" is read as `untracked`
+ * units so a shopper can buy it. Never negative: an oversold item reads as none.
+ */
+export declare function available(row: Pick<WooVariation, "manage_stock" | "stock_quantity" | "stock_status">, untracked: number): number;
+/** One page of products (and their variations), with the next page's cursor or null on the last. */
+export declare function inventoryPage(client: WooClient, cursor: string | null, untracked: number): Promise<Result<{
+    levels: ChannelInventoryLevel[];
+    nextCursor: string | null;
+}, ChannelConnectorError>>;
+/**
+ * Levels for the named ids, each a simple product's id or a variation's (the ids every order line and
+ * stock check carries). A variation is found through its parent; an id the store no longer has is
+ * absent, which the caller treats as unconfirmed.
+ */
+export declare function inventoryFor(client: WooClient, ids: string[], untracked: number): Promise<Result<ChannelInventoryLevel[], ChannelConnectorError>>;

package/dist/inventory.js

@@ -0,0 +1,78 @@
+import { Ok } from "@porulle/core";
+import { z } from "zod";
+import { isPurchasable, wooProductSchema, wooVariationSchema } from "./catalog.js";
+/**
+ * Sellable stock of one product or variation. A store that tracks quantity says how many (a variation
+ * whose stock is its parent's, `manage_stock: "parent"`, already reports the parent's count); one that
+ * does not (`manage_stock: false`) only says in or out of stock, and "in stock" is read as `untracked`
+ * units so a shopper can buy it. Never negative: an oversold item reads as none.
+ */
+export function available(row, untracked) {
+    if (row.manage_stock === true || row.manage_stock === "parent")
+        return Math.max(0, Math.floor(row.stock_quantity ?? 0));
+    return row.stock_status === "instock" || row.stock_status === "onbackorder" ? untracked : 0;
+}
+/** Levels for one page of products: a simple product by its own id, a variable one per variation. */
+async function levelsOf(client, products, untracked) {
+    const levels = [];
+    for (const product of products) {
+        if (!isPurchasable(product))
+            continue;
+        if (product.type === "simple") {
+            levels.push({ externalId: product.id, available: available(product, untracked) });
+            continue;
+        }
+        if (product.variations.length === 0)
+            continue;
+        const variations = await client.all(`/wc/v3/products/${encodeURIComponent(product.id)}/variations`, wooVariationSchema);
+        if (!variations.ok)
+            return variations;
+        for (const variation of variations.value)
+            levels.push({ externalId: variation.id, available: available(variation, untracked) });
+    }
+    return Ok(levels);
+}
+const pageCursor = z.coerce.number().int().positive();
+/** One page of products (and their variations), with the next page's cursor or null on the last. */
+export async function inventoryPage(client, cursor, untracked) {
+    const page = cursor === null ? 1 : pageCursor.catch(1).parse(cursor);
+    const read = await client.get("/wc/v3/products", z.array(wooProductSchema), { per_page: "50", page: String(page), orderby: "id", order: "asc" });
+    if (!read.ok)
+        return read;
+    const levels = await levelsOf(client, read.value.data, untracked);
+    if (!levels.ok)
+        return levels;
+    return Ok({ levels: levels.value, nextCursor: page < read.value.totalPages ? String(page + 1) : null });
+}
+/**
+ * Levels for the named ids, each a simple product's id or a variation's (the ids every order line and
+ * stock check carries). A variation is found through its parent; an id the store no longer has is
+ * absent, which the caller treats as unconfirmed.
+ */
+export async function inventoryFor(client, ids, untracked) {
+    if (ids.length === 0)
+        return Ok([]);
+    const wanted = new Set(ids);
+    const levels = [];
+    // Simple products answer by their own id; whatever is left must be a variation.
+    const products = await client.all("/wc/v3/products", wooProductSchema, { include: ids.join(","), status: "any" });
+    if (!products.ok)
+        return products;
+    for (const product of products.value) {
+        if (product.type === "simple" && wanted.has(product.id)) {
+            levels.push({ externalId: product.id, available: available(product, untracked) });
+            wanted.delete(product.id);
+        }
+    }
+    // A variation is a product too: `/products/{id}` answers it by its own id.
+    for (const variationId of wanted) {
+        const read = await client.get(`/wc/v3/products/${encodeURIComponent(variationId)}`, wooVariationSchema);
+        if (!read.ok) {
+            if (read.error.status === 404)
+                continue;
+            return read;
+        }
+        levels.push({ externalId: read.value.data.id, available: available(read.value.data, untracked) });
+    }
+    return Ok(levels);
+}

package/dist/orders.d.ts

@@ -0,0 +1,51 @@
+import type { ChannelCancelOrderInput, ChannelConnectorError, ChannelOrderSlice, ChannelOrderStatus, ChannelPushOrderResult, Result } from "@porulle/core";
+import { z } from "zod";
+import type { WooClient } from "./client.js";
+export declare const wooOrderSchema: z.ZodObject<{
+    id: z.ZodPipe<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>, z.ZodTransform<string, string | number>>;
+    status: z.ZodString;
+    total: z.ZodString;
+    currency: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    date_created_gmt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    meta_data: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        value: z.ZodUnknown;
+    }, z.core.$strip>>>;
+    line_items: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodPipe<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>, z.ZodTransform<string, string | number>>;
+        product_id: z.ZodPipe<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>, z.ZodTransform<string, string | number>>;
+        variation_id: z.ZodPipe<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>, z.ZodTransform<string, string | number>>;
+        quantity: z.ZodNumber;
+        total: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>>>;
+    refunds: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodPipe<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>, z.ZodTransform<string, string | number>>;
+        total: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type WooOrder = z.infer<typeof wooOrderSchema>;
+/** The meta key naming the marketplace order a store order was created for: how a retry finds it. */
+export declare const ORDER_META_KEY = "_porulle_order_id";
+/** Minor units as WooCommerce's money string: a string always (a number is refused), at the store's decimals. */
+export declare function moneyString(minor: number, currency: string, decimals: number | undefined): string;
+export interface PushOrderOptions {
+    paymentMethodTitle: string;
+    untrackedStockQuantity: number;
+}
+/**
+ * Creates the paid order in the store, at exactly what the shopper paid, once.
+ *
+ * WooCommerce never refuses an order for stock (it goes negative), has no idempotency key, and adds
+ * its own tax to whatever it is sent. So: stock is read fresh first; every line carries the
+ * `zero-rate` tax class and the delivery its own line; the total is checked after; a store order
+ * that oversold or came out at another total is cancelled again (cancelling restocks). The create is
+ * never retried here: an unclear answer is a retriable failure, and the next attempt finds the order
+ * by our meta key before creating anything.
+ */
+export declare function pushOrder(client: WooClient, slice: ChannelOrderSlice, options: PushOrderOptions): Promise<Result<ChannelPushOrderResult, ChannelConnectorError>>;
+/**
+ * Cancels an order we pushed. WooCommerce restocks on cancel. An order already cancelled is success; a
+ * completed or refunded one is the merchant's (shipped) and is refused, never moved backwards.
+ */
+export declare function cancelOrder(client: WooClient, remoteId: string, input: ChannelCancelOrderInput): Promise<Result<void, ChannelConnectorError>>;
+export declare function orderStatus(client: WooClient, remoteId: string): Promise<Result<ChannelOrderStatus, ChannelConnectorError>>;

package/dist/orders.js

@@ -0,0 +1,200 @@
+import { CHANNEL_CANCEL_REFUSED, CHANNEL_OUT_OF_STOCK, CHANNEL_TOTAL_MISMATCH, currencyExponent, Err, Ok, toMinorUnits } from "@porulle/core";
+import { z } from "zod";
+import { available } from "./inventory.js";
+const id = z.union([z.number(), z.string()]).transform(String);
+export const wooOrderSchema = z.object({
+    id,
+    status: z.string(),
+    total: z.string(),
+    currency: z.string().nullish(),
+    date_created_gmt: z.string().nullish(),
+    meta_data: z.array(z.object({ key: z.string(), value: z.unknown() })).default([]),
+    line_items: z.array(z.object({ id, product_id: id, variation_id: id, quantity: z.number(), total: z.string().nullish() })).default([]),
+    refunds: z.array(z.object({ id, total: z.string().nullish() })).default([]),
+});
+/** The meta key naming the marketplace order a store order was created for: how a retry finds it. */
+export const ORDER_META_KEY = "_porulle_order_id";
+const lineTargetSchema = z.object({
+    id,
+    type: z.string(),
+    parent_id: id.nullish(),
+    manage_stock: z.union([z.boolean(), z.literal("parent")]).nullish(),
+    stock_quantity: z.number().nullish(),
+    stock_status: z.string().nullish(),
+});
+/** Minor units as WooCommerce's money string: a string always (a number is refused), at the store's decimals. */
+export function moneyString(minor, currency, decimals) {
+    const exponent = currencyExponent(currency);
+    return (minor / 10 ** exponent).toFixed(decimals ?? exponent);
+}
+function ours(order, orderId) {
+    return order.meta_data.some((meta) => meta.key === ORDER_META_KEY && meta.value === orderId);
+}
+/** Never mistaken for a store order a merchant made: only a match on our own meta key counts. */
+async function findExisting(client, orderId) {
+    const searched = await client.get("/wc/v3/orders", z.array(wooOrderSchema), { search: orderId, per_page: "20", status: "any" });
+    if (!searched.ok)
+        return searched;
+    const found = searched.value.data.find((order) => ours(order, orderId));
+    if (found)
+        return Ok(found);
+    // Some stores (HPOS) do not search the note. The recent orders are scanned too: a lost answer is
+    // retried within minutes, so the order it created is recent.
+    const since = new Date(Date.now() - 6 * 60 * 60 * 1000).toISOString().slice(0, 19);
+    const recent = await client.get("/wc/v3/orders", z.array(wooOrderSchema), { after: since, dates_are_gmt: "true", per_page: "100", orderby: "date", order: "desc", status: "any" });
+    if (!recent.ok)
+        return recent;
+    return Ok(recent.value.data.find((order) => ours(order, orderId)));
+}
+function remoteUrl(client, orderId) {
+    return client.credentials.hpos
+        ? `${client.base}/wp-admin/admin.php?page=wc-orders&action=edit&id=${orderId}`
+        : `${client.base}/wp-admin/post.php?post=${orderId}&action=edit`;
+}
+/** The discount spread over the lines in proportion to their totals, the rounding remainder on the last. */
+function allocate(totals, discount) {
+    const sum = totals.reduce((acc, value) => acc + value, 0);
+    if (discount <= 0 || sum <= 0)
+        return totals.map(() => 0);
+    const shares = totals.map((value) => Math.floor((value * discount) / sum));
+    shares[shares.length - 1] = (shares.at(-1) ?? 0) + discount - shares.reduce((acc, value) => acc + value, 0);
+    return shares;
+}
+/**
+ * Creates the paid order in the store, at exactly what the shopper paid, once.
+ *
+ * WooCommerce never refuses an order for stock (it goes negative), has no idempotency key, and adds
+ * its own tax to whatever it is sent. So: stock is read fresh first; every line carries the
+ * `zero-rate` tax class and the delivery its own line; the total is checked after; a store order
+ * that oversold or came out at another total is cancelled again (cancelling restocks). The create is
+ * never retried here: an unclear answer is a retriable failure, and the next attempt finds the order
+ * by our meta key before creating anything.
+ */
+export async function pushOrder(client, slice, options) {
+    const existing = await findExisting(client, slice.orderId);
+    if (!existing.ok)
+        return existing;
+    if (existing.value)
+        return Ok({ remoteOrderId: existing.value.id, remoteUrl: remoteUrl(client, existing.value.id) });
+    // Each line's product, read fresh: whether it is a variation, and how many the store can sell.
+    const targets = new Map();
+    for (const line of slice.lines) {
+        const read = await client.get(`/wc/v3/products/${encodeURIComponent(line.externalVariantId)}`, lineTargetSchema);
+        if (!read.ok) {
+            if (read.error.status === 404) {
+                return Err({ code: CHANNEL_OUT_OF_STOCK, message: `The store no longer sells item ${line.externalVariantId}.`, retriable: false });
+            }
+            return read;
+        }
+        targets.set(line.externalVariantId, read.value.data);
+    }
+    const short = slice.lines.filter((line) => {
+        const target = targets.get(line.externalVariantId);
+        return !target || available(target, options.untrackedStockQuantity) < line.quantity;
+    });
+    if (short.length > 0) {
+        return Err({ code: CHANNEL_OUT_OF_STOCK, message: `The store does not have the stock for ${short.map((line) => `${line.quantity} × ${line.title}`).join(", ")}.`, retriable: false });
+    }
+    const currency = slice.currency;
+    const decimals = client.credentials.priceDecimals;
+    const discounts = allocate(slice.lines.map((line) => line.totalPrice), slice.discount?.amount ?? 0);
+    const [firstName = "", ...rest] = slice.customer.name.trim().split(/\s+/);
+    const source = slice.customer.shippingAddress;
+    const address = {
+        first_name: source.firstName,
+        last_name: source.lastName,
+        address_1: source.line1,
+        address_2: source.line2 ?? "",
+        city: source.city,
+        state: source.region ?? "",
+        postcode: source.postalCode ?? "",
+        country: source.countryCode,
+        phone: source.phone ?? "",
+    };
+    const body = {
+        set_paid: true,
+        currency,
+        payment_method: "runvae",
+        payment_method_title: options.paymentMethodTitle,
+        transaction_id: slice.orderId,
+        customer_note: `Runvae order ${slice.orderId}`,
+        meta_data: [{ key: ORDER_META_KEY, value: slice.orderId }],
+        billing: { ...address, first_name: firstName || source.firstName, last_name: rest.join(" ") || source.lastName, email: slice.customer.email },
+        shipping: address,
+        line_items: slice.lines.map((line, index) => {
+            const target = targets.get(line.externalVariantId);
+            const isVariation = target?.type === "variation";
+            return {
+                ...(isVariation ? { variation_id: Number(line.externalVariantId) } : { product_id: Number(line.externalVariantId) }),
+                quantity: line.quantity,
+                subtotal: moneyString(line.totalPrice, currency, decimals),
+                total: moneyString(line.totalPrice - (discounts[index] ?? 0), currency, decimals),
+                tax_class: "zero-rate",
+            };
+        }),
+        shipping_lines: slice.shipping ? [{ method_id: "flat_rate", method_title: slice.shipping.title, total: moneyString(slice.shipping.amount, currency, decimals) }] : [],
+    };
+    const created = await client.send("POST", "/wc/v3/orders", body, wooOrderSchema);
+    if (!created.ok) {
+        const error = created.error;
+        const draft = error.body?.data;
+        const draftId = draft && typeof draft === "object" && "new_draft_order_id" in draft ? z.coerce.number().int().positive().safeParse(draft.new_draft_order_id) : undefined;
+        // A refusal can leave a checkout-draft behind; it is ours, so it goes.
+        if (draftId?.success)
+            await client.send("DELETE", `/wc/v3/orders/${draftId.data}`, undefined, z.unknown(), { force: "true" });
+        // A 4xx is the store's answer. Anything else (timeout, 5xx, unreadable) may have created the
+        // order: retriable, and the next attempt looks for it before creating.
+        const answered = error.status !== undefined && error.status >= 400 && error.status < 500;
+        return Err({ code: answered ? "WOO_ORDER_REJECTED" : error.code, message: answered ? `WooCommerce refused the order: ${error.message}` : `The store's answer to the order was lost (${error.message}); it is looked for before trying again.`, retriable: !answered });
+    }
+    const order = created.value;
+    const total = toMinorUnits(order.total, currency);
+    if (total !== slice.grandTotal) {
+        await cancel(client, order.id, `Runvae: total ${order.total} is not what the shopper paid.`);
+        return Err({ code: CHANNEL_TOTAL_MISMATCH, message: `The store priced the order at ${order.total} ${currency}, not the ${moneyString(slice.grandTotal, currency, decimals)} the shopper paid (is the "Zero rate" tax class still there?). The store order was cancelled.`, retriable: false });
+    }
+    // Two orders racing for the last unit both pass the read above; the store then sits below zero.
+    for (const line of slice.lines) {
+        const after = await client.get(`/wc/v3/products/${encodeURIComponent(line.externalVariantId)}`, lineTargetSchema);
+        if (after.ok && (after.value.data.manage_stock === true || after.value.data.manage_stock === "parent") && (after.value.data.stock_quantity ?? 0) < 0) {
+            await cancel(client, order.id, "Runvae: the store did not have the stock.");
+            return Err({ code: CHANNEL_OUT_OF_STOCK, message: `The store sold out of ${line.title} while the order was placed. The store order was cancelled and restocked.`, retriable: false });
+        }
+    }
+    return Ok({ remoteOrderId: order.id, remoteUrl: remoteUrl(client, order.id) });
+}
+async function cancel(client, orderId, note) {
+    await client.send("POST", `/wc/v3/orders/${encodeURIComponent(orderId)}/notes`, { note, customer_note: false }, z.unknown());
+    return client.send("PUT", `/wc/v3/orders/${encodeURIComponent(orderId)}`, { status: "cancelled" }, wooOrderSchema);
+}
+/**
+ * Cancels an order we pushed. WooCommerce restocks on cancel. An order already cancelled is success; a
+ * completed or refunded one is the merchant's (shipped) and is refused, never moved backwards.
+ */
+export async function cancelOrder(client, remoteId, input) {
+    const read = await client.get(`/wc/v3/orders/${encodeURIComponent(remoteId)}`, wooOrderSchema);
+    if (!read.ok)
+        return read;
+    if (read.value.data.status === "cancelled")
+        return Ok(undefined);
+    if (read.value.data.status === "completed" || read.value.data.status === "refunded") {
+        return Err({ code: CHANNEL_CANCEL_REFUSED, message: `The store has already ${read.value.data.status === "completed" ? "completed (shipped)" : "refunded"} order ${remoteId}.`, retriable: false });
+    }
+    const cancelled = await cancel(client, remoteId, `Runvae: cancelled (${input.reason})${input.staffNote ? `: ${input.staffNote}` : ""}.`);
+    return cancelled.ok ? Ok(undefined) : cancelled;
+}
+export async function orderStatus(client, remoteId) {
+    const read = await client.get(`/wc/v3/orders/${encodeURIComponent(remoteId)}`, wooOrderSchema);
+    if (!read.ok)
+        return read;
+    const status = read.value.data.status;
+    if (status === "completed")
+        return Ok({ status: "fulfilled" });
+    if (status === "processing" || status === "on-hold")
+        return Ok({ status: "confirmed" });
+    if (status === "cancelled")
+        return Ok({ status: "cancelled" });
+    if (status === "failed" || status === "refunded")
+        return Ok({ status: "failed" });
+    return Ok({ status: "pending" });
+}