@rotateprotocol/sdk 1.0.0

package/src/marketplace.ts

@@ -0,0 +1,642 @@
+/**
+ * Rotate Marketplace — Multi-Vendor Cart & Split Payments
+ *
+ * Multi-vendor split payments for decentralized commerce.
+ * Manages vendors (merchants), routes payments, and splits multi-vendor carts
+ * into separate on-chain transactions per merchant.
+ *
+ * @example
+ * ```ts
+ * const marketplace = new RotateMarketplace(sdk, {
+ *   platformId: 1000000,
+ *   platformFeeBps: 200, // 2% marketplace fee
+ * });
+ *
+ * // Register vendors
+ * marketplace.addVendor({ id: 'vendor-a', merchantId: 1000001, name: 'Shirt Co.' });
+ * marketplace.addVendor({ id: 'vendor-b', merchantId: 1000002, name: 'Hat Store' });
+ *
+ * // Add products from different vendors
+ * marketplace.addProduct({ id: 'shirt-1', vendorId: 'vendor-a', name: 'Logo Tee', price: 29.99 });
+ * marketplace.addProduct({ id: 'hat-1', vendorId: 'vendor-b', name: 'Snapback', price: 24.99 });
+ *
+ * // Customer shops from multiple vendors
+ * const cart = marketplace.createCart();
+ * cart.addItem('shirt-1', 2);
+ * cart.addItem('hat-1', 1);
+ *
+ * const result = await cart.checkout();
+ * // Creates separate payment links per vendor:
+ * //   vendor-a: $59.98 (2x shirts)
+ * //   vendor-b: $24.99 (1x hat)
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+import RotateSDK, { calculateFees } from './index';
+import { Product, LineItem, Currency } from './store';
+import { Catalog } from './catalog';
+
+// ==================== TYPES ====================
+
+/** A vendor (merchant) in the marketplace */
+export interface Vendor {
+  /** Your internal vendor ID */
+  id: string;
+  /** On-chain merchant ID (7-digit) */
+  merchantId: number;
+  /** Display name */
+  name: string;
+  /** Description */
+  description?: string;
+  /** Logo URL */
+  logo?: string;
+  /** Rating (0-5) */
+  rating?: number;
+  /** Whether the vendor is active */
+  active: boolean;
+  /** Arbitrary metadata */
+  metadata?: Record<string, string>;
+}
+
+export interface VendorInput {
+  id: string;
+  merchantId: number;
+  name: string;
+  description?: string;
+  logo?: string;
+  rating?: number;
+  active?: boolean;
+  metadata?: Record<string, string>;
+}
+
+/** A marketplace product extends the base Product with a vendorId */
+export interface MarketplaceProduct extends Product {
+  vendorId: string;
+}
+
+export interface MarketplaceProductInput {
+  id: string;
+  vendorId: string;
+  name: string;
+  description?: string;
+  price: number;
+  compareAtPrice?: number;
+  category?: string;
+  images?: string[];
+  inventory?: number;
+  active?: boolean;
+  metadata?: Record<string, string>;
+}
+
+/** Line item with vendor context */
+export interface MarketplaceLineItem extends LineItem {
+  vendorId: string;
+  vendorName: string;
+}
+
+/** Per-vendor subtotals in a marketplace cart */
+export interface VendorSubtotal {
+  vendorId: string;
+  vendorName: string;
+  merchantId: number;
+  items: Array<{
+    productId: string;
+    name: string;
+    quantity: number;
+    unitPrice: number;
+    lineTotal: number;
+  }>;
+  subtotal: number;
+  fees: number;
+  total: number;
+  merchantReceives: number;
+}
+
+/** Full marketplace cart totals */
+export interface MarketplaceCartTotals {
+  /** Total unique items */
+  itemCount: number;
+  /** Total quantity */
+  totalQuantity: number;
+  /** Combined subtotal */
+  subtotal: number;
+  /** Combined fees */
+  fees: number;
+  /** Grand total */
+  total: number;
+  /** Number of vendors in this cart */
+  vendorCount: number;
+  /** Per-vendor breakdown */
+  vendors: VendorSubtotal[];
+}
+
+/** Result of a marketplace checkout — one payment link per vendor */
+export interface MarketplaceCheckoutResult {
+  /** Per-vendor payment links */
+  vendorPayments: Array<{
+    vendorId: string;
+    vendorName: string;
+    merchantId: number;
+    linkId: number;
+    tx: string;
+    paymentUrl: string;
+    qrCodeUrl: string;
+    subtotal: number;
+    fees: number;
+    total: number;
+  }>;
+  /** Combined totals */
+  totals: MarketplaceCartTotals;
+  /** Master order reference */
+  orderRef: string;
+  /** Timestamp */
+  createdAt: number;
+}
+
+export interface MarketplaceConfig {
+  platformId: number;
+  /** Platform fee BPS charged by the marketplace */
+  platformFeeBps?: number;
+  /** Default currency */
+  currency?: Currency;
+  /** Allow tips */
+  allowTips?: boolean;
+  /** Default link expiration in seconds (0 = never, default: 300 = 5min) */
+  defaultExpiresIn?: number;
+}
+
+// ==================== ROTATE MARKETPLACE ====================
+
+export class RotateMarketplace {
+  private sdk: RotateSDK;
+  private config: Required<MarketplaceConfig>;
+  private vendors: Map<string, Vendor> = new Map();
+  /** @internal Shared catalog logic for marketplace products */
+  private catalog: Catalog<MarketplaceProduct, MarketplaceProductInput>;
+
+  constructor(sdk: RotateSDK, config: MarketplaceConfig) {
+    this.sdk = sdk;
+    this.config = {
+      platformId: config.platformId,
+      platformFeeBps: config.platformFeeBps ?? 0,
+      currency: config.currency || 'USD',
+      allowTips: config.allowTips ?? false,
+      defaultExpiresIn: config.defaultExpiresIn ?? 300,
+    };
+    this.catalog = new Catalog<MarketplaceProduct, MarketplaceProductInput>((input) => {
+      // Validate vendor exists at creation time
+      const vendor = this.vendors.get(input.vendorId);
+      if (!vendor) throw new Error(`Vendor '${input.vendorId}' not found. Register the vendor first.`);
+      const now = Date.now();
+      return { ...input, active: input.active ?? true, createdAt: now, updatedAt: now };
+    });
+  }
+
+  // ==================== VENDOR MANAGEMENT ====================
+
+  /** Register a vendor */
+  addVendor(input: VendorInput): Vendor {
+    const vendor: Vendor = {
+      ...input,
+      active: input.active ?? true,
+    };
+    this.vendors.set(vendor.id, vendor);
+    return vendor;
+  }
+
+  /** Bulk register vendors */
+  addVendors(inputs: VendorInput[]): Vendor[] {
+    return inputs.map((v) => this.addVendor(v));
+  }
+
+  /** Update a vendor */
+  updateVendor(id: string, updates: Partial<VendorInput>): Vendor {
+    const existing = this.vendors.get(id);
+    if (!existing) throw new Error(`Vendor '${id}' not found`);
+    const updated: Vendor = { ...existing, ...updates, id: existing.id };
+    this.vendors.set(id, updated);
+    return updated;
+  }
+
+  /** Get a vendor */
+  getVendor(id: string): Vendor | undefined {
+    return this.vendors.get(id);
+  }
+
+  /** List all vendors */
+  getVendors(filter?: { active?: boolean; search?: string }): Vendor[] {
+    let results = Array.from(this.vendors.values());
+    if (filter?.active !== undefined) {
+      results = results.filter((v) => v.active === filter.active);
+    }
+    if (filter?.search) {
+      const q = filter.search.toLowerCase();
+      results = results.filter(
+        (v) => v.name.toLowerCase().includes(q) || v.description?.toLowerCase().includes(q)
+      );
+    }
+    return results;
+  }
+
+  /** Remove a vendor and all their products */
+  removeVendor(id: string): boolean {
+    // Remove all products from this vendor
+    this.catalog.removeProductsWhere((p) => p.vendorId === id);
+    return this.vendors.delete(id);
+  }
+
+  get vendorCount(): number {
+    return this.vendors.size;
+  }
+
+  // ==================== PRODUCT CATALOG (delegated to Catalog) ====================
+
+  addProduct(input: MarketplaceProductInput): MarketplaceProduct { return this.catalog.addProduct(input); }
+  addProducts(inputs: MarketplaceProductInput[]): MarketplaceProduct[] { return this.catalog.addProducts(inputs); }
+
+  updateProduct(id: string, updates: Partial<MarketplaceProductInput>): MarketplaceProduct {
+    // Ensure vendorId remains immutable
+    const existing = this.catalog.getProduct(id);
+    if (!existing) throw new Error(`Product '${id}' not found`);
+    const { vendorId: _ignored, ...safeUpdates } = updates;
+    return this.catalog.updateProduct(id, { ...safeUpdates, vendorId: existing.vendorId } as Partial<MarketplaceProductInput>);
+  }
+
+  removeProduct(id: string): boolean { return this.catalog.removeProduct(id); }
+  getProduct(id: string): MarketplaceProduct | undefined { return this.catalog.getProduct(id); }
+
+  /** List products with filters (includes vendorId filter on top of base catalog) */
+  getProducts(filter?: {
+    vendorId?: string;
+    category?: string; active?: boolean; search?: string;
+    minPrice?: number; maxPrice?: number;
+    sortBy?: 'name' | 'price' | 'createdAt' | 'rating';
+    sortOrder?: 'asc' | 'desc';
+    limit?: number; offset?: number;
+  }): MarketplaceProduct[] {
+    if (filter?.vendorId) {
+      // When filtering by vendor, strip limit/offset from the catalog query
+      // so pagination applies AFTER the vendor filter.  Without this, the
+      // catalog returns `limit` products of *any* vendor, and the subsequent
+      // vendorId filter would silently shrink the result set.
+      const { vendorId, limit, offset, ...catalogFilter } = filter;
+      let results = this.catalog.getProducts(catalogFilter);
+      results = results.filter((p) => p.vendorId === vendorId);
+      if (offset) results = results.slice(offset);
+      if (limit) results = results.slice(0, limit);
+      return results;
+    }
+    return this.catalog.getProducts(filter);
+  }
+
+  getVendorProducts(vendorId: string): MarketplaceProduct[] {
+    return this.getProducts({ vendorId, active: true });
+  }
+
+  getCategories(): string[] { return this.catalog.getCategories(); }
+  get productCount(): number { return this.catalog.productCount; }
+
+  // ==================== INVENTORY (delegated) ====================
+
+  isInStock(productId: string, quantity: number = 1): boolean { return this.catalog.isInStock(productId, quantity); }
+  reserveInventory(productId: string, quantity: number): void { this.catalog.reserveInventory(productId, quantity); }
+  releaseInventory(productId: string, quantity: number): void { this.catalog.releaseInventory(productId, quantity); }
+
+  // ==================== MARKETPLACE CART ====================
+
+  /** Create a multi-vendor cart */
+  createCart(): MarketplaceCart {
+    return new MarketplaceCart(this, this.sdk, this.config);
+  }
+
+  // ==================== SERIALIZATION ====================
+
+  exportCatalog(): { vendors: Vendor[]; products: MarketplaceProduct[] } {
+    return {
+      vendors: Array.from(this.vendors.values()),
+      products: this.catalog.exportProducts(),
+    };
+  }
+
+  importCatalog(data: { vendors: Vendor[]; products: MarketplaceProduct[] }): void {
+    this.vendors.clear();
+    for (const v of data.vendors) this.vendors.set(v.id, v);
+    this.catalog.importProducts(data.products);
+  }
+}
+
+// ==================== MARKETPLACE CART ====================
+
+export class MarketplaceCart {
+  private marketplace: RotateMarketplace;
+  private sdk: RotateSDK;
+  private config: Required<MarketplaceConfig>;
+  private items: Map<string, { product: MarketplaceProduct; quantity: number }> = new Map();
+  private _metadata: Record<string, string> = {};
+
+  /** @internal */
+  constructor(marketplace: RotateMarketplace, sdk: RotateSDK, config: Required<MarketplaceConfig>) {
+    this.marketplace = marketplace;
+    this.sdk = sdk;
+    this.config = config;
+  }
+
+  // ==================== LINE ITEMS ====================
+
+  addItem(productId: string, quantity: number = 1): void {
+    if (quantity <= 0) throw new Error('Quantity must be positive');
+
+    const product = this.marketplace.getProduct(productId);
+    if (!product) throw new Error(`Product '${productId}' not found`);
+    if (!product.active) throw new Error(`Product '${productId}' is not active`);
+
+    const existing = this.items.get(productId);
+    const newQty = (existing?.quantity || 0) + quantity;
+
+    if (!this.marketplace.isInStock(productId, newQty)) {
+      throw new Error(`Insufficient stock for '${productId}'`);
+    }
+
+    this.items.set(productId, { product, quantity: newQty });
+  }
+
+  setItemQuantity(productId: string, quantity: number): void {
+    if (quantity <= 0) {
+      this.items.delete(productId);
+      return;
+    }
+
+    const product = this.marketplace.getProduct(productId);
+    if (!product) throw new Error(`Product '${productId}' not found`);
+
+    if (!this.marketplace.isInStock(productId, quantity)) {
+      throw new Error(`Insufficient stock for '${productId}'`);
+    }
+
+    this.items.set(productId, { product, quantity });
+  }
+
+  removeItem(productId: string): boolean {
+    return this.items.delete(productId);
+  }
+
+  clear(): void {
+    this.items.clear();
+    this._metadata = {};
+  }
+
+  getItems(): MarketplaceLineItem[] {
+    const result: MarketplaceLineItem[] = [];
+    for (const { product, quantity } of this.items.values()) {
+      const vendor = this.marketplace.getVendor(product.vendorId);
+      result.push({
+        product,
+        quantity,
+        unitPrice: product.price,
+        vendorId: product.vendorId,
+        vendorName: vendor?.name || product.vendorId,
+      });
+    }
+    return result;
+  }
+
+  get isEmpty(): boolean {
+    return this.items.size === 0;
+  }
+
+  setMetadata(key: string, value: string): void {
+    this._metadata[key] = value;
+  }
+
+  // ==================== TOTALS ====================
+
+  /** Group items by vendor and calculate per-vendor + combined totals */
+  getTotals(): MarketplaceCartTotals {
+    // Group by vendor
+    const vendorGroups: Map<string, { vendor: Vendor; items: Array<{ product: MarketplaceProduct; quantity: number }> }> = new Map();
+
+    for (const { product, quantity } of this.items.values()) {
+      const vendor = this.marketplace.getVendor(product.vendorId);
+      if (!vendor) continue;
+
+      let group = vendorGroups.get(product.vendorId);
+      if (!group) {
+        group = { vendor, items: [] };
+        vendorGroups.set(product.vendorId, group);
+      }
+      group.items.push({ product, quantity });
+    }
+
+    const vendorSubtotals: VendorSubtotal[] = [];
+    let grandSubtotal = 0;
+    let grandFees = 0;
+    let grandTotal = 0;
+    let totalItems = 0;
+    let totalQuantity = 0;
+
+    for (const [vendorId, group] of vendorGroups.entries()) {
+      const items: VendorSubtotal['items'] = [];
+      let vendorSubtotal = 0;
+
+      for (const { product, quantity } of group.items) {
+        const lineTotal = Math.round(product.price * quantity * 100) / 100;
+        vendorSubtotal += lineTotal;
+        totalQuantity += quantity;
+        items.push({
+          productId: product.id,
+          name: product.name,
+          quantity,
+          unitPrice: product.price,
+          lineTotal,
+        });
+      }
+
+      vendorSubtotal = Math.round(vendorSubtotal * 100) / 100;
+
+
+      // Calculate fees
+      const amountMicro = Math.floor(vendorSubtotal * 1_000_000);
+      const feesResult = calculateFees(amountMicro, this.config.platformFeeBps);
+      const fees = Math.round(feesResult.buyerFeeShare / 1_000_000 * 100) / 100;
+      const vendorTotal = Math.round((vendorSubtotal + fees) * 100) / 100;
+      const merchantReceives = Math.round(feesResult.merchantReceives / 1_000_000 * 100) / 100;
+
+      totalItems += items.length;
+
+      vendorSubtotals.push({
+        vendorId,
+        vendorName: group.vendor.name,
+        merchantId: group.vendor.merchantId,
+        items,
+        subtotal: vendorSubtotal,
+        fees,
+        total: vendorTotal,
+        merchantReceives,
+      });
+
+      grandSubtotal += vendorSubtotal;
+      grandFees += fees;
+      grandTotal += vendorTotal;
+    }
+
+    return {
+      itemCount: totalItems,
+      totalQuantity,
+      subtotal: Math.round(grandSubtotal * 100) / 100,
+      fees: Math.round(grandFees * 100) / 100,
+      total: Math.round(grandTotal * 100) / 100,
+      vendorCount: vendorGroups.size,
+      vendors: vendorSubtotals,
+    };
+  }
+
+  // ==================== CHECKOUT ====================
+
+  /**
+   * Checkout the marketplace cart.
+   * Creates one on-chain payment link **per vendor** so each merchant
+   * receives funds directly into their own wallet — true decentralized
+   * marketplace payments with no intermediary holding funds.
+   */
+  async checkout(options?: {
+    expiresIn?: number;
+    currency?: Currency;
+    allowTips?: boolean;
+    orderRef?: string;
+  }): Promise<MarketplaceCheckoutResult> {
+    if (this.isEmpty) throw new Error('Cart is empty');
+
+    const totals = this.getTotals();
+    const masterOrderRef = options?.orderRef || `mkt_${Date.now()}_${Math.random().toString(36).substr(2, 6)}`;
+    const currency = options?.currency || this.config.currency;
+    const expiresAt = (options?.expiresIn ?? this.config.defaultExpiresIn) > 0
+      ? Math.floor(Date.now() / 1000) + (options?.expiresIn ?? this.config.defaultExpiresIn)
+      : 0;
+    const allowTips = options?.allowTips ?? this.config.allowTips;
+
+    // Validate stock
+    for (const { product, quantity } of this.items.values()) {
+      if (!this.marketplace.isInStock(product.id, quantity)) {
+        throw new Error(`'${product.name}' is out of stock`);
+      }
+    }
+
+    // Create one payment link per vendor
+    const vendorPayments: MarketplaceCheckoutResult['vendorPayments'] = [];
+
+    for (const vendorTotals of totals.vendors) {
+      const vendorOrderRef = `${masterOrderRef}_v${vendorTotals.vendorId}`;
+      const amountMicro = BigInt(Math.floor(vendorTotals.subtotal * 1_000_000));
+
+      // Auto-generate description from vendor items
+      const description = vendorTotals.items.map(i => `${i.quantity}x ${i.name}`).join(', ');
+
+      let result: { tx: string; linkId: number };
+
+      if (currency === 'SOL') {
+        const solPrice = await this.sdk.getSolPrice();
+        const lamports = BigInt(Math.floor((vendorTotals.subtotal / solPrice) * 1_000_000_000));
+        result = await this.sdk.createLinkSol({
+          merchantId: vendorTotals.merchantId,
+          platformId: this.config.platformId,
+          amount: lamports,
+          expiresAt,
+          allowTips,
+          allowPartial: false,
+          orderRef: vendorOrderRef,
+          description,
+        });
+      } else if (currency === 'USDC' || currency === 'USDT') {
+        result = await this.sdk.createLinkToken({
+          merchantId: vendorTotals.merchantId,
+          platformId: this.config.platformId,
+          amount: amountMicro,
+          expiresAt,
+          allowTips,
+          allowPartial: false,
+          orderRef: vendorOrderRef,
+          currency,
+          description,
+        });
+      } else {
+        result = await this.sdk.createLinkUsd({
+          merchantId: vendorTotals.merchantId,
+          platformId: this.config.platformId,
+          amount: amountMicro,
+          expiresAt,
+          allowTips,
+          allowPartial: false,
+          orderRef: vendorOrderRef,
+          description,
+        });
+      }
+
+      vendorPayments.push({
+        vendorId: vendorTotals.vendorId,
+        vendorName: vendorTotals.vendorName,
+        merchantId: vendorTotals.merchantId,
+        linkId: result.linkId,
+        tx: result.tx,
+        paymentUrl: this.sdk.getPaymentUrl(result.linkId),
+        qrCodeUrl: this.sdk.getQRCodeUrl(result.linkId),
+        subtotal: vendorTotals.subtotal,
+        fees: vendorTotals.fees,
+        total: vendorTotals.total,
+      });
+    }
+
+    // Reserve inventory
+    for (const { product, quantity } of this.items.values()) {
+      this.marketplace.reserveInventory(product.id, quantity);
+    }
+
+    return {
+      vendorPayments,
+      totals,
+      orderRef: masterOrderRef,
+      createdAt: Date.now(),
+    };
+  }
+
+  /**
+   * Wait for ALL vendor payments to complete.
+   * Returns once every link is paid or the timeout is reached.
+   */
+  async waitForAllPayments(
+    vendorPayments: MarketplaceCheckoutResult['vendorPayments'],
+    timeoutMs: number = 600000
+  ): Promise<{ allPaid: boolean; results: Array<{ vendorId: string; linkId: number; paid: boolean }> }> {
+    const startTime = Date.now();
+    const results = vendorPayments.map((vp) => ({
+      vendorId: vp.vendorId,
+      linkId: vp.linkId,
+      paid: false,
+    }));
+
+    while (Date.now() - startTime < timeoutMs) {
+      let allPaid = true;
+
+      for (const r of results) {
+        if (r.paid) continue;
+        const paid = await this.sdk.isLinkPaid(r.linkId);
+        if (paid) {
+          r.paid = true;
+        } else {
+          allPaid = false;
+        }
+      }
+
+      if (allPaid) return { allPaid: true, results };
+
+      await new Promise((resolve) => setTimeout(resolve, 3000));
+    }
+
+    return { allPaid: false, results };
+  }
+}
+
+// ==================== EXPORTS ====================
+
+export default RotateMarketplace;