@tallyui/connector-vendure 1.0.0 → 3.0.0-next.0

package/src/replication/products.ts

@@ -1,11 +1,17 @@
+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;
   updatedAt: string;
+  passMax?: string;
+  passHighWater?: string;
+  passTotal?: number;
 };
 
-const PRODUCT_LIST_QUERY = `
+export const PRODUCT_LIST_QUERY = (barcodeField?: string) => `
   query GetProducts($options: ProductListOptions) {
     products(options: $options) {
       items {
@@ -27,12 +33,15 @@ const PRODUCT_LIST_QUERY = `
           price
           priceWithTax
           currencyCode
-          stockLevel
-          stockOnHand
+          stockLevels { stockLocationId stockOnHand stockAllocated }
           trackInventory
+          outOfStockThreshold
+          useGlobalOutOfStockThreshold
+          enabled
           featuredAsset { id preview }
           options { id name code }
-          customFields
+          taxCategory { id }
+          ${barcodeField ? `customFields { ${barcodeField} }` : ''}
         }
       }
       totalItems
@@ -40,11 +49,12 @@ const PRODUCT_LIST_QUERY = `
   }
 `;
 
-const UPDATE_PRODUCT_MUTATION = `
-  mutation UpdateProduct($input: UpdateProductInput!) {
-    updateProduct(input: $input) {
-      id
-      updatedAt
+/** The high-water mark and the skew probes only compare ids and timestamps (backlog 29). */
+const PRODUCT_MARK_QUERY = `
+  query GetProductsMark($options: ProductListOptions) {
+    products(options: $options) {
+      items { id updatedAt }
+      totalItems
     }
   }
 `;
@@ -52,11 +62,12 @@ const UPDATE_PRODUCT_MUTATION = `
 /**
  * Helper to execute a GraphQL query against the Vendure Admin API.
  */
-async function gql(
+export async function gql(
   context: SyncContext,
   query: string,
   variables?: Record<string, any>,
 ): Promise<any> {
+  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: {
@@ -67,82 +78,171 @@ async function gql(
     signal: context.signal,
   });
 
-  if (!res.ok) throw new Error(`Vendure API error: ${res.status}`);
-  return res.json();
+  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);
+    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,
+ * variants) and returns its totalItems. Returns the mark actually probed
+ * (backlog 31: `remark`, given, may re-read a newer one; see below).
+ */
+export async function probeUpdatedAtSkew(
+  passHighWater: string,
+  updatedAtSkewMs: number,
+  fetchTotal: (after: string) => Promise<number>,
+  remark?: () => Promise<string | undefined>,
+): Promise<string> {
+  for (const overlap of [1, 0]) {
+    if (overlap === 0 && updatedAtSkewMs > 0) continue;
+    const after = (mark: string) => new Date(Date.parse(mark) + (overlap === 0 ? 1 : -1) - updatedAtSkewMs).toISOString();
+    let total = await fetchTotal(after(passHighWater));
+    if (overlap === 1 && total === 0 && remark) {
+      // The mark's own product can be deleted between the mark read and this
+      // probe (harmless on its own: RxDB retries the resulting error and the
+      // next mark read picks a survivor). Re-reading the mark once here means
+      // that common case settles without throwing at all.
+      const remarked = await remark();
+      if (remarked) {
+        passHighWater = remarked;
+        total = await fetchTotal(after(passHighWater));
+      }
+    }
+    if (overlap === 1 && total === 0) {
+      // 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.');
+    }
+  }
+  return passHighWater;
+}
+
+/** Project an API product onto the schema's top-level fields (RxDB rejects undeclared ones). Sorts `variants` by id (a stable copy; the input is not mutated), since Vendure does not guarantee variant order. */
+export function toProductDocument(p: any): Record<string, unknown> {
+  const doc: Record<string, unknown> = { _deleted: false };
+  for (const field of Object.keys(vendureProductSchema.properties)) {
+    if (p[field] !== undefined) doc[field] = p[field];
+  }
+  if (Array.isArray(doc.variants)) {
+    doc.variants = [...doc.variants].sort((a: any, b: any) => compareIds(a.id, b.id));
+  }
+  return doc;
 }
 
 /**
  * Replication adapter for Vendure products.
  *
- * Implements pull (GraphQL query with offset pagination and updatedAt
- * filtering) and push (GraphQL updateProduct mutation). Designed for
- * use with RxDB's replicateRxCollection.
+ * Pull-only (GraphQL query with offset pagination and updatedAt filtering)
+ * for RxDB's replicateRxCollection. Catalogue data is server-owned; the
+ * POS never writes products.
  */
-export const vendureProductReplication: ReplicationAdapter<any, VendureProductCheckpoint> = {
+export const createVendureProductReplication = (barcodeField?: string, updatedAtSkewMs = 0): ReplicationAdapter<any, VendureProductCheckpoint> => ({
   pull: {
     async handler(lastCheckpoint, batchSize, context) {
+      if (batchSize > 1000) throw new Error('Vendure Admin API take must not exceed 1000');
+      // A checkpoint with skip > 0 but neither passHighWater nor passTotal is
+      // the shape saved mid-pass by the code before #45 gave a pass its own
+      // high-water mark and total (that code kept only skip and updatedAt).
+      // Its skip counts offset pages under a different sort and a moving
+      // updatedAt filter, which don't line up with this pull's fixed-window
+      // paging by id: resuming at that offset could skip rows. Restarting the
+      // pass from offset 0 cannot skip anything, only re-read rows this or an
+      // earlier pass already applied, which RxDB's upsert makes harmless.
+      if (lastCheckpoint?.skip && lastCheckpoint.passHighWater === undefined && lastCheckpoint.passTotal === undefined) {
+        lastCheckpoint = { skip: 0, updatedAt: lastCheckpoint.updatedAt ?? '' };
+      }
+      let passHighWater = lastCheckpoint?.passHighWater ?? lastCheckpoint?.updatedAt ?? '';
+      if (!lastCheckpoint?.skip) {
+        const fetchMark = async () => {
+          const head = await gql(context, PRODUCT_MARK_QUERY, { options: { take: 1, sort: { updatedAt: 'DESC' } } });
+          return head.data?.products?.items?.[0]?.updatedAt as string | undefined;
+        };
+        const mark = await fetchMark();
+        passHighWater = mark ?? lastCheckpoint?.updatedAt ?? '';
+        // Same-ms writes after this read wait for a newer mark or periodic reconcile (ADR-060, to come).
+        if (mark === undefined || (lastCheckpoint?.updatedAt && passHighWater === lastCheckpoint.updatedAt)) {
+          return { documents: [], checkpoint: lastCheckpoint ?? { skip: 0, updatedAt: '' } };
+        }
+        passHighWater = await probeUpdatedAtSkew(passHighWater, updatedAtSkewMs, async (after) => {
+          const probe = await gql(context, PRODUCT_MARK_QUERY, {
+            options: { take: 1, sort: { updatedAt: 'DESC' }, filter: { updatedAt: { after } } },
+          });
+          return probe.data.products.totalItems;
+        }, fetchMark);
+      }
       const options: Record<string, any> = {
         take: batchSize,
         skip: lastCheckpoint?.skip ?? 0,
+        sort: { id: 'ASC' },
       };
 
       if (lastCheckpoint?.updatedAt) {
         options.filter = {
-          updatedAt: { after: lastCheckpoint.updatedAt },
+          // Vendure after is strict; overlap by 1 ms to include timestamp ties.
+          updatedAt: { after: new Date(Date.parse(lastCheckpoint.updatedAt) - 1 - updatedAtSkewMs).toISOString() },
         };
       }
 
-      const res = await gql(context, PRODUCT_LIST_QUERY, { options });
+      const res = await gql(context, PRODUCT_LIST_QUERY(barcodeField), { options });
 
-      if (res.errors?.length) {
-        throw new Error(`Vendure GraphQL error: ${res.errors[0].message}`);
+      let data = res.data?.products;
+      let passTotal = options.skip === 0 ? data.totalItems : lastCheckpoint?.passTotal ?? data.totalItems;
+      if (options.skip > 0 && data.totalItems < passTotal) {
+        options.skip = 0;
+        const restarted = await gql(context, PRODUCT_LIST_QUERY(barcodeField), { options });
+        data = restarted.data?.products;
+        passTotal = data.totalItems;
       }
-
-      const data = res.data?.products;
       const products: any[] = data?.items ?? [];
-      const documents = products.map((p) => ({ ...p, _deleted: false }));
-
-      // Reset skip when batch is smaller than batchSize (end of page)
-      const nextSkip = products.length < batchSize
-        ? 0
-        : (lastCheckpoint?.skip ?? 0) + products.length;
+      if (!products.length && options.skip > 0) {
+        return createVendureProductReplication(barcodeField, updatedAtSkewMs).pull.handler(
+          { skip: 0, updatedAt: lastCheckpoint?.updatedAt ?? '' }, batchSize, context,
+        );
+      }
+      const documents = products.map(toProductDocument);
 
-      const checkpoint: VendureProductCheckpoint = products.length > 0
-        ? {
-            skip: nextSkip,
-            updatedAt: products[products.length - 1].updatedAt,
-          }
-        : lastCheckpoint ?? { skip: 0, updatedAt: '' };
+      // Keep the lower bound fixed while paging by id; advance it only at pass end.
+      // RxDB merges checkpoints, so explicitly clear pass state at completion.
+      const checkpoint: VendureProductCheckpoint = options.skip + products.length >= data.totalItems
+        ? { skip: 0, updatedAt: passHighWater, passHighWater: undefined, passTotal: undefined }
+        : { skip: options.skip + products.length,
+            updatedAt: lastCheckpoint?.updatedAt ?? '', passHighWater, passTotal };
 
       return { documents, checkpoint };
     },
   },
+});
 
-  push: {
-    async handler(changeRows, context) {
-      const conflicts: any[] = [];
-
-      for (const row of changeRows) {
-        const doc = row.newDocumentState as any;
-
-        try {
-          const res = await gql(context, UPDATE_PRODUCT_MUTATION, {
-            input: doc,
-          });
-
-          if (res.errors?.length) {
-            if (row.assumedMasterState) {
-              conflicts.push({ ...row.assumedMasterState, _deleted: false });
-            }
-          }
-        } catch {
-          if (row.assumedMasterState) {
-            conflicts.push({ ...row.assumedMasterState, _deleted: false });
-          }
-        }
-      }
-
-      return conflicts;
-    },
-  },
-};
+export const vendureProductReplication = createVendureProductReplication();

package/src/replication/variant-feed.ts

@@ -0,0 +1,108 @@
+import type { ReplicationAdapter, SyncContext } from '@tallyui/core';
+import { gql, PRODUCT_LIST_QUERY, probeUpdatedAtSkew, toProductDocument, type VendureProductCheckpoint } from './products';
+
+/** Vendure Admin API maximum `take`; variant pages and parent re-fetch chunks use it. */
+const MAX_TAKE = 1000;
+
+const variants = (context: SyncContext, fields: string, options: Record<string, any>) => gql(context, `
+  query GetVariants($options: ProductVariantListOptions) {
+    productVariants(options: $options) { items { ${fields} } totalItems }
+  }
+`, { options }).then((res) => res.data.productVariants as { items: any[]; totalItems: number });
+/** The newest variant: each pass's high water, and a fresh install's seed. */
+const newest = (context: SyncContext) => variants(context, 'id updatedAt', { take: 1, sort: { updatedAt: 'DESC' } });
+
+/**
+ * Variant feed for Vendure products (ADR-060, decision 3).
+ *
+ * A variant price or stock edit bumps `ProductVariant.updatedAt` but not
+ * `Product.updatedAt`, so the product feed never sees it. This pull adapter
+ * pages changed variants with the same pass and high-water design as
+ * `createVendureProductReplication` and re-delivers their parent products,
+ * in the same document shape, into the `products` collection. It runs as a
+ * sub-adapter of the connector's combined `replication.products` adapter
+ * (`combinePullAdapters`), not as its own replication. Parents that no longer
+ * exist are skipped; deletions are the id reconcile's job.
+ *
+ * On a fresh install `seedCheckpoint` starts the cursor at the variant high
+ * water, read before the product feed's first pass, so the catalogue downloads
+ * once. An upgrade (a stored product checkpoint, none for this feed) is not
+ * seeded: its first pass re-delivers every product that has variants, once.
+ * That is deliberate: it heals any price or stock change the product feed
+ * missed before this feed existed.
+ *
+ * `variantPageSize` (the variant page `take`) is for tests and tuning.
+ */
+export const createVendureVariantFeedReplication = (barcodeField?: string, updatedAtSkewMs = 0, variantPageSize = MAX_TAKE): ReplicationAdapter<any, VendureProductCheckpoint> => ({
+  pull: {
+    // The next call's unchanged-high-water check then ends at one read, unless
+    // a variant changed since. The skew probe runs when a pass starts from it.
+    async seedCheckpoint(context) {
+      const head = await newest(context);
+      return { skip: 0, updatedAt: head.items[0]?.updatedAt ?? '', passHighWater: undefined, passTotal: undefined };
+    },
+    async handler(lastCheckpoint, batchSize, context) {
+      if (batchSize > MAX_TAKE || variantPageSize > MAX_TAKE) throw new Error('Vendure Admin API take must not exceed 1000');
+      let passHighWater = lastCheckpoint?.passHighWater ?? lastCheckpoint?.updatedAt ?? '';
+      let skip = lastCheckpoint?.skip ?? 0;
+      let passTotal = lastCheckpoint?.passTotal;
+      if (!skip) {
+        const head = await newest(context);
+        passHighWater = head.items[0]?.updatedAt ?? lastCheckpoint?.updatedAt ?? '';
+        if (!head.items.length || (lastCheckpoint?.updatedAt && passHighWater === lastCheckpoint.updatedAt)) {
+          return { documents: [], checkpoint: lastCheckpoint ?? { skip: 0, updatedAt: '' } };
+        }
+        await probeUpdatedAtSkew(passHighWater, updatedAtSkewMs, async (after) => {
+          const probe = await variants(context, 'id updatedAt', { take: 1, sort: { updatedAt: 'DESC' }, filter: { updatedAt: { after } } });
+          return probe.totalItems;
+        });
+      }
+      const filter = lastCheckpoint?.updatedAt
+        // Vendure after is strict; overlap by 1 ms to include timestamp ties.
+        ? { updatedAt: { after: new Date(Date.parse(lastCheckpoint.updatedAt) - 1 - updatedAtSkewMs).toISOString() } }
+        : undefined;
+      const page = (from: number) => variants(context, 'id productId', { take: variantPageSize, skip: from, sort: { id: 'ASC' }, filter });
+
+      // RxDB stops pulling on a page shorter than batchSize, so keep reading
+      // variant pages until enough parents are delivered or the pass ends.
+      const seen = new Set<string>();
+      const documents: Record<string, unknown>[] = [];
+      let complete = false;
+      while (!complete && documents.length < batchSize) {
+        let data = await page(skip);
+        if (skip > 0 && (!data.items.length || data.totalItems < (passTotal ?? data.totalItems))) {
+          skip = 0; // Rows vanished mid-pass: restart; re-reads are harmless, skips are not.
+          data = await page(0);
+        }
+        if (skip === 0) passTotal = data.totalItems;
+        const parentIds = [...new Set(data.items.map((v) => String(v.productId)))].filter((id) => !seen.has(id));
+        parentIds.forEach((id) => seen.add(id));
+        if (parentIds.length) { // At most variantPageSize (<= MAX_TAKE) ids: one variant page's worth.
+          const res = await gql(context, PRODUCT_LIST_QUERY(barcodeField), {
+            options: { take: parentIds.length, filter: { id: { in: parentIds } } },
+          });
+          documents.push(...(res.data?.products?.items ?? []).map(toProductDocument));
+        }
+        skip += data.items.length;
+        complete = skip >= data.totalItems || !data.items.length;
+      }
+
+      // Keep the lower bound fixed while paging by id; advance it only at pass end.
+      // RxDB merges checkpoints, so explicitly clear pass state at completion.
+      const checkpoint: VendureProductCheckpoint = complete
+        ? { skip: 0, updatedAt: passHighWater, passHighWater: undefined, passTotal: undefined }
+        : { skip, updatedAt: lastCheckpoint?.updatedAt ?? '', passHighWater, passTotal };
+      // RxDB saves no checkpoint from an empty page. If this call's variant
+      // pages mapped to no live parents but the cursor moved, the cursor would
+      // stick mid-pass and a later change below it would be lost. Carry the
+      // checkpoint on one current product; re-delivering it is harmless.
+      const moved = (['skip', 'updatedAt', 'passHighWater', 'passTotal'] as const)
+        .some((key) => checkpoint[key] !== lastCheckpoint?.[key]);
+      if (!documents.length && moved) {
+        const res = await gql(context, PRODUCT_LIST_QUERY(barcodeField), { options: { take: 1 } });
+        documents.push(...(res.data?.products?.items ?? []).map(toProductDocument));
+      }
+      return { documents, checkpoint };
+    },
+  },
+});

package/src/schemas/products.ts

@@ -12,7 +12,10 @@ import type { RxJsonSchema } from 'rxdb';
  * - No native barcode field (custom fields only)
  */
 export const vendureProductSchema: RxJsonSchema<any> = {
-  version: 0,
+  // 1: declares variant trackInventory/outOfStockThreshold/useGlobalOutOfStockThreshold/enabled
+  // (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: {
@@ -80,7 +83,21 @@ export const vendureProductSchema: RxJsonSchema<any> = {
           currencyCode: { type: 'string' },
           stockLevel: { type: 'string' },
           stockOnHand: { type: 'number' },
+          stockLevels: {
+            type: 'array',
+            items: {
+              type: 'object',
+              properties: {
+                stockLocationId: { type: 'string' },
+                stockOnHand: { type: 'number' },
+                stockAllocated: { type: 'number' },
+              },
+            },
+          },
           trackInventory: { type: 'string' },
+          outOfStockThreshold: { type: 'number' },
+          useGlobalOutOfStockThreshold: { type: 'boolean' },
+          enabled: { type: 'boolean' },
           featuredAsset: {
             type: ['object', 'null'],
             properties: {
@@ -100,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,39 @@
+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);
+  if (out === true) return new ConnectorUnauthorizedError(`Vendure GraphQL error: ${forbidden[0].message}`);
+  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

@@ -0,0 +1,81 @@
+import { StoreSettingsError } from '@tallyui/core';
+import type { StoreSettings, StoreSettingsChoice, SyncContext } from '@tallyui/core';
+
+import { gql } from './replication/products';
+
+const CHANNEL_AND_CATEGORIES_QUERY = `
+  query StoreSettingsChannel {
+    activeChannel { defaultCurrencyCode pricesIncludeTax defaultTaxZone { id } }
+    taxCategories { items { id isDefault } }
+  }
+`;
+
+const TAX_RATES_QUERY = `
+  query StoreSettingsTaxRates($zoneId: String!) {
+    taxRates(options: { take: 1000, filter: { zoneId: { eq: $zoneId } } }) {
+      items { 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 };
+
+/** `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> {
+  try {
+    return await gql(context, source, variables);
+  } catch (error) {
+    throw new StoreSettingsError('failed', error instanceof Error ? error.message : String(error));
+  }
+}
+
+/**
+ * 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`:
+ * Vendure's channel is already chosen by the `vendure-token` header sent
+ * with every request, so there is no `pricingContext` either.
+ */
+export const vendureStoreSettings = async (context: SyncContext, _choice?: StoreSettingsChoice): Promise<StoreSettings> => {
+  const head = await query(context, CHANNEL_AND_CATEGORIES_QUERY);
+  const channel = head.data?.activeChannel as ActiveChannel | undefined;
+  if (!channel) throw new StoreSettingsError('failed', 'Vendure returned no active channel');
+  const categories: TaxCategory[] = head.data?.taxCategories?.items ?? [];
+
+  let rateItems: TaxRateItem[] = [];
+  if (channel.defaultTaxZone) {
+    const ratesBody = await query(context, TAX_RATES_QUERY, { zoneId: channel.defaultTaxZone.id });
+    rateItems = ratesBody.data?.taxRates?.items ?? [];
+  }
+
+  const byCategory = new Map<string, number>();
+  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));
+  }
+
+  // Vendure's own fallback for a variant created without a category
+  // (getTaxCategoryForNewVariant, @vendure/core 3.7.3,
+  // dist/service/services/product-variant.service.js:875): the isDefault
+  // category, or, when none is flagged, taxCategories.items[0]. When that
+  // category has no enabled rate in the zone (or there are no categories
+  // 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 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,
+  };
+};

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.
@@ -15,7 +17,7 @@ const PRODUCT_LIST_QUERY = `
   }
 `;
 
-const PRODUCT_DETAIL_QUERY = `
+const PRODUCT_DETAIL_QUERY = (barcodeField?: string) => `
   query GetProduct($id: ID!) {
     product(id: $id) {
       id
@@ -36,12 +38,11 @@ const PRODUCT_DETAIL_QUERY = `
         price
         priceWithTax
         currencyCode
-        stockLevel
-        stockOnHand
+        stockLevels { stockLocationId stockOnHand stockAllocated }
         trackInventory
         featuredAsset { id preview }
         options { id name code }
-        customFields
+        ${barcodeField ? `customFields { ${barcodeField} }` : ''}
       }
     }
   }
@@ -53,7 +54,7 @@ const PRODUCT_DETAIL_QUERY = `
  * Uses the Admin GraphQL API. Vendure uses offset-based pagination
  * with `take` and `skip` options.
  */
-export const vendureProductSync: CollectionSync = {
+export const createVendureProductSync = (barcodeField?: string): CollectionSync => ({
   fetchAllIds: async (context: SyncContext) => {
     const entries: { id: string; dateModified?: string }[] = [];
     const take = 100;
@@ -86,7 +87,7 @@ export const vendureProductSync: CollectionSync = {
     const products: any[] = [];
     // Vendure doesn't support batch-by-IDs natively, so fetch individually
     for (const id of ids) {
-      const res = await gql(context, PRODUCT_DETAIL_QUERY, { id });
+      const res = await gql(context, PRODUCT_DETAIL_QUERY(barcodeField), { id });
       if (res.data?.product) {
         products.push(res.data.product);
       }
@@ -118,7 +119,7 @@ export const vendureProductSync: CollectionSync = {
 
       // Fetch full details for each modified product
       for (const item of data.items ?? []) {
-        const detail = await gql(context, PRODUCT_DETAIL_QUERY, { id: item.id });
+        const detail = await gql(context, PRODUCT_DETAIL_QUERY(barcodeField), { id: item.id });
         if (detail.data?.product) {
           products.push(detail.data.product);
         }
@@ -129,7 +130,9 @@ export const vendureProductSync: CollectionSync = {
 
     return products;
   },
-};
+});
+
+export const vendureProductSync = createVendureProductSync();
 
 /**
  * Helper to execute a GraphQL query against the Vendure Admin API.
@@ -149,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);
   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;
 }