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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Paul Kilmurray and TallyUI contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,7 @@
+# TallyUI Vendure connector
+
+## Errors
+
+Requests with expired or rejected credentials reject with `ConnectorUnauthorizedError` (`code: 'unauthorized'`), defined in `@tallyui/core` and re-exported by this connector. The app should sign in again.
+
+Sign-in itself rejects with `SignInError`.

package/dist/index.d.ts

@@ -1,6 +1,10 @@
-import { ProductTraits, CollectionSync, ReplicationAdapter, TallyConnector } from '@tallyui/core';
+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']>;
+declare const vendureAuth: ConnectorAuth;
+
 /**
  * RxDB schema for Vendure products.
  *
@@ -14,56 +18,124 @@ import { RxJsonSchema } from 'rxdb';
  */
 declare const vendureProductSchema: RxJsonSchema<any>;
 
-/**
- * Vendure product trait implementations.
- *
- * Key differences from other connectors:
- * - Product name is `name` (same as WooCommerce, unlike Medusa's `title`)
- * - Price is on `variants[].priceWithTax` (integer cents, like Medusa)
- * - Images use `featuredAsset.preview` and `assets[].preview`
- * - Stock status is a string from the Shop API: 'IN_STOCK', 'OUT_OF_STOCK', 'LOW_STOCK'
- * - Categories are `collections[].name` (Vendure's equivalent of categories)
- * - No native sale price — Vendure handles sales via promotions at checkout
- * - No native barcode field — uses custom fields if configured
- */
-declare const vendureProductTraits: ProductTraits;
+declare const vendureProductTraits: ProductTraits<any>;
 
-/**
- * Vendure product sync implementation.
- *
- * Uses the Admin GraphQL API. Vendure uses offset-based pagination
- * with `take` and `skip` options.
- */
-declare const vendureProductSync: CollectionSync;
+declare const vendureProductSync: CollectionSync<any>;
 
 type VendureProductCheckpoint = {
     skip: number;
     updatedAt: string;
+    passMax?: string;
+    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.
  *
- * 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.
  */
+declare const createVendureProductReplication: (barcodeField?: string, updatedAtSkewMs?: number) => ReplicationAdapter<any, VendureProductCheckpoint>;
 declare const vendureProductReplication: ReplicationAdapter<any, VendureProductCheckpoint>;
 
 /**
- * Vendure connector for Tally UI.
+ * 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.
+ */
+declare const createVendureVariantFeedReplication: (barcodeField?: string, updatedAtSkewMs?: number, variantPageSize?: number) => ReplicationAdapter<any, VendureProductCheckpoint>;
+
+/**
+ * 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.
+ */
+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`:
+ * Vendure's channel is already chosen by the `vendure-token` header sent
+ * with every request, so there is no `pricingContext` either.
+ */
+declare const vendureStoreSettings: (context: SyncContext, _choice?: StoreSettingsChoice) => Promise<StoreSettings>;
+
+/**
+ * The channel-wide stock defaults an `INHERIT` variant falls back to
+ * (backlog 28). Read with `vendureGlobalStockSettings` after sign-in, like
+ * `pricesIncludeTax` from `storeSettings`.
+ */
+declare function vendureGlobalStockSettings(context: SyncContext): Promise<{
+    trackInventory: boolean;
+    outOfStockThreshold: number;
+}>;
+
+/**
+ * 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`.
+ */
+declare const createVendureConnector: (options?: {
+    barcodeField?: string;
+    stockLocationId?: string;
+    pricesIncludeTax?: boolean;
+    updatedAtSkewMs?: number;
+    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 { vendureConnector, vendureProductReplication, vendureProductSchema, vendureProductSync, vendureProductTraits };
+export { VendureTimezoneConfigError, createVendureConnector, createVendureProductReplication, createVendureVariantFeedReplication, vendureAuth, vendureConnector, vendureGlobalStockSettings, vendureProductReplication, vendureProductSchema, vendureProductSync, vendureProductTraits, vendureSignIn, vendureStockReconcile, vendureStoreSettings };