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

package/README.md

@@ -30,11 +30,12 @@ The incremental pull can miss an edit: a `modified_after` that over-excludes (in
 - 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.
+- When `wcpos/v2/status` lists `products_id_fast_path` in `capabilities`, the whole catalogue is listed in one request (`per_page=-1` with `_fields=id,date_modified_gmt,stock_quantity,stock_status`) instead of pages of 100; a store that refuses it (a 400) is listed page by page in the same pass.
+- Both listings key on the numeric product id, never the till-local uuid; the adapter's `matchKey` is how the runner finds the till's copy.
 
 ## 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.
+- `ConnectorUnauthorizedError`, 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. `error.status` is `401` (`code: 'unauthorized'`, sign in again) or `403` (`code: 'forbidden'`, signed in but not allowed: the pull retries on the store schedule; don't sign out).
 - `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

@@ -88,9 +88,9 @@ declare const wooReconcileFingerprint: (p: {
     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.
+ * The daily catalogue check for WooCommerce (#248): lists every published product with its fingerprint, in one
+ * fast-path request where the store offers it (#313), else 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>;
 

package/dist/index.js

@@ -380,7 +380,7 @@ var wooProductReplication = {
 // 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 LISTING_FIELDS = "id,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) {
@@ -401,12 +401,30 @@ async function wooHasIdFastPath(context) {
   }
   return Array.isArray(status?.capabilities) && status.capabilities.includes(ID_FAST_PATH);
 }
+function wooBulkListingUrl(baseUrl) {
+  return `${baseUrl}/products?${new URLSearchParams({ per_page: "-1", _fields: LISTING_FIELDS })}`;
+}
+var toEntries = (rows) => rows.filter((row) => Number.isInteger(row?.id)).map((row) => ({ key: String(row.id), fingerprint: wooReconcileFingerprint(row), remote: row.id }));
 function wooCatalogueReconcile(feed) {
   return {
     async *fetchPages(context, from = 1) {
       const fast = await wooHasIdFastPath(context);
       yield { entries: [], cursor: from };
       if (fast) {
+        let rows;
+        let failed = false;
+        try {
+          rows = await get(wooBulkListingUrl(""), context);
+        } catch (error) {
+          if (errorKind(error) === "till" || context.signal?.aborted) throw error;
+          failed = true;
+          console.warn(`WooCommerce catalogue reconcile: the fast path failed (${error?.message ?? error}); listing page by page.`);
+        }
+        if (Array.isArray(rows)) {
+          yield { entries: toEntries(rows), cursor: from };
+          return;
+        }
+        if (!failed) console.warn("WooCommerce catalogue reconcile: the fast path answered with something that is not a list; listing page by page.");
       }
       for (let page = from; ; page++) {
         const params = new URLSearchParams({
@@ -418,15 +436,13 @@ function wooCatalogueReconcile(feed) {
           _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 };
+        yield { entries: toEntries(rows), cursor: page + 1 };
         if (rows.length < PAGE_SIZE) return;
       }
     },
     fingerprint: wooReconcileFingerprint,
+    // Both listings key on the numeric id, never the till-local uuid (#313).
+    matchKey: (doc) => Number.isInteger(doc.id) ? String(doc.id) : void 0,
     async confirmGone(locals, context) {
       const ids = locals.map((doc) => doc.id).filter((id) => Number.isInteger(id));
       if (!ids.length) return [];
@@ -460,11 +476,11 @@ async function wooFetchByIds(entries, context) {
   return documents;
 }
 function createWooReconcileFeed() {
-  return createReconcileFeed({ key: (doc) => doc.uuid, fetchByIds: wooFetchByIds });
+  return createReconcileFeed({ key: (doc) => doc.uuid, remote: (doc) => doc.id, fetchByIds: wooFetchByIds });
 }
 
 // package.json
-var version = "3.0.0-next.0";
+var version = "3.0.0-next.1";
 
 // src/index.ts
 import { ConnectorUnauthorizedError as ConnectorUnauthorizedError3 } from "@tallyui/core";
@@ -473,7 +489,7 @@ function wcposClientPart(part) {
 }
 var WooMissingTokenError = class extends ConnectorUnauthorizedError2 {
   constructor() {
-    super("WooCommerce credentials have no WCPOS access token: sign in again");
+    super("WooCommerce credentials have no WCPOS access token: sign in again", 401);
     this.name = "WooMissingTokenError";
   }
 };
@@ -482,9 +498,10 @@ function createWooCommerceConnector() {
   return {
     ...wooConnectorParts,
     replication: {
-      // One replication per collection; the reconcile feed is last, so its fetch wins duplicates. legacyKey
+      // One replication per collection; the reconcile feed is last, so its fetch wins duplicates;
+      // duplicates are matched by uuid, the primary key, not the store id (#331). 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" })
+      products: combinePullAdapters({ products: wooProductReplication, reconcile: catalogueFeed.adapter }, { legacyKey: "products", key: (doc) => doc.uuid })
     },
     reconcile: {
       // The feed's fetchByIds asks for at most this many ids per request; the runner budgets by requests.

package/package.json

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

package/src/index.ts

@@ -15,7 +15,7 @@ export function wcposClientPart(part: string): string {
 
 export class WooMissingTokenError extends ConnectorUnauthorizedError {
   constructor() {
-    super('WooCommerce credentials have no WCPOS access token: sign in again');
+    super('WooCommerce credentials have no WCPOS access token: sign in again', 401);
     this.name = 'WooMissingTokenError';
   }
 }
@@ -44,9 +44,10 @@ export function createWooCommerceConnector(): TallyConnector {
   return {
     ...wooConnectorParts,
     replication: {
-      // One replication per collection; the reconcile feed is last, so its fetch wins duplicates. legacyKey
+      // One replication per collection; the reconcile feed is last, so its fetch wins duplicates;
+      // duplicates are matched by uuid, the primary key, not the store id (#331). 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' }),
+      products: combinePullAdapters({ products: wooProductReplication, reconcile: catalogueFeed.adapter }, { legacyKey: 'products', key: (doc: any) => doc.uuid }),
     },
     reconcile: {
       // The feed's fetchByIds asks for at most this many ids per request; the runner budgets by requests.

package/src/reconcile/catalogue.ts

@@ -1,10 +1,13 @@
 import { errorKind, type CatalogueReconcileAdapter, type CatalogueReconcileEntry, type ReconcileFeed, type SyncContext } from '@tallyui/core';
-import { checkResponse, WooMissingUuidError } from '../replication/products';
+import { checkResponse } 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';
+/**
+ * Both listings' fields, and exactly the fast path's: the numeric id (the key, and how a product is refetched) and
+ * the fingerprint's. No uuid: the pull's `toProductDocument` still requires one on every product it delivers.
+ */
+const LISTING_FIELDS = 'id,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';
 
@@ -42,19 +45,21 @@ export async function wooHasIdFastPath(context: SyncContext): Promise<boolean> {
 }
 
 /**
- * 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`.
+ * The fast path's one request (wcpos/woocommerce-pos #2116, #2119, #2121): WordPress's `_fields` with exactly these
+ * four, answered from SQL, published POS-visible products only. 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}`;
+  return `${baseUrl}/products?${new URLSearchParams({ per_page: '-1', _fields: LISTING_FIELDS })}`;
 }
 
+/** Listing rows as entries keyed by the numeric id (#313); a row without an integer id cannot be asked about, and is dropped. */
+const toEntries = (rows: any[]) => rows.filter((row) => Number.isInteger(row?.id))
+  .map((row): CatalogueReconcileEntry => ({ key: String(row.id), fingerprint: wooReconcileFingerprint(row), remote: row.id }));
+
 /**
- * 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.
+ * The daily catalogue check for WooCommerce (#248): lists every published product with its fingerprint, in one
+ * fast-path request where the store offers it (#313), else 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 {
@@ -63,9 +68,22 @@ export function wooCatalogueReconcile(feed: Pick<ReconcileFeed<any>, 'enqueue'>)
       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.
+        // The whole catalogue in one request, so `from` is moot. A store that refuses it (a store scope answers 400)
+        // is listed page by page in this pass; only a till-class error or an abort stops it.
+        let rows: any;
+        let failed = false;
+        try {
+          rows = await get(wooBulkListingUrl(''), context); // get() prefixes context.baseUrl
+        } catch (error) {
+          if (errorKind(error) === 'till' || context.signal?.aborted) throw error;
+          failed = true;
+          console.warn(`WooCommerce catalogue reconcile: the fast path failed (${(error as Error)?.message ?? error}); listing page by page.`);
+        }
+        if (Array.isArray(rows)) {
+          yield { entries: toEntries(rows), cursor: from };
+          return;
+        }
+        if (!failed) console.warn('WooCommerce catalogue reconcile: the fast path answered with something that is not a list; listing page by page.');
       }
       // status=publish: a product that is not published is absent, so it becomes a deletion candidate and
       // confirmGone decides; drafts cost no daily refetch.
@@ -74,15 +92,13 @@ export function wooCatalogueReconcile(feed: Pick<ReconcileFeed<any>, 'enqueue'>)
           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 };
+        yield { entries: toEntries(rows), cursor: page + 1 };
         if (rows.length < PAGE_SIZE) return;
       }
     },
     fingerprint: wooReconcileFingerprint,
+    // Both listings key on the numeric id, never the till-local uuid (#313).
+    matchKey: (doc) => (Number.isInteger(doc.id) ? String(doc.id) : undefined),
     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.

package/src/reconcile/feed.ts

@@ -26,9 +26,10 @@ export async function wooFetchByIds(entries: Array<ReconcileFetchEntry<any>>, co
 }
 
 /**
- * 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.
+ * The reconcile feed for `products`, keyed by the primary key (`uuid`): the numeric `id` is how the store is
+ * asked (#248 design note, §6), and how a listed product the till lacks, queued under its id, is matched (#313).
+ * Its corrections reach the collection only through the pull.
  */
 export function createWooReconcileFeed(): ReconcileFeed<any> {
-  return createReconcileFeed<any>({ key: (doc) => doc.uuid, fetchByIds: wooFetchByIds });
+  return createReconcileFeed<any>({ key: (doc) => doc.uuid, remote: (doc) => doc.id, fetchByIds: wooFetchByIds });
 }

package/src/replication/products.ts

@@ -21,7 +21,7 @@ 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);
+    throw new ConnectorUnauthorizedError(`WooCommerce API error: ${response.status}`, response.status as 401 | 403);
   }
   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.