@tallyui/connector-vendure 1.0.0 → 2.0.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/dist/index.d.ts

@@ -1,6 +1,9 @@
-import { ProductTraits, CollectionSync, ReplicationAdapter, TallyConnector } from '@tallyui/core';
+import { ConnectorAuth, ProductTraits, CollectionSync, ReplicationAdapter, StockReconcileAdapter, SyncContext, StoreSettingsChoice, StoreSettings, TallyConnector } from '@tallyui/core';
 import { RxJsonSchema } from 'rxdb';
 
+declare const vendureSignIn: NonNullable<ConnectorAuth['signIn']>;
+declare const vendureAuth: ConnectorAuth;
+
 /**
  * RxDB schema for Vendure products.
  *
@@ -14,41 +17,76 @@ 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;
 };
 /**
  * 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>;
 
+/**
+ * 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.
  *
@@ -63,7 +101,21 @@ declare const vendureProductReplication: ReplicationAdapter<any, VendureProductC
  *   <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;
 declare const vendureConnector: TallyConnector;
 
-export { vendureConnector, vendureProductReplication, vendureProductSchema, vendureProductSync, vendureProductTraits };
+export { createVendureConnector, createVendureProductReplication, createVendureVariantFeedReplication, vendureAuth, vendureConnector, vendureGlobalStockSettings, vendureProductReplication, vendureProductSchema, vendureProductSync, vendureProductTraits, vendureSignIn, vendureStockReconcile, vendureStoreSettings };