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

package/README.md

@@ -13,6 +13,8 @@ It also sends `X-WCPOS-Protocol: 2`, which WCPOS 2.0 requires of POS requests, a
 
 ## Product pull
 
+On WCPOS 1.10.x, the product uuid comes from the `_woocommerce_pos_uuid` meta and the barcode from `global_unique_id`. Non-empty top-level `uuid` / `barcode` fields (WCPOS 2.0) win when present.
+
 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;
@@ -36,7 +38,7 @@ The incremental pull can miss an edit: a `modified_after` that over-excludes (in
 ## Errors
 
 - `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.
+- `WooTokenRefusedError` (`code: 'store_misconfigured'`, `fixedBy: 'store'`, `fix`, and the store's own `storeCode`): the store answered a `jwt_auth_*` 403, the JWT Authentication plugin refusing the till's token. WCPOS 1.10.0–1.10.7 sent it for a valid token (wcpos#1863), and later versions can still send it when the token resolves to another user, so the error names no version. The store owner checks the JWT Authentication plugin's settings, or the till is paired again; 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,14 +69,19 @@ 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 {
+/**
+ * A `jwt_auth_*` 403: the store's JWT Authentication plugin refused the till's token. WCPOS 1.10.0–1.10.7 sent it for a valid token
+ * (wcpos/woocommerce-pos#1863); 1.10.8 and later can still send it when the token resolves to another user. So the
+ * message names no version: a version hint belongs only where a response itself carries the WCPOS version (#360).
+ */
+declare class WooTokenRefusedError extends Error {
     readonly storeCode: string;
     name: string;
-    readonly code: "unsupported_store";
+    readonly code: "store_misconfigured";
+    /** The store owner fixes it on the store, so the pull waits the store delay and the till stays signed in (`errorKind`). */
     readonly fixedBy: "store";
-    readonly software = "WCPOS";
-    readonly minVersion = "1.10.8";
+    /** The store-side remedy, for `SyncStatus`'s detail. */
+    readonly fix = "check the JWT Authentication plugin's settings";
     constructor(storeCode: string);
 }
 /**
@@ -134,4 +139,4 @@ declare function createWooCommerceConnector(): TallyConnector;
  */
 declare const woocommerceConnector: TallyConnector;
 
-export { WooDateFilterError, WooMissingTokenError, WooMissingUuidError, WooPluginUpdateRequiredError, WooTillUpdateRequiredError, createWooCommerceConnector, wcposClientPart, wooCatalogueReconcile, wooProductReplication, wooProductSchema, wooProductSync, wooProductTraits, wooReconcileFingerprint, woocommerceConnector };
+export { WooDateFilterError, WooMissingTokenError, WooMissingUuidError, WooTillUpdateRequiredError, WooTokenRefusedError, createWooCommerceConnector, wcposClientPart, wooCatalogueReconcile, wooProductReplication, wooProductSchema, wooProductSync, wooProductTraits, wooReconcileFingerprint, woocommerceConnector };

package/dist/index.js

@@ -148,109 +148,6 @@ var wooProductSchema = {
 
 // src/traits/product.ts
 import { moneyFromMajor } from "@tallyui/core";
-var WOO_STOCK_STATUS = {
-  instock: "in_stock",
-  outofstock: "out_of_stock",
-  onbackorder: "backorder"
-};
-var wooProductTraits = {
-  getId: (doc) => String(doc.id),
-  getName: (doc) => doc.name ?? "",
-  getSku: (doc) => doc.sku || void 0,
-  getPrices: (doc, context) => {
-    const currency = context?.currency ?? "XXX";
-    const prices = [];
-    const base = moneyFromMajor(doc.regular_price || doc.price, currency);
-    if (base) prices.push({ ...base, kind: "base" });
-    const sale = doc.on_sale === true ? moneyFromMajor(doc.sale_price, currency) : void 0;
-    if (sale) prices.push({ ...sale, kind: "sale" });
-    return prices;
-  },
-  getStock: (doc) => ({
-    status: WOO_STOCK_STATUS[doc.stock_status] ?? "unknown",
-    quantity: doc.manage_stock === false ? void 0 : doc.stock_quantity ?? void 0
-  }),
-  getPrice: (doc) => doc.price || void 0,
-  getRegularPrice: (doc) => doc.regular_price || void 0,
-  getSalePrice: (doc) => doc.sale_price || void 0,
-  isOnSale: (doc) => doc.on_sale === true,
-  getImageUrl: (doc) => doc.images?.[0]?.src || void 0,
-  getImageUrls: (doc) => (doc.images ?? []).map((img) => img.src).filter(Boolean),
-  getDescription: (doc) => doc.short_description || doc.description || void 0,
-  getStockStatus: (doc) => {
-    const status = doc.stock_status;
-    if (status === "instock" || status === "outofstock" || status === "onbackorder") {
-      return status;
-    }
-    return "unknown";
-  },
-  getStockQuantity: (doc) => doc.stock_quantity ?? null,
-  hasVariants: (doc) => doc.type === "variable",
-  isSellable: (doc) => doc.status === void 0 || doc.status === "publish",
-  getVariantCount: (doc) => doc.type === "variable" ? doc.variations?.length ?? 0 : 1,
-  getType: (doc) => doc.type ?? "simple",
-  getBarcode: (doc) => doc.barcode || void 0,
-  getCategoryNames: (doc) => (doc.categories ?? []).map((cat) => cat.name).filter(Boolean)
-};
-
-// src/sync/products.ts
-var wooProductSync = {
-  async fetchAllIds(context) {
-    const response = await fetch(`${context.baseUrl}/products`, {
-      headers: {
-        ...context.headers,
-        "Content-Type": "application/json"
-      },
-      signal: context.signal
-    });
-    if (!response.ok) {
-      throw new Error(`WooCommerce API error: ${response.status}`);
-    }
-    const products = await response.json();
-    return products.map((p) => ({
-      id: String(p.id),
-      dateModified: p.date_modified_gmt
-    }));
-  },
-  async fetchByIds(ids, context) {
-    const include = ids.join(",");
-    const response = await fetch(
-      `${context.baseUrl}/products?include=${include}&per_page=${ids.length}`,
-      {
-        headers: {
-          ...context.headers,
-          "Content-Type": "application/json"
-        },
-        signal: context.signal
-      }
-    );
-    if (!response.ok) {
-      throw new Error(`WooCommerce API error: ${response.status}`);
-    }
-    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?${params}`,
-      {
-        headers: {
-          ...context.headers,
-          "Content-Type": "application/json"
-        },
-        signal: context.signal
-      }
-    );
-    if (!response.ok) {
-      throw new Error(`WooCommerce API error: ${response.status}`);
-    }
-    return response.json();
-  }
-};
 
 // src/replication/products.ts
 import { ConnectorUnauthorizedError } from "@tallyui/core";
@@ -260,7 +157,7 @@ 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);
+    if (typeof body?.code === "string" && body.code.startsWith("jwt_auth_")) throw new WooTokenRefusedError(body.code);
     throw new ConnectorUnauthorizedError(`WooCommerce API error: ${response.status}`, response.status);
   }
   if (response.status === 426) {
@@ -295,9 +192,22 @@ var WooMissingUuidError = class extends Error {
     this.productId = id;
   }
 };
+var WCPOS_UUID_META_KEY = "_woocommerce_pos_uuid";
+function wooProductUuid(product) {
+  if (typeof product.uuid === "string" && product.uuid.length > 0) return product.uuid;
+  return product.meta_data?.find((entry) => entry.key === WCPOS_UUID_META_KEY && typeof entry.value === "string" && entry.value.length > 0)?.value;
+}
+function wooProductBarcode(product) {
+  if (typeof product.barcode === "string" && product.barcode.length > 0) return product.barcode;
+  if (typeof product.global_unique_id === "string" && product.global_unique_id.length > 0) return product.global_unique_id;
+  return void 0;
+}
 function toProductDocument(product) {
-  if (typeof product.uuid !== "string" || product.uuid.length === 0) throw new WooMissingUuidError(product.id);
-  return { ...product, _deleted: product.status !== "publish" };
+  const uuid = wooProductUuid(product);
+  if (uuid === void 0) throw new WooMissingUuidError(product.id);
+  const barcode = wooProductBarcode(product);
+  const projected = Object.fromEntries(Object.keys(wooProductSchema.properties).filter((key) => Object.prototype.hasOwnProperty.call(product, key)).map((key) => [key, product[key]]));
+  return { ...projected, uuid, ...barcode !== void 0 ? { barcode } : {}, _deleted: product.status !== "publish" };
 }
 var WooDateFilterError = class extends Error {
   constructor(productId, bound, received) {
@@ -315,16 +225,17 @@ var WooDateFilterError = class extends Error {
   /** The first WooCommerce version that applies `modified_after` (5.8). */
   minVersion = "5.8";
 };
-var WooPluginUpdateRequiredError = class extends Error {
+var WooTokenRefusedError = 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.");
+    super("The store refused the sign-in token (403). Ask the store owner to check the JWT Authentication plugin's settings, or pair the till again.");
     this.storeCode = storeCode;
   }
-  name = "WooPluginUpdateRequiredError";
-  code = "unsupported_store";
+  name = "WooTokenRefusedError";
+  code = "store_misconfigured";
+  /** The store owner fixes it on the store, so the pull waits the store delay and the till stays signed in (`errorKind`). */
   fixedBy = "store";
-  software = "WCPOS";
-  minVersion = "1.10.8";
+  /** The store-side remedy, for `SyncStatus`'s detail. */
+  fix = "check the JWT Authentication plugin's settings";
 };
 var wooProductReplication = {
   pull: {
@@ -390,6 +301,111 @@ var wooProductReplication = {
   }
 };
 
+// src/traits/product.ts
+var WOO_STOCK_STATUS = {
+  instock: "in_stock",
+  outofstock: "out_of_stock",
+  onbackorder: "backorder"
+};
+var wooProductTraits = {
+  getId: (doc) => String(doc.id),
+  getName: (doc) => doc.name ?? "",
+  getSku: (doc) => doc.sku || void 0,
+  getPrices: (doc, context) => {
+    const currency = context?.currency ?? "XXX";
+    const prices = [];
+    const base = moneyFromMajor(doc.regular_price || doc.price, currency);
+    if (base) prices.push({ ...base, kind: "base" });
+    const sale = doc.on_sale === true ? moneyFromMajor(doc.sale_price, currency) : void 0;
+    if (sale) prices.push({ ...sale, kind: "sale" });
+    return prices;
+  },
+  getStock: (doc) => ({
+    status: WOO_STOCK_STATUS[doc.stock_status] ?? "unknown",
+    quantity: doc.manage_stock === false ? void 0 : doc.stock_quantity ?? void 0
+  }),
+  getPrice: (doc) => doc.price || void 0,
+  getRegularPrice: (doc) => doc.regular_price || void 0,
+  getSalePrice: (doc) => doc.sale_price || void 0,
+  isOnSale: (doc) => doc.on_sale === true,
+  getImageUrl: (doc) => doc.images?.[0]?.src || void 0,
+  getImageUrls: (doc) => (doc.images ?? []).map((img) => img.src).filter(Boolean),
+  getDescription: (doc) => doc.short_description || doc.description || void 0,
+  getStockStatus: (doc) => {
+    const status = doc.stock_status;
+    if (status === "instock" || status === "outofstock" || status === "onbackorder") {
+      return status;
+    }
+    return "unknown";
+  },
+  getStockQuantity: (doc) => doc.stock_quantity ?? null,
+  hasVariants: (doc) => doc.type === "variable",
+  isSellable: (doc) => doc.status === void 0 || doc.status === "publish",
+  getVariantCount: (doc) => doc.type === "variable" ? doc.variations?.length ?? 0 : 1,
+  getType: (doc) => doc.type ?? "simple",
+  getBarcode: (doc) => wooProductBarcode(doc),
+  getCategoryNames: (doc) => (doc.categories ?? []).map((cat) => cat.name).filter(Boolean)
+};
+
+// src/sync/products.ts
+var wooProductSync = {
+  async fetchAllIds(context) {
+    const response = await fetch(`${context.baseUrl}/products`, {
+      headers: {
+        ...context.headers,
+        "Content-Type": "application/json"
+      },
+      signal: context.signal
+    });
+    if (!response.ok) {
+      throw new Error(`WooCommerce API error: ${response.status}`);
+    }
+    const products = await response.json();
+    return products.map((p) => ({
+      id: String(p.id),
+      dateModified: p.date_modified_gmt
+    }));
+  },
+  async fetchByIds(ids, context) {
+    const include = ids.join(",");
+    const response = await fetch(
+      `${context.baseUrl}/products?include=${include}&per_page=${ids.length}`,
+      {
+        headers: {
+          ...context.headers,
+          "Content-Type": "application/json"
+        },
+        signal: context.signal
+      }
+    );
+    if (!response.ok) {
+      throw new Error(`WooCommerce API error: ${response.status}`);
+    }
+    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?${params}`,
+      {
+        headers: {
+          ...context.headers,
+          "Content-Type": "application/json"
+        },
+        signal: context.signal
+      }
+    );
+    if (!response.ok) {
+      throw new Error(`WooCommerce API error: ${response.status}`);
+    }
+    return response.json();
+  }
+};
+
 // src/reconcile/catalogue.ts
 import { errorKind } from "@tallyui/core";
 var PAGE_SIZE = 100;
@@ -438,6 +454,7 @@ function wooCatalogueReconcile(feed) {
           return;
         }
         if (!failed) console.warn("WooCommerce catalogue reconcile: the fast path answered with something that is not a list; listing page by page.");
+        yield { entries: [], cursor: from };
       }
       for (let page = from; ; page++) {
         const params = new URLSearchParams({
@@ -459,10 +476,10 @@ function wooCatalogueReconcile(feed) {
     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 params = new URLSearchParams({ include: ids.join(","), per_page: String(PAGE_SIZE), status: "any", _fields: "id,uuid,status,meta_data" });
       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);
+      const live = new Map(rows.filter((row) => row.status === "publish").map((row) => [row.id, wooProductUuid(row)]));
+      return locals.filter((doc) => Number.isInteger(doc.id) && (!live.has(doc.id) || typeof live.get(doc.id) === "string" && live.get(doc.id) !== doc.uuid)).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.)
@@ -493,7 +510,7 @@ function createWooReconcileFeed() {
 }
 
 // package.json
-var version = "3.0.0-next.2";
+var version = "3.0.1";
 
 // src/index.ts
 import { ConnectorUnauthorizedError as ConnectorUnauthorizedError3 } from "@tallyui/core";
@@ -575,8 +592,8 @@ export {
   WooDateFilterError,
   WooMissingTokenError,
   WooMissingUuidError,
-  WooPluginUpdateRequiredError,
   WooTillUpdateRequiredError,
+  WooTokenRefusedError,
   createWooCommerceConnector,
   wcposClientPart,
   wooCatalogueReconcile,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tallyui/connector-woocommerce",
-  "version": "3.0.0-next.2",
+  "version": "3.0.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.2"
+    "@tallyui/core": "^3.0.1"
   },
   "devDependencies": {
-    "@tallyui/database": "3.0.0-next.2",
+    "@tallyui/database": "3.0.1",
     "rxdb": "17.5.0"
   },
   "scripts": {

package/src/index.ts

@@ -119,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, WooPluginUpdateRequiredError, WooMissingUuidError, WooTillUpdateRequiredError } from './replication/products';
+export { wooProductReplication, WooDateFilterError, WooTokenRefusedError, WooMissingUuidError, WooTillUpdateRequiredError } from './replication/products';
 export { wooCatalogueReconcile, wooReconcileFingerprint } from './reconcile/catalogue';

package/src/reconcile/catalogue.ts

@@ -1,5 +1,5 @@
 import { errorKind, type CatalogueReconcileAdapter, type CatalogueReconcileEntry, type ReconcileFeed, type SyncContext } from '@tallyui/core';
-import { checkResponse } from '../replication/products';
+import { checkResponse, wooProductUuid } from '../replication/products';
 
 /** The listing's page size, WordPress's per_page maximum. */
 const PAGE_SIZE = 100;
@@ -32,7 +32,7 @@ async function get(path: string, context: SyncContext): Promise<any> {
  * `capabilities` (a missing field is false). Never a version number, and never a failed attempt.
  * 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.
+ * A 403 `forbidden` is store-class: the whole pass is logged `skipped` and runs again at the next check (hourly by default).
  */
 export async function wooHasIdFastPath(context: SyncContext): Promise<boolean> {
   let status: any;
@@ -86,6 +86,8 @@ export function wooCatalogueReconcile(feed: Pick<ReconcileFeed<any>, 'enqueue'>)
           return;
         }
         if (!failed) console.warn('WooCommerce catalogue reconcile: the fast path answered with something that is not a list; listing page by page.');
+        // An empty page, so the fallback's first request takes its own budget slot, as the status read does.
+        yield { entries: [], cursor: from };
       }
       // status=publish: a product that is not published is absent, so it becomes a deletion candidate and
       // confirmGone decides; drafts cost no daily refetch.
@@ -105,10 +107,12 @@ export function wooCatalogueReconcile(feed: Pick<ReconcileFeed<any>, 'enqueue'>)
       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);
+      const params = new URLSearchParams({ include: ids.join(','), per_page: String(PAGE_SIZE), status: 'any', _fields: 'id,uuid,status,meta_data' });
+      const rows: Array<{ id: number; uuid: string; status: string }> = await get(`/products?${params}`, context);
+      const live = new Map(rows.filter((row) => row.status === 'publish').map((row) => [row.id, wooProductUuid(row)]));
+      // A live id backs only the store's uuid; other local copies are gone (#369).
+      // A row without a uuid can't prove the local copy stale, so a live id keeps it (#375 review).
+      return locals.filter((doc) => Number.isInteger(doc.id) && (!live.has(doc.id) || (typeof live.get(doc.id) === 'string' && live.get(doc.id) !== doc.uuid))).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.)

package/src/replication/products.ts

@@ -1,4 +1,5 @@
 import { ConnectorUnauthorizedError, type ReplicationAdapter } from '@tallyui/core';
+import { wooProductSchema } from '../schemas/products';
 
 export type WooProductCheckpoint = {
   /** Inclusive lower bound (date_modified_gmt) of the current pass; '' = the whole catalogue. */
@@ -21,9 +22,9 @@ const MAX_STORE_MESSAGE = 200;
 export async function checkResponse(response: Response) {
   if (response.ok) return;
   if (response.status === 401 || response.status === 403) {
-    // Older WCPOS versions leak the JWT plugin's stale 403 despite a valid token.
+    // A jwt_auth_* 403 is the store's JWT layer refusing the token, on any WCPOS version (#360).
     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);
+    if (typeof body?.code === 'string' && body.code.startsWith('jwt_auth_')) throw new WooTokenRefusedError(body.code);
     throw new ConnectorUnauthorizedError(`WooCommerce API error: ${response.status}`, response.status as 401 | 403);
   }
   if (response.status === 426) {
@@ -65,13 +66,35 @@ export class WooMissingUuidError extends Error {
   }
 }
 
+/** WCPOS's own uuid meta key; 1.10.x sends the product uuid only here (Uuid_Handler.php:29). */
+export const WCPOS_UUID_META_KEY = '_woocommerce_pos_uuid';
+
+/** The product's uuid: top-level `uuid` (the `next` shape) wins, else the `_woocommerce_pos_uuid` meta (1.10.x). */
+export function wooProductUuid(product: any): string | undefined {
+  if (typeof product.uuid === 'string' && product.uuid.length > 0) return product.uuid;
+  return product.meta_data?.find((entry: any) =>
+    entry.key === WCPOS_UUID_META_KEY && typeof entry.value === 'string' && entry.value.length > 0)?.value;
+}
+
+/** The product's barcode: top-level `barcode` wins, else `global_unique_id` (WCPOS's default barcode field), else undefined. */
+export function wooProductBarcode(product: any): string | undefined {
+  if (typeof product.barcode === 'string' && product.barcode.length > 0) return product.barcode;
+  if (typeof product.global_unique_id === 'string' && product.global_unique_id.length > 0) return product.global_unique_id;
+  return undefined;
+}
+
 /**
  * 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' };
+  const uuid = wooProductUuid(product);
+  if (uuid === undefined) throw new WooMissingUuidError(product.id);
+  const barcode = wooProductBarcode(product);
+  const projected = Object.fromEntries(Object.keys(wooProductSchema.properties)
+    .filter((key) => Object.prototype.hasOwnProperty.call(product, key))
+    .map((key) => [key, product[key]]));
+  return { ...projected, uuid, ...(barcode !== undefined ? { barcode } : {}), _deleted: product.status !== 'publish' };
 }
 
 /** The store returned a product outside a modified_after window, so it does not apply the filter. */
@@ -90,16 +113,21 @@ 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;
+/**
+ * A `jwt_auth_*` 403: the store's JWT Authentication plugin refused the till's token. WCPOS 1.10.0–1.10.7 sent it for a valid token
+ * (wcpos/woocommerce-pos#1863); 1.10.8 and later can still send it when the token resolves to another user. So the
+ * message names no version: a version hint belongs only where a response itself carries the WCPOS version (#360).
+ */
+export class WooTokenRefusedError extends Error {
+  name = 'WooTokenRefusedError';
+  readonly code = 'store_misconfigured' as const;
+  /** The store owner fixes it on the store, so the pull waits the store delay and the till stays signed in (`errorKind`). */
   readonly fixedBy = 'store' as const;
-  readonly software = 'WCPOS';
-  readonly minVersion = '1.10.8';
+  /** The store-side remedy, for `SyncStatus`'s detail. */
+  readonly fix = "check the JWT Authentication plugin's settings";
 
   constructor(readonly storeCode: string) {
-    super('This store needs WCPOS 1.10.8 or later: the JWT Authentication plugin blocks the till on older versions.');
+    super("The store refused the sign-in token (403). Ask the store owner to check the JWT Authentication plugin's settings, or pair the till again.");
   }
 }
 

package/src/traits/product.ts

@@ -1,5 +1,6 @@
 import { moneyFromMajor } from '@tallyui/core';
 import type { ProductPrice, ProductTraits, StockStatus } from '@tallyui/core';
+import { wooProductBarcode } from '../replication/products';
 
 /** WooCommerce's stock_status strings, mapped to the neutral enum. */
 const WOO_STOCK_STATUS: Record<string, StockStatus> = {
@@ -69,7 +70,7 @@ export const wooProductTraits: ProductTraits = {
 
   getType: (doc) => doc.type ?? 'simple',
 
-  getBarcode: (doc) => doc.barcode || undefined,
+  getBarcode: (doc) => wooProductBarcode(doc),
 
   getCategoryNames: (doc) =>
     (doc.categories ?? []).map((cat: any) => cat.name).filter(Boolean),