@rotateprotocol/sdk 1.0.0

package/src/catalog.ts

@@ -0,0 +1,299 @@
+/**
+ * Rotate Catalog — Shared product catalog, inventory, and discount logic.
+ *
+ * Used internally by `RotateStore` and `RotateMarketplace` to avoid
+ * duplicating catalog management code.  Not exported to SDK consumers —
+ * use `RotateStore` or `RotateMarketplace` instead.
+ *
+ * @internal
+ * @packageDocumentation
+ */
+
+// ==================== TYPES ====================
+
+/** Base product shape — extend this for domain-specific fields */
+export interface BaseProduct {
+  id: string;
+  name: string;
+  description?: string;
+  price: number;
+  compareAtPrice?: number;
+  category?: string;
+  images?: string[];
+  inventory?: number;
+  active: boolean;
+  metadata?: Record<string, string>;
+  createdAt: number;
+  updatedAt: number;
+}
+
+/** Minimum required input to create a product */
+export interface BaseProductInput {
+  id: string;
+  name: string;
+  description?: string;
+  price: number;
+  compareAtPrice?: number;
+  category?: string;
+  images?: string[];
+  inventory?: number;
+  active?: boolean;
+  metadata?: Record<string, string>;
+}
+
+/** Discount code */
+export interface Discount {
+  code: string;
+  type: 'percent' | 'fixed';
+  value: number;
+  minAmount?: number;
+  maxUses?: number;
+  usedCount: number;
+  expiresAt?: number;
+  productIds?: string[];
+  active: boolean;
+}
+
+export interface DiscountInput {
+  code: string;
+  type: 'percent' | 'fixed';
+  value: number;
+  minAmount?: number;
+  maxUses?: number;
+  expiresAt?: number;
+  productIds?: string[];
+  active?: boolean;
+}
+
+/** Product filter options */
+export interface ProductFilter {
+  category?: string;
+  active?: boolean;
+  search?: string;
+  minPrice?: number;
+  maxPrice?: number;
+  sortBy?: 'name' | 'price' | 'createdAt' | 'rating';
+  sortOrder?: 'asc' | 'desc';
+  limit?: number;
+  offset?: number;
+}
+
+// ==================== CATALOG ====================
+
+/**
+ * Generic product catalog with inventory and discount management.
+ *
+ * @typeParam P - Product type (must extend BaseProduct).
+ * @typeParam I - Product input type (must extend BaseProductInput).
+ */
+export class Catalog<P extends BaseProduct, I extends BaseProductInput> {
+  private products: Map<string, P> = new Map();
+  private discounts: Map<string, Discount> = new Map();
+  private categories: Set<string> = new Set();
+
+  /** Optional hook to transform an input into a full product. */
+  private createProduct: (input: I) => P;
+
+  constructor(createProduct: (input: I) => P) {
+    this.createProduct = createProduct;
+  }
+
+  // ==================== PRODUCT MANAGEMENT ====================
+
+  addProduct(input: I): P {
+    const product = this.createProduct(input);
+    this.products.set(product.id, product);
+    if (product.category) this.categories.add(product.category);
+    return product;
+  }
+
+  addProducts(inputs: I[]): P[] {
+    return inputs.map((p) => this.addProduct(p));
+  }
+
+  updateProduct(id: string, updates: Partial<I>): P {
+    const existing = this.products.get(id);
+    if (!existing) throw new Error(`Product '${id}' not found`);
+    const updated: P = {
+      ...existing,
+      ...updates,
+      id: existing.id, // immutable
+      updatedAt: Date.now(),
+    } as P;
+    this.products.set(id, updated);
+    if (updated.category) this.categories.add(updated.category);
+    return updated;
+  }
+
+  removeProduct(id: string): boolean {
+    return this.products.delete(id);
+  }
+
+  getProduct(id: string): P | undefined {
+    return this.products.get(id);
+  }
+
+  getProducts(filter?: ProductFilter): P[] {
+    let results = Array.from(this.products.values());
+
+    if (filter) {
+      if (filter.active !== undefined) {
+        results = results.filter((p) => p.active === filter.active);
+      }
+      if (filter.category) {
+        results = results.filter((p) => p.category === filter.category);
+      }
+      if (filter.search) {
+        const q = filter.search.toLowerCase();
+        results = results.filter(
+          (p) =>
+            p.name.toLowerCase().includes(q) ||
+            p.description?.toLowerCase().includes(q) ||
+            p.id.toLowerCase().includes(q),
+        );
+      }
+      if (filter.minPrice !== undefined) {
+        results = results.filter((p) => p.price >= filter.minPrice!);
+      }
+      if (filter.maxPrice !== undefined) {
+        results = results.filter((p) => p.price <= filter.maxPrice!);
+      }
+
+      const sortBy = filter.sortBy || 'createdAt';
+      const order = filter.sortOrder === 'desc' ? -1 : 1;
+      results.sort((a, b) => {
+        if (sortBy === 'name') return a.name.localeCompare(b.name) * order;
+        if (sortBy === 'price') return (a.price - b.price) * order;
+        return (a.createdAt - b.createdAt) * order;
+      });
+
+      if (filter.offset) results = results.slice(filter.offset);
+      if (filter.limit) results = results.slice(0, filter.limit);
+    }
+
+    return results;
+  }
+
+  getCategories(): string[] {
+    return Array.from(this.categories).sort();
+  }
+
+  get productCount(): number {
+    return this.products.size;
+  }
+
+  /** Direct access to the internal product map (for advanced filtering). */
+  entries(): IterableIterator<[string, P]> {
+    return this.products.entries();
+  }
+
+  values(): IterableIterator<P> {
+    return this.products.values();
+  }
+
+  // ==================== INVENTORY ====================
+
+  isInStock(productId: string, quantity: number = 1): boolean {
+    const product = this.products.get(productId);
+    if (!product || !product.active) return false;
+    if (product.inventory === undefined) return true;
+    return product.inventory >= quantity;
+  }
+
+  reserveInventory(productId: string, quantity: number): void {
+    const product = this.products.get(productId);
+    if (!product) throw new Error(`Product '${productId}' not found`);
+    if (product.inventory !== undefined) {
+      if (product.inventory < quantity) {
+        throw new Error(
+          `Insufficient inventory for '${productId}': need ${quantity}, have ${product.inventory}`,
+        );
+      }
+      product.inventory -= quantity;
+      product.updatedAt = Date.now();
+    }
+  }
+
+  releaseInventory(productId: string, quantity: number): void {
+    const product = this.products.get(productId);
+    if (!product) throw new Error(`Product '${productId}' not found`);
+    if (product.inventory !== undefined) {
+      product.inventory += quantity;
+      product.updatedAt = Date.now();
+    }
+  }
+
+  // ==================== DISCOUNTS ====================
+
+  addDiscount(input: DiscountInput): Discount {
+    const discount: Discount = {
+      ...input,
+      usedCount: 0,
+      active: input.active ?? true,
+    };
+    this.discounts.set(discount.code.toUpperCase(), discount);
+    return discount;
+  }
+
+  getDiscount(code: string): Discount | undefined {
+    return this.discounts.get(code.toUpperCase());
+  }
+
+  isDiscountValid(code: string, subtotal: number): boolean {
+    const d = this.discounts.get(code.toUpperCase());
+    if (!d || !d.active) return false;
+    if (d.expiresAt && Date.now() > d.expiresAt) return false;
+    if (d.maxUses !== undefined && d.usedCount >= d.maxUses) return false;
+    if (d.minAmount !== undefined && subtotal < d.minAmount) return false;
+    return true;
+  }
+
+  useDiscount(code: string): void {
+    const d = this.discounts.get(code.toUpperCase());
+    if (d) d.usedCount++;
+  }
+
+  // ==================== SERIALIZATION ====================
+
+  exportProducts(): P[] {
+    return Array.from(this.products.values());
+  }
+
+  exportDiscounts(): Discount[] {
+    return Array.from(this.discounts.values());
+  }
+
+  importProducts(products: P[]): void {
+    this.products.clear();
+    this.categories.clear();
+    for (const p of products) {
+      this.products.set(p.id, p);
+      if (p.category) this.categories.add(p.category);
+    }
+  }
+
+  importDiscounts(discounts: Discount[]): void {
+    this.discounts.clear();
+    for (const d of discounts) {
+      this.discounts.set(d.code.toUpperCase(), d);
+    }
+  }
+
+  clear(): void {
+    this.products.clear();
+    this.discounts.clear();
+    this.categories.clear();
+  }
+
+  /** Remove all products matching a predicate. Returns count removed. */
+  removeProductsWhere(predicate: (product: P) => boolean): number {
+    let removed = 0;
+    for (const [id, product] of this.products.entries()) {
+      if (predicate(product)) {
+        this.products.delete(id);
+        removed++;
+      }
+    }
+    return removed;
+  }
+}