@tallyui/connector-woocommerce 3.2.0 → 3.3.0

package/dist/index.d.ts

@@ -1,7 +1,12 @@
-import { SyncContext, Customer, CustomerInput, OrderCreateEnvelope, CommandResult, ProductTraits, CollectionSync, ReplicationAdapter, ReconcileFeed, CatalogueReconcileAdapter, ConnectorUnauthorizedError, TallyConnector } from '@tallyui/core';
+import { SyncContext, ServerCapabilities, StoreSettings, Customer, CustomerInput, OrderCreateEnvelope, CommandResult, ProductTraits, CollectionSync, ReplicationAdapter, ReconcileFeed, CatalogueReconcileAdapter, ConnectorUnauthorizedError, TallyConnector } from '@tallyui/core';
 export { ConnectorUnauthorizedError } from '@tallyui/core';
 import { RxJsonSchema } from 'rxdb';
 
+/** The highest order.create version the WooCommerce transport maps: discounts and the customer (v3). It rises when the transport maps split payments (v4) and fees, shipping and custom lines (v5). */
+declare const WOO_ORDER_CREATE_VERSION = 3;
+declare function wooStoreSettings(context: SyncContext): Promise<StoreSettings>;
+declare function readWooCapabilities(context: SyncContext): Promise<ServerCapabilities | undefined>;
+
 type WooCustomerRow = {
     id: number | string;
     first_name?: string | null;
@@ -48,8 +53,19 @@ interface WooCommandTransportOptions {
     getHeaders: () => Record<string, string> | Promise<Record<string, string>>;
     fetch?: typeof fetch;
     timeoutMs?: number;
+    /** True when the store's `/status` lists `order_payments_list` (`ServerCapabilities.multiplePayments`): an order may
+     * then carry several payments, recorded in `_woocommerce_pos_payments`. */
+    acceptsPaymentsList?: boolean | (() => boolean | Promise<boolean>);
+}
+interface WooLocalOrder {
+    lines: ReadonlyArray<{
+        id: string;
+        netMicros?: string;
+    }>;
 }
-declare function toWooOrderPayload(envelope: OrderCreateEnvelope): {
+declare function toWooOrderPayload(envelope: OrderCreateEnvelope, local?: WooLocalOrder, options?: {
+    paymentsList?: boolean;
+}): {
     payload: Record<string, unknown>;
 } | {
     error: {
@@ -58,7 +74,11 @@ declare function toWooOrderPayload(envelope: OrderCreateEnvelope): {
     };
 };
 declare function createWooCommandTransport(options: WooCommandTransportOptions): {
-    send(batch: OrderCreateEnvelope[]): Promise<WooTransportOutcome>;
+    send(batch: OrderCreateEnvelope[], context?: {
+        local?: {
+            orders?: ReadonlyMap<string, WooLocalOrder>;
+        };
+    }): Promise<WooTransportOutcome>;
 };
 
 /**
@@ -198,4 +218,4 @@ declare function createWooCommerceConnector(): TallyConnector;
  */
 declare const woocommerceConnector: TallyConnector;
 
-export { type WooCommandTransportOptions, WooDateFilterError, WooMissingTokenError, WooMissingUuidError, WooTillUpdateRequiredError, WooTokenRefusedError, createWooCommandTransport, createWooCommerceConnector, createWooCustomers, toWooCustomer, toWooOrderPayload, wcposClientPart, wooCatalogueReconcile, wooProductReplication, wooProductSchema, wooProductSync, wooProductTraits, wooReconcileFingerprint, woocommerceConnector };
+export { WOO_ORDER_CREATE_VERSION, type WooCommandTransportOptions, WooDateFilterError, WooMissingTokenError, WooMissingUuidError, WooTillUpdateRequiredError, WooTokenRefusedError, createWooCommandTransport, createWooCommerceConnector, createWooCustomers, readWooCapabilities, toWooCustomer, toWooOrderPayload, wcposClientPart, wooCatalogueReconcile, wooProductReplication, wooProductSchema, wooProductSync, wooProductTraits, wooReconcileFingerprint, wooStoreSettings, woocommerceConnector };

package/dist/index.js

@@ -1,10 +1,10 @@
 // src/index.ts
-import { combinePullAdapters, ConnectorUnauthorizedError as ConnectorUnauthorizedError2 } from "@tallyui/core";
+import { combinePullAdapters, ConnectorUnauthorizedError as ConnectorUnauthorizedError3 } from "@tallyui/core";
 
 // src/schemas/products.ts
 var wooProductSchema = {
   title: "WooCommerce Product",
-  version: 1,
+  version: 2,
   type: "object",
   primaryKey: "uuid",
   properties: {
@@ -50,6 +50,12 @@ var wooProductSchema = {
     sale_price: {
       type: "string"
     },
+    tax_class: {
+      type: "string"
+    },
+    tax_status: {
+      type: "string"
+    },
     on_sale: {
       type: "boolean"
     },
@@ -135,6 +141,8 @@ var wooProductSchema = {
       price: { type: "string" },
       regular_price: { type: "string" },
       sale_price: { type: "string" },
+      tax_class: { type: "string" },
+      tax_status: { type: "string" },
       on_sale: { type: "boolean" },
       stock_status: { type: "string" },
       stock_quantity: { type: ["number", "null"] },
@@ -230,7 +238,9 @@ function toVariationDocument(payload) {
     stock_quantity,
     manage_stock,
     status,
-    purchasable
+    purchasable,
+    tax_class,
+    tax_status
   } = payload;
   return Object.fromEntries(Object.entries({
     id,
@@ -245,6 +255,8 @@ function toVariationDocument(payload) {
     manage_stock,
     status,
     purchasable,
+    tax_class,
+    tax_status,
     attributes: (payload.attributes ?? []).map(({ name, option }) => ({ name, option }))
   }).filter(([, value]) => value !== void 0));
 }
@@ -379,6 +391,17 @@ var wooProductTraits = {
   getId: (doc) => String(doc.id),
   getName: (doc) => doc.name ?? "",
   getSku: (doc) => doc.sku || void 0,
+  getTaxClass: (doc, variantId) => {
+    const variation = variantId === void 0 ? void 0 : doc.variation_docs?.find((v) => String(v.id) === variantId);
+    const taxClass = typeof variation?.tax_class === "string" && variation.tax_class !== "parent" ? variation.tax_class : doc.tax_class;
+    return taxClass === void 0 || taxClass === "" || taxClass === "standard" ? void 0 : taxClass;
+  },
+  getTaxStatus: (doc, variantId) => {
+    const variation = variantId === void 0 ? void 0 : doc.variation_docs?.find((v) => String(v.id) === variantId);
+    const taxStatus = typeof variation?.tax_status === "string" ? variation.tax_status : doc.tax_status;
+    if (taxStatus === "none" || taxStatus === "shipping") return "none";
+    return taxStatus === "taxable" ? "taxable" : void 0;
+  },
   getPrices: (doc, context) => {
     const currency = context?.currency ?? "XXX";
     const prices = [];
@@ -693,50 +716,211 @@ function createWooCustomers(options) {
   };
 }
 
+// src/store-settings.ts
+import { ConnectorUnauthorizedError as ConnectorUnauthorizedError2, StoreSettingsError, minorUnitDigits, woocommerceTax } from "@tallyui/core";
+var WOO_ORDER_CREATE_VERSION = 3;
+async function wooStoreSettings(context) {
+  try {
+    const init = { method: "GET", headers: context.headers, signal: context.signal };
+    const storesResponse = await fetch(`${context.baseUrl}/stores`, init);
+    if (storesResponse.status === 401 || storesResponse.status === 403) {
+      throw new ConnectorUnauthorizedError2(`WooCommerce stores: HTTP ${storesResponse.status}`, storesResponse.status);
+    }
+    if (!storesResponse.ok) throw new Error(`WooCommerce stores: HTTP ${storesResponse.status}`);
+    const stores = await storesResponse.json();
+    if (!Array.isArray(stores) || stores.length === 0) throw new Error("WooCommerce stores: expected a non-empty array");
+    const store = stores[0];
+    const currency = store.currency.toUpperCase();
+    const digits = minorUnitDigits(currency);
+    if (typeof store.price_num_decimals === "number" && store.price_num_decimals !== digits) {
+      console.warn(`WooCommerce price_num_decimals is ${store.price_num_decimals}; the till rounds ${currency} to ${digits} digits`);
+    }
+    const classesResponse = await fetch(`${context.baseUrl}/taxes/classes`, init);
+    if (classesResponse.status === 401 || classesResponse.status === 403) {
+      throw new ConnectorUnauthorizedError2(`WooCommerce tax classes: HTTP ${classesResponse.status}`, classesResponse.status);
+    }
+    if (!classesResponse.ok) throw new Error(`WooCommerce tax classes: HTTP ${classesResponse.status}`);
+    const classes = await classesResponse.json();
+    if (!Array.isArray(classes)) throw new Error("WooCommerce tax classes: expected an array");
+    const taxRates = {};
+    const taxRatesPpm = { default: 0 };
+    const settings = {
+      currency,
+      pricesIncludeTax: store.prices_include_tax === "yes",
+      taxRoundAtSubtotal: store.tax_round_at_subtotal === "yes",
+      ...typeof store.shipping_tax_class === "string" ? { shippingTaxClass: store.shipping_tax_class } : {},
+      taxClassSlugs: classes.map((row) => row.slug),
+      taxRates,
+      taxRatesPpm
+    };
+    if (store.calc_taxes !== "yes") return settings;
+    const rates = [];
+    for (let page = 1; page <= 100; page++) {
+      const response = await fetch(`${context.baseUrl}/taxes?per_page=100&page=${page}&orderby=order&order=asc`, init);
+      if (response.status === 401 || response.status === 403) {
+        throw new ConnectorUnauthorizedError2(`WooCommerce taxes: HTTP ${response.status}`, response.status);
+      }
+      if (!response.ok) throw new Error(`WooCommerce taxes: HTTP ${response.status}`);
+      const rows = await response.json();
+      if (!Array.isArray(rows)) throw new Error("WooCommerce taxes: expected an array");
+      rates.push(...rows.map((row) => ({
+        ...row,
+        postcodes: row.postcodes ?? [],
+        cities: row.cities ?? []
+      })));
+      if (rows.length < 100) break;
+    }
+    const taxAddress = store.tax_address;
+    let address = taxAddress && typeof taxAddress === "object" && typeof taxAddress.country === "string" && taxAddress.country.length > 0 ? taxAddress : { country: store.store_country, state: store.store_state, postcode: store.store_postcode, city: store.store_city };
+    if (!address.country) {
+      console.warn("WooCommerce has no tax or store country; matching tax rates with an empty address");
+      address = {};
+    }
+    const matched = woocommerceTax.filterTaxRates(rates, address.country, address.state, address.postcode, address.city);
+    for (const rate of matched) {
+      const slug = woocommerceTax.normalizeTaxClass(rate.class);
+      (taxRates[slug] ??= []).push({
+        id: rate.id,
+        code: [rate.country, rate.state, rate.name || "TAX", String(rate.priority)].filter(Boolean).join("-").toUpperCase(),
+        label: rate.name,
+        rate: rate.rate,
+        priority: rate.priority,
+        compound: rate.compound,
+        shipping: rate.shipping
+      });
+      const key = slug === "standard" ? "default" : slug;
+      taxRatesPpm[key] = (taxRatesPpm[key] ?? 0) + Math.round(Number(rate.rate) * 1e4);
+    }
+    return settings;
+  } catch (error) {
+    if (error instanceof ConnectorUnauthorizedError2) throw error;
+    throw new StoreSettingsError("failed", error instanceof Error ? error.message : String(error));
+  }
+}
+async function readWooCapabilities(context) {
+  try {
+    const response = await fetch(`${context.baseUrl}/stores`, {
+      method: "GET",
+      headers: context.headers,
+      signal: context.signal
+    });
+    if (response.status === 401 || response.status === 403) {
+      throw new ConnectorUnauthorizedError2(`WooCommerce stores: HTTP ${response.status}`, response.status);
+    }
+    if (!response.ok) return void 0;
+    const stores = await response.json();
+    if (!Array.isArray(stores) || !stores[0] || typeof stores[0] !== "object" || Array.isArray(stores[0])) return void 0;
+    let multiplePayments = false;
+    try {
+      const status = await fetch(`${context.baseUrl}/status`, {
+        method: "GET",
+        headers: context.headers,
+        signal: context.signal
+      });
+      if (status.status === 401 || status.status === 403) {
+        throw new ConnectorUnauthorizedError2(`WooCommerce status: HTTP ${status.status}`, status.status);
+      }
+      if (status.ok) {
+        const body = await status.json();
+        multiplePayments = Array.isArray(body?.capabilities) && body.capabilities.includes("order_payments_list");
+      }
+    } catch (error) {
+      if (error instanceof ConnectorUnauthorizedError2) throw error;
+    }
+    return {
+      orderCreate: WOO_ORDER_CREATE_VERSION,
+      taxRounding: { granularity: "woocommerce", roundAtSubtotal: stores[0].tax_round_at_subtotal === "yes" },
+      multiplePayments,
+      // WCPOS always takes a fee's, shipping line's and custom line's tax_status and tax_class (orders #146, #161); it has no /tally/v1/info.
+      lineTax: { none: true, classes: true }
+    };
+  } catch (error) {
+    if (error instanceof ConnectorUnauthorizedError2) throw error;
+    return void 0;
+  }
+}
+
 // package.json
-var version = "3.2.0";
+var version = "3.3.0";
 
 // src/commands/transport.ts
-import { minorUnitDigits, moneyFromDecimalString, moneyFromMajor as moneyFromMajor2 } from "@tallyui/core";
+import { minorUnitDigits as minorUnitDigits2, moneyFromDecimalString, moneyFromMajor as moneyFromMajor2 } from "@tallyui/core";
 function wooMinorFromDecimal(text, currency) {
   const trimmed = text.trim();
   if (!/^\d+(\.\d+)?$/.test(trimmed)) return void 0;
-  const digits = minorUnitDigits(currency);
+  const digits = minorUnitDigits2(currency);
   const [whole, fraction = ""] = trimmed.split(".");
   let end = fraction.length;
   while (end > digits && fraction[end - 1] === "0") end--;
   if (end > digits) return moneyFromMajor2(trimmed, currency)?.amount;
   return moneyFromDecimalString(end ? `${whole}.${fraction.slice(0, end)}` : whole, currency)?.amount;
 }
-function toWooOrderPayload(envelope) {
+function toWooOrderPayload(envelope, local, options) {
   const p = envelope.payload;
-  if (p.pricesIncludeTax || p.lines.some((line) => line.taxInclusive === true)) {
-    return { error: { code: "unsupported_tax_mode", message: "Prices that include tax are not supported for WooCommerce yet." } };
+  if (envelope.version === 5 && (p.fees?.length || p.shipping?.length || p.lines.some((line) => line.custom))) {
+    return { error: { code: "invalid_payload", message: "Fees, shipping and custom lines are not supported by this connector yet." } };
   }
-  if (p.payments.length !== 1) {
+  if (p.payments.length === 0 || p.payments.length > 1 && !options?.paymentsList) {
     return { error: { code: "invalid_payload", message: "WooCommerce orders take one payment." } };
   }
+  if (p.payments.length > 20) {
+    return { error: { code: "invalid_payload", message: "WooCommerce records at most 20 payments." } };
+  }
+  if (p.payments.length > 1 && p.payments.reduce((sum, payment) => sum + payment.amountMinor, 0) !== p.totalMinor) {
+    return { error: { code: "invalid_payload", message: "Payments do not add up to the order total." } };
+  }
   for (const line of p.lines) {
-    if (!/^[1-9]\d*$/.test(line.variantId) || !Number.isSafeInteger(Number(line.variantId))) {
+    if (!/^[1-9]\d*$/.test(line.variantId ?? "") || !Number.isSafeInteger(Number(line.variantId))) {
       return { error: { code: "invalid_payload", message: `Line ${line.clientLineId} has no WooCommerce product id.` } };
     }
   }
-  const digits = p.display?.exponent ?? minorUnitDigits(p.currency);
+  const digits = p.display?.exponent ?? minorUnitDigits2(p.currency);
   const major = (minor) => (minor / 10 ** digits).toFixed(digits);
-  const cash = p.payments[0].method === "cash";
+  const line_items = [];
+  for (const line of p.lines) {
+    let subtotal = major(line.unitPriceMinor * line.quantity);
+    let total = major(line.unitPriceMinor * line.quantity - (line.discountMinor ?? 0));
+    if (line.taxInclusive ?? p.pricesIncludeTax) {
+      if ((line.discountMinor ?? 0) > 0) {
+        return { error: { code: "unsupported_tax_mode", message: "Discounted tax-inclusive lines are not supported for WooCommerce yet." } };
+      }
+      const netMicros = local?.lines.find((stored) => stored.id === line.clientLineId)?.netMicros;
+      if (netMicros === void 0) {
+        return { error: { code: "unsupported_tax_mode", message: "Tax-inclusive prices need the till's WooCommerce tax figures; update the till." } };
+      }
+      const net = BigInt(netMicros), divisor = 10n ** BigInt(digits);
+      if (net < 0n) {
+        return { error: { code: "invalid_payload", message: `Line ${line.clientLineId} has a negative net.` } };
+      }
+      if (net % divisor !== 0n) {
+        return { error: { code: "invalid_payload", message: `Line ${line.clientLineId} has a net finer than 6 decimals.` } };
+      }
+      const micros = net / divisor;
+      subtotal = total = `${micros / 1000000n}.${(micros % 1000000n).toString().padStart(6, "0")}`;
+    }
+    line_items.push({ product_id: Number(line.variantId), quantity: line.quantity, subtotal, total });
+  }
+  const primary = p.payments.reduce((largest, payment) => payment.amountMinor > largest.amountMinor ? payment : largest);
+  const cash = primary.method === "cash";
+  const meta_data = [{ key: "_woocommerce_pos_uuid", value: p.clientOrderId }];
+  if (p.payments.length > 1) {
+    meta_data.push({ key: "_woocommerce_pos_payments", value: JSON.stringify(p.payments.map((payment) => ({
+      method: payment.method === "cash" ? "pos_cash" : "pos_card",
+      title: payment.method === "cash" ? "Cash" : "Card",
+      amount: major(payment.amountMinor),
+      ...payment.reference !== void 0 ? { reference: payment.reference } : {},
+      ...payment.method === "cash" && payment.tenderedMinor !== void 0 ? { tendered: major(payment.tenderedMinor) } : {},
+      ...payment.method === "cash" && payment.changeMinor !== void 0 ? { change: major(payment.changeMinor) } : {}
+    }))) });
+  }
   return { payload: {
     status: "completed",
     set_paid: true,
     currency: p.currency,
     payment_method: cash ? "pos_cash" : "pos_card",
     payment_method_title: cash ? "Cash" : "Card",
-    line_items: p.lines.map((line) => ({
-      product_id: Number(line.variantId),
-      quantity: line.quantity,
-      subtotal: major(line.unitPriceMinor * line.quantity),
-      total: major(line.unitPriceMinor * line.quantity - (line.discountMinor ?? 0))
-    })),
-    meta_data: [{ key: "_woocommerce_pos_uuid", value: p.clientOrderId }],
+    line_items,
+    meta_data,
     ...p.customer?.customerId && /^\d+$/.test(p.customer.customerId) ? { customer_id: Number(p.customer.customerId) } : {},
     ...p.customer?.email ? { billing: { email: p.customer.email } } : {}
   } };
@@ -746,10 +930,11 @@ function createWooCommandTransport(options) {
   let baseUrl = options.baseUrl;
   while (baseUrl.endsWith("/")) baseUrl = baseUrl.slice(0, -1);
   return {
-    async send(batch) {
+    async send(batch, context) {
+      const paymentsList = typeof options.acceptsPaymentsList === "function" ? await options.acceptsPaymentsList() : options.acceptsPaymentsList ?? false;
       const results = [];
       for (const envelope of batch) {
-        const mapped = toWooOrderPayload(envelope);
+        const mapped = toWooOrderPayload(envelope, context?.local?.orders?.get(envelope.id), { paymentsList });
         if ("error" in mapped) {
           results.push({ id: envelope.id, status: "rejected", error: mapped.error });
           continue;
@@ -827,11 +1012,11 @@ function createWooCommandTransport(options) {
 }
 
 // src/index.ts
-import { ConnectorUnauthorizedError as ConnectorUnauthorizedError3 } from "@tallyui/core";
+import { ConnectorUnauthorizedError as ConnectorUnauthorizedError4 } from "@tallyui/core";
 function wcposClientPart(part) {
   return part.toLowerCase().replace(/[^a-z0-9._-]/g, "").slice(0, 32);
 }
-var WooMissingTokenError = class extends ConnectorUnauthorizedError2 {
+var WooMissingTokenError = class extends ConnectorUnauthorizedError3 {
   constructor() {
     super("WooCommerce credentials have no WCPOS access token: sign in again", 401);
     this.name = "WooMissingTokenError";
@@ -862,6 +1047,8 @@ var wooConnectorParts = {
   description: "Connect to WooCommerce stores via the REST API",
   icon: void 0,
   // TODO: WooCommerce logo
+  storeSettings: wooStoreSettings,
+  capabilities: readWooCapabilities,
   auth: {
     type: "WCPOS token",
     fields: [
@@ -905,7 +1092,8 @@ var wooConnectorParts = {
 };
 var woocommerceConnector = createWooCommerceConnector();
 export {
-  ConnectorUnauthorizedError3 as ConnectorUnauthorizedError,
+  ConnectorUnauthorizedError4 as ConnectorUnauthorizedError,
+  WOO_ORDER_CREATE_VERSION,
   WooDateFilterError,
   WooMissingTokenError,
   WooMissingUuidError,
@@ -914,6 +1102,7 @@ export {
   createWooCommandTransport,
   createWooCommerceConnector,
   createWooCustomers,
+  readWooCapabilities,
   toWooCustomer,
   toWooOrderPayload,
   wcposClientPart,
@@ -923,5 +1112,6 @@ export {
   wooProductSync,
   wooProductTraits,
   wooReconcileFingerprint,
+  wooStoreSettings,
   woocommerceConnector
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tallyui/connector-woocommerce",
-  "version": "3.2.0",
+  "version": "3.3.0",
   "type": "module",
   "description": "WooCommerce connector for Tally UI",
   "main": "./dist/index.js",
@@ -26,10 +26,10 @@
     "directory": "connectors/woocommerce"
   },
   "peerDependencies": {
-    "@tallyui/core": "^3.2.0"
+    "@tallyui/core": "^3.3.0"
   },
   "devDependencies": {
-    "@tallyui/database": "3.2.0",
+    "@tallyui/database": "3.3.0",
     "rxdb": "17.5.0"
   },
   "scripts": {

package/src/commands/transport.ts

@@ -12,6 +12,9 @@ export interface WooCommandTransportOptions {
   getHeaders: () => Record<string, string> | Promise<Record<string, string>>;
   fetch?: typeof fetch;
   timeoutMs?: number;
+  /** True when the store's `/status` lists `order_payments_list` (`ServerCapabilities.multiplePayments`): an order may
+   * then carry several payments, recorded in `_woocommerce_pos_payments`. */
+  acceptsPaymentsList?: boolean | (() => boolean | Promise<boolean>);
 }
 
 export function wooMinorFromDecimal(text: string, currency: string): number | undefined {
@@ -25,45 +28,88 @@ export function wooMinorFromDecimal(text: string, currency: string): number | un
   return moneyFromDecimalString(end ? `${whole}.${fraction.slice(0, end)}` : whole, currency)?.amount;
 }
 
-export function toWooOrderPayload(envelope: OrderCreateEnvelope): { payload: Record<string, unknown> } | { error: { code: string; message: string } } {
+export interface WooLocalOrder { lines: ReadonlyArray<{ id: string; netMicros?: string }> }
+
+export function toWooOrderPayload(envelope: OrderCreateEnvelope, local?: WooLocalOrder, options?: { paymentsList?: boolean }): { payload: Record<string, unknown> } | { error: { code: string; message: string } } {
   const p = envelope.payload;
-  if (p.pricesIncludeTax || p.lines.some((line) => line.taxInclusive === true)) {
-    return { error: { code: 'unsupported_tax_mode', message: 'Prices that include tax are not supported for WooCommerce yet.' } };
+  if (envelope.version === 5 && (p.fees?.length || p.shipping?.length || p.lines.some((line) => line.custom))) {
+    return { error: { code: 'invalid_payload', message: 'Fees, shipping and custom lines are not supported by this connector yet.' } };
   }
-  if (p.payments.length !== 1) {
+  if (p.payments.length === 0 || (p.payments.length > 1 && !options?.paymentsList)) {
     return { error: { code: 'invalid_payload', message: 'WooCommerce orders take one payment.' } };
   }
+  if (p.payments.length > 20) {
+    return { error: { code: 'invalid_payload', message: 'WooCommerce records at most 20 payments.' } };
+  }
+  if (p.payments.length > 1 && p.payments.reduce((sum, payment) => sum + payment.amountMinor, 0) !== p.totalMinor) {
+    return { error: { code: 'invalid_payload', message: 'Payments do not add up to the order total.' } };
+  }
   for (const line of p.lines) {
-    if (!/^[1-9]\d*$/.test(line.variantId) || !Number.isSafeInteger(Number(line.variantId))) {
+    if (!/^[1-9]\d*$/.test(line.variantId ?? '') || !Number.isSafeInteger(Number(line.variantId))) {
       return { error: { code: 'invalid_payload', message: `Line ${line.clientLineId} has no WooCommerce product id.` } };
     }
   }
   const digits = p.display?.exponent ?? minorUnitDigits(p.currency);
   const major = (minor: number) => (minor / 10 ** digits).toFixed(digits);
-  const cash = p.payments[0].method === 'cash';
+  const line_items = [];
+  for (const line of p.lines) {
+    let subtotal = major(line.unitPriceMinor * line.quantity);
+    let total = major(line.unitPriceMinor * line.quantity - (line.discountMinor ?? 0));
+    if (line.taxInclusive ?? p.pricesIncludeTax) {
+      if ((line.discountMinor ?? 0) > 0) {
+        return { error: { code: 'unsupported_tax_mode', message: 'Discounted tax-inclusive lines are not supported for WooCommerce yet.' } };
+      }
+      const netMicros = local?.lines.find((stored) => stored.id === line.clientLineId)?.netMicros;
+      if (netMicros === undefined) {
+        return { error: { code: 'unsupported_tax_mode', message: "Tax-inclusive prices need the till's WooCommerce tax figures; update the till." } };
+      }
+      const net = BigInt(netMicros), divisor = 10n ** BigInt(digits);
+      if (net < 0n) {
+        return { error: { code: 'invalid_payload', message: `Line ${line.clientLineId} has a negative net.` } };
+      }
+      if (net % divisor !== 0n) {
+        return { error: { code: 'invalid_payload', message: `Line ${line.clientLineId} has a net finer than 6 decimals.` } };
+      }
+      const micros = net / divisor;
+      subtotal = total = `${micros / 1000000n}.${(micros % 1000000n).toString().padStart(6, '0')}`;
+    }
+    line_items.push({ product_id: Number(line.variantId), quantity: line.quantity, subtotal, total });
+  }
+  const primary = p.payments.reduce((largest, payment) => payment.amountMinor > largest.amountMinor ? payment : largest);
+  const cash = primary.method === 'cash';
+  const meta_data = [{ key: '_woocommerce_pos_uuid', value: p.clientOrderId }];
+  if (p.payments.length > 1) {
+    meta_data.push({ key: '_woocommerce_pos_payments', value: JSON.stringify(p.payments.map((payment) => ({
+      method: payment.method === 'cash' ? 'pos_cash' : 'pos_card',
+      title: payment.method === 'cash' ? 'Cash' : 'Card', amount: major(payment.amountMinor),
+      ...(payment.reference !== undefined ? { reference: payment.reference } : {}),
+      ...(payment.method === 'cash' && payment.tenderedMinor !== undefined ? { tendered: major(payment.tenderedMinor) } : {}),
+      ...(payment.method === 'cash' && payment.changeMinor !== undefined ? { change: major(payment.changeMinor) } : {}),
+    }))) });
+  }
   return { payload: {
     status: 'completed', set_paid: true, currency: p.currency,
     payment_method: cash ? 'pos_cash' : 'pos_card', payment_method_title: cash ? 'Cash' : 'Card',
-    line_items: p.lines.map((line) => ({
-      product_id: Number(line.variantId), quantity: line.quantity,
-      subtotal: major(line.unitPriceMinor * line.quantity),
-      total: major(line.unitPriceMinor * line.quantity - (line.discountMinor ?? 0)),
-    })),
-    meta_data: [{ key: '_woocommerce_pos_uuid', value: p.clientOrderId }],
+    line_items,
+    meta_data,
     ...(p.customer?.customerId && /^\d+$/.test(p.customer.customerId) ? { customer_id: Number(p.customer.customerId) } : {}),
     ...(p.customer?.email ? { billing: { email: p.customer.email } } : {}),
   } };
 }
 
-export function createWooCommandTransport(options: WooCommandTransportOptions): { send(batch: OrderCreateEnvelope[]): Promise<WooTransportOutcome> } {
+export function createWooCommandTransport(options: WooCommandTransportOptions): {
+  send(batch: OrderCreateEnvelope[], context?: { local?: { orders?: ReadonlyMap<string, WooLocalOrder> } }): Promise<WooTransportOutcome>;
+} {
   const fetch = options.fetch ?? globalThis.fetch;
   let baseUrl = options.baseUrl;
   while (baseUrl.endsWith('/')) baseUrl = baseUrl.slice(0, -1);
   return {
-    async send(batch) {
+    async send(batch, context) {
+      const paymentsList = typeof options.acceptsPaymentsList === 'function'
+        ? await options.acceptsPaymentsList() : options.acceptsPaymentsList ?? false;
       const results: CommandResult[] = [];
       for (const envelope of batch) {
-        const mapped = toWooOrderPayload(envelope);
+        const mapped = toWooOrderPayload(envelope, context?.local?.orders?.get(envelope.id), { paymentsList });
         if ('error' in mapped) {
           results.push({ id: envelope.id, status: 'rejected', error: mapped.error });
           continue;

package/src/index.ts

@@ -7,6 +7,7 @@ import { wooProductReplication } from './replication/products';
 import { wooCatalogueReconcile } from './reconcile/catalogue';
 import { createWooReconcileFeed, MAX_IDS_PER_REQUEST } from './reconcile/feed';
 import { createWooCustomers } from './customers';
+import { wooStoreSettings, readWooCapabilities } from './store-settings';
 import { version } from '../package.json';
 
 /** One part of X-WCPOS-Client as WCPOS keeps it: lowercase [a-z0-9._-], at most 32 characters. */
@@ -66,6 +67,8 @@ const wooConnectorParts = {
   name: 'WooCommerce',
   description: 'Connect to WooCommerce stores via the REST API',
   icon: undefined, // TODO: WooCommerce logo
+  storeSettings: wooStoreSettings,
+  capabilities: readWooCapabilities,
 
   auth: {
     type: 'WCPOS token',
@@ -119,6 +122,7 @@ const wooConnectorParts = {
 export const woocommerceConnector: TallyConnector = createWooCommerceConnector();
 
 // Re-export pieces for advanced usage
+export { wooStoreSettings, readWooCapabilities, WOO_ORDER_CREATE_VERSION } from './store-settings';
 export { createWooCustomers, toWooCustomer } from './customers';
 export { createWooCommandTransport, toWooOrderPayload, type WooCommandTransportOptions } from './commands/transport';
 export { ConnectorUnauthorizedError } from '@tallyui/core';

package/src/replication/products.ts

@@ -85,10 +85,11 @@ export function wooProductBarcode(product: any): string | undefined {
 
 export function toVariationDocument(payload: any) {
   const { id, sku, price, regular_price, sale_price, on_sale, stock_status,
-    stock_quantity, manage_stock, status, purchasable } = payload;
+    stock_quantity, manage_stock, status, purchasable, tax_class, tax_status } = payload;
   return Object.fromEntries(Object.entries({
     id, sku, barcode: wooProductBarcode(payload), price, regular_price, sale_price, on_sale,
     stock_status, stock_quantity, manage_stock, status, purchasable,
+    tax_class, tax_status,
     attributes: (payload.attributes ?? []).map(({ name, option }: any) => ({ name, option })),
   }).filter(([, value]) => value !== undefined));
 }

package/src/schemas/products.ts

@@ -7,7 +7,7 @@ import type { RxJsonSchema } from 'rxdb';
  */
 export const wooProductSchema: RxJsonSchema<any> = {
   title: 'WooCommerce Product',
-  version: 1,
+  version: 2,
   type: 'object',
   primaryKey: 'uuid',
   properties: {
@@ -53,6 +53,12 @@ export const wooProductSchema: RxJsonSchema<any> = {
     sale_price: {
       type: 'string',
     },
+    tax_class: {
+      type: 'string',
+    },
+    tax_status: {
+      type: 'string',
+    },
     on_sale: {
       type: 'boolean',
     },
@@ -134,6 +140,7 @@ export const wooProductSchema: RxJsonSchema<any> = {
     variation_docs: { type: 'array', items: { type: 'object', properties: {
       id: { type: 'integer' }, sku: { type: 'string' }, barcode: { type: 'string' },
       price: { type: 'string' }, regular_price: { type: 'string' }, sale_price: { type: 'string' },
+      tax_class: { type: 'string' }, tax_status: { type: 'string' },
       on_sale: { type: 'boolean' }, stock_status: { type: 'string' }, stock_quantity: { type: ['number', 'null'] },
       manage_stock: { type: 'boolean' }, status: { type: 'string' }, purchasable: { type: 'boolean' },
       attributes: { type: 'array', items: { type: 'object', properties: { name: { type: 'string' }, option: { type: 'string' } } } },

package/src/store-settings.ts

@@ -0,0 +1,128 @@
+import { ConnectorUnauthorizedError, StoreSettingsError, minorUnitDigits, woocommerceTax } from '@tallyui/core';
+import type { ServerCapabilities, StoreSettings, SyncContext } from '@tallyui/core';
+
+/** The highest order.create version the WooCommerce transport maps: discounts and the customer (v3). It rises when the transport maps split payments (v4) and fees, shipping and custom lines (v5). */
+export const WOO_ORDER_CREATE_VERSION = 3;
+
+export async function wooStoreSettings(context: SyncContext): Promise<StoreSettings> {
+  try {
+    const init = { method: 'GET', headers: context.headers, signal: context.signal };
+    const storesResponse = await fetch(`${context.baseUrl}/stores`, init);
+    if (storesResponse.status === 401 || storesResponse.status === 403) {
+      throw new ConnectorUnauthorizedError(`WooCommerce stores: HTTP ${storesResponse.status}`, storesResponse.status);
+    }
+    if (!storesResponse.ok) throw new Error(`WooCommerce stores: HTTP ${storesResponse.status}`);
+    const stores = await storesResponse.json();
+    if (!Array.isArray(stores) || stores.length === 0) throw new Error('WooCommerce stores: expected a non-empty array');
+    const store = stores[0];
+    const currency = store.currency.toUpperCase();
+    const digits = minorUnitDigits(currency);
+    if (typeof store.price_num_decimals === 'number' && store.price_num_decimals !== digits) {
+      console.warn(`WooCommerce price_num_decimals is ${store.price_num_decimals}; the till rounds ${currency} to ${digits} digits`);
+    }
+
+    const classesResponse = await fetch(`${context.baseUrl}/taxes/classes`, init);
+    if (classesResponse.status === 401 || classesResponse.status === 403) {
+      throw new ConnectorUnauthorizedError(`WooCommerce tax classes: HTTP ${classesResponse.status}`, classesResponse.status);
+    }
+    if (!classesResponse.ok) throw new Error(`WooCommerce tax classes: HTTP ${classesResponse.status}`);
+    const classes = await classesResponse.json();
+    if (!Array.isArray(classes)) throw new Error('WooCommerce tax classes: expected an array');
+
+    const taxRates: NonNullable<StoreSettings['taxRates']> = {};
+    /** Simple-rate view for strategies other than `woocommerce`; the WooCommerce strategy reads `taxRates`. */
+    const taxRatesPpm: StoreSettings['taxRatesPpm'] = { default: 0 };
+    const settings: StoreSettings = {
+      currency,
+      pricesIncludeTax: store.prices_include_tax === 'yes',
+      taxRoundAtSubtotal: store.tax_round_at_subtotal === 'yes',
+      ...(typeof store.shipping_tax_class === 'string' ? { shippingTaxClass: store.shipping_tax_class } : {}),
+      taxClassSlugs: classes.map((row) => row.slug),
+      taxRates,
+      taxRatesPpm,
+    };
+    if (store.calc_taxes !== 'yes') return settings;
+
+    const rates: woocommerceTax.WooTaxRate[] = [];
+    for (let page = 1; page <= 100; page++) {
+      const response = await fetch(`${context.baseUrl}/taxes?per_page=100&page=${page}&orderby=order&order=asc`, init);
+      if (response.status === 401 || response.status === 403) {
+        throw new ConnectorUnauthorizedError(`WooCommerce taxes: HTTP ${response.status}`, response.status);
+      }
+      if (!response.ok) throw new Error(`WooCommerce taxes: HTTP ${response.status}`);
+      const rows = await response.json();
+      if (!Array.isArray(rows)) throw new Error('WooCommerce taxes: expected an array');
+      rates.push(...rows.map((row: woocommerceTax.WooTaxRate) => ({
+        ...row, postcodes: row.postcodes ?? [], cities: row.cities ?? [],
+      })));
+      if (rows.length < 100) break;
+    }
+
+    const taxAddress = store.tax_address;
+    let address = taxAddress && typeof taxAddress === 'object' && typeof taxAddress.country === 'string' && taxAddress.country.length > 0
+      ? taxAddress
+      : { country: store.store_country, state: store.store_state, postcode: store.store_postcode, city: store.store_city };
+    if (!address.country) {
+      console.warn('WooCommerce has no tax or store country; matching tax rates with an empty address');
+      address = {};
+    }
+    const matched = woocommerceTax.filterTaxRates(rates, address.country, address.state, address.postcode, address.city);
+    for (const rate of matched) {
+      const slug = woocommerceTax.normalizeTaxClass(rate.class);
+      (taxRates[slug] ??= []).push({
+        id: rate.id,
+        code: [rate.country, rate.state, rate.name || 'TAX', String(rate.priority)].filter(Boolean).join('-').toUpperCase(),
+        label: rate.name,
+        rate: rate.rate,
+        priority: rate.priority,
+        compound: rate.compound,
+        shipping: rate.shipping,
+      });
+      const key = slug === 'standard' ? 'default' : slug;
+      taxRatesPpm[key] = (taxRatesPpm[key] ?? 0) + Math.round(Number(rate.rate) * 10000);
+    }
+    return settings;
+  } catch (error) {
+    if (error instanceof ConnectorUnauthorizedError) throw error;
+    throw new StoreSettingsError('failed', error instanceof Error ? error.message : String(error));
+  }
+}
+
+export async function readWooCapabilities(context: SyncContext): Promise<ServerCapabilities | undefined> {
+  try {
+    const response = await fetch(`${context.baseUrl}/stores`, {
+      method: 'GET', headers: context.headers, signal: context.signal,
+    });
+    if (response.status === 401 || response.status === 403) {
+      throw new ConnectorUnauthorizedError(`WooCommerce stores: HTTP ${response.status}`, response.status);
+    }
+    if (!response.ok) return undefined;
+    const stores = await response.json();
+    if (!Array.isArray(stores) || !stores[0] || typeof stores[0] !== 'object' || Array.isArray(stores[0])) return undefined;
+    let multiplePayments = false;
+    try {
+      const status = await fetch(`${context.baseUrl}/status`, {
+        method: 'GET', headers: context.headers, signal: context.signal,
+      });
+      if (status.status === 401 || status.status === 403) {
+        throw new ConnectorUnauthorizedError(`WooCommerce status: HTTP ${status.status}`, status.status);
+      }
+      if (status.ok) {
+        const body = await status.json();
+        multiplePayments = Array.isArray(body?.capabilities) && body.capabilities.includes('order_payments_list');
+      }
+    } catch (error) {
+      if (error instanceof ConnectorUnauthorizedError) throw error;
+    }
+    return {
+      orderCreate: WOO_ORDER_CREATE_VERSION,
+      taxRounding: { granularity: 'woocommerce', roundAtSubtotal: stores[0].tax_round_at_subtotal === 'yes' },
+      multiplePayments,
+      // WCPOS always takes a fee's, shipping line's and custom line's tax_status and tax_class (orders #146, #161); it has no /tally/v1/info.
+      lineTax: { none: true, classes: true },
+    };
+  } catch (error) {
+    if (error instanceof ConnectorUnauthorizedError) throw error;
+    return undefined;
+  }
+}

package/src/traits/product.ts

@@ -22,6 +22,22 @@ export const wooProductTraits: ProductTraits = {
 
   getSku: (doc) => doc.sku || undefined,
 
+  getTaxClass: (doc, variantId) => {
+    const variation = variantId === undefined ? undefined
+      : doc.variation_docs?.find((v: any) => String(v.id) === variantId);
+    const taxClass = typeof variation?.tax_class === 'string' && variation.tax_class !== 'parent'
+      ? variation.tax_class : doc.tax_class;
+    return taxClass === undefined || taxClass === '' || taxClass === 'standard' ? undefined : taxClass;
+  },
+
+  getTaxStatus: (doc, variantId) => {
+    const variation = variantId === undefined ? undefined
+      : doc.variation_docs?.find((v: any) => String(v.id) === variantId);
+    const taxStatus = typeof variation?.tax_status === 'string' ? variation.tax_status : doc.tax_status;
+    if (taxStatus === 'none' || taxStatus === 'shipping') return 'none';
+    return taxStatus === 'taxable' ? 'taxable' : undefined;
+  },
+
   getPrices: (doc, context) => {
     // Woo prices are decimal strings with no currency; the store supplies it.
     const currency = context?.currency ?? 'XXX';