@tallyui/connector-woocommerce 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,58 @@
+import { ProductTraits, CollectionSync, ReplicationAdapter, TallyConnector } from '@tallyui/core';
+import { RxJsonSchema } from 'rxdb';
+
+/**
+ * WooCommerce Product RxDB schema.
+ * Closely mirrors the WooCommerce REST API product shape.
+ * Ported from @wcpos/database.
+ */
+declare const wooProductSchema: RxJsonSchema<any>;
+
+/**
+ * WooCommerce product trait implementations.
+ *
+ * Maps the WooCommerce REST API product shape to the universal
+ * Tally UI product interface.
+ */
+declare const wooProductTraits: ProductTraits;
+
+/**
+ * WooCommerce product sync implementation.
+ *
+ * Uses the WooCommerce REST API (or WCPOS API) to fetch products.
+ * For the MVP, this is a simple implementation that fetches all products.
+ * The full WCPOS sync engine has much more sophisticated diffing/queueing.
+ */
+declare const wooProductSync: CollectionSync;
+
+type WooProductCheckpoint = {
+    id: string;
+    modified: string;
+};
+/**
+ * Replication adapter for WooCommerce products.
+ *
+ * Implements pull (cursor-based pagination by date_modified_gmt) and push
+ * (individual create/update via WC REST API v3). Designed for use with
+ * RxDB's replicateRxCollection.
+ */
+declare const wooProductReplication: ReplicationAdapter<any, WooProductCheckpoint>;
+
+/**
+ * WooCommerce connector for Tally UI.
+ *
+ * Connects to WooCommerce sites via the REST API (v3) or WCPOS API.
+ * Products are stored in RxDB using a schema that mirrors the WC API shape.
+ *
+ * ```ts
+ * import { woocommerceConnector } from '@tallyui/connector-woocommerce';
+ * import { ConnectorProvider } from '@tallyui/core';
+ *
+ * <ConnectorProvider connector={woocommerceConnector}>
+ *   <App />
+ * </ConnectorProvider>
+ * ```
+ */
+declare const woocommerceConnector: TallyConnector;
+
+export { wooProductReplication, wooProductSchema, wooProductSync, wooProductTraits, woocommerceConnector };

package/dist/index.js

@@ -0,0 +1,349 @@
+// src/schemas/products.ts
+var wooProductSchema = {
+  title: "WooCommerce Product",
+  version: 0,
+  type: "object",
+  primaryKey: "uuid",
+  properties: {
+    uuid: {
+      type: "string",
+      maxLength: 36
+    },
+    id: {
+      type: "integer",
+      multipleOf: 1,
+      minimum: 0,
+      maximum: 2147483647
+    },
+    name: {
+      type: "string"
+    },
+    slug: {
+      type: "string"
+    },
+    type: {
+      type: "string",
+      default: "simple",
+      enum: ["simple", "grouped", "external", "variable"]
+    },
+    status: {
+      type: "string",
+      default: "publish",
+      enum: ["draft", "pending", "private", "publish"]
+    },
+    sku: {
+      type: "string"
+    },
+    barcode: {
+      type: "string",
+      maxLength: 255
+    },
+    price: {
+      type: "string"
+    },
+    regular_price: {
+      type: "string"
+    },
+    sale_price: {
+      type: "string"
+    },
+    on_sale: {
+      type: "boolean"
+    },
+    description: {
+      type: "string"
+    },
+    short_description: {
+      type: "string"
+    },
+    stock_quantity: {
+      type: ["number", "null"]
+    },
+    stock_status: {
+      type: "string",
+      default: "instock",
+      enum: ["instock", "outofstock", "onbackorder", "lowstock"],
+      maxLength: 255
+    },
+    manage_stock: {
+      type: "boolean",
+      default: false
+    },
+    categories: {
+      type: "array",
+      items: {
+        type: "object",
+        properties: {
+          id: { type: "integer" },
+          name: { type: "string" },
+          slug: { type: "string" }
+        }
+      }
+    },
+    tags: {
+      type: "array",
+      items: {
+        type: "object",
+        properties: {
+          id: { type: "integer" },
+          name: { type: "string" },
+          slug: { type: "string" }
+        }
+      }
+    },
+    images: {
+      type: "array",
+      items: {
+        type: "object",
+        properties: {
+          id: { type: "integer" },
+          src: { type: "string" },
+          name: { type: "string" },
+          alt: { type: "string" }
+        }
+      }
+    },
+    attributes: {
+      type: "array",
+      items: {
+        type: "object",
+        properties: {
+          id: { type: "integer" },
+          name: { type: "string" },
+          position: { type: "integer" },
+          visible: { type: "boolean" },
+          variation: { type: "boolean" },
+          options: {
+            type: "array",
+            items: { type: "string" }
+          }
+        }
+      }
+    },
+    variations: {
+      type: "array",
+      items: { type: "integer" }
+    },
+    meta_data: {
+      type: "array",
+      items: {
+        type: "object",
+        properties: {
+          id: { type: "integer" },
+          key: { type: "string" },
+          value: { type: "string" }
+        }
+      }
+    },
+    date_modified_gmt: {
+      type: "string"
+    }
+  },
+  indexes: ["id", "barcode", "stock_status"],
+  required: ["uuid"]
+};
+
+// src/traits/product.ts
+var wooProductTraits = {
+  getId: (doc) => String(doc.id),
+  getName: (doc) => doc.name ?? "",
+  getSku: (doc) => doc.sku || void 0,
+  getPrice: (doc) => doc.price || void 0,
+  getRegularPrice: (doc) => doc.regular_price || void 0,
+  getSalePrice: (doc) => doc.sale_price || void 0,
+  isOnSale: (doc) => doc.on_sale === true,
+  getImageUrl: (doc) => doc.images?.[0]?.src || void 0,
+  getImageUrls: (doc) => (doc.images ?? []).map((img) => img.src).filter(Boolean),
+  getDescription: (doc) => doc.short_description || doc.description || void 0,
+  getStockStatus: (doc) => {
+    const status = doc.stock_status;
+    if (status === "instock" || status === "outofstock" || status === "onbackorder") {
+      return status;
+    }
+    return "unknown";
+  },
+  getStockQuantity: (doc) => doc.stock_quantity ?? null,
+  hasVariants: (doc) => doc.type === "variable",
+  getType: (doc) => doc.type ?? "simple",
+  getBarcode: (doc) => doc.barcode || void 0,
+  getCategoryNames: (doc) => (doc.categories ?? []).map((cat) => cat.name).filter(Boolean)
+};
+
+// src/sync/products.ts
+var wooProductSync = {
+  async fetchAllIds(context) {
+    const response = await fetch(`${context.baseUrl}/products`, {
+      headers: {
+        ...context.headers,
+        "Content-Type": "application/json"
+      },
+      signal: context.signal
+    });
+    if (!response.ok) {
+      throw new Error(`WooCommerce API error: ${response.status}`);
+    }
+    const products = await response.json();
+    return products.map((p) => ({
+      id: String(p.id),
+      dateModified: p.date_modified_gmt
+    }));
+  },
+  async fetchByIds(ids, context) {
+    const include = ids.join(",");
+    const response = await fetch(
+      `${context.baseUrl}/products?include=${include}&per_page=${ids.length}`,
+      {
+        headers: {
+          ...context.headers,
+          "Content-Type": "application/json"
+        },
+        signal: context.signal
+      }
+    );
+    if (!response.ok) {
+      throw new Error(`WooCommerce API error: ${response.status}`);
+    }
+    return response.json();
+  },
+  async fetchModifiedAfter(date, context) {
+    const response = await fetch(
+      `${context.baseUrl}/products?modified_after=${date}&per_page=100`,
+      {
+        headers: {
+          ...context.headers,
+          "Content-Type": "application/json"
+        },
+        signal: context.signal
+      }
+    );
+    if (!response.ok) {
+      throw new Error(`WooCommerce API error: ${response.status}`);
+    }
+    return response.json();
+  }
+};
+
+// src/replication/products.ts
+var wooProductReplication = {
+  pull: {
+    async handler(lastCheckpoint, batchSize, context) {
+      const params = new URLSearchParams({
+        per_page: String(batchSize),
+        orderby: "modified",
+        order: "asc"
+      });
+      if (lastCheckpoint?.modified) {
+        params.set("modified_after", lastCheckpoint.modified);
+      }
+      const response = await fetch(`${context.baseUrl}/products?${params}`, {
+        headers: {
+          ...context.headers,
+          "Content-Type": "application/json"
+        },
+        signal: context.signal
+      });
+      if (!response.ok) {
+        throw new Error(`WooCommerce API error: ${response.status}`);
+      }
+      const products = await response.json();
+      const documents = products.map((p) => ({ ...p, _deleted: false }));
+      const checkpoint = products.length > 0 ? {
+        id: String(products[products.length - 1].uuid ?? products[products.length - 1].id),
+        modified: products[products.length - 1].date_modified_gmt
+      } : lastCheckpoint ?? { id: "", modified: "" };
+      return { documents, checkpoint };
+    }
+  },
+  push: {
+    async handler(changeRows, context) {
+      const conflicts = [];
+      for (const row of changeRows) {
+        const doc = row.newDocumentState;
+        try {
+          const isCreate = !row.assumedMasterState;
+          const method = isCreate ? "POST" : "PUT";
+          const url = isCreate ? `${context.baseUrl}/products` : `${context.baseUrl}/products/${doc.id}`;
+          const response = await fetch(url, {
+            method,
+            headers: {
+              ...context.headers,
+              "Content-Type": "application/json"
+            },
+            body: JSON.stringify(doc),
+            signal: context.signal
+          });
+          if (!response.ok) {
+            if (row.assumedMasterState) {
+              conflicts.push({ ...row.assumedMasterState, _deleted: false });
+            }
+          }
+        } catch {
+          if (row.assumedMasterState) {
+            conflicts.push({ ...row.assumedMasterState, _deleted: false });
+          }
+        }
+      }
+      return conflicts;
+    }
+  }
+};
+
+// src/index.ts
+var woocommerceConnector = {
+  id: "woocommerce",
+  name: "WooCommerce",
+  description: "Connect to WooCommerce stores via the REST API",
+  icon: void 0,
+  // TODO: WooCommerce logo
+  auth: {
+    type: "WooCommerce REST API",
+    fields: [
+      {
+        key: "url",
+        label: "Store URL",
+        type: "url",
+        placeholder: "https://mystore.com",
+        required: true
+      },
+      {
+        key: "consumer_key",
+        label: "Consumer Key",
+        type: "text",
+        placeholder: "ck_...",
+        required: true
+      },
+      {
+        key: "consumer_secret",
+        label: "Consumer Secret",
+        type: "password",
+        placeholder: "cs_...",
+        required: true
+      }
+    ],
+    getHeaders: (credentials) => {
+      const encoded = btoa(`${credentials.consumer_key}:${credentials.consumer_secret}`);
+      return {
+        Authorization: `Basic ${encoded}`
+      };
+    }
+  },
+  schemas: {
+    products: wooProductSchema
+  },
+  traits: {
+    product: wooProductTraits
+  },
+  sync: {
+    products: wooProductSync
+  },
+  replication: {
+    products: wooProductReplication
+  }
+};
+export {
+  wooProductReplication,
+  wooProductSchema,
+  wooProductSync,
+  wooProductTraits,
+  woocommerceConnector
+};

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@tallyui/connector-woocommerce",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "WooCommerce connector for Tally UI",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "source": "./src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "source": "./src/index.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@tallyui/core": "0.2.0"
+  },
+  "devDependencies": {
+    "rxdb": "16.21.1"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "echo \"no tests yet\""
+  }
+}

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

@@ -0,0 +1,191 @@
+import { describe, it, expect } from 'vitest';
+import { wooProductTraits } from '../traits/product';
+
+/**
+ * Realistic WooCommerce product document, shaped like the REST API v3 response.
+ */
+const fullProduct = {
+  id: 42,
+  name: 'Espresso Machine Pro',
+  slug: 'espresso-machine-pro',
+  type: 'simple',
+  status: 'publish',
+  sku: 'ESP-001',
+  price: '599.99',
+  regular_price: '599.99',
+  sale_price: '',
+  on_sale: false,
+  stock_status: 'instock',
+  stock_quantity: 15,
+  barcode: '1234567890123',
+  short_description: 'High-end espresso machine.',
+  description: 'Full description here.',
+  images: [
+    { id: 1, src: 'https://store.example/espresso.jpg', alt: 'Espresso Machine' },
+    { id: 2, src: 'https://store.example/espresso-side.jpg', alt: '' },
+  ],
+  categories: [
+    { id: 1, name: 'Equipment', slug: 'equipment' },
+    { id: 2, name: 'Coffee', slug: 'coffee' },
+  ],
+};
+
+const saleProduct = {
+  ...fullProduct,
+  id: 43,
+  price: '499.99',
+  sale_price: '499.99',
+  on_sale: true,
+};
+
+const variableProduct = {
+  ...fullProduct,
+  id: 44,
+  type: 'variable',
+  variations: [101, 102],
+};
+
+const minimalProduct = {
+  id: 99,
+};
+
+describe('WooCommerce product traits', () => {
+  describe('getId', () => {
+    it('returns the product id as a string', () => {
+      expect(wooProductTraits.getId(fullProduct)).toBe('42');
+    });
+  });
+
+  describe('getName', () => {
+    it('returns the product name', () => {
+      expect(wooProductTraits.getName(fullProduct)).toBe('Espresso Machine Pro');
+    });
+
+    it('returns empty string for missing name', () => {
+      expect(wooProductTraits.getName(minimalProduct)).toBe('');
+    });
+  });
+
+  describe('getSku', () => {
+    it('returns the SKU', () => {
+      expect(wooProductTraits.getSku(fullProduct)).toBe('ESP-001');
+    });
+
+    it('returns undefined when no SKU', () => {
+      expect(wooProductTraits.getSku(minimalProduct)).toBeUndefined();
+    });
+  });
+
+  describe('getPrice', () => {
+    it('returns the price string', () => {
+      expect(wooProductTraits.getPrice(fullProduct)).toBe('599.99');
+    });
+
+    it('returns undefined for missing price', () => {
+      expect(wooProductTraits.getPrice(minimalProduct)).toBeUndefined();
+    });
+  });
+
+  describe('getRegularPrice / getSalePrice / isOnSale', () => {
+    it('returns regular price', () => {
+      expect(wooProductTraits.getRegularPrice(fullProduct)).toBe('599.99');
+    });
+
+    it('detects non-sale product', () => {
+      expect(wooProductTraits.isOnSale(fullProduct)).toBe(false);
+      expect(wooProductTraits.getSalePrice(fullProduct)).toBeUndefined();
+    });
+
+    it('detects sale product', () => {
+      expect(wooProductTraits.isOnSale(saleProduct)).toBe(true);
+      expect(wooProductTraits.getSalePrice(saleProduct)).toBe('499.99');
+    });
+  });
+
+  describe('getImageUrl / getImageUrls', () => {
+    it('returns the first image src', () => {
+      expect(wooProductTraits.getImageUrl(fullProduct)).toBe('https://store.example/espresso.jpg');
+    });
+
+    it('returns all image URLs', () => {
+      expect(wooProductTraits.getImageUrls(fullProduct)).toEqual([
+        'https://store.example/espresso.jpg',
+        'https://store.example/espresso-side.jpg',
+      ]);
+    });
+
+    it('returns undefined / empty for missing images', () => {
+      expect(wooProductTraits.getImageUrl(minimalProduct)).toBeUndefined();
+      expect(wooProductTraits.getImageUrls(minimalProduct)).toEqual([]);
+    });
+  });
+
+  describe('getDescription', () => {
+    it('prefers short_description', () => {
+      expect(wooProductTraits.getDescription(fullProduct)).toBe('High-end espresso machine.');
+    });
+
+    it('falls back to description', () => {
+      const doc = { ...fullProduct, short_description: '' };
+      expect(wooProductTraits.getDescription(doc)).toBe('Full description here.');
+    });
+
+    it('returns undefined when neither exists', () => {
+      expect(wooProductTraits.getDescription(minimalProduct)).toBeUndefined();
+    });
+  });
+
+  describe('getStockStatus / getStockQuantity', () => {
+    it('returns instock status', () => {
+      expect(wooProductTraits.getStockStatus(fullProduct)).toBe('instock');
+    });
+
+    it('returns stock quantity', () => {
+      expect(wooProductTraits.getStockQuantity(fullProduct)).toBe(15);
+    });
+
+    it('returns unknown for unrecognised status', () => {
+      expect(wooProductTraits.getStockStatus({ ...fullProduct, stock_status: 'weird' })).toBe('unknown');
+    });
+
+    it('returns null quantity when missing', () => {
+      expect(wooProductTraits.getStockQuantity(minimalProduct)).toBeNull();
+    });
+  });
+
+  describe('hasVariants / getType', () => {
+    it('simple product has no variants', () => {
+      expect(wooProductTraits.hasVariants(fullProduct)).toBe(false);
+      expect(wooProductTraits.getType(fullProduct)).toBe('simple');
+    });
+
+    it('variable product has variants', () => {
+      expect(wooProductTraits.hasVariants(variableProduct)).toBe(true);
+      expect(wooProductTraits.getType(variableProduct)).toBe('variable');
+    });
+
+    it('defaults to simple for missing type', () => {
+      expect(wooProductTraits.getType(minimalProduct)).toBe('simple');
+    });
+  });
+
+  describe('getBarcode', () => {
+    it('returns barcode', () => {
+      expect(wooProductTraits.getBarcode(fullProduct)).toBe('1234567890123');
+    });
+
+    it('returns undefined when missing', () => {
+      expect(wooProductTraits.getBarcode(minimalProduct)).toBeUndefined();
+    });
+  });
+
+  describe('getCategoryNames', () => {
+    it('returns category name strings', () => {
+      expect(wooProductTraits.getCategoryNames(fullProduct)).toEqual(['Equipment', 'Coffee']);
+    });
+
+    it('returns empty array when no categories', () => {
+      expect(wooProductTraits.getCategoryNames(minimalProduct)).toEqual([]);
+    });
+  });
+});

package/src/index.ts

@@ -0,0 +1,83 @@
+import type { TallyConnector } from '@tallyui/core';
+
+import { wooProductSchema } from './schemas/products';
+import { wooProductTraits } from './traits/product';
+import { wooProductSync } from './sync/products';
+import { wooProductReplication } from './replication/products';
+
+/**
+ * WooCommerce connector for Tally UI.
+ *
+ * Connects to WooCommerce sites via the REST API (v3) or WCPOS API.
+ * Products are stored in RxDB using a schema that mirrors the WC API shape.
+ *
+ * ```ts
+ * import { woocommerceConnector } from '@tallyui/connector-woocommerce';
+ * import { ConnectorProvider } from '@tallyui/core';
+ *
+ * <ConnectorProvider connector={woocommerceConnector}>
+ *   <App />
+ * </ConnectorProvider>
+ * ```
+ */
+export const woocommerceConnector: TallyConnector = {
+  id: 'woocommerce',
+  name: 'WooCommerce',
+  description: 'Connect to WooCommerce stores via the REST API',
+  icon: undefined, // TODO: WooCommerce logo
+
+  auth: {
+    type: 'WooCommerce REST API',
+    fields: [
+      {
+        key: 'url',
+        label: 'Store URL',
+        type: 'url',
+        placeholder: 'https://mystore.com',
+        required: true,
+      },
+      {
+        key: 'consumer_key',
+        label: 'Consumer Key',
+        type: 'text',
+        placeholder: 'ck_...',
+        required: true,
+      },
+      {
+        key: 'consumer_secret',
+        label: 'Consumer Secret',
+        type: 'password',
+        placeholder: 'cs_...',
+        required: true,
+      },
+    ],
+    getHeaders: (credentials) => {
+      const encoded = btoa(`${credentials.consumer_key}:${credentials.consumer_secret}`);
+      return {
+        Authorization: `Basic ${encoded}`,
+      };
+    },
+  },
+
+  schemas: {
+    products: wooProductSchema,
+  },
+
+  traits: {
+    product: wooProductTraits,
+  },
+
+  sync: {
+    products: wooProductSync,
+  },
+
+  replication: {
+    products: wooProductReplication,
+  },
+};
+
+// Re-export pieces for advanced usage
+export { wooProductSchema } from './schemas/products';
+export { wooProductTraits } from './traits/product';
+export { wooProductSync } from './sync/products';
+export { wooProductReplication } from './replication/products';

package/src/replication/products.test.ts

@@ -0,0 +1,189 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import type { SyncContext } from '@tallyui/core';
+
+import { wooProductReplication } from './products';
+
+const context: SyncContext = {
+  connectorId: 'woocommerce',
+  baseUrl: 'https://example.com/wp-json/wc/v3',
+  headers: { Authorization: 'Basic dGVzdDp0ZXN0' },
+};
+
+describe('wooProductReplication.pull.handler', () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('fetches products from initial checkpoint (undefined)', async () => {
+    const mockProducts = [
+      { id: 1, uuid: 'abc', name: 'Widget', date_modified_gmt: '2026-01-01T00:00:00' },
+      { id: 2, uuid: 'def', name: 'Gadget', date_modified_gmt: '2026-01-02T00:00:00' },
+    ];
+
+    vi.spyOn(globalThis, 'fetch').mockResolvedValueOnce(
+      new Response(JSON.stringify(mockProducts), { status: 200 }),
+    );
+
+    const result = await wooProductReplication.pull.handler(undefined, 100, context);
+
+    expect(result.documents).toHaveLength(2);
+    expect(result.documents[0]._deleted).toBe(false);
+    expect(result.checkpoint).toEqual({
+      id: 'def',
+      modified: '2026-01-02T00:00:00',
+    });
+  });
+
+  it('fetches products after a checkpoint', async () => {
+    vi.spyOn(globalThis, 'fetch').mockResolvedValueOnce(
+      new Response(JSON.stringify([]), { status: 200 }),
+    );
+
+    const checkpoint = { id: 'abc', modified: '2026-01-01T00:00:00' };
+    const result = await wooProductReplication.pull.handler(checkpoint, 100, context);
+
+    expect(result.documents).toHaveLength(0);
+
+    const calledUrl = (globalThis.fetch as any).mock.calls[0][0];
+    expect(calledUrl).toContain('modified_after=2026-01-01T00%3A00%3A00');
+    expect(calledUrl).toContain('orderby=modified');
+    expect(calledUrl).toContain('order=asc');
+  });
+
+  it('uses batchSize as per_page', async () => {
+    vi.spyOn(globalThis, 'fetch').mockResolvedValueOnce(
+      new Response(JSON.stringify([]), { status: 200 }),
+    );
+
+    await wooProductReplication.pull.handler(undefined, 25, context);
+
+    const calledUrl = (globalThis.fetch as any).mock.calls[0][0];
+    expect(calledUrl).toContain('per_page=25');
+  });
+
+  it('throws on non-OK response', async () => {
+    vi.spyOn(globalThis, 'fetch').mockResolvedValueOnce(
+      new Response('Internal Server Error', { status: 500 }),
+    );
+
+    await expect(
+      wooProductReplication.pull.handler(undefined, 100, context),
+    ).rejects.toThrow('WooCommerce API error: 500');
+  });
+
+  it('returns lastCheckpoint when no products are returned', async () => {
+    vi.spyOn(globalThis, 'fetch').mockResolvedValueOnce(
+      new Response(JSON.stringify([]), { status: 200 }),
+    );
+
+    const checkpoint = { id: 'abc', modified: '2026-01-01T00:00:00' };
+    const result = await wooProductReplication.pull.handler(checkpoint, 100, context);
+
+    expect(result.checkpoint).toEqual(checkpoint);
+  });
+
+  it('falls back to id when uuid is missing', async () => {
+    const mockProducts = [
+      { id: 42, name: 'No UUID', date_modified_gmt: '2026-03-01T00:00:00' },
+    ];
+
+    vi.spyOn(globalThis, 'fetch').mockResolvedValueOnce(
+      new Response(JSON.stringify(mockProducts), { status: 200 }),
+    );
+
+    const result = await wooProductReplication.pull.handler(undefined, 100, context);
+
+    expect(result.checkpoint.id).toBe('42');
+  });
+});
+
+describe('wooProductReplication.push.handler', () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('sends PUT for updates', async () => {
+    vi.spyOn(globalThis, 'fetch').mockResolvedValueOnce(
+      new Response(JSON.stringify({}), { status: 200 }),
+    );
+
+    const conflicts = await wooProductReplication.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 [url, opts] = (globalThis.fetch as any).mock.calls[0];
+    expect(url).toContain('/products/1');
+    expect(opts.method).toBe('PUT');
+  });
+
+  it('sends POST for creates', async () => {
+    vi.spyOn(globalThis, 'fetch').mockResolvedValueOnce(
+      new Response(JSON.stringify({}), { status: 200 }),
+    );
+
+    const conflicts = await wooProductReplication.push!.handler(
+      [{
+        newDocumentState: { id: '1', name: 'New Product', _deleted: false } as any,
+        // No assumedMasterState = create
+      }],
+      context,
+    );
+
+    expect(conflicts).toHaveLength(0);
+    const [, opts] = (globalThis.fetch as any).mock.calls[0];
+    expect(opts.method).toBe('POST');
+  });
+
+  it('returns conflicts on server error', async () => {
+    vi.spyOn(globalThis, 'fetch').mockResolvedValueOnce(
+      new Response('conflict', { status: 409 }),
+    );
+
+    const conflicts = await wooProductReplication.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 wooProductReplication.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 for creates that fail', async () => {
+    vi.spyOn(globalThis, 'fetch').mockResolvedValueOnce(
+      new Response('error', { status: 500 }),
+    );
+
+    const conflicts = await wooProductReplication.push!.handler(
+      [{
+        newDocumentState: { id: '1', name: 'New Product', _deleted: false } as any,
+        // No assumedMasterState = create, so no conflict to report
+      }],
+      context,
+    );
+
+    // Creates without assumedMasterState don't produce conflicts
+    expect(conflicts).toHaveLength(0);
+  });
+});

package/src/replication/products.ts

@@ -0,0 +1,93 @@
+import type { ReplicationAdapter, SyncContext } from '@tallyui/core';
+
+export type WooProductCheckpoint = {
+  id: string;
+  modified: string;
+};
+
+/**
+ * Replication adapter for WooCommerce products.
+ *
+ * Implements pull (cursor-based pagination by date_modified_gmt) and push
+ * (individual create/update via WC REST API v3). Designed for use with
+ * RxDB's replicateRxCollection.
+ */
+export const wooProductReplication: ReplicationAdapter<any, WooProductCheckpoint> = {
+  pull: {
+    async handler(lastCheckpoint, batchSize, context) {
+      const params = new URLSearchParams({
+        per_page: String(batchSize),
+        orderby: 'modified',
+        order: 'asc',
+      });
+
+      if (lastCheckpoint?.modified) {
+        params.set('modified_after', lastCheckpoint.modified);
+      }
+
+      const response = await fetch(`${context.baseUrl}/products?${params}`, {
+        headers: {
+          ...context.headers,
+          'Content-Type': 'application/json',
+        },
+        signal: context.signal,
+      });
+
+      if (!response.ok) {
+        throw new Error(`WooCommerce API error: ${response.status}`);
+      }
+
+      const products: any[] = await response.json();
+      const documents = products.map((p) => ({ ...p, _deleted: false }));
+
+      const checkpoint: WooProductCheckpoint = products.length > 0
+        ? {
+            id: String(products[products.length - 1].uuid ?? products[products.length - 1].id),
+            modified: products[products.length - 1].date_modified_gmt,
+          }
+        : lastCheckpoint ?? { id: '', modified: '' };
+
+      return { documents, checkpoint };
+    },
+  },
+
+  push: {
+    async handler(changeRows, context) {
+      const conflicts: any[] = [];
+
+      for (const row of changeRows) {
+        const doc = row.newDocumentState as any;
+
+        try {
+          const isCreate = !row.assumedMasterState;
+          const method = isCreate ? 'POST' : 'PUT';
+          const url = isCreate
+            ? `${context.baseUrl}/products`
+            : `${context.baseUrl}/products/${doc.id}`;
+
+          const response = await fetch(url, {
+            method,
+            headers: {
+              ...context.headers,
+              'Content-Type': 'application/json',
+            },
+            body: JSON.stringify(doc),
+            signal: context.signal,
+          });
+
+          if (!response.ok) {
+            if (row.assumedMasterState) {
+              conflicts.push({ ...row.assumedMasterState, _deleted: false });
+            }
+          }
+        } catch {
+          if (row.assumedMasterState) {
+            conflicts.push({ ...row.assumedMasterState, _deleted: false });
+          }
+        }
+      }
+
+      return conflicts;
+    },
+  },
+};

package/src/schemas/products.ts

@@ -0,0 +1,150 @@
+import type { RxJsonSchema } from 'rxdb';
+
+/**
+ * WooCommerce Product RxDB schema.
+ * Closely mirrors the WooCommerce REST API product shape.
+ * Ported from @wcpos/database.
+ */
+export const wooProductSchema: RxJsonSchema<any> = {
+  title: 'WooCommerce Product',
+  version: 0,
+  type: 'object',
+  primaryKey: 'uuid',
+  properties: {
+    uuid: {
+      type: 'string',
+      maxLength: 36,
+    },
+    id: {
+      type: 'integer',
+      multipleOf: 1,
+      minimum: 0,
+      maximum: 2147483647,
+    },
+    name: {
+      type: 'string',
+    },
+    slug: {
+      type: 'string',
+    },
+    type: {
+      type: 'string',
+      default: 'simple',
+      enum: ['simple', 'grouped', 'external', 'variable'],
+    },
+    status: {
+      type: 'string',
+      default: 'publish',
+      enum: ['draft', 'pending', 'private', 'publish'],
+    },
+    sku: {
+      type: 'string',
+    },
+    barcode: {
+      type: 'string',
+      maxLength: 255,
+    },
+    price: {
+      type: 'string',
+    },
+    regular_price: {
+      type: 'string',
+    },
+    sale_price: {
+      type: 'string',
+    },
+    on_sale: {
+      type: 'boolean',
+    },
+    description: {
+      type: 'string',
+    },
+    short_description: {
+      type: 'string',
+    },
+    stock_quantity: {
+      type: ['number', 'null'],
+    },
+    stock_status: {
+      type: 'string',
+      default: 'instock',
+      enum: ['instock', 'outofstock', 'onbackorder', 'lowstock'],
+      maxLength: 255,
+    },
+    manage_stock: {
+      type: 'boolean',
+      default: false,
+    },
+    categories: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          id: { type: 'integer' },
+          name: { type: 'string' },
+          slug: { type: 'string' },
+        },
+      },
+    },
+    tags: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          id: { type: 'integer' },
+          name: { type: 'string' },
+          slug: { type: 'string' },
+        },
+      },
+    },
+    images: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          id: { type: 'integer' },
+          src: { type: 'string' },
+          name: { type: 'string' },
+          alt: { type: 'string' },
+        },
+      },
+    },
+    attributes: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          id: { type: 'integer' },
+          name: { type: 'string' },
+          position: { type: 'integer' },
+          visible: { type: 'boolean' },
+          variation: { type: 'boolean' },
+          options: {
+            type: 'array',
+            items: { type: 'string' },
+          },
+        },
+      },
+    },
+    variations: {
+      type: 'array',
+      items: { type: 'integer' },
+    },
+    meta_data: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          id: { type: 'integer' },
+          key: { type: 'string' },
+          value: { type: 'string' },
+        },
+      },
+    },
+    date_modified_gmt: {
+      type: 'string',
+    },
+  },
+  indexes: ['id', 'barcode', 'stock_status'],
+  required: ['uuid'],
+};

package/src/sync/products.ts

@@ -0,0 +1,70 @@
+import type { CollectionSync, SyncContext, RemoteIdEntry } from '@tallyui/core';
+
+/**
+ * WooCommerce product sync implementation.
+ *
+ * Uses the WooCommerce REST API (or WCPOS API) to fetch products.
+ * For the MVP, this is a simple implementation that fetches all products.
+ * The full WCPOS sync engine has much more sophisticated diffing/queueing.
+ */
+export const wooProductSync: CollectionSync = {
+  async fetchAllIds(context: SyncContext): Promise<RemoteIdEntry[]> {
+    const response = await fetch(`${context.baseUrl}/products`, {
+      headers: {
+        ...context.headers,
+        'Content-Type': 'application/json',
+      },
+      signal: context.signal,
+    });
+
+    if (!response.ok) {
+      throw new Error(`WooCommerce API error: ${response.status}`);
+    }
+
+    const products = await response.json();
+    return products.map((p: any) => ({
+      id: String(p.id),
+      dateModified: p.date_modified_gmt,
+    }));
+  },
+
+  async fetchByIds(ids: string[], context: SyncContext): Promise<any[]> {
+    // WooCommerce supports ?include=1,2,3 for bulk fetching
+    const include = ids.join(',');
+    const response = await fetch(
+      `${context.baseUrl}/products?include=${include}&per_page=${ids.length}`,
+      {
+        headers: {
+          ...context.headers,
+          'Content-Type': 'application/json',
+        },
+        signal: context.signal,
+      }
+    );
+
+    if (!response.ok) {
+      throw new Error(`WooCommerce API error: ${response.status}`);
+    }
+
+    return response.json();
+  },
+
+  async fetchModifiedAfter(date: string, context: SyncContext): Promise<any[]> {
+    const response = await fetch(
+      `${context.baseUrl}/products?modified_after=${date}&per_page=100`,
+      {
+        headers: {
+          ...context.headers,
+          'Content-Type': 'application/json',
+        },
+        signal: context.signal,
+      }
+    );
+
+    if (!response.ok) {
+      throw new Error(`WooCommerce API error: ${response.status}`);
+    }
+
+    return response.json();
+  },
+};

package/src/traits/product.ts

@@ -0,0 +1,48 @@
+import type { ProductTraits } from '@tallyui/core';
+
+/**
+ * WooCommerce product trait implementations.
+ *
+ * Maps the WooCommerce REST API product shape to the universal
+ * Tally UI product interface.
+ */
+export const wooProductTraits: ProductTraits = {
+  getId: (doc) => String(doc.id),
+
+  getName: (doc) => doc.name ?? '',
+
+  getSku: (doc) => doc.sku || undefined,
+
+  getPrice: (doc) => doc.price || undefined,
+
+  getRegularPrice: (doc) => doc.regular_price || undefined,
+
+  getSalePrice: (doc) => doc.sale_price || undefined,
+
+  isOnSale: (doc) => doc.on_sale === true,
+
+  getImageUrl: (doc) => doc.images?.[0]?.src || undefined,
+
+  getImageUrls: (doc) => (doc.images ?? []).map((img: any) => img.src).filter(Boolean),
+
+  getDescription: (doc) => doc.short_description || doc.description || undefined,
+
+  getStockStatus: (doc) => {
+    const status = doc.stock_status;
+    if (status === 'instock' || status === 'outofstock' || status === 'onbackorder') {
+      return status;
+    }
+    return 'unknown';
+  },
+
+  getStockQuantity: (doc) => doc.stock_quantity ?? null,
+
+  hasVariants: (doc) => doc.type === 'variable',
+
+  getType: (doc) => doc.type ?? 'simple',
+
+  getBarcode: (doc) => doc.barcode || undefined,
+
+  getCategoryNames: (doc) =>
+    (doc.categories ?? []).map((cat: any) => cat.name).filter(Boolean),
+};