@tallyui/connector-woocommerce 1.0.0 → 3.0.0-next.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Paul Kilmurray and TallyUI contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,40 @@
+# TallyUI WooCommerce connector
+
+## Requirements
+
+- **WooCommerce 5.8 or later.** The product pull filters by modification date with `modified_after`, added in WooCommerce 5.8, and compares it in GMT with `dates_are_gmt`, added in 5.4.
+- **The WCPOS Free plugin, 1.10.0 or later.** The connector reads through its `wcpos/v2` routes, which add each product's `uuid`. Set `SyncContext.baseUrl` to `<site>/wp-json/wcpos/v2`.
+
+## Authentication
+
+`auth.getHeaders({ token })` sends the WCPOS access token as `Authorization: Bearer <token>`, together with the POS marker `X-WCPOS: 1`. Without a token it throws `WooMissingTokenError`. WooCommerce consumer keys are not supported.
+
+It also sends `X-WCPOS-Protocol: 2`, which WCPOS 2.0 requires of POS requests, and `X-WCPOS-Client: tallyui/<connector version>` (lowercase `[a-z0-9._-]`, at most 32 characters), which WCPOS uses only for consent-gated telemetry.
+
+## Product pull
+
+The pull works in passes:
+- a small request finds the store's newest `date_modified_gmt`;
+- the pass then pages every product modified since the last pass, by id with an offset;
+- if a product leaves the window mid-pass (read from `X-WP-Total`), the pass restarts.
+
+When nothing has changed, a poll costs one request. Products whose `status` is not `publish` reach the till as deletions.
+
+Dates are sent as GMT digits **without** a timezone offset, together with `dates_are_gmt=true`. WordPress parses an offset-bearing date in the site's timezone before it compares it with the GMT column, so an explicit offset would shift the filter by the site's UTC offset.
+
+## Reconciliation
+
+The incremental pull can miss an edit: a `modified_after` that over-excludes (including a bound in the site's spring-forward hour), an edit in the same second as the last mark, a removal mid-pass on a store that hides `X-WP-Total`, a trashed product, or a stock change written without a modified-time bump. `reconcile.catalogue` is the daily safety net for all of them. Run it with `@tallyui/database`'s `startCatalogueReconcile`, beside the product replication, on the same collection.
+- It reads `wcpos/v2/status` once per pass, then lists every published product (`status=publish`, `_fields=id,uuid,date_modified_gmt,stock_quantity,stock_status`, 100 per page) with no date filter. A failed status read only means no capability is known; a rejected token (401, 403) or a till that needs updating (426) stops the pass.
+- A product whose `(date_modified_gmt, stock_quantity, stock_status)` differs from the till's copy, or that the till lacks, is refetched by id through the product pull (`replication.products` combines the product feed with a reconcile feed). Nothing is written locally.
+- A product the till holds but the listing omits is removed only when a by-id re-read (`include=`, `status=any`) finds it gone, trashed or unpublished, and within the runner's mass-delete brake.
+- A product hidden from the POS after it synced (WCPOS "online only" visibility, with POS-only products turned on) is removed from the till by the pass; hiding many at once is held by the mass-delete brake.
+- An existing install keeps its pull checkpoint: the combined pull reads it under `legacyKey: 'products'`.
+- The WCPOS bulk-id fast path is dormant: it is chosen only when `status.capabilities` includes `products_id_fast_path` (wcpos/woocommerce-pos#2113), and until its id-to-uuid mapping exists the listing stays paged.
+
+## Errors
+
+- `ConnectorUnauthorizedError` (`code: 'unauthorized'`), from `@tallyui/core` and re-exported here: the store rejected the token (401 or 403), or `WooMissingTokenError` (a subclass) was thrown for a missing token. The app should sign in again.
+- `WooDateFilterError` (`code: 'unsupported_store'`): the store returned a product outside the requested date window, so it does not honour `modified_after` (WooCommerce before 5.8, or a proxy that drops the parameter). An app should show its own words for the `code`; the message, `This store needs WooCommerce 5.8 or later to sync products.`, is a plain fallback. The diagnostics are in `productId`, `bound` (the `modified_after` sent) and `received`. Today the pull retries a failed request every 5 s (RxDB's `retryTime`), one mark request each time. Stopping on errors that cannot recover is shared replication work.
+- `WooTillUpdateRequiredError` (`code: 'till_update_required'`, `fixedBy: 'till'`): the store answered 426, normally WCPOS's protocol gate (`serverCode: 'wcpos_update_required'`), so this till must be updated; the pull pauses until `resume()`.
+- `WooMissingUuidError`: a product came back without a `uuid`, so the store is not running the WCPOS Free plugin 1.10.0 or later, or the connector is not reaching it through `wcpos/v2`.

package/dist/index.d.ts

@@ -1,4 +1,5 @@
-import { ProductTraits, CollectionSync, ReplicationAdapter, TallyConnector } from '@tallyui/core';
+import { ProductTraits, CollectionSync, ReplicationAdapter, ReconcileFeed, CatalogueReconcileAdapter, ConnectorUnauthorizedError, TallyConnector } from '@tallyui/core';
+export { ConnectorUnauthorizedError } from '@tallyui/core';
 import { RxJsonSchema } from 'rxdb';
 
 /**
@@ -26,33 +27,101 @@ declare const wooProductTraits: ProductTraits;
 declare const wooProductSync: CollectionSync;
 
 type WooProductCheckpoint = {
-    id: string;
+    /** Inclusive lower bound (date_modified_gmt) of the current pass; '' = the whole catalogue. */
     modified: string;
+    /** Rows of the current pass already returned, in id order. */
+    offset: number;
+    /** Newest date_modified_gmt in the store when the pass started; the next pass's lower bound. */
+    pass_mark?: string;
+    /** X-WP-Total of the window on the last page; undefined when the store sends none. */
+    pass_count?: number;
 };
+/** WCPOS's protocol gate refused this till (HTTP 426 with `wcpos_update_required`): only updating the till fixes it. */
+declare class WooTillUpdateRequiredError extends Error {
+    readonly serverCode: string | undefined;
+    name: string;
+    readonly code: "till_update_required";
+    /** Only updating this till fixes it, so the pull pauses until resume() (`errorKind`). */
+    readonly fixedBy: "till";
+    /** The body's `code`, kept for diagnostics. */
+    constructor(serverCode: string | undefined);
+}
+declare class WooMissingUuidError extends Error {
+    name: string;
+    readonly code: "missing_plugin";
+    /** Only the store owner can fix it, by installing or enabling the plugin, so the pull waits the store delay (`errorKind`). */
+    readonly fixedBy: "store";
+    productId: number;
+    constructor(id: number);
+}
+/** The store returned a product outside a modified_after window, so it does not apply the filter. */
+declare class WooDateFilterError extends Error {
+    readonly productId: number | undefined;
+    readonly bound: string;
+    readonly received: string | undefined;
+    name: string;
+    readonly code: "unsupported_store";
+    /** Only the store owner can fix it, by updating WooCommerce, so the pull waits the store delay (`errorKind`). */
+    readonly fixedBy: "store";
+    /** The software to update, for `SyncStatus`'s detail; the component never names it itself. */
+    readonly software = "WooCommerce";
+    /** The first WooCommerce version that applies `modified_after` (5.8). */
+    readonly minVersion = "5.8";
+    constructor(productId: number | undefined, bound: string, received: string | undefined);
+}
 /**
  * Replication adapter for WooCommerce products.
  *
- * Implements pull (cursor-based pagination by date_modified_gmt) and push
- * (individual create/update via WC REST API v3). Designed for use with
- * RxDB's replicateRxCollection.
+ * Pull-only (id-ordered offset pages within a date_modified_gmt window) for RxDB's
+ * replicateRxCollection. Catalogue data is server-owned; the POS never
+ * writes products.
  */
 declare const wooProductReplication: ReplicationAdapter<any, WooProductCheckpoint>;
 
 /**
- * WooCommerce connector for Tally UI.
+ * What the catalogue reconcile compares: the modified time and the stock (#248 A1). WooCommerce's
+ * `update_product_stock()` writes `_stock` by a direct query that leaves the modified time alone.
+ */
+declare const wooReconcileFingerprint: (p: {
+    date_modified_gmt?: string | null;
+    stock_quantity?: number | null;
+    stock_status?: string | null;
+}) => string;
+/**
+ * The daily catalogue check for WooCommerce (#248): lists every published product with its fingerprint,
+ * page by page with no date filter, and hands differences to `feed`, which reaches the collection only
+ * through the pull. `confirmGone` is the deletion proof: a by-id re-read.
+ */
+declare function wooCatalogueReconcile(feed: Pick<ReconcileFeed<any>, 'enqueue'>): CatalogueReconcileAdapter<any, number>;
+
+/** One part of X-WCPOS-Client as WCPOS keeps it: lowercase [a-z0-9._-], at most 32 characters. */
+declare function wcposClientPart(part: string): string;
+declare class WooMissingTokenError extends ConnectorUnauthorizedError {
+    constructor();
+}
+/**
+ * WooCommerce connector for Tally UI. Build one per store session, anew on each sign-in or store change:
+ * it owns the reconcile feed, whose queued work must never reach another store's database (#307).
  *
- * Connects to WooCommerce sites via the REST API (v3) or WCPOS API.
+ * Requires the WCPOS Free plugin 1.10.0 or later. SyncContext.baseUrl must
+ * be the store's wcpos/v2 root: <site>/wp-json/wcpos/v2.
  * Products are stored in RxDB using a schema that mirrors the WC API shape.
  *
  * ```ts
- * import { woocommerceConnector } from '@tallyui/connector-woocommerce';
+ * import { createWooCommerceConnector } from '@tallyui/connector-woocommerce';
  * import { ConnectorProvider } from '@tallyui/core';
  *
- * <ConnectorProvider connector={woocommerceConnector}>
+ * const connector = useMemo(() => createWooCommerceConnector(), [storeUrl]);
+ * <ConnectorProvider connector={connector}>
  *   <App />
  * </ConnectorProvider>
  * ```
  */
+declare function createWooCommerceConnector(): TallyConnector;
+/**
+ * @deprecated One instance for the whole app: a store switch can leak queued reconcile work across stores.
+ * Use createWooCommerceConnector() per store session. Removed in 4.0.
+ */
 declare const woocommerceConnector: TallyConnector;
 
-export { wooProductReplication, wooProductSchema, wooProductSync, wooProductTraits, woocommerceConnector };
+export { WooDateFilterError, WooMissingTokenError, WooMissingUuidError, WooTillUpdateRequiredError, createWooCommerceConnector, wcposClientPart, wooCatalogueReconcile, wooProductReplication, wooProductSchema, wooProductSync, wooProductTraits, wooReconcileFingerprint, woocommerceConnector };

package/dist/index.js

@@ -1,3 +1,6 @@
+// src/index.ts
+import { combinePullAdapters, ConnectorUnauthorizedError as ConnectorUnauthorizedError2 } from "@tallyui/core";
+
 // src/schemas/products.ts
 var wooProductSchema = {
   title: "WooCommerce Product",
@@ -144,10 +147,29 @@ var wooProductSchema = {
 };
 
 // src/traits/product.ts
+import { moneyFromMajor } from "@tallyui/core";
+var WOO_STOCK_STATUS = {
+  instock: "in_stock",
+  outofstock: "out_of_stock",
+  onbackorder: "backorder"
+};
 var wooProductTraits = {
   getId: (doc) => String(doc.id),
   getName: (doc) => doc.name ?? "",
   getSku: (doc) => doc.sku || void 0,
+  getPrices: (doc, context) => {
+    const currency = context?.currency ?? "XXX";
+    const prices = [];
+    const base = moneyFromMajor(doc.regular_price || doc.price, currency);
+    if (base) prices.push({ ...base, kind: "base" });
+    const sale = doc.on_sale === true ? moneyFromMajor(doc.sale_price, currency) : void 0;
+    if (sale) prices.push({ ...sale, kind: "sale" });
+    return prices;
+  },
+  getStock: (doc) => ({
+    status: WOO_STOCK_STATUS[doc.stock_status] ?? "unknown",
+    quantity: doc.manage_stock === false ? void 0 : doc.stock_quantity ?? void 0
+  }),
   getPrice: (doc) => doc.price || void 0,
   getRegularPrice: (doc) => doc.regular_price || void 0,
   getSalePrice: (doc) => doc.sale_price || void 0,
@@ -164,6 +186,8 @@ var wooProductTraits = {
   },
   getStockQuantity: (doc) => doc.stock_quantity ?? null,
   hasVariants: (doc) => doc.type === "variable",
+  isSellable: (doc) => doc.status === void 0 || doc.status === "publish",
+  getVariantCount: (doc) => doc.type === "variable" ? doc.variations?.length ?? 0 : 1,
   getType: (doc) => doc.type ?? "simple",
   getBarcode: (doc) => doc.barcode || void 0,
   getCategoryNames: (doc) => (doc.categories ?? []).map((cat) => cat.name).filter(Boolean)
@@ -206,8 +230,13 @@ var wooProductSync = {
     return response.json();
   },
   async fetchModifiedAfter(date, context) {
+    const params = new URLSearchParams({
+      modified_after: date,
+      dates_are_gmt: "true",
+      per_page: "100"
+    });
     const response = await fetch(
-      `${context.baseUrl}/products?modified_after=${date}&per_page=100`,
+      `${context.baseUrl}/products?${params}`,
       {
         headers: {
           ...context.headers,
@@ -224,17 +253,98 @@ var wooProductSync = {
 };
 
 // src/replication/products.ts
+import { ConnectorUnauthorizedError } from "@tallyui/core";
+var MAX_REQUESTS_PER_CALL = 4;
+var MAX_STORE_MESSAGE = 200;
+async function checkResponse(response) {
+  if (response.ok) return;
+  if (response.status === 401 || response.status === 403) {
+    throw new ConnectorUnauthorizedError(`WooCommerce API error: ${response.status}`, response.status);
+  }
+  if (response.status === 426) {
+    const body = await response.json().catch(() => void 0);
+    if (body?.code === "wcpos_update_required") throw new WooTillUpdateRequiredError(body.code);
+    const code = typeof body?.code === "string" && body.code ? ` (${body.code})` : "";
+    const text = typeof body?.message === "string" ? body.message : "";
+    const message = text ? `: ${text.length > MAX_STORE_MESSAGE ? `${text.slice(0, MAX_STORE_MESSAGE)}\u2026` : text}` : "";
+    throw new Error(`WooCommerce API error: 426${code}${message}`);
+  }
+  throw new Error(`WooCommerce API error: ${response.status}`);
+}
+var WooTillUpdateRequiredError = class extends Error {
+  /** The body's `code`, kept for diagnostics. */
+  constructor(serverCode) {
+    super("WooCommerce API error: 426: this till needs updating to sync with the store");
+    this.serverCode = serverCode;
+  }
+  name = "WooTillUpdateRequiredError";
+  code = "till_update_required";
+  /** Only updating this till fixes it, so the pull pauses until resume() (`errorKind`). */
+  fixedBy = "till";
+};
+var WooMissingUuidError = class extends Error {
+  name = "WooMissingUuidError";
+  code = "missing_plugin";
+  /** Only the store owner can fix it, by installing or enabling the plugin, so the pull waits the store delay (`errorKind`). */
+  fixedBy = "store";
+  productId;
+  constructor(id) {
+    super(`WooCommerce product ${id} has no uuid: the store must run the WCPOS Free plugin (1.10.0 or later) and be reached through its wcpos/v2 routes`);
+    this.productId = id;
+  }
+};
+function toProductDocument(product) {
+  if (typeof product.uuid !== "string" || product.uuid.length === 0) throw new WooMissingUuidError(product.id);
+  return { ...product, _deleted: product.status !== "publish" };
+}
+var WooDateFilterError = class extends Error {
+  constructor(productId, bound, received) {
+    super("This store needs WooCommerce 5.8 or later to sync products.");
+    this.productId = productId;
+    this.bound = bound;
+    this.received = received;
+  }
+  name = "WooDateFilterError";
+  code = "unsupported_store";
+  /** Only the store owner can fix it, by updating WooCommerce, so the pull waits the store delay (`errorKind`). */
+  fixedBy = "store";
+  /** The software to update, for `SyncStatus`'s detail; the component never names it itself. */
+  software = "WooCommerce";
+  /** The first WooCommerce version that applies `modified_after` (5.8). */
+  minVersion = "5.8";
+};
 var wooProductReplication = {
   pull: {
-    async handler(lastCheckpoint, batchSize, context) {
+    handler: async function pull(lastCheckpoint, batchSize, context, requests = 0) {
+      const modified = lastCheckpoint?.modified ?? "";
+      const offset = lastCheckpoint?.offset ?? 0;
+      const spent = { documents: [], checkpoint: lastCheckpoint ?? { modified, offset } };
+      let passMark = lastCheckpoint?.pass_mark ?? modified;
+      if (offset === 0 && lastCheckpoint?.pass_mark === void 0) {
+        if (requests++ >= MAX_REQUESTS_PER_CALL) return spent;
+        const newer = modified ? { modified_after: modified, dates_are_gmt: "true" } : {};
+        const mark = new URLSearchParams({ per_page: "1", orderby: "modified", order: "desc", ...newer });
+        const markResponse = await fetch(
+          `${context.baseUrl}/products?${mark}`,
+          { headers: { ...context.headers, "Content-Type": "application/json" }, signal: context.signal }
+        );
+        await checkResponse(markResponse);
+        const [newest] = await markResponse.json();
+        if (newest === void 0) return { documents: [], checkpoint: lastCheckpoint ?? { modified: "", offset: 0 } };
+        if (modified && !(newest.date_modified_gmt > modified)) throw new WooDateFilterError(newest.id, modified, newest.date_modified_gmt);
+        passMark = newest.date_modified_gmt ?? modified;
+      }
       const params = new URLSearchParams({
         per_page: String(batchSize),
-        orderby: "modified",
+        offset: String(offset),
+        orderby: "id",
         order: "asc"
       });
-      if (lastCheckpoint?.modified) {
-        params.set("modified_after", lastCheckpoint.modified);
+      if (modified) {
+        params.set("modified_after", new Date(Date.parse(modified + "Z") - 1e3).toISOString().slice(0, 19));
+        params.set("dates_are_gmt", "true");
       }
+      if (requests++ >= MAX_REQUESTS_PER_CALL) return spent;
       const response = await fetch(`${context.baseUrl}/products?${params}`, {
         headers: {
           ...context.headers,
@@ -242,61 +352,154 @@ var wooProductReplication = {
         },
         signal: context.signal
       });
-      if (!response.ok) {
-        throw new Error(`WooCommerce API error: ${response.status}`);
-      }
+      await checkResponse(response);
       const products = await response.json();
-      const documents = products.map((p) => ({ ...p, _deleted: false }));
-      const checkpoint = products.length > 0 ? {
-        id: String(products[products.length - 1].uuid ?? products[products.length - 1].id),
-        modified: products[products.length - 1].date_modified_gmt
-      } : lastCheckpoint ?? { id: "", modified: "" };
-      return { documents, checkpoint };
-    }
-  },
-  push: {
-    async handler(changeRows, context) {
-      const conflicts = [];
-      for (const row of changeRows) {
-        const doc = row.newDocumentState;
-        try {
-          const isCreate = !row.assumedMasterState;
-          const method = isCreate ? "POST" : "PUT";
-          const url = isCreate ? `${context.baseUrl}/products` : `${context.baseUrl}/products/${doc.id}`;
-          const response = await fetch(url, {
-            method,
-            headers: {
-              ...context.headers,
-              "Content-Type": "application/json"
-            },
-            body: JSON.stringify(doc),
-            signal: context.signal
-          });
-          if (!response.ok) {
-            if (row.assumedMasterState) {
-              conflicts.push({ ...row.assumedMasterState, _deleted: false });
-            }
-          }
-        } catch {
-          if (row.assumedMasterState) {
-            conflicts.push({ ...row.assumedMasterState, _deleted: false });
-          }
+      const total = response.headers.get("X-WP-Total");
+      const count = total !== null && /^\d+$/.test(total) ? Number(total) : void 0;
+      if (offset > 0 && count !== void 0 && (products.length === 0 || count < (lastCheckpoint?.pass_count ?? count))) {
+        return pull({ modified, offset: 0, pass_mark: passMark }, batchSize, context, requests);
+      }
+      const documents = products.map((product) => {
+        const document = toProductDocument(product);
+        if (modified && !(product.date_modified_gmt >= modified)) {
+          throw new WooDateFilterError(product.id, params.get("modified_after"), product.date_modified_gmt);
         }
+        return document;
+      });
+      const complete = count === void 0 ? products.length < batchSize : offset + products.length >= count;
+      const checkpoint = complete ? { modified: passMark, offset: 0, pass_mark: void 0, pass_count: void 0 } : { modified, offset: offset + products.length, pass_mark: passMark, pass_count: count };
+      if (complete && products.length === 0) {
+        const next = await pull({ modified: passMark, offset: 0 }, batchSize, context, requests);
+        return next.documents.length > 0 ? next : { documents: [], checkpoint: lastCheckpoint ?? checkpoint };
       }
-      return conflicts;
+      return { documents, checkpoint };
     }
   }
 };
 
+// src/reconcile/catalogue.ts
+import { errorKind } from "@tallyui/core";
+var PAGE_SIZE = 100;
+var LISTING_FIELDS = "id,uuid,date_modified_gmt,stock_quantity,stock_status";
+var ID_FAST_PATH = "products_id_fast_path";
+var wooReconcileFingerprint = (p) => [p.date_modified_gmt ?? "", p.stock_quantity ?? "", p.stock_status ?? ""].join("|");
+async function get(path, context) {
+  const response = await fetch(`${context.baseUrl}${path}`, {
+    headers: { ...context.headers, "Content-Type": "application/json" },
+    signal: context.signal
+  });
+  await checkResponse(response);
+  return response.json();
+}
+async function wooHasIdFastPath(context) {
+  let status;
+  try {
+    status = await get("/status", context);
+  } catch (error) {
+    if (errorKind(error) === "till" || context.signal?.aborted) throw error;
+    return false;
+  }
+  return Array.isArray(status?.capabilities) && status.capabilities.includes(ID_FAST_PATH);
+}
+function wooCatalogueReconcile(feed) {
+  return {
+    async *fetchPages(context, from = 1) {
+      const fast = await wooHasIdFastPath(context);
+      yield { entries: [], cursor: from };
+      if (fast) {
+      }
+      for (let page = from; ; page++) {
+        const params = new URLSearchParams({
+          per_page: String(PAGE_SIZE),
+          page: String(page),
+          orderby: "id",
+          order: "asc",
+          status: "publish",
+          _fields: LISTING_FIELDS
+        });
+        const rows = await get(`/products?${params}`, context);
+        const entries = rows.map((row) => {
+          if (typeof row.uuid !== "string" || row.uuid.length === 0) throw new WooMissingUuidError(row.id);
+          return { key: row.uuid, fingerprint: wooReconcileFingerprint(row), remote: row.id };
+        });
+        yield { entries, cursor: page + 1 };
+        if (rows.length < PAGE_SIZE) return;
+      }
+    },
+    fingerprint: wooReconcileFingerprint,
+    async confirmGone(locals, context) {
+      const ids = locals.map((doc) => doc.id).filter((id) => Number.isInteger(id));
+      if (!ids.length) return [];
+      const params = new URLSearchParams({ include: ids.join(","), per_page: String(PAGE_SIZE), status: "any", _fields: "id,uuid,status" });
+      const rows = await get(`/products?${params}`, context);
+      const live = new Set(rows.filter((row) => row.status === "publish").map((row) => row.id));
+      return locals.filter((doc) => Number.isInteger(doc.id) && !live.has(doc.id)).map((doc) => doc.uuid);
+    },
+    // An entry with no numeric id, locally or in the listing, is dropped: the store cannot be asked about it, so
+    // the feed would find nothing and tombstone it without proof. (The schema requires only uuid.)
+    enqueue: (entries) => feed.enqueue(entries.filter((e) => e.tombstone || Number.isInteger(e.local?.id) || Number.isInteger(e.remote)))
+  };
+}
+
+// src/reconcile/feed.ts
+import { createReconcileFeed } from "@tallyui/core";
+var MAX_IDS_PER_REQUEST = 100;
+async function wooFetchByIds(entries, context) {
+  const ids = entries.map((e) => e.local?.id ?? e.remote).filter((id) => Number.isInteger(id));
+  const documents = [];
+  for (let i = 0; i < ids.length; i += MAX_IDS_PER_REQUEST) {
+    const chunk = ids.slice(i, i + MAX_IDS_PER_REQUEST);
+    const params = new URLSearchParams({ include: chunk.join(","), per_page: String(MAX_IDS_PER_REQUEST), status: "any" });
+    const response = await fetch(`${context.baseUrl}/products?${params}`, {
+      headers: { ...context.headers, "Content-Type": "application/json" },
+      signal: context.signal
+    });
+    await checkResponse(response);
+    documents.push(...(await response.json()).map(toProductDocument));
+  }
+  return documents;
+}
+function createWooReconcileFeed() {
+  return createReconcileFeed({ key: (doc) => doc.uuid, fetchByIds: wooFetchByIds });
+}
+
+// package.json
+var version = "3.0.0-next.0";
+
 // src/index.ts
-var woocommerceConnector = {
+import { ConnectorUnauthorizedError as ConnectorUnauthorizedError3 } from "@tallyui/core";
+function wcposClientPart(part) {
+  return part.toLowerCase().replace(/[^a-z0-9._-]/g, "").slice(0, 32);
+}
+var WooMissingTokenError = class extends ConnectorUnauthorizedError2 {
+  constructor() {
+    super("WooCommerce credentials have no WCPOS access token: sign in again");
+    this.name = "WooMissingTokenError";
+  }
+};
+function createWooCommerceConnector() {
+  const catalogueFeed = createWooReconcileFeed();
+  return {
+    ...wooConnectorParts,
+    replication: {
+      // One replication per collection; the reconcile feed is last, so its fetch wins duplicates. legacyKey
+      // reads an existing install's plain pull checkpoint as the product feed's, so it does not resync.
+      products: combinePullAdapters({ products: wooProductReplication, reconcile: catalogueFeed.adapter }, { legacyKey: "products" })
+    },
+    reconcile: {
+      // The feed's fetchByIds asks for at most this many ids per request; the runner budgets by requests.
+      catalogue: { ...wooCatalogueReconcile(catalogueFeed), refetchBatchSize: MAX_IDS_PER_REQUEST }
+    }
+  };
+}
+var wooConnectorParts = {
   id: "woocommerce",
   name: "WooCommerce",
   description: "Connect to WooCommerce stores via the REST API",
   icon: void 0,
   // TODO: WooCommerce logo
   auth: {
-    type: "WooCommerce REST API",
+    type: "WCPOS token",
     fields: [
       {
         key: "url",
@@ -306,24 +509,23 @@ var woocommerceConnector = {
         required: true
       },
       {
-        key: "consumer_key",
-        label: "Consumer Key",
-        type: "text",
-        placeholder: "ck_...",
-        required: true
-      },
-      {
-        key: "consumer_secret",
-        label: "Consumer Secret",
+        key: "token",
+        label: "Access token",
         type: "password",
-        placeholder: "cs_...",
         required: true
       }
     ],
     getHeaders: (credentials) => {
-      const encoded = btoa(`${credentials.consumer_key}:${credentials.consumer_secret}`);
+      if (typeof credentials.token !== "string" || credentials.token.length === 0) {
+        throw new WooMissingTokenError();
+      }
       return {
-        Authorization: `Basic ${encoded}`
+        Authorization: `Bearer ${credentials.token}`,
+        "X-WCPOS": "1",
+        // WCPOS 2.0 refuses a POS request below protocol 2 (HTTP 426); the connector already speaks 2.
+        "X-WCPOS-Protocol": "2",
+        // For WCPOS's consent-gated telemetry only.
+        "X-WCPOS-Client": `tallyui/${wcposClientPart(version)}`
       };
     }
   },
@@ -335,15 +537,22 @@ var woocommerceConnector = {
   },
   sync: {
     products: wooProductSync
-  },
-  replication: {
-    products: wooProductReplication
   }
 };
+var woocommerceConnector = createWooCommerceConnector();
 export {
+  ConnectorUnauthorizedError3 as ConnectorUnauthorizedError,
+  WooDateFilterError,
+  WooMissingTokenError,
+  WooMissingUuidError,
+  WooTillUpdateRequiredError,
+  createWooCommerceConnector,
+  wcposClientPart,
+  wooCatalogueReconcile,
   wooProductReplication,
   wooProductSchema,
   wooProductSync,
   wooProductTraits,
+  wooReconcileFingerprint,
   woocommerceConnector
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tallyui/connector-woocommerce",
-  "version": "1.0.0",
+  "version": "3.0.0-next.0",
   "type": "module",
   "description": "WooCommerce connector for Tally UI",
   "main": "./dist/index.js",
@@ -15,14 +15,22 @@
   },
   "files": [
     "dist",
-    "src"
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/__tests__/**"
   ],
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TallyUI/tallyui.git",
+    "directory": "connectors/woocommerce"
+  },
   "peerDependencies": {
-    "@tallyui/core": "0.2.0"
+    "@tallyui/core": "^3.0.0-next.0"
   },
   "devDependencies": {
-    "rxdb": "16.21.1"
+    "@tallyui/database": "3.0.0-next.0",
+    "rxdb": "17.5.0"
   },
   "scripts": {
     "build": "tsup",