@tallyui/core 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,237 @@
+import { RxReplicationPullStreamItem, RxReplicationWriteToMasterRow, RxJsonSchema } from 'rxdb';
+import { Observable } from 'rxjs';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+
+/**
+ * Product traits — the stable interface that UI components program against.
+ *
+ * Each connector implements these accessors to extract standard product data
+ * from its own schema shape. Components call these instead of reaching into
+ * the raw document, so they work identically across WooCommerce, Medusa,
+ * Vendure, Shopify, etc.
+ *
+ * The generic `Doc` type is the connector's raw RxDB document type.
+ */
+interface ProductTraits<Doc = any> {
+    /** Product display name */
+    getName: (doc: Doc) => string;
+    /** SKU / stock keeping unit */
+    getSku: (doc: Doc) => string | undefined;
+    /** Current selling price as a string (connector-native format) */
+    getPrice: (doc: Doc) => string | undefined;
+    /** Regular (non-sale) price */
+    getRegularPrice: (doc: Doc) => string | undefined;
+    /** Sale price, if on sale */
+    getSalePrice: (doc: Doc) => string | undefined;
+    /** Whether the product is currently on sale */
+    isOnSale: (doc: Doc) => boolean;
+    /** Primary image URL */
+    getImageUrl: (doc: Doc) => string | undefined;
+    /** All image URLs */
+    getImageUrls: (doc: Doc) => string[];
+    /** Short description / excerpt */
+    getDescription: (doc: Doc) => string | undefined;
+    /** Stock status */
+    getStockStatus: (doc: Doc) => 'instock' | 'outofstock' | 'onbackorder' | 'unknown';
+    /** Stock quantity (null if not tracked) */
+    getStockQuantity: (doc: Doc) => number | null;
+    /** Whether this product has variants/variations */
+    hasVariants: (doc: Doc) => boolean;
+    /** Product type (simple, variable, etc. — connector-specific but useful for UI hints) */
+    getType: (doc: Doc) => string;
+    /** Barcode / UPC / EAN */
+    getBarcode: (doc: Doc) => string | undefined;
+    /** Categories as simple label strings */
+    getCategoryNames: (doc: Doc) => string[];
+    /** The connector-specific unique ID (as string for consistency) */
+    getId: (doc: Doc) => string;
+}
+
+/**
+ * Customer traits — the stable interface that UI components program against.
+ *
+ * Each connector implements these to extract standard customer data
+ * from its own schema shape.
+ */
+interface CustomerTraits<Doc = any> {
+    /** Customer display name (first + last or company) */
+    getName: (doc: Doc) => string;
+    /** Email address */
+    getEmail: (doc: Doc) => string | undefined;
+    /** Phone number */
+    getPhone: (doc: Doc) => string | undefined;
+    /** One-line address summary (e.g., "123 Main St, Springfield") */
+    getAddressSummary: (doc: Doc) => string | undefined;
+    /** The connector-specific unique ID (as string for consistency) */
+    getId: (doc: Doc) => string;
+}
+
+/**
+ * Replication adapter interface for a single collection.
+ *
+ * Each connector implements this to provide pull/push handlers
+ * compatible with RxDB's replicateRxCollection protocol.
+ *
+ * CheckpointType is connector-specific (cursor, offset+timestamp, etc).
+ */
+interface ReplicationAdapter<RxDocType, CheckpointType = any> {
+    pull: {
+        /**
+         * Fetch documents changed since the last checkpoint.
+         * Return an empty documents array when fully caught up.
+         */
+        handler: (lastCheckpoint: CheckpointType | undefined, batchSize: number, context: SyncContext) => Promise<{
+            documents: Array<RxDocType & {
+                _deleted: boolean;
+            }>;
+            checkpoint: CheckpointType;
+        }>;
+        /**
+         * Optional real-time event stream.
+         * Emit { documents, checkpoint } for live updates,
+         * or 'RESYNC' to trigger a full pull cycle.
+         */
+        stream$?: Observable<RxReplicationPullStreamItem<RxDocType, CheckpointType>>;
+    };
+    push?: {
+        /**
+         * Push local changes to the remote API.
+         * Return an array of conflict documents (server's version wins).
+         * Return empty array if no conflicts.
+         */
+        handler: (changeRows: RxReplicationWriteToMasterRow<RxDocType>[], context: SyncContext) => Promise<Array<RxDocType & {
+            _deleted: boolean;
+        }>>;
+        /** Max documents per push batch. Defaults to 100. */
+        batchSize?: number;
+    };
+}
+
+/**
+ * Authentication configuration for a connector.
+ * Each API has wildly different auth — JWT, API keys, OAuth, etc.
+ * The connector declares what it needs and how to use it.
+ */
+interface ConnectorAuth {
+    /** Human-readable auth type for UI display */
+    type: string;
+    /** Fields required from the user to authenticate */
+    fields: AuthField[];
+    /** Build request headers from stored credentials */
+    getHeaders: (credentials: Record<string, string>) => Record<string, string>;
+    /** Optional: validate that credentials work (e.g., test API call) */
+    validate?: (credentials: Record<string, string>) => Promise<boolean>;
+}
+interface AuthField {
+    key: string;
+    label: string;
+    type: 'text' | 'password' | 'url';
+    placeholder?: string;
+    required?: boolean;
+}
+/**
+ * Sync configuration for a collection.
+ * Defines how to fetch data from the remote API and push changes back.
+ *
+ * @deprecated Use ReplicationAdapter instead. This interface will be removed
+ * once all connectors have migrated to the RxDB replication protocol.
+ */
+interface CollectionSync<T = any> {
+    /** Fetch all remote IDs (for diffing against local) */
+    fetchAllIds: (context: SyncContext) => Promise<RemoteIdEntry[]>;
+    /** Fetch documents by IDs */
+    fetchByIds: (ids: string[], context: SyncContext) => Promise<T[]>;
+    /** Fetch documents modified after a given date */
+    fetchModifiedAfter?: (date: string, context: SyncContext) => Promise<T[]>;
+    /** Push a local change to the remote */
+    push?: (doc: T, context: SyncContext) => Promise<T>;
+    /** Create a new document on the remote */
+    create?: (doc: Partial<T>, context: SyncContext) => Promise<T>;
+    /** Delete a document on the remote */
+    delete?: (id: string, context: SyncContext) => Promise<void>;
+}
+interface RemoteIdEntry {
+    id: string;
+    dateModified?: string;
+}
+interface SyncContext {
+    /** Unique connector identifier (used as replication namespace) */
+    connectorId: string;
+    /** Base URL for the API */
+    baseUrl: string;
+    /** Authenticated headers */
+    headers: Record<string, string>;
+    /** Optional abort signal */
+    signal?: AbortSignal;
+}
+/**
+ * Schema definitions for a connector.
+ * Each connector provides its own RxDB schemas that mirror its API shape.
+ */
+interface ConnectorSchemas {
+    products: RxJsonSchema<any>;
+    [key: string]: RxJsonSchema<any>;
+}
+/**
+ * Trait implementations for a connector.
+ * These are the accessor functions that components program against.
+ */
+interface ConnectorTraits {
+    product: ProductTraits;
+    customer?: CustomerTraits;
+}
+/**
+ * The main connector interface.
+ * Each backend (WooCommerce, Medusa, Vendure, etc.) implements this.
+ */
+interface TallyConnector {
+    /** Unique identifier for this connector */
+    id: string;
+    /** Human-readable name */
+    name: string;
+    /** Description of the backend this connects to */
+    description: string;
+    /** Icon or logo URL */
+    icon?: string;
+    /** Authentication configuration */
+    auth: ConnectorAuth;
+    /** RxDB schemas for each collection */
+    schemas: ConnectorSchemas;
+    /** Trait implementations — how to extract standard data from connector-specific docs */
+    traits: ConnectorTraits;
+    /**
+     * @deprecated Use `replication` instead.
+     * Sync configuration for each collection (legacy pull-based sync).
+     */
+    sync: {
+        products: CollectionSync;
+        [key: string]: CollectionSync;
+    };
+    /** Replication adapters for each collection (RxDB replication protocol) */
+    replication?: {
+        products?: ReplicationAdapter<any>;
+        [key: string]: ReplicationAdapter<any> | undefined;
+    };
+}
+
+interface ConnectorProviderProps {
+    connector: TallyConnector;
+    children: ReactNode;
+}
+declare function ConnectorProvider({ connector, children }: ConnectorProviderProps): react_jsx_runtime.JSX.Element;
+/**
+ * Access the active connector. Throws if used outside a ConnectorProvider.
+ */
+declare function useConnector(): TallyConnector;
+/**
+ * Convenience hook: grab just the product traits from the active connector.
+ */
+declare function useProductTraits(): ProductTraits<any>;
+/**
+ * Convenience hook: grab just the customer traits from the active connector.
+ * Returns undefined if the connector doesn't implement customer traits.
+ */
+declare function useCustomerTraits(): CustomerTraits<any> | undefined;
+
+export { type AuthField, type CollectionSync, type ConnectorAuth, ConnectorProvider, type ConnectorProviderProps, type ConnectorSchemas, type ConnectorTraits, type CustomerTraits, type ProductTraits, type RemoteIdEntry, type ReplicationAdapter, type SyncContext, type TallyConnector, useConnector, useCustomerTraits, useProductTraits };

package/dist/index.js

@@ -0,0 +1,30 @@
+// src/context/connector-context.tsx
+import { createContext, useContext } from "react";
+import { jsx } from "react/jsx-runtime";
+var ConnectorContext = createContext(null);
+function ConnectorProvider({ connector, children }) {
+  return /* @__PURE__ */ jsx(ConnectorContext.Provider, { value: connector, children });
+}
+function useConnector() {
+  const connector = useContext(ConnectorContext);
+  if (!connector) {
+    throw new Error(
+      "useConnector() must be used within a <ConnectorProvider>. Wrap your app with <ConnectorProvider connector={yourConnector}>."
+    );
+  }
+  return connector;
+}
+function useProductTraits() {
+  const connector = useConnector();
+  return connector.traits.product;
+}
+function useCustomerTraits() {
+  const connector = useConnector();
+  return connector.traits.customer;
+}
+export {
+  ConnectorProvider,
+  useConnector,
+  useCustomerTraits,
+  useProductTraits
+};

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@tallyui/core",
+  "version": "0.2.0",
+  "type": "module",
+  "description": "Core interfaces, traits, and context providers 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": {
+    "react": ">=18",
+    "rxdb": ">=16",
+    "rxjs": ">=7"
+  },
+  "devDependencies": {
+    "@types/react": ">=18"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "echo \"no tests yet\""
+  }
+}

package/src/__tests__/connector-context.test.tsx

@@ -0,0 +1,100 @@
+import { describe, it, expect } from 'vitest';
+import { renderHook } from '@testing-library/react';
+import type { ReactNode } from 'react';
+import { ConnectorProvider, useConnector, useProductTraits } from '../context/connector-context';
+import type { TallyConnector } from '../types';
+
+/**
+ * Minimal connector stub that satisfies the TallyConnector interface
+ * just enough for context tests.
+ */
+const stubConnector: TallyConnector = {
+  id: 'test',
+  name: 'Test Connector',
+  description: 'Stub for testing',
+  auth: {
+    type: 'none',
+    fields: [],
+    getHeaders: () => ({}),
+  },
+  schemas: {
+    products: {
+      version: 0,
+      primaryKey: 'id',
+      type: 'object',
+      properties: { id: { type: 'string', maxLength: 100 } },
+      required: ['id'],
+    },
+  },
+  traits: {
+    product: {
+      getId: (doc) => doc.id,
+      getName: (doc) => doc.name,
+      getSku: () => undefined,
+      getPrice: () => undefined,
+      getRegularPrice: () => undefined,
+      getSalePrice: () => undefined,
+      isOnSale: () => false,
+      getImageUrl: () => undefined,
+      getImageUrls: () => [],
+      getDescription: () => undefined,
+      getStockStatus: () => 'unknown',
+      getStockQuantity: () => null,
+      hasVariants: () => false,
+      getType: () => 'simple',
+      getBarcode: () => undefined,
+      getCategoryNames: () => [],
+    },
+  },
+  sync: {
+    products: {
+      fetchAllIds: async () => [],
+      fetchByIds: async () => [],
+    },
+  },
+};
+
+function wrapper({ children }: { children: ReactNode }) {
+  return <ConnectorProvider connector={stubConnector}>{children}</ConnectorProvider>;
+}
+
+describe('ConnectorProvider + useConnector', () => {
+  it('provides the connector through context', () => {
+    const { result } = renderHook(() => useConnector(), { wrapper });
+
+    expect(result.current).toBe(stubConnector);
+    expect(result.current.id).toBe('test');
+    expect(result.current.name).toBe('Test Connector');
+  });
+
+  it('throws when useConnector is called outside a provider', () => {
+    expect(() => {
+      renderHook(() => useConnector());
+    }).toThrow('useConnector() must be used within a <ConnectorProvider>');
+  });
+});
+
+describe('useProductTraits', () => {
+  it('returns the product traits from the active connector', () => {
+    const { result } = renderHook(() => useProductTraits(), { wrapper });
+
+    expect(result.current).toBe(stubConnector.traits.product);
+    expect(typeof result.current.getName).toBe('function');
+    expect(typeof result.current.getPrice).toBe('function');
+  });
+
+  it('traits work against a mock document', () => {
+    const { result } = renderHook(() => useProductTraits(), { wrapper });
+    const traits = result.current;
+
+    const doc = { id: '1', name: 'Widget' };
+    expect(traits.getName(doc)).toBe('Widget');
+    expect(traits.getId(doc)).toBe('1');
+  });
+
+  it('throws when called outside a provider', () => {
+    expect(() => {
+      renderHook(() => useProductTraits());
+    }).toThrow('useConnector() must be used within a <ConnectorProvider>');
+  });
+});

package/src/context/connector-context.tsx

@@ -0,0 +1,54 @@
+import { createContext, useContext, type ReactNode } from 'react';
+
+import type { TallyConnector } from '../types';
+
+/**
+ * React context that holds the active connector.
+ * Wrap your app (or a section of it) in <ConnectorProvider> to make
+ * the connector's traits available to all Tally UI components below.
+ */
+const ConnectorContext = createContext<TallyConnector | null>(null);
+
+export interface ConnectorProviderProps {
+  connector: TallyConnector;
+  children: ReactNode;
+}
+
+export function ConnectorProvider({ connector, children }: ConnectorProviderProps) {
+  return (
+    <ConnectorContext.Provider value={connector}>
+      {children}
+    </ConnectorContext.Provider>
+  );
+}
+
+/**
+ * Access the active connector. Throws if used outside a ConnectorProvider.
+ */
+export function useConnector(): TallyConnector {
+  const connector = useContext(ConnectorContext);
+  if (!connector) {
+    throw new Error(
+      'useConnector() must be used within a <ConnectorProvider>. ' +
+      'Wrap your app with <ConnectorProvider connector={yourConnector}>.'
+    );
+  }
+  return connector;
+}
+
+/**
+ * Convenience hook: grab just the product traits from the active connector.
+ */
+export function useProductTraits() {
+  const connector = useConnector();
+  return connector.traits.product;
+}
+
+/**
+ * Convenience hook: grab just the customer traits from the active connector.
+ * Returns undefined if the connector doesn't implement customer traits.
+ */
+export function useCustomerTraits() {
+  const connector = useConnector();
+  return connector.traits.customer;
+}

package/src/index.ts

@@ -0,0 +1,23 @@
+// Types
+export type {
+  TallyConnector,
+  ConnectorAuth,
+  ConnectorSchemas,
+  ConnectorTraits,
+  AuthField,
+  CollectionSync,
+  RemoteIdEntry,
+  ReplicationAdapter,
+  SyncContext,
+  ProductTraits,
+  CustomerTraits,
+} from './types';
+
+// Context & hooks
+export {
+  ConnectorProvider,
+  useConnector,
+  useProductTraits,
+  useCustomerTraits,
+} from './context/connector-context';
+export type { ConnectorProviderProps } from './context/connector-context';

package/src/types/connector.ts

@@ -0,0 +1,125 @@
+import type { RxJsonSchema } from 'rxdb';
+
+import type { ProductTraits } from './traits/product';
+import type { CustomerTraits } from './traits/customer';
+import type { ReplicationAdapter } from './replication';
+
+/**
+ * Authentication configuration for a connector.
+ * Each API has wildly different auth — JWT, API keys, OAuth, etc.
+ * The connector declares what it needs and how to use it.
+ */
+export interface ConnectorAuth {
+  /** Human-readable auth type for UI display */
+  type: string;
+  /** Fields required from the user to authenticate */
+  fields: AuthField[];
+  /** Build request headers from stored credentials */
+  getHeaders: (credentials: Record<string, string>) => Record<string, string>;
+  /** Optional: validate that credentials work (e.g., test API call) */
+  validate?: (credentials: Record<string, string>) => Promise<boolean>;
+}
+
+export interface AuthField {
+  key: string;
+  label: string;
+  type: 'text' | 'password' | 'url';
+  placeholder?: string;
+  required?: boolean;
+}
+
+/**
+ * Sync configuration for a collection.
+ * Defines how to fetch data from the remote API and push changes back.
+ *
+ * @deprecated Use ReplicationAdapter instead. This interface will be removed
+ * once all connectors have migrated to the RxDB replication protocol.
+ */
+export interface CollectionSync<T = any> {
+  /** Fetch all remote IDs (for diffing against local) */
+  fetchAllIds: (context: SyncContext) => Promise<RemoteIdEntry[]>;
+  /** Fetch documents by IDs */
+  fetchByIds: (ids: string[], context: SyncContext) => Promise<T[]>;
+  /** Fetch documents modified after a given date */
+  fetchModifiedAfter?: (date: string, context: SyncContext) => Promise<T[]>;
+  /** Push a local change to the remote */
+  push?: (doc: T, context: SyncContext) => Promise<T>;
+  /** Create a new document on the remote */
+  create?: (doc: Partial<T>, context: SyncContext) => Promise<T>;
+  /** Delete a document on the remote */
+  delete?: (id: string, context: SyncContext) => Promise<void>;
+}
+
+export interface RemoteIdEntry {
+  id: string;
+  dateModified?: string;
+}
+
+export interface SyncContext {
+  /** Unique connector identifier (used as replication namespace) */
+  connectorId: string;
+  /** Base URL for the API */
+  baseUrl: string;
+  /** Authenticated headers */
+  headers: Record<string, string>;
+  /** Optional abort signal */
+  signal?: AbortSignal;
+}
+
+/**
+ * Schema definitions for a connector.
+ * Each connector provides its own RxDB schemas that mirror its API shape.
+ */
+export interface ConnectorSchemas {
+  products: RxJsonSchema<any>;
+  // Future: orders, customers, taxes, etc.
+  [key: string]: RxJsonSchema<any>;
+}
+
+/**
+ * Trait implementations for a connector.
+ * These are the accessor functions that components program against.
+ */
+export interface ConnectorTraits {
+  product: ProductTraits;
+  customer?: CustomerTraits;
+}
+
+/**
+ * The main connector interface.
+ * Each backend (WooCommerce, Medusa, Vendure, etc.) implements this.
+ */
+export interface TallyConnector {
+  /** Unique identifier for this connector */
+  id: string;
+  /** Human-readable name */
+  name: string;
+  /** Description of the backend this connects to */
+  description: string;
+  /** Icon or logo URL */
+  icon?: string;
+
+  /** Authentication configuration */
+  auth: ConnectorAuth;
+
+  /** RxDB schemas for each collection */
+  schemas: ConnectorSchemas;
+
+  /** Trait implementations — how to extract standard data from connector-specific docs */
+  traits: ConnectorTraits;
+
+  /**
+   * @deprecated Use `replication` instead.
+   * Sync configuration for each collection (legacy pull-based sync).
+   */
+  sync: {
+    products: CollectionSync;
+    [key: string]: CollectionSync;
+  };
+
+  /** Replication adapters for each collection (RxDB replication protocol) */
+  replication?: {
+    products?: ReplicationAdapter<any>;
+    [key: string]: ReplicationAdapter<any> | undefined;
+  };
+}

package/src/types/index.ts

@@ -0,0 +1,16 @@
+export type {
+  TallyConnector,
+  ConnectorAuth,
+  ConnectorSchemas,
+  ConnectorTraits,
+  AuthField,
+  CollectionSync,
+  RemoteIdEntry,
+  SyncContext,
+} from './connector';
+
+export type { ReplicationAdapter } from './replication';
+
+export type { ProductTraits } from './traits/product';
+
+export type { CustomerTraits } from './traits/customer';

package/src/types/replication.test-d.ts

@@ -0,0 +1,20 @@
+import { describe, expectTypeOf, it } from 'vitest';
+import type { ReplicationAdapter, SyncContext } from '@tallyui/core';
+
+describe('ReplicationAdapter types', () => {
+  it('accepts a typed adapter with custom checkpoint', () => {
+    type Product = { id: string; name: string; _deleted: boolean };
+    type Checkpoint = { id: string; modified: string };
+
+    const adapter: ReplicationAdapter<Product, Checkpoint> = {} as any;
+
+    expectTypeOf(adapter.pull.handler).toBeFunction();
+    expectTypeOf(adapter.push).toEqualTypeOf<ReplicationAdapter<Product, Checkpoint>['push']>();
+  });
+
+  it('requires _deleted on document type', () => {
+    type Doc = { id: string; _deleted: boolean };
+    type Adapter = ReplicationAdapter<Doc>;
+    expectTypeOf<Adapter['pull']['handler']>().toBeFunction();
+  });
+});

package/src/types/replication.ts

@@ -0,0 +1,51 @@
+import type { RxReplicationPullStreamItem, RxReplicationWriteToMasterRow } from 'rxdb';
+import type { Observable } from 'rxjs';
+
+import type { SyncContext } from './connector';
+
+/**
+ * Replication adapter interface for a single collection.
+ *
+ * Each connector implements this to provide pull/push handlers
+ * compatible with RxDB's replicateRxCollection protocol.
+ *
+ * CheckpointType is connector-specific (cursor, offset+timestamp, etc).
+ */
+export interface ReplicationAdapter<RxDocType, CheckpointType = any> {
+  pull: {
+    /**
+     * Fetch documents changed since the last checkpoint.
+     * Return an empty documents array when fully caught up.
+     */
+    handler: (
+      lastCheckpoint: CheckpointType | undefined,
+      batchSize: number,
+      context: SyncContext
+    ) => Promise<{
+      documents: Array<RxDocType & { _deleted: boolean }>;
+      checkpoint: CheckpointType;
+    }>;
+
+    /**
+     * Optional real-time event stream.
+     * Emit { documents, checkpoint } for live updates,
+     * or 'RESYNC' to trigger a full pull cycle.
+     */
+    stream$?: Observable<RxReplicationPullStreamItem<RxDocType, CheckpointType>>;
+  };
+
+  push?: {
+    /**
+     * Push local changes to the remote API.
+     * Return an array of conflict documents (server's version wins).
+     * Return empty array if no conflicts.
+     */
+    handler: (
+      changeRows: RxReplicationWriteToMasterRow<RxDocType>[],
+      context: SyncContext
+    ) => Promise<Array<RxDocType & { _deleted: boolean }>>;
+
+    /** Max documents per push batch. Defaults to 100. */
+    batchSize?: number;
+  };
+}

package/src/types/traits/customer.ts

@@ -0,0 +1,22 @@
+/**
+ * Customer traits — the stable interface that UI components program against.
+ *
+ * Each connector implements these to extract standard customer data
+ * from its own schema shape.
+ */
+export interface CustomerTraits<Doc = any> {
+  /** Customer display name (first + last or company) */
+  getName: (doc: Doc) => string;
+
+  /** Email address */
+  getEmail: (doc: Doc) => string | undefined;
+
+  /** Phone number */
+  getPhone: (doc: Doc) => string | undefined;
+
+  /** One-line address summary (e.g., "123 Main St, Springfield") */
+  getAddressSummary: (doc: Doc) => string | undefined;
+
+  /** The connector-specific unique ID (as string for consistency) */
+  getId: (doc: Doc) => string;
+}

package/src/types/traits/product.ts

@@ -0,0 +1,59 @@
+/**
+ * Product traits — the stable interface that UI components program against.
+ *
+ * Each connector implements these accessors to extract standard product data
+ * from its own schema shape. Components call these instead of reaching into
+ * the raw document, so they work identically across WooCommerce, Medusa,
+ * Vendure, Shopify, etc.
+ *
+ * The generic `Doc` type is the connector's raw RxDB document type.
+ */
+export interface ProductTraits<Doc = any> {
+  /** Product display name */
+  getName: (doc: Doc) => string;
+
+  /** SKU / stock keeping unit */
+  getSku: (doc: Doc) => string | undefined;
+
+  /** Current selling price as a string (connector-native format) */
+  getPrice: (doc: Doc) => string | undefined;
+
+  /** Regular (non-sale) price */
+  getRegularPrice: (doc: Doc) => string | undefined;
+
+  /** Sale price, if on sale */
+  getSalePrice: (doc: Doc) => string | undefined;
+
+  /** Whether the product is currently on sale */
+  isOnSale: (doc: Doc) => boolean;
+
+  /** Primary image URL */
+  getImageUrl: (doc: Doc) => string | undefined;
+
+  /** All image URLs */
+  getImageUrls: (doc: Doc) => string[];
+
+  /** Short description / excerpt */
+  getDescription: (doc: Doc) => string | undefined;
+
+  /** Stock status */
+  getStockStatus: (doc: Doc) => 'instock' | 'outofstock' | 'onbackorder' | 'unknown';
+
+  /** Stock quantity (null if not tracked) */
+  getStockQuantity: (doc: Doc) => number | null;
+
+  /** Whether this product has variants/variations */
+  hasVariants: (doc: Doc) => boolean;
+
+  /** Product type (simple, variable, etc. — connector-specific but useful for UI hints) */
+  getType: (doc: Doc) => string;
+
+  /** Barcode / UPC / EAN */
+  getBarcode: (doc: Doc) => string | undefined;
+
+  /** Categories as simple label strings */
+  getCategoryNames: (doc: Doc) => string[];
+
+  /** The connector-specific unique ID (as string for consistency) */
+  getId: (doc: Doc) => string;
+}