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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tallyui/connector-vendure",
-  "version": "1.0.0",
+  "version": "3.0.0-next.0",
   "type": "module",
   "description": "Vendure connector for Tally UI",
   "main": "./dist/index.js",
@@ -15,14 +15,23 @@
   },
   "files": [
     "dist",
-    "src"
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.fixture.json"
   ],
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TallyUI/tallyui.git",
+    "directory": "connectors/vendure"
+  },
   "peerDependencies": {
-    "@tallyui/core": "0.2.0"
+    "@tallyui/core": "^3.0.0-next.0"
   },
   "devDependencies": {
-    "rxdb": "16.21.1"
+    "@tallyui/database": "3.0.0-next.0",
+    "@tallyui/pos": "3.0.0-next.0",
+    "rxdb": "17.5.0"
   },
   "scripts": {
     "build": "tsup",

package/src/auth.ts

@@ -0,0 +1,79 @@
+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
+    ... on CurrentUser { id }
+    ... on ErrorResult { errorCode message }
+  }
+}`;
+
+type LoginBody = { data?: { login?: { __typename: string; errorCode?: string; message?: string } }; errors?: { message: string }[] };
+
+// Signs in on the Admin API; the session token comes back in the vendure-auth-token header.
+// Vendure sessions roll forward on use, so there is no expiresAt.
+export const vendureSignIn: NonNullable<ConnectorAuth['signIn']> = async (baseUrl, { email, password }, init = {}) => {
+  const doFetch = init.fetch ?? fetch;
+  let res: Response;
+  try {
+    res = await doFetch(`${baseUrl}/admin-api`, {
+      method: 'POST', headers: { 'Content-Type': 'application/json' }, signal: init.signal,
+      body: JSON.stringify({ query: LOGIN, variables: { email, password } }),
+    });
+  } catch (error) {
+    if ((error as { name?: unknown })?.name === 'AbortError' || init.signal?.aborted) throw error;
+    throw new SignInError('failed', `Could not reach Vendure at ${baseUrl}: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  let body: LoginBody;
+  try {
+    body = await res.json();
+  } catch {
+    throw new SignInError('server_error', `Vendure sent an unreadable response (HTTP ${res.status})`, res.status);
+  }
+  if (!res.ok) throw new SignInError('server_error', body?.errors?.[0]?.message ?? `Vendure sign-in failed (HTTP ${res.status})`, res.status);
+  const login = body?.data?.login;
+  if (body?.errors?.length || !login) {
+    throw new SignInError('server_error', body?.errors?.[0]?.message ?? `Vendure sign-in failed (HTTP ${res.status})`, res.status);
+  }
+  if (login.errorCode === 'INVALID_CREDENTIALS_ERROR') throw new SignInError('invalid_credentials', login.message ?? 'Invalid email or password');
+  // Native email/password auth is disabled on the server, so it needs a sign-in flow this connector can't do.
+  if (login.errorCode === 'NATIVE_AUTH_STRATEGY_ERROR') throw new SignInError('unsupported', login.message ?? 'Native email and password sign-in is disabled on this Vendure server');
+  if (login.__typename !== 'CurrentUser') throw new SignInError('server_error', login.message ?? `Vendure sign-in failed (${login.__typename})`, res.status);
+  const token = res.headers.get('vendure-auth-token');
+  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.");
+  }
+  // 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.
+let warnedAuthToken = false;
+
+export const vendureAuth: ConnectorAuth = {
+  type: 'Vendure Admin API',
+  fields: [
+    { key: 'url', label: 'Backend URL', type: 'url', placeholder: 'https://my-vendure-server.com', required: true },
+    { key: 'email', label: 'Email', type: 'text', required: true },
+    { key: 'password', label: 'Password', type: 'password', required: true },
+    { key: 'channel_token', label: 'Channel token (optional)', type: 'text' },
+  ],
+  // An API key (Vendure 3.6+) wins over a signed-in session token; channel_token selects a non-default channel.
+  // auth_token is the deprecated name for token, kept so existing apps keep working.
+  getHeaders: (credentials): Record<string, string> => {
+    if (credentials.token === undefined && credentials.auth_token !== undefined && !warnedAuthToken) {
+      warnedAuthToken = true;
+      console.warn("@tallyui/connector-vendure: the 'auth_token' credential is deprecated; store the credential as 'token' instead.");
+    }
+    const token = credentials.token ?? credentials.auth_token;
+    return {
+      ...(credentials.api_key ? { 'vendure-api-key': credentials.api_key } : token ? { Authorization: `Bearer ${token}` } : {}),
+      ...(credentials.channel_token ? { 'vendure-token': credentials.channel_token } : {}),
+    };
+  },
+  signIn: vendureSignIn,
+};

package/src/capabilities.ts

@@ -0,0 +1,44 @@
+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 2xx gives `parseInfoCapabilities`; a 404 or a non-JSON body
+ * means no plugin and gives `{ orderCreate: 1 }`; a network failure, a 5xx or any other
+ * non-2xx 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 });
+    if (out === true) throw new ConnectorUnauthorizedError(`Vendure refused ${CAPABILITIES_PATH}: the session is signed out`, res.status);
+    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 { orderCreate: 1 };
+  }
+  return parseInfoCapabilities(body, (reason) => console.warn(`@tallyui/connector-vendure: ${reason}`));
+}

package/src/global-settings.ts

@@ -0,0 +1,18 @@
+import type { SyncContext } from '@tallyui/core';
+import { gql } from './replication/products';
+
+const GLOBAL_SETTINGS_QUERY = `
+  query GlobalStockSettings {
+    globalSettings { trackInventory outOfStockThreshold }
+  }
+`;
+
+/**
+ * The channel-wide stock defaults an `INHERIT` variant falls back to
+ * (backlog 28). Read with `vendureGlobalStockSettings` after sign-in, like
+ * `pricesIncludeTax` from `storeSettings`.
+ */
+export async function vendureGlobalStockSettings(context: SyncContext): Promise<{ trackInventory: boolean; outOfStockThreshold: number }> {
+  const res = await gql(context, GLOBAL_SETTINGS_QUERY);
+  return res.data.globalSettings;
+}

package/src/index.ts

@@ -1,73 +1,112 @@
-import type { TallyConnector } from '@tallyui/core';
+import { combinePullAdapters, createReconcileFeed, type TallyConnector } from '@tallyui/core';
 
+import { vendureAuth } from './auth';
+import { readVendureCapabilities } from './capabilities';
 import { vendureProductSchema } from './schemas/products';
-import { vendureProductTraits } from './traits/product';
-import { vendureProductSync } from './sync/products';
-import { vendureProductReplication } from './replication/products';
+import { createVendureProductTraits } from './traits/product';
+import { createVendureProductSync } from './sync/products';
+import { createVendureProductReplication } from './replication/products';
+import { createVendureVariantFeedReplication } from './replication/variant-feed';
+import { vendureStockReconcile } from './reconcile/stock';
+import { createFetchByIds, fetchPages, variantIds } from './reconcile/ids';
+import { fetchPages as fetchPricePages, fingerprint as priceFingerprint } from './reconcile/prices';
+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>
  * ```
+ *
+ * `pricesIncludeTax` must equal the POS tax setting (`TaxContext.pricesIncludeTax`);
+ * pass `settings.pricesIncludeTax` from `storeSettings`. `globalTrackInventory`
+ * and `globalOutOfStockThreshold` are the channel's stock defaults; read them
+ * with `vendureGlobalStockSettings` after sign-in, like `pricesIncludeTax`
+ * from `storeSettings`.
  */
-export const vendureConnector: TallyConnector = {
-  id: 'vendure',
-  name: 'Vendure',
-  description: 'Connect to Vendure backends via the Admin GraphQL API',
-  icon: undefined,
+export const createVendureConnector = (options: {
+  barcodeField?: string; stockLocationId?: string; pricesIncludeTax?: boolean; updatedAtSkewMs?: number;
+  globalTrackInventory?: boolean; globalOutOfStockThreshold?: number;
+} = {}): TallyConnector => {
+  // The id reconcile's corrections reach `products` only through this pull adapter (ADR-060).
+  const idFeed = createReconcileFeed({ fetchByIds: createFetchByIds(options.barcodeField) });
+  return {
+    id: 'vendure',
+    name: 'Vendure',
+    description: 'Connect to Vendure backends via the Admin GraphQL API',
+    icon: undefined,
+
+    auth: vendureAuth,
+
+    schemas: {
+      products: vendureProductSchema,
+    },
+
+    traits: {
+      product: createVendureProductTraits(
+        options.barcodeField, options.stockLocationId, options.pricesIncludeTax,
+        options.globalTrackInventory, options.globalOutOfStockThreshold,
+      ),
+    },
 
-  auth: {
-    type: 'Vendure Admin API',
-    fields: [
-      {
-        key: 'url',
-        label: 'Backend URL',
-        type: 'url',
-        placeholder: 'https://my-vendure-server.com',
-        required: true,
-      },
-      {
-        key: 'auth_token',
-        label: 'Auth Token',
-        type: 'password',
-        placeholder: 'vendure-auth-token from login',
-        required: true,
-      },
-    ],
-    getHeaders: (credentials) => ({
-      Authorization: `Bearer ${credentials.auth_token}`,
-    }),
-  },
+    sync: {
+      products: createVendureProductSync(options.barcodeField),
+    },
 
-  schemas: {
-    products: vendureProductSchema,
-  },
+    replication: {
+      // One replication per collection: the product, variant and id-reconcile feeds
+      // share it (ADR-060). reconcile is last so its fetch wins duplicates.
+      products: combinePullAdapters({
+        products: createVendureProductReplication(options.barcodeField, options.updatedAtSkewMs),
+        variants: createVendureVariantFeedReplication(options.barcodeField, options.updatedAtSkewMs),
+        reconcile: idFeed.adapter,
+      }, { legacyKey: 'products' }),
+    },
 
-  traits: {
-    product: vendureProductTraits,
-  },
+    reconcile: {
+      stock: vendureStockReconcile,
+      ids: { fetchPages, variantIds, enqueue: idFeed.enqueue, refetchBatchSize: VENDURE_IDS_PER_REQUEST },
+      prices: { fetchPages: fetchPricePages, fingerprint: priceFingerprint, enqueue: idFeed.enqueue, refetchBatchSize: VENDURE_IDS_PER_REQUEST },
+    },
 
-  sync: {
-    products: vendureProductSync,
-  },
+    storeSettings: vendureStoreSettings,
 
-  replication: {
-    products: vendureProductReplication,
-  },
+    // 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
+export { vendureAuth, vendureSignIn } from './auth';
 export { vendureProductSchema } from './schemas/products';
 export { vendureProductTraits } from './traits/product';
 export { vendureProductSync } from './sync/products';
-export { vendureProductReplication } from './replication/products';
+export { createVendureProductReplication, vendureProductReplication } from './replication/products';
+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/reconcile/ids.ts

@@ -0,0 +1,38 @@
+import type { SyncContext } from '@tallyui/core';
+import { gql, PRODUCT_LIST_QUERY, toProductDocument } from '../replication/products';
+
+/** Vendure Admin API maximum `take`; also the id-listing page size. */
+const PAGE_SIZE = 1000;
+
+const ID_LIST_QUERY = `
+  query GetProductIds($options: ProductListOptions) {
+    products(options: $options) { items { id variants { id } } totalItems }
+  }
+`;
+
+/** Every live product id with its live variant ids, one request per page (ADR-060). */
+export async function* fetchPages(context: SyncContext): AsyncIterable<Array<{ id: string; variantIds: string[] }>> {
+  // total starts at 1 so the loop runs at least once, before totalItems is known.
+  for (let skip = 0, total = 1; skip < total; skip += PAGE_SIZE) {
+    const res = await gql(context, ID_LIST_QUERY, { options: { take: PAGE_SIZE, skip, sort: { id: 'ASC' } } });
+    const { items, totalItems } = res.data.products as {
+      items: Array<{ id: string; variants: Array<{ id: string }> }>; totalItems: number;
+    };
+    total = totalItems;
+    yield items.map((p) => ({ id: String(p.id), variantIds: (p.variants ?? []).map((v) => String(v.id)) }));
+  }
+}
+
+/** The variant ids a local product document lists. */
+export function variantIds(doc: any): string[] {
+  return (doc.variants ?? []).map((v: any) => String(v.id));
+}
+
+/** `fetchByIds` for `createReconcileFeed`, in the replication feeds' document shape. */
+export function createFetchByIds(barcodeField?: string) {
+  return async function fetchByIds(ids: string[], context: SyncContext): Promise<Record<string, unknown>[]> {
+    if (!ids.length) return [];
+    const res = await gql(context, PRODUCT_LIST_QUERY(barcodeField), { options: { take: ids.length, filter: { id: { in: ids } } } });
+    return (res.data?.products?.items ?? []).map(toProductDocument);
+  };
+}

package/src/reconcile/prices.ts

@@ -0,0 +1,58 @@
+import type { SyncContext } from '@tallyui/core';
+import { gql } from '../replication/products';
+
+/** Vendure Admin API maximum `take`; also the price-listing page size (ADR-060). */
+const PAGE_SIZE = 1000;
+
+/**
+ * The nightly base-price backstop's interval: tax-rate changes move
+ * `priceWithTax` without bumping `updatedAt` (ADR-060).
+ */
+export const VENDURE_PRICE_RECONCILE_INTERVAL_MS = 24 * 60 * 60 * 1000;
+
+const PRICE_LIST_QUERY = `
+  query GetVariantPrices($options: ProductVariantListOptions) {
+    productVariants(options: $options) { items { id productId price priceWithTax currencyCode } totalItems }
+  }
+`;
+
+/** `${variantId}:${currencyCode}:${price}:${priceWithTax}` entries, sorted and joined. */
+const fingerprintOf = (entries: string[]): string => [...entries].sort().join('|');
+
+/**
+ * Every product's price fingerprint, one `productVariants` page at a time
+ * (ADR-060's nightly backstop). The listing is not grouped by product, so a
+ * product's variants may land on different pages; a page's yielded entry is
+ * always recomputed from every variant seen for that product so far, so the
+ * last page that touches a product carries its complete, correct
+ * fingerprint. The reconcile runner keeps only the latest entry per id, so
+ * earlier, partial entries are harmless.
+ */
+export async function* fetchPages(context: SyncContext): AsyncIterable<Map<string, string>> {
+  const byProduct = new Map<string, string[]>();
+  for (let skip = 0, total = 1; skip < total; skip += PAGE_SIZE) {
+    const res = await gql(context, PRICE_LIST_QUERY, { options: { take: PAGE_SIZE, skip, sort: { id: 'ASC' } } });
+    const { items, totalItems } = res.data.productVariants as {
+      items: Array<{ id: string; productId: string; price: number; priceWithTax: number; currencyCode: string }>;
+      totalItems: number;
+    };
+    total = totalItems;
+    const touched = new Set<string>();
+    for (const variant of items) {
+      const productId = String(variant.productId);
+      touched.add(productId);
+      const entries = byProduct.get(productId) ?? [];
+      byProduct.set(productId, entries);
+      entries.push(`${variant.id}:${variant.currencyCode}:${variant.price}:${variant.priceWithTax}`);
+    }
+    yield new Map([...touched].map((id) => [id, fingerprintOf(byProduct.get(id) ?? [])]));
+  }
+}
+
+/** The same fingerprint, computed from a local product document's variants. Replicated Vendure documents already carry `price`, `priceWithTax` and `currencyCode`. */
+export function fingerprint(doc: any): string {
+  const entries: string[] = (doc.variants ?? []).map(
+    (v: any) => `${v.id}:${v.currencyCode}:${v.price}:${v.priceWithTax}`,
+  );
+  return fingerprintOf(entries);
+}

package/src/reconcile/stock.ts

@@ -0,0 +1,48 @@
+import type { StockReconcileAdapter } from '@tallyui/core';
+
+import { gql } from '../replication/products';
+
+type StockLevel = { stockLocationId: string; stockOnHand: number; stockAllocated: number };
+
+/** Admin API maximum `take`. */
+const PAGE_SIZE = 1000;
+
+const VARIANT_STOCK_QUERY = `
+  query VariantStock($options: ProductVariantListOptions) {
+    productVariants(options: $options) {
+      items { id stockLevels { stockLocationId stockOnHand stockAllocated } }
+      totalItems
+    }
+  }
+`;
+
+/** Compared by value as sorted tuples; neither key nor level order is guaranteed. */
+const levelsKey = (levels: StockLevel[] = []) =>
+  levels.map((l) => JSON.stringify([l.stockLocationId, l.stockOnHand, l.stockAllocated])).sort().join();
+
+/**
+ * Stock reconciler for Vendure products (ADR-060). Stock edits bump only the
+ * variant's updatedAt and allocations bump nothing, so replication misses them.
+ * Pages are keyed by variant id; each value is the variant's stockLevels.
+ */
+export const vendureStockReconcile: StockReconcileAdapter = {
+  async *fetchPages(context) {
+    for (let skip = 0, total = 1; skip < total; skip += PAGE_SIZE) {
+      const body = await gql(context, VARIANT_STOCK_QUERY, { options: { take: PAGE_SIZE, skip, sort: { id: 'ASC' } } });
+      const { items, totalItems } = body.data.productVariants as { items: Array<{ id: string; stockLevels: StockLevel[] }>; totalItems: number };
+      total = totalItems;
+      yield new Map(items.map((v) => [v.id, v.stockLevels]));
+    }
+  },
+  overlay(doc, stock) {
+    const variants: any[] = doc.variants ?? [];
+    let changed = false;
+    const next = variants.map((v) => {
+      const levels = stock.get(v.id) as StockLevel[] | undefined;
+      if (!levels || levelsKey(levels) === levelsKey(v.stockLevels)) return v;
+      changed = true;
+      return { ...v, stockLevels: levels };
+    });
+    return changed ? { variants: next } : undefined;
+  },
+};