@tallyui/connector-vendure 1.0.0

package/src/__tests__/product-traits.test.ts

@@ -0,0 +1,248 @@
+import { describe, it, expect } from 'vitest';
+import { vendureProductTraits } from '../traits/product';
+
+/**
+ * Realistic Vendure product document, shaped like the Admin GraphQL API response.
+ */
+const fullProduct = {
+  id: '42',
+  name: 'Commercial Espresso Machine',
+  slug: 'commercial-espresso-machine',
+  description: '<p>High-end commercial espresso machine with dual boilers.</p>',
+  enabled: true,
+  featuredAsset: {
+    id: '89',
+    preview: 'https://cdn.example.com/assets/espresso-main__preview.jpg',
+  },
+  assets: [
+    { id: '89', preview: 'https://cdn.example.com/assets/espresso-main__preview.jpg' },
+    { id: '90', preview: 'https://cdn.example.com/assets/espresso-side__preview.jpg' },
+    { id: '91', preview: 'https://cdn.example.com/assets/espresso-back__preview.jpg' },
+  ],
+  collections: [
+    { id: '5', name: 'Equipment', slug: 'equipment' },
+    { id: '12', name: 'Coffee Machines', slug: 'coffee-machines' },
+  ],
+  facetValues: [
+    { id: '23', name: 'Espresso', code: 'espresso', facet: { id: '3', name: 'Category' } },
+    { id: '31', name: 'La Marzocco', code: 'la-marzocco', facet: { id: '5', name: 'Brand' } },
+  ],
+  variants: [
+    {
+      id: '101',
+      name: 'Commercial Espresso Machine 110V',
+      sku: 'VND-ESP-110',
+      price: 489900,
+      priceWithTax: 534191,
+      currencyCode: 'USD',
+      stockLevel: 'IN_STOCK',
+      stockOnHand: 12,
+      trackInventory: 'INHERIT',
+      featuredAsset: null,
+      options: [{ id: '14', name: '110V', code: '110v' }],
+      customFields: { barcode: '5901234123457' },
+    },
+    {
+      id: '102',
+      name: 'Commercial Espresso Machine 220V',
+      sku: 'VND-ESP-220',
+      price: 489900,
+      priceWithTax: 534191,
+      currencyCode: 'USD',
+      stockLevel: 'OUT_OF_STOCK',
+      stockOnHand: 0,
+      trackInventory: 'INHERIT',
+      featuredAsset: null,
+      options: [{ id: '15', name: '220V', code: '220v' }],
+      customFields: {},
+    },
+  ],
+};
+
+const simpleProduct = {
+  id: '43',
+  name: 'Coffee Mug',
+  slug: 'coffee-mug',
+  description: 'A simple ceramic mug.',
+  enabled: true,
+  featuredAsset: null,
+  assets: [],
+  collections: [],
+  facetValues: [],
+  variants: [
+    {
+      id: '201',
+      name: 'Coffee Mug',
+      sku: 'MUG-001',
+      price: 1299,
+      priceWithTax: 1499,
+      currencyCode: 'USD',
+      stockLevel: 'LOW_STOCK',
+      stockOnHand: 3,
+      trackInventory: 'INHERIT',
+      featuredAsset: null,
+      options: [],
+      customFields: {},
+    },
+  ],
+};
+
+const minimalProduct = {
+  id: '999',
+};
+
+describe('Vendure product traits', () => {
+  describe('getId', () => {
+    it('returns the product id as a string', () => {
+      expect(vendureProductTraits.getId(fullProduct)).toBe('42');
+    });
+  });
+
+  describe('getName', () => {
+    it('returns the name', () => {
+      expect(vendureProductTraits.getName(fullProduct)).toBe('Commercial Espresso Machine');
+    });
+
+    it('returns empty string for missing name', () => {
+      expect(vendureProductTraits.getName(minimalProduct)).toBe('');
+    });
+  });
+
+  describe('getSku', () => {
+    it('returns SKU from first variant', () => {
+      expect(vendureProductTraits.getSku(fullProduct)).toBe('VND-ESP-110');
+    });
+
+    it('returns undefined when no variants', () => {
+      expect(vendureProductTraits.getSku(minimalProduct)).toBeUndefined();
+    });
+  });
+
+  describe('getPrice', () => {
+    it('converts priceWithTax cents to decimal string', () => {
+      expect(vendureProductTraits.getPrice(fullProduct)).toBe('5341.91');
+    });
+
+    it('handles smaller prices', () => {
+      expect(vendureProductTraits.getPrice(simpleProduct)).toBe('14.99');
+    });
+
+    it('returns undefined when no variants', () => {
+      expect(vendureProductTraits.getPrice(minimalProduct)).toBeUndefined();
+    });
+  });
+
+  describe('getRegularPrice / getSalePrice / isOnSale', () => {
+    it('regular price matches price (Vendure uses promotions, not product-level sales)', () => {
+      expect(vendureProductTraits.getRegularPrice(fullProduct)).toBe('5341.91');
+    });
+
+    it('sale price is always undefined', () => {
+      expect(vendureProductTraits.getSalePrice(fullProduct)).toBeUndefined();
+    });
+
+    it('isOnSale is always false', () => {
+      expect(vendureProductTraits.isOnSale(fullProduct)).toBe(false);
+    });
+  });
+
+  describe('getImageUrl / getImageUrls', () => {
+    it('returns featuredAsset preview URL', () => {
+      expect(vendureProductTraits.getImageUrl(fullProduct)).toBe(
+        'https://cdn.example.com/assets/espresso-main__preview.jpg'
+      );
+    });
+
+    it('returns all asset preview URLs', () => {
+      expect(vendureProductTraits.getImageUrls(fullProduct)).toEqual([
+        'https://cdn.example.com/assets/espresso-main__preview.jpg',
+        'https://cdn.example.com/assets/espresso-side__preview.jpg',
+        'https://cdn.example.com/assets/espresso-back__preview.jpg',
+      ]);
+    });
+
+    it('returns undefined / empty when no assets', () => {
+      expect(vendureProductTraits.getImageUrl(simpleProduct)).toBeUndefined();
+      expect(vendureProductTraits.getImageUrls(simpleProduct)).toEqual([]);
+    });
+  });
+
+  describe('getDescription', () => {
+    it('returns the description', () => {
+      expect(vendureProductTraits.getDescription(fullProduct)).toBe(
+        '<p>High-end commercial espresso machine with dual boilers.</p>'
+      );
+    });
+
+    it('returns undefined when missing', () => {
+      expect(vendureProductTraits.getDescription(minimalProduct)).toBeUndefined();
+    });
+  });
+
+  describe('getStockStatus', () => {
+    it('maps IN_STOCK to instock', () => {
+      expect(vendureProductTraits.getStockStatus(fullProduct)).toBe('instock');
+    });
+
+    it('maps LOW_STOCK to instock', () => {
+      expect(vendureProductTraits.getStockStatus(simpleProduct)).toBe('instock');
+    });
+
+    it('maps OUT_OF_STOCK to outofstock', () => {
+      const outOfStock = {
+        ...fullProduct,
+        variants: [{ ...fullProduct.variants[1] }], // 220V variant is OUT_OF_STOCK
+      };
+      expect(vendureProductTraits.getStockStatus(outOfStock)).toBe('outofstock');
+    });
+
+    it('returns unknown when no variants', () => {
+      expect(vendureProductTraits.getStockStatus(minimalProduct)).toBe('unknown');
+    });
+  });
+
+  describe('getStockQuantity', () => {
+    it('returns stockOnHand from first variant', () => {
+      expect(vendureProductTraits.getStockQuantity(fullProduct)).toBe(12);
+    });
+
+    it('returns null when no variants', () => {
+      expect(vendureProductTraits.getStockQuantity(minimalProduct)).toBeNull();
+    });
+  });
+
+  describe('hasVariants / getType', () => {
+    it('multi-variant product has variants', () => {
+      expect(vendureProductTraits.hasVariants(fullProduct)).toBe(true);
+      expect(vendureProductTraits.getType(fullProduct)).toBe('variable');
+    });
+
+    it('single-variant product has no variants', () => {
+      expect(vendureProductTraits.hasVariants(simpleProduct)).toBe(false);
+      expect(vendureProductTraits.getType(simpleProduct)).toBe('simple');
+    });
+  });
+
+  describe('getBarcode', () => {
+    it('returns barcode from custom fields', () => {
+      expect(vendureProductTraits.getBarcode(fullProduct)).toBe('5901234123457');
+    });
+
+    it('returns undefined when no custom barcode', () => {
+      expect(vendureProductTraits.getBarcode(simpleProduct)).toBeUndefined();
+    });
+  });
+
+  describe('getCategoryNames', () => {
+    it('returns collection names', () => {
+      expect(vendureProductTraits.getCategoryNames(fullProduct)).toEqual([
+        'Equipment',
+        'Coffee Machines',
+      ]);
+    });
+
+    it('returns empty array when no collections', () => {
+      expect(vendureProductTraits.getCategoryNames(simpleProduct)).toEqual([]);
+    });
+  });
+});

package/src/index.ts

@@ -0,0 +1,73 @@
+import type { TallyConnector } from '@tallyui/core';
+
+import { vendureProductSchema } from './schemas/products';
+import { vendureProductTraits } from './traits/product';
+import { vendureProductSync } from './sync/products';
+import { vendureProductReplication } from './replication/products';
+
+/**
+ * Vendure connector for Tally UI.
+ *
+ * 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 { ConnectorProvider } from '@tallyui/core';
+ *
+ * <ConnectorProvider connector={vendureConnector}>
+ *   <App />
+ * </ConnectorProvider>
+ * ```
+ */
+export const vendureConnector: TallyConnector = {
+  id: 'vendure',
+  name: 'Vendure',
+  description: 'Connect to Vendure backends via the Admin GraphQL API',
+  icon: undefined,
+
+  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}`,
+    }),
+  },
+
+  schemas: {
+    products: vendureProductSchema,
+  },
+
+  traits: {
+    product: vendureProductTraits,
+  },
+
+  sync: {
+    products: vendureProductSync,
+  },
+
+  replication: {
+    products: vendureProductReplication,
+  },
+};
+
+// Re-export pieces for advanced usage
+export { vendureProductSchema } from './schemas/products';
+export { vendureProductTraits } from './traits/product';
+export { vendureProductSync } from './sync/products';
+export { vendureProductReplication } from './replication/products';

package/src/replication/products.test.ts

@@ -0,0 +1,204 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import type { SyncContext } from '@tallyui/core';
+
+import { vendureProductReplication } from './products';
+
+const context: SyncContext = {
+  connectorId: 'vendure',
+  baseUrl: 'https://my-vendure-server.com',
+  headers: { Authorization: 'Bearer test_token' },
+};
+
+/**
+ * Helper to build a mock GraphQL response.
+ */
+function gqlResponse(data: any, errors?: any[]) {
+  return new Response(
+    JSON.stringify({ data, errors }),
+    { status: 200, headers: { 'Content-Type': 'application/json' } },
+  );
+}
+
+describe('vendureProductReplication.pull.handler', () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('fetches products from initial checkpoint (undefined)', async () => {
+    const mockProducts = [
+      { id: '1', name: 'Widget', updatedAt: '2026-01-01T00:00:00Z' },
+      { id: '2', name: 'Gadget', updatedAt: '2026-01-02T00:00:00Z' },
+    ];
+
+    vi.spyOn(globalThis, 'fetch').mockResolvedValueOnce(
+      gqlResponse({
+        products: { items: mockProducts, totalItems: 2 },
+      }),
+    );
+
+    const result = await vendureProductReplication.pull.handler(undefined, 100, context);
+
+    expect(result.documents).toHaveLength(2);
+    expect(result.documents[0]._deleted).toBe(false);
+    expect(result.checkpoint).toEqual({
+      skip: 0,
+      updatedAt: '2026-01-02T00:00:00Z',
+    });
+
+    // Verify the GraphQL request
+    const [url, opts] = (globalThis.fetch as any).mock.calls[0];
+    expect(url).toContain('/admin-api');
+    const body = JSON.parse(opts.body);
+    expect(body.variables.options.take).toBe(100);
+    expect(body.variables.options.skip).toBe(0);
+    expect(body.variables.options.filter).toBeUndefined();
+  });
+
+  it('passes updatedAt filter and skip from checkpoint', async () => {
+    const mockProducts = [
+      { id: '3', name: 'Thingamajig', updatedAt: '2026-02-01T00:00:00Z' },
+    ];
+
+    vi.spyOn(globalThis, 'fetch').mockResolvedValueOnce(
+      gqlResponse({
+        products: { items: mockProducts, totalItems: 1 },
+      }),
+    );
+
+    const checkpoint = { skip: 50, updatedAt: '2026-01-15T00:00:00Z' };
+    const result = await vendureProductReplication.pull.handler(checkpoint, 100, context);
+
+    const body = JSON.parse((globalThis.fetch as any).mock.calls[0][1].body);
+    expect(body.variables.options.skip).toBe(50);
+    expect(body.variables.options.filter).toEqual({
+      updatedAt: { after: '2026-01-15T00:00:00Z' },
+    });
+
+    // Batch smaller than batchSize resets skip to 0
+    expect(result.checkpoint.skip).toBe(0);
+  });
+
+  it('advances skip when batch equals batchSize', async () => {
+    const mockProducts = Array.from({ length: 25 }, (_, i) => ({
+      id: String(i),
+      name: `Product ${i}`,
+      updatedAt: '2026-01-01T00:00:00Z',
+    }));
+
+    vi.spyOn(globalThis, 'fetch').mockResolvedValueOnce(
+      gqlResponse({
+        products: { items: mockProducts, totalItems: 100 },
+      }),
+    );
+
+    const result = await vendureProductReplication.pull.handler(undefined, 25, context);
+
+    expect(result.checkpoint.skip).toBe(25);
+  });
+
+  it('throws on non-OK HTTP response', async () => {
+    vi.spyOn(globalThis, 'fetch').mockResolvedValueOnce(
+      new Response('Internal Server Error', { status: 500 }),
+    );
+
+    await expect(
+      vendureProductReplication.pull.handler(undefined, 100, context),
+    ).rejects.toThrow('Vendure API error: 500');
+  });
+
+  it('throws on GraphQL errors', async () => {
+    vi.spyOn(globalThis, 'fetch').mockResolvedValueOnce(
+      gqlResponse(null, [{ message: 'Something went wrong' }]),
+    );
+
+    await expect(
+      vendureProductReplication.pull.handler(undefined, 100, context),
+    ).rejects.toThrow('Vendure GraphQL error: Something went wrong');
+  });
+
+  it('returns lastCheckpoint when no products are returned', async () => {
+    vi.spyOn(globalThis, 'fetch').mockResolvedValueOnce(
+      gqlResponse({
+        products: { items: [], totalItems: 0 },
+      }),
+    );
+
+    const checkpoint = { skip: 0, updatedAt: '2026-01-01T00:00:00Z' };
+    const result = await vendureProductReplication.pull.handler(checkpoint, 100, context);
+
+    expect(result.checkpoint).toEqual(checkpoint);
+  });
+});
+
+describe('vendureProductReplication.push.handler', () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('sends updateProduct mutation', async () => {
+    vi.spyOn(globalThis, 'fetch').mockResolvedValueOnce(
+      gqlResponse({
+        updateProduct: { id: '1', updatedAt: '2026-01-03T00:00:00Z' },
+      }),
+    );
+
+    const conflicts = await vendureProductReplication.push!.handler(
+      [{
+        newDocumentState: { id: '1', name: 'Updated', _deleted: false } as any,
+        assumedMasterState: { id: '1', name: 'Old', _deleted: false } as any,
+      }],
+      context,
+    );
+
+    expect(conflicts).toHaveLength(0);
+    const body = JSON.parse((globalThis.fetch as any).mock.calls[0][1].body);
+    expect(body.query).toContain('updateProduct');
+    expect(body.variables.input.name).toBe('Updated');
+  });
+
+  it('returns conflicts on GraphQL error', async () => {
+    vi.spyOn(globalThis, 'fetch').mockResolvedValueOnce(
+      gqlResponse(null, [{ message: 'Conflict' }]),
+    );
+
+    const conflicts = await vendureProductReplication.push!.handler(
+      [{
+        newDocumentState: { id: '1', name: 'Updated', _deleted: false } as any,
+        assumedMasterState: { id: '1', name: 'Server Version', _deleted: false } as any,
+      }],
+      context,
+    );
+
+    expect(conflicts).toHaveLength(1);
+    expect(conflicts[0].name).toBe('Server Version');
+  });
+
+  it('returns conflicts on network failure', async () => {
+    vi.spyOn(globalThis, 'fetch').mockRejectedValueOnce(new Error('Network error'));
+
+    const conflicts = await vendureProductReplication.push!.handler(
+      [{
+        newDocumentState: { id: '1', name: 'Updated', _deleted: false } as any,
+        assumedMasterState: { id: '1', name: 'Server Version', _deleted: false } as any,
+      }],
+      context,
+    );
+
+    expect(conflicts).toHaveLength(1);
+  });
+
+  it('does not return conflict when assumedMasterState is absent', async () => {
+    vi.spyOn(globalThis, 'fetch').mockResolvedValueOnce(
+      gqlResponse(null, [{ message: 'Error' }]),
+    );
+
+    const conflicts = await vendureProductReplication.push!.handler(
+      [{
+        newDocumentState: { id: '1', name: 'New Product', _deleted: false } as any,
+      }],
+      context,
+    );
+
+    expect(conflicts).toHaveLength(0);
+  });
+});

package/src/replication/products.ts

@@ -0,0 +1,148 @@
+import type { ReplicationAdapter, SyncContext } from '@tallyui/core';
+
+export type VendureProductCheckpoint = {
+  skip: number;
+  updatedAt: string;
+};
+
+const PRODUCT_LIST_QUERY = `
+  query GetProducts($options: ProductListOptions) {
+    products(options: $options) {
+      items {
+        id
+        createdAt
+        updatedAt
+        name
+        slug
+        description
+        enabled
+        featuredAsset { id preview }
+        assets { id preview }
+        collections { id name slug }
+        facetValues { id name code facet { id name } }
+        variants {
+          id
+          name
+          sku
+          price
+          priceWithTax
+          currencyCode
+          stockLevel
+          stockOnHand
+          trackInventory
+          featuredAsset { id preview }
+          options { id name code }
+          customFields
+        }
+      }
+      totalItems
+    }
+  }
+`;
+
+const UPDATE_PRODUCT_MUTATION = `
+  mutation UpdateProduct($input: UpdateProductInput!) {
+    updateProduct(input: $input) {
+      id
+      updatedAt
+    }
+  }
+`;
+
+/**
+ * Helper to execute a GraphQL query against the Vendure Admin API.
+ */
+async function gql(
+  context: SyncContext,
+  query: string,
+  variables?: Record<string, any>,
+): Promise<any> {
+  const res = await fetch(`${context.baseUrl}/admin-api`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      ...context.headers,
+    },
+    body: JSON.stringify({ query, variables }),
+    signal: context.signal,
+  });
+
+  if (!res.ok) throw new Error(`Vendure API error: ${res.status}`);
+  return res.json();
+}
+
+/**
+ * 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.
+ */
+export const vendureProductReplication: ReplicationAdapter<any, VendureProductCheckpoint> = {
+  pull: {
+    async handler(lastCheckpoint, batchSize, context) {
+      const options: Record<string, any> = {
+        take: batchSize,
+        skip: lastCheckpoint?.skip ?? 0,
+      };
+
+      if (lastCheckpoint?.updatedAt) {
+        options.filter = {
+          updatedAt: { after: lastCheckpoint.updatedAt },
+        };
+      }
+
+      const res = await gql(context, PRODUCT_LIST_QUERY, { options });
+
+      if (res.errors?.length) {
+        throw new Error(`Vendure GraphQL error: ${res.errors[0].message}`);
+      }
+
+      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;
+
+      const checkpoint: VendureProductCheckpoint = products.length > 0
+        ? {
+            skip: nextSkip,
+            updatedAt: products[products.length - 1].updatedAt,
+          }
+        : lastCheckpoint ?? { skip: 0, updatedAt: '' };
+
+      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;
+    },
+  },
+};