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

package/README.md

@@ -30,11 +30,13 @@ 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 refused the request (401: the token is missing, expired or revoked; 403: signed in but not allowed), 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).
+- `WooPluginUpdateRequiredError` (`code: 'unsupported_store'`, `fixedBy: 'store'`): the store answered a `jwt_auth_*` 403, which WCPOS before 1.10.8 sends for a valid token (wcpos#1863). The store owner must update WCPOS to `minVersion` (`1.10.8`); the pull retries on the store schedule and the till stays signed in.
 - `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

@@ -69,6 +69,16 @@ declare class WooDateFilterError extends Error {
     readonly minVersion = "5.8";
     constructor(productId: number | undefined, bound: string, received: string | undefined);
 }
+/** A stale JWT plugin 403 on WCPOS 1.10.0–1.10.7 (wcpos/woocommerce-pos#1863; fixed by 7243675c9). */
+declare class WooPluginUpdateRequiredError extends Error {
+    readonly storeCode: string;
+    name: string;
+    readonly code: "unsupported_store";
+    readonly fixedBy: "store";
+    readonly software = "WCPOS";
+    readonly minVersion = "1.10.8";
+    constructor(storeCode: string);
+}
 /**
  * Replication adapter for WooCommerce products.
  *
@@ -88,9 +98,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>;
 
@@ -124,4 +134,4 @@ declare function createWooCommerceConnector(): TallyConnector;
  */
 declare const woocommerceConnector: TallyConnector;
 
-export { WooDateFilterError, WooMissingTokenError, WooMissingUuidError, WooTillUpdateRequiredError, createWooCommerceConnector, wcposClientPart, wooCatalogueReconcile, wooProductReplication, wooProductSchema, wooProductSync, wooProductTraits, wooReconcileFingerprint, woocommerceConnector };
+export { WooDateFilterError, WooMissingTokenError, WooMissingUuidError, WooPluginUpdateRequiredError, WooTillUpdateRequiredError, createWooCommerceConnector, wcposClientPart, wooCatalogueReconcile, wooProductReplication, wooProductSchema, wooProductSync, wooProductTraits, wooReconcileFingerprint, woocommerceConnector };

package/dist/index.js

@@ -259,6 +259,8 @@ var MAX_STORE_MESSAGE = 200;
 async function checkResponse(response) {
   if (response.ok) return;
   if (response.status === 401 || response.status === 403) {
+    const body = response.status === 403 ? await response.json().catch(() => void 0) : void 0;
+    if (typeof body?.code === "string" && body.code.startsWith("jwt_auth_")) throw new WooPluginUpdateRequiredError(body.code);
     throw new ConnectorUnauthorizedError(`WooCommerce API error: ${response.status}`, response.status);
   }
   if (response.status === 426) {
@@ -313,6 +315,17 @@ var WooDateFilterError = class extends Error {
   /** The first WooCommerce version that applies `modified_after` (5.8). */
   minVersion = "5.8";
 };
+var WooPluginUpdateRequiredError = class extends Error {
+  constructor(storeCode) {
+    super("This store needs WCPOS 1.10.8 or later: the JWT Authentication plugin blocks the till on older versions.");
+    this.storeCode = storeCode;
+  }
+  name = "WooPluginUpdateRequiredError";
+  code = "unsupported_store";
+  fixedBy = "store";
+  software = "WCPOS";
+  minVersion = "1.10.8";
+};
 var wooProductReplication = {
   pull: {
     handler: async function pull(lastCheckpoint, batchSize, context, requests = 0) {
@@ -380,7 +393,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 +414,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 +449,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 +489,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.2";
 
 // src/index.ts
 import { ConnectorUnauthorizedError as ConnectorUnauthorizedError3 } from "@tallyui/core";
@@ -473,7 +502,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 +511,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.
@@ -545,6 +575,7 @@ export {
   WooDateFilterError,
   WooMissingTokenError,
   WooMissingUuidError,
+  WooPluginUpdateRequiredError,
   WooTillUpdateRequiredError,
   createWooCommerceConnector,
   wcposClientPart,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tallyui/connector-woocommerce",
-  "version": "3.0.0-next.0",
+  "version": "3.0.0-next.2",
   "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.2"
   },
   "devDependencies": {
-    "@tallyui/database": "3.0.0-next.0",
+    "@tallyui/database": "3.0.0-next.2",
     "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.
@@ -118,5 +119,5 @@ export { ConnectorUnauthorizedError } from '@tallyui/core';
 export { wooProductSchema } from './schemas/products';
 export { wooProductTraits } from './traits/product';
 export { wooProductSync } from './sync/products';
-export { wooProductReplication, WooDateFilterError, WooMissingUuidError, WooTillUpdateRequiredError } from './replication/products';
+export { wooProductReplication, WooDateFilterError, WooPluginUpdateRequiredError, WooMissingUuidError, WooTillUpdateRequiredError } from './replication/products';
 export { wooCatalogueReconcile, wooReconcileFingerprint } from './reconcile/catalogue';

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';
 
@@ -27,8 +30,9 @@ async function get(path: string, context: SyncContext): Promise<any> {
 /**
  * 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.
+ * A failed status read is "no capability known"; only a 401 or 403 would make the paged listing fail the same way.
+ * Only a till-class error (401 `unauthorized`, 426 `till_update_required`) or an abort stops the pass.
+ * A 403 `forbidden` is store-class: the catalogue reconcile skips this check and tries again at the next hourly check.
  */
 export async function wooHasIdFastPath(context: SyncContext): Promise<boolean> {
   let status: any;
@@ -42,19 +46,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 +69,23 @@ 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)
+        // falls back to the paged listing, which fails the same way. A 403 `forbidden` is skipped until the next hourly
+        // check; only a till-class error or an abort stops the pass.
+        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 +94,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,10 @@ 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);
+    // Older WCPOS versions leak the JWT plugin's stale 403 despite a valid token.
+    const body = response.status === 403 ? await response.json().catch(() => undefined) : undefined;
+    if (typeof body?.code === 'string' && body.code.startsWith('jwt_auth_')) throw new WooPluginUpdateRequiredError(body.code);
+    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.
@@ -87,6 +90,19 @@ export class WooDateFilterError extends Error {
   }
 }
 
+/** A stale JWT plugin 403 on WCPOS 1.10.0–1.10.7 (wcpos/woocommerce-pos#1863; fixed by 7243675c9). */
+export class WooPluginUpdateRequiredError extends Error {
+  name = 'WooPluginUpdateRequiredError';
+  readonly code = 'unsupported_store' as const;
+  readonly fixedBy = 'store' as const;
+  readonly software = 'WCPOS';
+  readonly minVersion = '1.10.8';
+
+  constructor(readonly storeCode: string) {
+    super('This store needs WCPOS 1.10.8 or later: the JWT Authentication plugin blocks the till on older versions.');
+  }
+}
+
 /**
  * Replication adapter for WooCommerce products.
  *