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

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.
  *
- * Pull-only (cursor-based pagination by date_modified_gmt) for RxDB's
+ * 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",
@@ -227,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,
@@ -245,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,
@@ -263,29 +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: "" };
+      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 { 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",
@@ -295,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)}`
       };
     }
   },
@@ -324,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": "2.0.0",
+  "version": "3.0.0-next.0",
   "type": "module",
   "description": "WooCommerce connector for Tally UI",
   "main": "./dist/index.js",
@@ -16,7 +16,8 @@
   "files": [
     "dist",
     "src",
-    "!src/**/*.test.ts"
+    "!src/**/*.test.ts",
+    "!src/**/__tests__/**"
   ],
   "license": "MIT",
   "repository": {
@@ -25,10 +26,11 @@
     "directory": "connectors/woocommerce"
   },
   "peerDependencies": {
-    "@tallyui/core": "2.0.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",

package/src/index.ts

@@ -1,33 +1,69 @@
-import type { TallyConnector } from '@tallyui/core';
+import { combinePullAdapters, ConnectorUnauthorizedError, type TallyConnector } from '@tallyui/core';
 
 import { wooProductSchema } from './schemas/products';
 import { wooProductTraits } from './traits/product';
 import { wooProductSync } from './sync/products';
 import { wooProductReplication } from './replication/products';
+import { wooCatalogueReconcile } from './reconcile/catalogue';
+import { createWooReconcileFeed, MAX_IDS_PER_REQUEST } from './reconcile/feed';
+import { version } from '../package.json';
+
+/** One part of X-WCPOS-Client as WCPOS keeps it: lowercase [a-z0-9._-], at most 32 characters. */
+export function wcposClientPart(part: string): string {
+  return part.toLowerCase().replace(/[^a-z0-9._-]/g, '').slice(0, 32);
+}
+
+export class WooMissingTokenError extends ConnectorUnauthorizedError {
+  constructor() {
+    super('WooCommerce credentials have no WCPOS access token: sign in again');
+    this.name = 'WooMissingTokenError';
+  }
+}
 
 /**
- * WooCommerce connector for Tally UI.
+ * 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>
  * ```
  */
-export const woocommerceConnector: TallyConnector = {
+export function createWooCommerceConnector(): TallyConnector {
+  // The catalogue reconcile's corrections reach `products` only through this pull adapter (#248).
+  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 },
+    },
+  };
+}
+
+// Everything but the reconcile feed and what is wired to it: stateless, so every instance shares it.
+const wooConnectorParts = {
   id: 'woocommerce',
   name: 'WooCommerce',
   description: 'Connect to WooCommerce stores via the REST API',
   icon: undefined, // TODO: WooCommerce logo
 
   auth: {
-    type: 'WooCommerce REST API',
+    type: 'WCPOS token',
     fields: [
       {
         key: 'url',
@@ -37,24 +73,23 @@ export const woocommerceConnector: TallyConnector = {
         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)}`,
       };
     },
   },
@@ -70,14 +105,18 @@ export const woocommerceConnector: TallyConnector = {
   sync: {
     products: wooProductSync,
   },
+} satisfies Omit<TallyConnector, 'replication' | 'reconcile'>;
 
-  replication: {
-    products: wooProductReplication,
-  },
-};
+/**
+ * @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.
+ */
+export const woocommerceConnector: TallyConnector = createWooCommerceConnector();
 
 // Re-export pieces for advanced usage
+export { ConnectorUnauthorizedError } from '@tallyui/core';
 export { wooProductSchema } from './schemas/products';
 export { wooProductTraits } from './traits/product';
 export { wooProductSync } from './sync/products';
-export { wooProductReplication } from './replication/products';
+export { wooProductReplication, WooDateFilterError, WooMissingUuidError, WooTillUpdateRequiredError } from './replication/products';
+export { wooCatalogueReconcile, wooReconcileFingerprint } from './reconcile/catalogue';

package/src/reconcile/catalogue.ts

@@ -0,0 +1,99 @@
+import { errorKind, type CatalogueReconcileAdapter, type CatalogueReconcileEntry, type ReconcileFeed, type SyncContext } from '@tallyui/core';
+import { checkResponse, WooMissingUuidError } from '../replication/products';
+
+/** The listing's page size, WordPress's per_page maximum. */
+const PAGE_SIZE = 100;
+/** Enough to compare: the key, the numeric id to refetch by, and the fingerprint's fields. */
+const LISTING_FIELDS = 'id,uuid,date_modified_gmt,stock_quantity,stock_status';
+/** The wcpos/v2/status capability that announces the bulk-id listing (wcpos/woocommerce-pos#2113). */
+const ID_FAST_PATH = 'products_id_fast_path';
+
+/**
+ * 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.
+ */
+export const wooReconcileFingerprint = (p: { date_modified_gmt?: string | null; stock_quantity?: number | null; stock_status?: string | null }) =>
+  [p.date_modified_gmt ?? '', p.stock_quantity ?? '', p.stock_status ?? ''].join('|');
+
+async function get(path: string, context: SyncContext): Promise<any> {
+  const response = await fetch(`${context.baseUrl}${path}`, {
+    headers: { ...context.headers, 'Content-Type': 'application/json' },
+    signal: context.signal,
+  });
+  await checkResponse(response);
+  return response.json();
+}
+
+/**
+ * The switch for the bulk-id fast path: true only when wcpos/v2/status lists `products_id_fast_path` in
+ * `capabilities` (a missing field is false). Never a version number, and never a failed attempt.
+ * A failed read (network, non-OK, non-JSON) is "no capability known", so the paged listing runs; only a
+ * till-class error (401, 403, 426 through checkResponse) stops the pass, since the listing would fail the same way.
+ */
+export async function wooHasIdFastPath(context: SyncContext): Promise<boolean> {
+  let status: any;
+  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);
+}
+
+/**
+ * The fast path's one request, pinned to the contract recorded for wcpos/woocommerce-pos#2113: WCPOS's own
+ * `fields`, not WordPress's `_fields`, answered from SQL. The context headers carry `X-WCPOS`.
+ */
+export function wooBulkListingUrl(baseUrl: string): string {
+  const params = new URLSearchParams({ per_page: '-1' });
+  for (const field of ['id', 'date_modified_gmt', 'stock_quantity', 'stock_status']) params.append('fields[]', field);
+  return `${baseUrl}/products?${params}`;
+}
+
+/**
+ * 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.
+ */
+export function wooCatalogueReconcile(feed: Pick<ReconcileFeed<any>, 'enqueue'>): CatalogueReconcileAdapter<any, number> {
+  return {
+    async *fetchPages(context, from = 1) {
+      // One status read per pass, yielded as an empty page so that it takes its own budget slot.
+      const fast = await wooHasIdFastPath(context);
+      yield { entries: [], cursor: from };
+      if (fast) {
+        // TODO(#2113): list with one wooBulkListingUrl request. It returns `id` but no `uuid`, and entries are
+        // keyed by uuid, so it needs an id-to-uuid mapping from the till's documents, which this adapter cannot
+        // read. Until that is designed, a store with the capability is listed page by page like any other.
+      }
+      // status=publish: a product that is not published is absent, so it becomes a deletion candidate and
+      // confirmGone decides; drafts cost no daily refetch.
+      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: any[] = await get(`/products?${params}`, context);
+        const entries = rows.map((row): CatalogueReconcileEntry => {
+          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));
+      // An empty include= would list the whole store; a local without a numeric id has no proof and is kept.
+      if (!ids.length) return [];
+      const params = new URLSearchParams({ include: ids.join(','), per_page: String(PAGE_SIZE), status: 'any', _fields: 'id,uuid,status' });
+      const rows: Array<{ id: number; status: string }> = 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))),
+  };
+}

package/src/reconcile/feed.ts

@@ -0,0 +1,34 @@
+import { createReconcileFeed, type ReconcileFeed, type ReconcileFetchEntry, type SyncContext } from '@tallyui/core';
+import { checkResponse, toProductDocument } from '../replication/products';
+
+/** WordPress caps per_page at 100, so at most this many ids per include= request. */
+export const MAX_IDS_PER_REQUEST = 100;
+
+/**
+ * `fetchByIds` for the reconcile feed (#248): full products by numeric id (the till's own `id`, else the
+ * listing's `remote`), with `status=any` so that an unpublished product comes back and arrives deleted.
+ * The pull's rules apply through `toProductDocument`.
+ */
+export async function wooFetchByIds(entries: Array<ReconcileFetchEntry<any>>, context: SyncContext): Promise<any[]> {
+  const ids = entries.map((e) => e.local?.id ?? e.remote).filter((id): id is number => Number.isInteger(id));
+  const documents: any[] = [];
+  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;
+}
+
+/**
+ * The reconcile feed for `products`, keyed by the primary key (`uuid`): the numeric `id` is only how the
+ * store is asked (#248 design note, §6). Its corrections reach the collection only through the pull.
+ */
+export function createWooReconcileFeed(): ReconcileFeed<any> {
+  return createReconcileFeed<any>({ key: (doc) => doc.uuid, fetchByIds: wooFetchByIds });
+}

package/src/replication/products.ts

@@ -1,30 +1,140 @@
-import type { ReplicationAdapter } from '@tallyui/core';
+import { ConnectorUnauthorizedError, type ReplicationAdapter } from '@tallyui/core';
 
 export 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;
 };
 
+// RxDB drops the checkpoint of an empty result, so the handler moves on to the next useful request
+// in the same call instead; every fetch in one call, mark requests included, counts against this.
+const MAX_REQUESTS_PER_CALL = 4;
+
+/** The most of a foreign 426's message kept in the error, so a store's long page never floods the log; longer is cut with "…". */
+const MAX_STORE_MESSAGE = 200;
+
+export async function checkResponse(response: 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) {
+    // Only the plugin's own gate means the till needs updating; any other 426 is retried as transient, with the store's message.
+    const body = await response.json().catch(() => undefined);
+    if (body?.code === 'wcpos_update_required') throw new WooTillUpdateRequiredError(body.code);
+    // `426 (code): message`, each part only when the body has it.
+    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)}…` : text}` : '';
+    throw new Error(`WooCommerce API error: 426${code}${message}`);
+  }
+  throw new Error(`WooCommerce API error: ${response.status}`);
+}
+
+/** WCPOS's protocol gate refused this till (HTTP 426 with `wcpos_update_required`): only updating the till fixes it. */
+export class WooTillUpdateRequiredError extends Error {
+  name = 'WooTillUpdateRequiredError';
+  readonly code = 'till_update_required' as const;
+  /** Only updating this till fixes it, so the pull pauses until resume() (`errorKind`). */
+  readonly fixedBy = 'till' as const;
+
+  /** The body's `code`, kept for diagnostics. */
+  constructor(readonly serverCode: string | undefined) {
+    super('WooCommerce API error: 426: this till needs updating to sync with the store');
+  }
+}
+
+export class WooMissingUuidError extends Error {
+  name = 'WooMissingUuidError';
+  readonly code = 'missing_plugin' as const;
+  /** Only the store owner can fix it, by installing or enabling the plugin, so the pull waits the store delay (`errorKind`). */
+  readonly fixedBy = 'store' as const;
+  productId: number;
+
+  constructor(id: number) {
+    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;
+  }
+}
+
+/**
+ * One product row as the till stores it, the rule the pull and the reconcile feed share: a uuid is
+ * required (WooMissingUuidError), and a product that is not published arrives deleted (#229).
+ */
+export function toProductDocument(product: any): any {
+  if (typeof product.uuid !== 'string' || product.uuid.length === 0) throw new WooMissingUuidError(product.id);
+  return { ...product, _deleted: product.status !== 'publish' };
+}
+
+/** The store returned a product outside a modified_after window, so it does not apply the filter. */
+export class WooDateFilterError extends Error {
+  name = 'WooDateFilterError';
+  readonly code = 'unsupported_store' as const;
+  /** Only the store owner can fix it, by updating WooCommerce, so the pull waits the store delay (`errorKind`). */
+  readonly fixedBy = 'store' as const;
+  /** 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(readonly productId: number | undefined, readonly bound: string, readonly received: string | undefined) {
+    super('This store needs WooCommerce 5.8 or later to sync products.');
+  }
+}
+
 /**
  * Replication adapter for WooCommerce products.
  *
- * Pull-only (cursor-based pagination by date_modified_gmt) for RxDB's
+ * 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.
  */
 export const wooProductReplication: ReplicationAdapter<any, WooProductCheckpoint> = {
   pull: {
-    async handler(lastCheckpoint, batchSize, context) {
+    handler: async function pull(lastCheckpoint, batchSize, context, requests = 0): Promise<{ documents: any[]; checkpoint: WooProductCheckpoint }> {
+      const modified = lastCheckpoint?.modified ?? '';
+      const offset = lastCheckpoint?.offset ?? 0;
+      // Budget spent: a call never fetches after gathering documents, so return [] and let the stored checkpoint stand.
+      const spent = { documents: [], checkpoint: lastCheckpoint ?? { modified, offset } };
+      let passMark = lastCheckpoint?.pass_mark ?? modified;
+      if (offset === 0 && lastCheckpoint?.pass_mark === undefined) {
+        if (requests++ >= MAX_REQUESTS_PER_CALL) return spent;
+        // orderby=modified sorts by local time, so the store is asked in GMT whether anything is newer than L.
+        // No Z or offset on modified_after: WP_Date_Query::build_mysql_datetime parses it in the site time zone and
+        // formats it back in that zone, so an offset would move the bound to local time before the post_modified_gmt comparison.
+        const newer: Record<string, string> = 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();
+        // Nothing modified after L (or no product at all): every window is empty.
+        if (newest === undefined) return { documents: [], checkpoint: lastCheckpoint ?? { modified: '', offset: 0 } };
+        if (modified && !(newest.date_modified_gmt > modified)) throw new WooDateFilterError(newest.id, modified, newest.date_modified_gmt);
+        // The local sort may put an older GMT time first: as the next lower bound that costs a re-read, never a skip.
+        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) {
+        // GMT digits with no offset, for WP_Date_Query (see the mark request).
+        params.set('modified_after', new Date(Date.parse(modified + 'Z') - 1000).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,
@@ -33,19 +143,36 @@ export const wooProductReplication: ReplicationAdapter<any, WooProductCheckpoint
         signal: context.signal,
       });
 
-      if (!response.ok) {
-        throw new Error(`WooCommerce API error: ${response.status}`);
-      }
+      await checkResponse(response);
 
       const products: any[] = await response.json();
-      const documents = products.map((p) => ({ ...p, _deleted: false }));
-
-      const checkpoint: WooProductCheckpoint = 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: '' };
+      const total = response.headers.get('X-WP-Total');
+      const count = total !== null && /^\d+$/.test(total) ? Number(total) : undefined;
+      if (offset > 0 && count !== undefined && (products.length === 0 || count < (lastCheckpoint?.pass_count ?? count))) {
+        // Restart the pass in this call, so RxDB stores its first page's checkpoint; the request budget bounds the call.
+        return pull({ modified, offset: 0, pass_mark: passMark }, batchSize, context, requests);
+      }
+      const documents = products.map((product) => {
+        const document = toProductDocument(product);
+        // The window is modified_after = L − 1 s, so a product missing its time or below L was not filtered.
+        if (modified && !(product.date_modified_gmt >= modified)) {
+          throw new WooDateFilterError(product.id, params.get('modified_after')!, product.date_modified_gmt);
+        }
+        return document;
+      });
+
+      // RxDB merges checkpoints, so clear pass state explicitly at completion.
+      const complete = count === undefined ? products.length < batchSize : offset + products.length >= count;
+      const checkpoint: WooProductCheckpoint = complete
+        ? { modified: passMark, offset: 0, pass_mark: undefined, pass_count: undefined }
+        : { modified, offset: offset + products.length, pass_mark: passMark, pass_count: count };
+      if (complete && products.length === 0) {
+        // Chain into the next pass: RxDB would drop this completion with the empty result. While the next pass
+        // has nothing either, each poll re-derives these requests from the stored checkpoint, at most
+        // MAX_REQUESTS_PER_CALL of them.
+        const next = await pull({ modified: passMark, offset: 0 }, batchSize, context, requests);
+        return next.documents.length > 0 ? next : { documents: [], checkpoint: lastCheckpoint ?? checkpoint };
+      }
 
       return { documents, checkpoint };
     },

package/src/sync/products.ts

@@ -50,8 +50,13 @@ export const wooProductSync: CollectionSync = {
   },
 
   async fetchModifiedAfter(date: string, context: SyncContext): Promise<any[]> {
+    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,