@tallyui/connector-vendure 2.0.0 → 3.0.0-next.1

package/README.md

@@ -0,0 +1,7 @@
+# TallyUI Vendure connector
+
+## Errors
+
+Requests with expired or rejected credentials reject with `ConnectorUnauthorizedError`, defined in `@tallyui/core` and re-exported by this connector. `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); a signed-out Vendure session is always `401`.
+
+Sign-in itself rejects with `SignInError`.

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import { ConnectorAuth, ProductTraits, CollectionSync, ReplicationAdapter, StockReconcileAdapter, SyncContext, StoreSettingsChoice, StoreSettings, TallyConnector } from '@tallyui/core';
+export { ConnectorUnauthorizedError } from '@tallyui/core';
 import { RxJsonSchema } from 'rxdb';
 
 declare const vendureSignIn: NonNullable<ConnectorAuth['signIn']>;
@@ -28,6 +29,19 @@ type VendureProductCheckpoint = {
     passHighWater?: string;
     passTotal?: number;
 };
+/** The server's updatedAt filters miss changes because it does not run in UTC (probeUpdatedAtSkew). */
+declare class VendureTimezoneConfigError extends Error {
+    name: string;
+    readonly code: "store_misconfigured";
+    /** Only the store owner can fix it on the server, so the pull waits the store delay (`errorKind`). */
+    readonly fixedBy: "store";
+    /**
+     * The store-side remedy, for `SyncStatus`'s detail. The message's other remedy,
+     * `updatedAtSkewMs`, is a connector option on the till, so it stays in the message only.
+     */
+    readonly fix = "run the Vendure server with its time zone set to UTC";
+    constructor();
+}
 /**
  * Replication adapter for Vendure products.
  *
@@ -71,7 +85,7 @@ declare const vendureStockReconcile: StockReconcileAdapter;
 /**
  * Reads the active channel's currency and tax-inclusivity (ADR-049), and the
  * default tax zone's enabled, non-customer-group rates keyed by tax category
- * id, in integer ppm rounded once. Read-only (ADR-048). Ignores `choice`:
+ * id, in integer ppm rounded once, with their rate names for grouping. Read-only (ADR-048). Ignores `choice`:
  * Vendure's channel is already chosen by the `vendure-token` header sent
  * with every request, so there is no `pricingContext` either.
  */
@@ -88,16 +102,18 @@ declare function vendureGlobalStockSettings(context: SyncContext): Promise<{
 }>;
 
 /**
- * Vendure connector for Tally UI.
+ * Vendure connector for Tally UI. Build one per store session, anew on each sign-in or store change:
+ * each instance owns its reconcile feed, whose queued work must never reach another store's database (#307).
  *
  * Connects to Vendure backends via the Admin GraphQL API.
  * Products are stored in RxDB using a schema that mirrors the Vendure API shape.
  *
  * ```ts
- * import { vendureConnector } from '@tallyui/connector-vendure';
+ * import { createVendureConnector } from '@tallyui/connector-vendure';
  * import { ConnectorProvider } from '@tallyui/core';
  *
- * <ConnectorProvider connector={vendureConnector}>
+ * const connector = useMemo(() => createVendureConnector({ pricesIncludeTax }), [backendUrl, pricesIncludeTax]);
+ * <ConnectorProvider connector={connector}>
  *   <App />
  * </ConnectorProvider>
  * ```
@@ -116,6 +132,10 @@ declare const createVendureConnector: (options?: {
     globalTrackInventory?: boolean;
     globalOutOfStockThreshold?: number;
 }) => TallyConnector;
+/**
+ * @deprecated One instance for the whole app: a store switch can leak queued reconcile work across stores.
+ * Use createVendureConnector() per store session. Removed in 4.0.
+ */
 declare const vendureConnector: TallyConnector;
 
-export { createVendureConnector, createVendureProductReplication, createVendureVariantFeedReplication, vendureAuth, vendureConnector, vendureGlobalStockSettings, vendureProductReplication, vendureProductSchema, vendureProductSync, vendureProductTraits, vendureSignIn, vendureStockReconcile, vendureStoreSettings };
+export { VendureTimezoneConfigError, createVendureConnector, createVendureProductReplication, createVendureVariantFeedReplication, vendureAuth, vendureConnector, vendureGlobalStockSettings, vendureProductReplication, vendureProductSchema, vendureProductSync, vendureProductTraits, vendureSignIn, vendureStockReconcile, vendureStoreSettings };

package/dist/index.js

@@ -3,6 +3,66 @@ import { combinePullAdapters, createReconcileFeed } from "@tallyui/core";
 
 // src/auth.ts
 import { SignInError } from "@tallyui/core";
+
+// src/capabilities.ts
+import { ConnectorUnauthorizedError as ConnectorUnauthorizedError2, parseInfoCapabilities } from "@tallyui/core";
+
+// src/session-probe.ts
+import { ConnectorUnauthorizedError } from "@tallyui/core";
+async function signedOut(context) {
+  try {
+    const res = await fetch(`${context.baseUrl}/admin-api`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", ...context.headers },
+      body: JSON.stringify({ query: "query { activeAdministrator { id } }" }),
+      signal: context.signal
+    });
+    if (!res.ok) return void 0;
+    const body = await res.json();
+    if (body.errors?.length) return void 0;
+    if (body.data?.activeAdministrator === null) return true;
+    return body.data?.activeAdministrator?.id != null ? false : void 0;
+  } catch (error) {
+    if (context.signal?.aborted) throw error;
+    return void 0;
+  }
+}
+async function forbiddenError(context, forbidden) {
+  const out = await signedOut(context);
+  if (out === true) return new ConnectorUnauthorizedError(`Vendure GraphQL error: ${forbidden[0].message}`, 401);
+  const what = forbidden.map(({ message, path }) => path?.length ? `${path.join(".")}: ${message}` : message).join("; ");
+  if (out === false) return new Error(`Vendure GraphQL error: FORBIDDEN: the store refused this request although the session is signed in (a permission is missing): ${what}`);
+  return new Error(`Vendure GraphQL error: FORBIDDEN: ${what} (the session check failed, so this may be transient)`);
+}
+
+// src/capabilities.ts
+var CAPABILITIES_PATH = "/tally/v1/info";
+async function readVendureCapabilities(baseUrl, headers, init = {}) {
+  const doFetch = init.fetch ?? fetch;
+  let res;
+  try {
+    res = await doFetch(`${baseUrl}${CAPABILITIES_PATH}`, { method: "GET", headers, signal: init.signal });
+  } catch {
+    return void 0;
+  }
+  if (res.status === 401 || res.status === 403) {
+    const out = await signedOut({ connectorId: "vendure", baseUrl, headers, signal: init.signal });
+    if (out === true) throw new ConnectorUnauthorizedError2(`Vendure refused ${CAPABILITIES_PATH}: the session is signed out`, 401);
+    if (out === false) throw new Error(`Vendure refused ${CAPABILITIES_PATH} although the session is signed in: the CreateOrder permission is missing (HTTP ${res.status})`);
+    return void 0;
+  }
+  if (res.status === 404) return { orderCreate: 1 };
+  if (!res.ok) return void 0;
+  let body;
+  try {
+    body = await res.json();
+  } catch {
+    return void 0;
+  }
+  return parseInfoCapabilities(body, (reason) => console.warn(`@tallyui/connector-vendure: ${reason}`));
+}
+
+// src/auth.ts
 var LOGIN = `mutation Login($email: String!, $password: String!) {
   login(username: $email, password: $password) {
     __typename
@@ -42,7 +102,8 @@ var vendureSignIn = async (baseUrl, { email, password }, init = {}) => {
   if (!token) {
     throw new SignInError("unsupported", "Vendure signed in but sent no 'vendure-auth-token' header. Add 'bearer' to the server's authOptions.tokenMethod. This connector reads the default header name, so a server that renames authOptions.authTokenHeaderKey also gives this error.");
   }
-  return { token, expiresAt: void 0 };
+  const capabilities = await readVendureCapabilities(baseUrl, { Authorization: `Bearer ${token}` }, { fetch: doFetch, signal: init.signal }).catch(() => void 0);
+  return { token, expiresAt: void 0, capabilities };
 };
 var warnedAuthToken = false;
 var vendureAuth = {
@@ -72,8 +133,9 @@ var vendureAuth = {
 // src/schemas/products.ts
 var vendureProductSchema = {
   // 1: declares variant trackInventory/outOfStockThreshold/useGlobalOutOfStockThreshold/enabled
-  // (backlog 28). A bump drops and resyncs (ConnectorSchemas, ADR-060 amendment 9).
-  version: 1,
+  // (backlog 28). 2: declares variant taxCategory { id } (#288). A bump drops and resyncs
+  // (ConnectorSchemas, ADR-060 amendment 9).
+  version: 2,
   primaryKey: "id",
   type: "object",
   properties: {
@@ -174,7 +236,8 @@ var vendureProductSchema = {
               }
             }
           },
-          customFields: { type: "object" }
+          customFields: { type: "object" },
+          taxCategory: { type: ["object", "null"], properties: { id: { type: "string" } } }
         }
       }
     },
@@ -235,6 +298,12 @@ function createVendureProductTraits(barcodeField, stockLocationId, pricesInclude
       prices: traits.getPrices({ variants: [variant] }, context),
       stock: traits.getStock({ variants: [variant] })
     })),
+    // The variant's tax category id: store-settings.ts keys taxRatesPpm by the same id. No variant id: the default
+    // (first live) variant, as getPrices.
+    getTaxClass: (doc, variantId) => {
+      const variant = variantId === void 0 ? liveVariants(doc)[0] : (doc.variants ?? []).find((v) => String(v.id) === variantId);
+      return variant?.taxCategory?.id == null ? void 0 : String(variant.taxCategory.id);
+    },
     getStock: (doc) => productStock(liveVariants(doc).map((variant) => variantStock(variant, stockLocationId, globalTrackInventory, globalOutOfStockThreshold))),
     getPrice: (doc) => {
       const amount = liveVariants(doc)[0]?.[priceField];
@@ -272,7 +341,7 @@ function createVendureProductTraits(barcodeField, stockLocationId, pricesInclude
       return "simple";
     },
     getBarcode: (doc) => {
-      return barcodeField ? doc.variants?.[0]?.customFields?.[barcodeField] || void 0 : void 0;
+      return barcodeField ? liveVariants(doc)[0]?.customFields?.[barcodeField] || void 0 : void 0;
     },
     getCategoryNames: (doc) => (doc.collections ?? []).map((c) => c.name).filter(Boolean)
   };
@@ -281,6 +350,7 @@ function createVendureProductTraits(barcodeField, stockLocationId, pricesInclude
 var vendureProductTraits = createVendureProductTraits();
 
 // src/sync/products.ts
+import { ConnectorUnauthorizedError as ConnectorUnauthorizedError3 } from "@tallyui/core";
 var PRODUCT_LIST_QUERY = `
   query GetProducts($options: ProductListOptions) {
     products(options: $options) {
@@ -395,12 +465,16 @@ async function gql(context, query2, variables) {
     body: JSON.stringify({ query: query2, variables }),
     signal: context.signal
   });
+  if (res.status === 401 || res.status === 403) throw new ConnectorUnauthorizedError3(`Vendure API error: ${res.status}`, res.status);
   if (!res.ok) throw new Error(`Vendure API error: ${res.status}`);
-  return res.json();
+  const body = await res.json();
+  const forbidden = body.errors?.filter((error) => error.extensions?.code === "FORBIDDEN") ?? [];
+  if (forbidden.length) throw await forbiddenError(context, forbidden);
+  return body;
 }
 
 // src/replication/products.ts
-import { compareIds } from "@tallyui/core";
+import { compareIds, ConnectorUnauthorizedError as ConnectorUnauthorizedError4 } from "@tallyui/core";
 var PRODUCT_LIST_QUERY2 = (barcodeField) => `
   query GetProducts($options: ProductListOptions) {
     products(options: $options) {
@@ -430,6 +504,7 @@ var PRODUCT_LIST_QUERY2 = (barcodeField) => `
           enabled
           featuredAsset { id preview }
           options { id name code }
+          taxCategory { id }
           ${barcodeField ? `customFields { ${barcodeField} }` : ""}
         }
       }
@@ -458,12 +533,30 @@ async function gql2(context, query2, variables) {
   if (!res.ok) {
     const body2 = await res.json().catch(() => void 0);
     const message = body2?.errors?.[0]?.message;
+    if (res.status === 401 || res.status === 403) throw new ConnectorUnauthorizedError4(`Vendure API error: ${res.status}${message ? `: ${message}` : ""}`, res.status);
     throw new Error(`Vendure API error: ${res.status}${message ? `: ${message}` : ""}`);
   }
   const body = await res.json();
+  const forbidden = body.errors?.filter((error) => error.extensions?.code === "FORBIDDEN") ?? [];
+  if (forbidden.length) throw await forbiddenError(context, forbidden);
   if (body.errors?.length) throw new Error(`Vendure GraphQL error: ${body.errors[0].message}`);
   return body;
 }
+var TIMEZONE_MESSAGE = "Vendure updatedAt filters miss changes: run Vendure with TZ=UTC or set updatedAtSkewMs to at least the magnitude of the server UTC offset in milliseconds.";
+var VendureTimezoneConfigError = class extends Error {
+  name = "VendureTimezoneConfigError";
+  code = "store_misconfigured";
+  /** Only the store owner can fix it on the server, so the pull waits the store delay (`errorKind`). */
+  fixedBy = "store";
+  /**
+   * The store-side remedy, for `SyncStatus`'s detail. The message's other remedy,
+   * `updatedAtSkewMs`, is a connector option on the till, so it stays in the message only.
+   */
+  fix = "run the Vendure server with its time zone set to UTC";
+  constructor() {
+    super(TIMEZONE_MESSAGE);
+  }
+};
 async function probeUpdatedAtSkew(passHighWater, updatedAtSkewMs, fetchTotal, remark) {
   for (const overlap of [1, 0]) {
     if (overlap === 0 && updatedAtSkewMs > 0) continue;
@@ -477,7 +570,8 @@ async function probeUpdatedAtSkew(passHighWater, updatedAtSkewMs, fetchTotal, re
       }
     }
     if (overlap === 1 && total === 0) {
-      throw new Error("Vendure updatedAt filters miss changes: run Vendure with TZ=UTC or set updatedAtSkewMs to at least the magnitude of the server UTC offset in milliseconds.");
+      if (remark) throw new VendureTimezoneConfigError();
+      throw new Error(TIMEZONE_MESSAGE);
     }
     if (overlap === 0 && total > 0) {
       console.warn("Vendure updatedAt filters over-fetch because the server is not in UTC.");
@@ -730,7 +824,7 @@ var CHANNEL_AND_CATEGORIES_QUERY = `
 var TAX_RATES_QUERY = `
   query StoreSettingsTaxRates($zoneId: String!) {
     taxRates(options: { take: 1000, filter: { zoneId: { eq: $zoneId } } }) {
-      items { enabled value category { id } customerGroup { id } }
+      items { name enabled value category { id } customerGroup { id } }
     }
   }
 `;
@@ -752,19 +846,28 @@ var vendureStoreSettings = async (context, _choice) => {
     rateItems = ratesBody.data?.taxRates?.items ?? [];
   }
   const byCategory = /* @__PURE__ */ new Map();
+  const namesByCategory = /* @__PURE__ */ new Map();
   for (const rate of rateItems) {
     if (!rate.enabled || rate.customerGroup || !rate.category) continue;
     byCategory.set(rate.category.id, Math.round(rate.value * 1e4));
+    if (typeof rate.name === "string" && rate.name) namesByCategory.set(rate.category.id, rate.name);
+    else namesByCategory.delete(rate.category.id);
   }
   const defaultCategory = categories.find((c) => c.isDefault) ?? categories[0];
+  const taxRateCodes = {};
+  const defaultName = defaultCategory && namesByCategory.get(defaultCategory.id);
+  if (defaultName) taxRateCodes.default = defaultName;
+  for (const [categoryId, name] of namesByCategory) taxRateCodes[categoryId] = name;
   const taxRatesPpm = {
     default: defaultCategory ? byCategory.get(defaultCategory.id) ?? 0 : 0
   };
   for (const [categoryId, ppm] of byCategory) taxRatesPpm[categoryId] = ppm;
+  for (const category of categories) taxRatesPpm[category.id] ??= 0;
   return {
     currency: channel.defaultCurrencyCode,
     pricesIncludeTax: channel.pricesIncludeTax,
-    taxRatesPpm
+    taxRatesPpm,
+    ...Object.keys(taxRateCodes).length > 0 && { taxRateCodes }
   };
 };
 
@@ -780,6 +883,8 @@ async function vendureGlobalStockSettings(context) {
 }
 
 // src/index.ts
+import { ConnectorUnauthorizedError as ConnectorUnauthorizedError5 } from "@tallyui/core";
+var VENDURE_IDS_PER_REQUEST = 1e3;
 var createVendureConnector = (options = {}) => {
   const idFeed = createReconcileFeed({ fetchByIds: createFetchByIds(options.barcodeField) });
   return {
@@ -814,14 +919,18 @@ var createVendureConnector = (options = {}) => {
     },
     reconcile: {
       stock: vendureStockReconcile,
-      ids: { fetchPages, variantIds, enqueue: idFeed.enqueue },
-      prices: { fetchPages: fetchPages2, fingerprint, enqueue: idFeed.enqueue }
+      ids: { fetchPages, variantIds, enqueue: idFeed.enqueue, refetchBatchSize: VENDURE_IDS_PER_REQUEST },
+      prices: { fetchPages: fetchPages2, fingerprint, enqueue: idFeed.enqueue, refetchBatchSize: VENDURE_IDS_PER_REQUEST }
     },
-    storeSettings: vendureStoreSettings
+    storeSettings: vendureStoreSettings,
+    // Re-reads a restored session's capabilities; with an API key and no sign-in, the only reader.
+    capabilities: (context) => readVendureCapabilities(context.baseUrl, context.headers, { signal: context.signal })
   };
 };
 var vendureConnector = createVendureConnector();
 export {
+  ConnectorUnauthorizedError5 as ConnectorUnauthorizedError,
+  VendureTimezoneConfigError,
   createVendureConnector,
   createVendureProductReplication,
   createVendureVariantFeedReplication,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tallyui/connector-vendure",
-  "version": "2.0.0",
+  "version": "3.0.0-next.1",
   "type": "module",
   "description": "Vendure connector for Tally UI",
   "main": "./dist/index.js",
@@ -26,12 +26,12 @@
     "directory": "connectors/vendure"
   },
   "peerDependencies": {
-    "@tallyui/core": "2.0.0"
+    "@tallyui/core": "^3.0.0-next.1"
   },
   "devDependencies": {
-    "@tallyui/database": "2.0.0",
-    "@tallyui/pos": "2.0.0",
-    "rxdb": "16.21.1"
+    "@tallyui/database": "3.0.0-next.1",
+    "@tallyui/pos": "3.0.0-next.1",
+    "rxdb": "17.5.0"
   },
   "scripts": {
     "build": "tsup",

package/src/auth.ts

@@ -1,5 +1,7 @@
 import { SignInError, type ConnectorAuth } from '@tallyui/core';
 
+import { readVendureCapabilities } from './capabilities';
+
 const LOGIN = `mutation Login($email: String!, $password: String!) {
   login(username: $email, password: $password) {
     __typename
@@ -43,7 +45,10 @@ export const vendureSignIn: NonNullable<ConnectorAuth['signIn']> = async (baseUr
   if (!token) {
     throw new SignInError('unsupported', "Vendure signed in but sent no 'vendure-auth-token' header. Add 'bearer' to the server's authOptions.tokenMethod. This connector reads the default header name, so a server that renames authOptions.authTokenHeaderKey also gives this error.");
   }
-  return { token, expiresAt: undefined };
+  // A capabilities read that fails never fails the sign-in: the capabilities are then unknown.
+  const capabilities = await readVendureCapabilities(baseUrl, { Authorization: `Bearer ${token}` }, { fetch: doFetch, signal: init.signal })
+    .catch(() => undefined);
+  return { token, expiresAt: undefined, capabilities };
 };
 
 // Warns once per module lifetime when a caller still relies on the deprecated auth_token alias.

package/src/capabilities.ts

@@ -0,0 +1,45 @@
+import { ConnectorUnauthorizedError, parseInfoCapabilities, type ServerCapabilities } from '@tallyui/core';
+
+import { signedOut } from './session-probe';
+
+/** The plugin's capability endpoint on Vendure's REST server (ADR-062), relative to the base URL. */
+export const CAPABILITIES_PATH = '/tally/v1/info';
+
+/**
+ * Reads the store's contract capabilities (ADR-062) and `taxRounding` (#287) with the
+ * connector's own headers. A 404 means an old plugin and gives the default; a network failure,
+ * non-2xx other than 404/401/403, non-JSON 2xx or malformed `taxRounding` is unknown and gives
+ * `undefined`. The route answers a dead session and a missing
+ * `CreateOrder` permission alike with 403, so a 401/403 asks who is signed in (#279): nobody
+ * throws `ConnectorUnauthorizedError`, an administrator throws a plain Error naming the
+ * permission, and a failed check is unknown.
+ */
+export async function readVendureCapabilities(
+  baseUrl: string,
+  headers: Record<string, string>,
+  init: { fetch?: typeof fetch; signal?: AbortSignal } = {},
+): Promise<ServerCapabilities | undefined> {
+  const doFetch = init.fetch ?? fetch;
+  let res: Response;
+  try {
+    res = await doFetch(`${baseUrl}${CAPABILITIES_PATH}`, { method: 'GET', headers, signal: init.signal });
+  } catch {
+    return undefined;
+  }
+  if (res.status === 401 || res.status === 403) {
+    const out = await signedOut({ connectorId: 'vendure', baseUrl, headers, signal: init.signal });
+    // The probe confirms sign-out; the route's 403 also covers missing permissions.
+    if (out === true) throw new ConnectorUnauthorizedError(`Vendure refused ${CAPABILITIES_PATH}: the session is signed out`, 401);
+    if (out === false) throw new Error(`Vendure refused ${CAPABILITIES_PATH} although the session is signed in: the CreateOrder permission is missing (HTTP ${res.status})`);
+    return undefined;
+  }
+  if (res.status === 404) return { orderCreate: 1 };
+  if (!res.ok) return undefined;
+  let body: unknown;
+  try {
+    body = await res.json();
+  } catch {
+    return undefined;
+  }
+  return parseInfoCapabilities(body, (reason) => console.warn(`@tallyui/connector-vendure: ${reason}`));
+}

package/src/index.ts

@@ -1,6 +1,7 @@
 import { combinePullAdapters, createReconcileFeed, type TallyConnector } from '@tallyui/core';
 
 import { vendureAuth } from './auth';
+import { readVendureCapabilities } from './capabilities';
 import { vendureProductSchema } from './schemas/products';
 import { createVendureProductTraits } from './traits/product';
 import { createVendureProductSync } from './sync/products';
@@ -12,17 +13,22 @@ import { fetchPages as fetchPricePages, fingerprint as priceFingerprint } from '
 import { vendureStoreSettings } from './store-settings';
 import { vendureGlobalStockSettings } from './global-settings';
 
+/** Ids per fetchByIds request: it sends the reconcile feed's whole chunk (at most 1,000 ids, ADR-060) in one query. */
+const VENDURE_IDS_PER_REQUEST = 1000;
+
 /**
- * Vendure connector for Tally UI.
+ * Vendure connector for Tally UI. Build one per store session, anew on each sign-in or store change:
+ * each instance owns its reconcile feed, whose queued work must never reach another store's database (#307).
  *
  * Connects to Vendure backends via the Admin GraphQL API.
  * Products are stored in RxDB using a schema that mirrors the Vendure API shape.
  *
  * ```ts
- * import { vendureConnector } from '@tallyui/connector-vendure';
+ * import { createVendureConnector } from '@tallyui/connector-vendure';
  * import { ConnectorProvider } from '@tallyui/core';
  *
- * <ConnectorProvider connector={vendureConnector}>
+ * const connector = useMemo(() => createVendureConnector({ pricesIncludeTax }), [backendUrl, pricesIncludeTax]);
+ * <ConnectorProvider connector={connector}>
  *   <App />
  * </ConnectorProvider>
  * ```
@@ -74,14 +80,21 @@ export const createVendureConnector = (options: {
 
     reconcile: {
       stock: vendureStockReconcile,
-      ids: { fetchPages, variantIds, enqueue: idFeed.enqueue },
-      prices: { fetchPages: fetchPricePages, fingerprint: priceFingerprint, enqueue: idFeed.enqueue },
+      ids: { fetchPages, variantIds, enqueue: idFeed.enqueue, refetchBatchSize: VENDURE_IDS_PER_REQUEST },
+      prices: { fetchPages: fetchPricePages, fingerprint: priceFingerprint, enqueue: idFeed.enqueue, refetchBatchSize: VENDURE_IDS_PER_REQUEST },
     },
 
     storeSettings: vendureStoreSettings,
+
+    // Re-reads a restored session's capabilities; with an API key and no sign-in, the only reader.
+    capabilities: (context) => readVendureCapabilities(context.baseUrl, context.headers, { signal: context.signal }),
   };
 };
 
+/**
+ * @deprecated One instance for the whole app: a store switch can leak queued reconcile work across stores.
+ * Use createVendureConnector() per store session. Removed in 4.0.
+ */
 export const vendureConnector = createVendureConnector();
 
 // Re-export pieces for advanced usage
@@ -94,3 +107,6 @@ export { createVendureVariantFeedReplication } from './replication/variant-feed'
 export { vendureStockReconcile } from './reconcile/stock';
 export { vendureStoreSettings } from './store-settings';
 export { vendureGlobalStockSettings } from './global-settings';
+
+export { ConnectorUnauthorizedError } from '@tallyui/core';
+export { VendureTimezoneConfigError } from './replication/products';

package/src/replication/products.ts

@@ -1,6 +1,7 @@
-import { compareIds } from '@tallyui/core';
+import { compareIds, ConnectorUnauthorizedError } from '@tallyui/core';
 import type { ReplicationAdapter, SyncContext } from '@tallyui/core';
 import { vendureProductSchema } from '../schemas/products';
+import { forbiddenError } from '../session-probe';
 
 export type VendureProductCheckpoint = {
   skip: number;
@@ -39,6 +40,7 @@ export const PRODUCT_LIST_QUERY = (barcodeField?: string) => `
           enabled
           featuredAsset { id preview }
           options { id name code }
+          taxCategory { id }
           ${barcodeField ? `customFields { ${barcodeField} }` : ''}
         }
       }
@@ -65,7 +67,7 @@ export async function gql(
   query: string,
   variables?: Record<string, any>,
 ): Promise<any> {
-  type GqlBody = { data?: any; errors?: Array<{ message?: string }> };
+  type GqlBody = { data?: any; errors?: Array<{ message?: string; path?: Array<string | number>; extensions?: { code?: string } }> };
   const res = await fetch(`${context.baseUrl}/admin-api`, {
     method: 'POST',
     headers: {
@@ -79,13 +81,35 @@ export async function gql(
   if (!res.ok) {
     const body = await res.json().catch(() => undefined) as GqlBody | undefined;
     const message = body?.errors?.[0]?.message;
+    if (res.status === 401 || res.status === 403) throw new ConnectorUnauthorizedError(`Vendure API error: ${res.status}${message ? `: ${message}` : ''}`, res.status as 401 | 403);
     throw new Error(`Vendure API error: ${res.status}${message ? `: ${message}` : ''}`);
   }
   const body = await res.json() as GqlBody;
+  const forbidden = body.errors?.filter((error) => error.extensions?.code === 'FORBIDDEN') ?? [];
+  if (forbidden.length) throw await forbiddenError(context, forbidden);
   if (body.errors?.length) throw new Error(`Vendure GraphQL error: ${body.errors[0].message}`);
   return body;
 }
 
+const TIMEZONE_MESSAGE = 'Vendure updatedAt filters miss changes: run Vendure with TZ=UTC or set updatedAtSkewMs to at least the magnitude of the server UTC offset in milliseconds.';
+
+/** The server's updatedAt filters miss changes because it does not run in UTC (probeUpdatedAtSkew). */
+export class VendureTimezoneConfigError extends Error {
+  name = 'VendureTimezoneConfigError';
+  readonly code = 'store_misconfigured' as const;
+  /** Only the store owner can fix it on the server, so the pull waits the store delay (`errorKind`). */
+  readonly fixedBy = 'store' as const;
+  /**
+   * The store-side remedy, for `SyncStatus`'s detail. The message's other remedy,
+   * `updatedAtSkewMs`, is a connector option on the till, so it stays in the message only.
+   */
+  readonly fix = 'run the Vendure server with its time zone set to UTC';
+
+  constructor() {
+    super(TIMEZONE_MESSAGE);
+  }
+}
+
 /**
  * Probes around a pass's high-water mark for the server's updatedAt skew
  * (ADR-060). `fetchTotal(after)` runs the caller's own list query (products,
@@ -114,7 +138,9 @@ export async function probeUpdatedAtSkew(
       }
     }
     if (overlap === 1 && total === 0) {
-      throw new Error('Vendure updatedAt filters miss changes: run Vendure with TZ=UTC or set updatedAtSkewMs to at least the magnitude of the server UTC offset in milliseconds.');
+      // Only a re-read rules out a mark deleted mid-probe; without one (the variant feed) the race stays a transient error.
+      if (remark) throw new VendureTimezoneConfigError();
+      throw new Error(TIMEZONE_MESSAGE);
     }
     if (overlap === 0 && total > 0) {
       console.warn('Vendure updatedAt filters over-fetch because the server is not in UTC.');

package/src/schemas/products.ts

@@ -13,8 +13,9 @@ import type { RxJsonSchema } from 'rxdb';
  */
 export const vendureProductSchema: RxJsonSchema<any> = {
   // 1: declares variant trackInventory/outOfStockThreshold/useGlobalOutOfStockThreshold/enabled
-  // (backlog 28). A bump drops and resyncs (ConnectorSchemas, ADR-060 amendment 9).
-  version: 1,
+  // (backlog 28). 2: declares variant taxCategory { id } (#288). A bump drops and resyncs
+  // (ConnectorSchemas, ADR-060 amendment 9).
+  version: 2,
   primaryKey: 'id',
   type: 'object',
   properties: {
@@ -116,6 +117,7 @@ export const vendureProductSchema: RxJsonSchema<any> = {
             },
           },
           customFields: { type: 'object' },
+          taxCategory: { type: ['object', 'null'], properties: { id: { type: 'string' } } },
         },
       },
     },

package/src/session-probe.ts

@@ -0,0 +1,40 @@
+import { ConnectorUnauthorizedError } from '@tallyui/core';
+import type { SyncContext } from '@tallyui/core';
+
+/**
+ * Vendure answers a dead session and a missing permission alike: HTTP 200 with GraphQL
+ * `FORBIDDEN` (#274). Asks who is signed in with the failed request's headers: `true` when
+ * nobody is, `false` when an administrator is, `undefined` when the check itself failed.
+ */
+export async function signedOut(context: SyncContext): Promise<boolean | undefined> {
+  try {
+    const res = await fetch(`${context.baseUrl}/admin-api`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', ...context.headers },
+      body: JSON.stringify({ query: 'query { activeAdministrator { id } }' }),
+      signal: context.signal,
+    });
+    if (!res.ok) return undefined;
+    const body = await res.json() as { data?: { activeAdministrator?: { id?: unknown } | null }; errors?: unknown[] };
+    if (body.errors?.length) return undefined;
+    if (body.data?.activeAdministrator === null) return true;
+    return body.data?.activeAdministrator?.id != null ? false : undefined;
+  } catch (error) {
+    if (context.signal?.aborted) throw error;
+    return undefined;
+  }
+}
+
+/**
+ * The error for a `FORBIDDEN` answer: only a signed-out session signs the till out. The plain
+ * errors name everything refused, in the answer's order (each GraphQL `path`, e.g. `product.variants`),
+ * for the store owner's log. One probe answers for the whole response.
+ */
+export async function forbiddenError(context: SyncContext, forbidden: Array<{ message?: string; path?: ReadonlyArray<string | number> }>): Promise<Error> {
+  const out = await signedOut(context);
+  // The probe confirmed a signed-out session even though Vendure answered FORBIDDEN.
+  if (out === true) return new ConnectorUnauthorizedError(`Vendure GraphQL error: ${forbidden[0].message}`, 401);
+  const what = forbidden.map(({ message, path }) => (path?.length ? `${path.join('.')}: ${message}` : message)).join('; ');
+  if (out === false) return new Error(`Vendure GraphQL error: FORBIDDEN: the store refused this request although the session is signed in (a permission is missing): ${what}`);
+  return new Error(`Vendure GraphQL error: FORBIDDEN: ${what} (the session check failed, so this may be transient)`);
+}

package/src/store-settings.ts

@@ -13,14 +13,14 @@ const CHANNEL_AND_CATEGORIES_QUERY = `
 const TAX_RATES_QUERY = `
   query StoreSettingsTaxRates($zoneId: String!) {
     taxRates(options: { take: 1000, filter: { zoneId: { eq: $zoneId } } }) {
-      items { enabled value category { id } customerGroup { id } }
+      items { name enabled value category { id } customerGroup { id } }
     }
   }
 `;
 
 type ActiveChannel = { defaultCurrencyCode: string; pricesIncludeTax: boolean; defaultTaxZone: { id: string } | null };
 type TaxCategory = { id: string; isDefault: boolean };
-type TaxRateItem = { enabled: boolean; value: number; category: { id: string } | null; customerGroup: { id: string } | null };
+type TaxRateItem = { name?: string; enabled: boolean; value: number; category: { id: string } | null; customerGroup: { id: string } | null };
 
 /** `gql` throws a plain `Error` for a non-OK response or a GraphQL `errors` body; both become `StoreSettingsError('failed')` here. */
 async function query(context: SyncContext, source: string, variables?: Record<string, unknown>): Promise<any> {
@@ -34,7 +34,7 @@ async function query(context: SyncContext, source: string, variables?: Record<st
 /**
  * Reads the active channel's currency and tax-inclusivity (ADR-049), and the
  * default tax zone's enabled, non-customer-group rates keyed by tax category
- * id, in integer ppm rounded once. Read-only (ADR-048). Ignores `choice`:
+ * id, in integer ppm rounded once, with their rate names for grouping. Read-only (ADR-048). Ignores `choice`:
  * Vendure's channel is already chosen by the `vendure-token` header sent
  * with every request, so there is no `pricingContext` either.
  */
@@ -51,10 +51,13 @@ export const vendureStoreSettings = async (context: SyncContext, _choice?: Store
   }
 
   const byCategory = new Map<string, number>();
+  const namesByCategory = new Map<string, string>();
   for (const rate of rateItems) {
     if (!rate.enabled || rate.customerGroup || !rate.category) continue;
     // Rounded once, here, at the connector's edge (a backend decimal percentage -> integer ppm).
     byCategory.set(rate.category.id, Math.round(rate.value * 10_000));
+    if (typeof rate.name === 'string' && rate.name) namesByCategory.set(rate.category.id, rate.name);
+    else namesByCategory.delete(rate.category.id);
   }
 
   // Vendure's own fallback for a variant created without a category
@@ -65,14 +68,22 @@ export const vendureStoreSettings = async (context: SyncContext, _choice?: Store
   // at all), `default` is 0 — that is what Vendure itself charges in that
   // case, never a silent guess.
   const defaultCategory = categories.find((c) => c.isDefault) ?? categories[0];
+  const taxRateCodes: Record<string, string> = {};
+  const defaultName = defaultCategory && namesByCategory.get(defaultCategory.id);
+  if (defaultName) taxRateCodes.default = defaultName;
+  for (const [categoryId, name] of namesByCategory) taxRateCodes[categoryId] = name;
   const taxRatesPpm: { default: number; [taxClass: string]: number } = {
     default: defaultCategory ? byCategory.get(defaultCategory.id) ?? 0 : 0,
   };
   for (const [categoryId, ppm] of byCategory) taxRatesPpm[categoryId] = ppm;
+  // A category with no enabled rate in the zone is charged 0 by Vendure, as for `default` above: an explicit 0, so the
+  // till never taxes it at the default rate (#288).
+  for (const category of categories) taxRatesPpm[category.id] ??= 0;
 
   return {
     currency: channel.defaultCurrencyCode,
     pricesIncludeTax: channel.pricesIncludeTax,
     taxRatesPpm,
+    ...(Object.keys(taxRateCodes).length > 0 && { taxRateCodes }),
   };
 };

package/src/sync/products.ts

@@ -1,4 +1,6 @@
+import { ConnectorUnauthorizedError } from '@tallyui/core';
 import type { CollectionSync, SyncContext } from '@tallyui/core';
+import { forbiddenError } from '../session-probe';
 
 /**
  * GraphQL query fragments used by the Vendure sync.
@@ -150,6 +152,10 @@ async function gql(
     signal: context.signal,
   });
 
+  if (res.status === 401 || res.status === 403) throw new ConnectorUnauthorizedError(`Vendure API error: ${res.status}`, res.status as 401 | 403);
   if (!res.ok) throw new Error(`Vendure API error: ${res.status}`);
-  return res.json();
+  const body: { data?: any; errors?: Array<{ message?: string; path?: Array<string | number>; extensions?: { code?: string } }> } = await res.json();
+  const forbidden = body.errors?.filter((error) => error.extensions?.code === 'FORBIDDEN') ?? [];
+  if (forbidden.length) throw await forbiddenError(context, forbidden);
+  return body;
 }

package/src/traits/product.ts

@@ -110,6 +110,14 @@ const traits: ProductTraits = {
     stock: traits.getStock({ variants: [variant] }),
   })),
 
+  // The variant's tax category id: store-settings.ts keys taxRatesPpm by the same id. No variant id: the default
+  // (first live) variant, as getPrices.
+  getTaxClass: (doc, variantId) => {
+    const variant = variantId === undefined ? liveVariants(doc)[0]
+      : (doc.variants ?? []).find((v: any) => String(v.id) === variantId);
+    return variant?.taxCategory?.id == null ? undefined : String(variant.taxCategory.id);
+  },
+
   getStock: (doc) => productStock(liveVariants(doc).map((variant: any) =>
     variantStock(variant, stockLocationId, globalTrackInventory, globalOutOfStockThreshold))),
 
@@ -171,7 +179,7 @@ const traits: ProductTraits = {
 
   getBarcode: (doc) => {
     // Vendure has no native barcode — check custom fields
-    return barcodeField ? doc.variants?.[0]?.customFields?.[barcodeField] || undefined : undefined;
+    return barcodeField ? liveVariants(doc)[0]?.customFields?.[barcodeField] || undefined : undefined;
   },
 
   getCategoryNames: (doc) =>