@rotateprotocol/sdk 1.0.0

package/src/store.ts

@@ -0,0 +1,577 @@
+/**
+ * Rotate Store — Product Catalog, Cart & Checkout
+ *
+ * A complete store layer that sits on top of the Rotate Protocol.
+ * Products and cart state are managed client-side / in your database;
+ * only the final payment touches the blockchain.
+ *
+ * @example
+ * ```ts
+ * const store = new RotateStore(sdk, {
+ *   merchantId: 1000000,
+ *   platformId: 1000000,
+ *   currency: 'USD',
+ * });
+ *
+ * store.addProduct({ id: 'tshirt-01', name: 'Logo Tee', price: 29.99, inventory: 100 });
+ * store.addProduct({ id: 'hoodie-01', name: 'Zip Hoodie', price: 59.99, inventory: 50 });
+ *
+ * const cart = store.createCart();
+ * cart.addItem('tshirt-01', 2);
+ * cart.addItem('hoodie-01', 1);
+ *
+ * const session = await cart.checkout(); // creates on-chain payment link
+ * console.log(session.linkId, session.paymentUrl);
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+import RotateSDK, {
+  calculateFees,
+  PaymentLink,
+  CreateLinkParams,
+  CreateLinkTokenParams,
+} from './index';
+import { Catalog, BaseProduct, BaseProductInput, Discount, DiscountInput } from './catalog';
+
+// ==================== TYPES ====================
+
+export type Currency = 'SOL' | 'USDC' | 'USDT' | 'USD';
+
+/** A product in the catalog */
+export interface Product extends BaseProduct {}
+
+export interface ProductInput extends BaseProductInput {}
+
+/** A line item in a cart */
+export interface LineItem {
+  product: Product;
+  quantity: number;
+  /** Per-item price override (for dynamic pricing / discounts) */
+  unitPrice: number;
+}
+
+// Re-export Discount types from catalog for backwards compatibility
+export type { Discount, DiscountInput } from './catalog';
+
+/** Cart totals breakdown */
+export interface CartTotals {
+  /** Number of unique items */
+  itemCount: number;
+  /** Total quantity across all items */
+  totalQuantity: number;
+  /** Subtotal before discounts and fees */
+  subtotal: number;
+  /** Total discount amount */
+  discountAmount: number;
+  /** Subtotal after discounts, before fees */
+  afterDiscount: number;
+  /** Buyer's fee share (protocol + platform) */
+  fees: number;
+  /** Grand total the buyer pays */
+  total: number;
+  /** What the merchant receives after seller-side fee deduction */
+  merchantReceives: number;
+  /** Line-by-line breakdown */
+  lines: Array<{
+    productId: string;
+    name: string;
+    quantity: number;
+    unitPrice: number;
+    lineTotal: number;
+  }>;
+}
+
+/** Result of a checkout */
+export interface CheckoutResult {
+  /** On-chain link ID */
+  linkId: number;
+  /** Transaction signature */
+  tx: string;
+  /** Payment URL */
+  paymentUrl: string;
+  /** QR code URL */
+  qrCodeUrl: string;
+  /** Cart totals at time of checkout */
+  totals: CartTotals;
+  /** Order reference */
+  orderRef: string;
+  /** Created timestamp */
+  createdAt: number;
+}
+
+/** Batch link creation result */
+export interface BatchLinkResult {
+  productId: string;
+  linkId: number;
+  tx: string;
+  paymentUrl: string;
+}
+
+/** Store configuration */
+export interface StoreConfig {
+  merchantId: number;
+  platformId: number;
+  /** Default currency for the store */
+  currency?: Currency;
+  /** Allow tips on checkout */
+  allowTips?: boolean;
+  /** Default link expiration in seconds (0 = never, default: 300 = 5min) */
+  defaultExpiresIn?: number;
+  /** Platform fee BPS for fee calculations */
+  platformFeeBps?: number;
+}
+
+// ==================== ROTATE STORE ====================
+
+export class RotateStore {
+  private sdk: RotateSDK;
+  private config: Required<StoreConfig>;
+  /** @internal Shared catalog logic */
+  private catalog: Catalog<Product, ProductInput>;
+
+  constructor(sdk: RotateSDK, config: StoreConfig) {
+    this.sdk = sdk;
+    this.config = {
+      merchantId: config.merchantId,
+      platformId: config.platformId,
+      currency: config.currency || 'USD',
+      allowTips: config.allowTips ?? false,
+      defaultExpiresIn: config.defaultExpiresIn ?? 300,
+      platformFeeBps: config.platformFeeBps ?? 0,
+    };
+    this.catalog = new Catalog<Product, ProductInput>((input) => {
+      const now = Date.now();
+      return { ...input, active: input.active ?? true, createdAt: now, updatedAt: now };
+    });
+  }
+
+  // ==================== PRODUCT CATALOG (delegated to Catalog) ====================
+
+  addProduct(input: ProductInput): Product { return this.catalog.addProduct(input); }
+  addProducts(inputs: ProductInput[]): Product[] { return this.catalog.addProducts(inputs); }
+  updateProduct(id: string, updates: Partial<ProductInput>): Product { return this.catalog.updateProduct(id, updates); }
+  removeProduct(id: string): boolean { return this.catalog.removeProduct(id); }
+  getProduct(id: string): Product | undefined { return this.catalog.getProduct(id); }
+  getProducts(filter?: {
+    category?: string; active?: boolean; search?: string;
+    minPrice?: number; maxPrice?: number;
+    sortBy?: 'name' | 'price' | 'createdAt'; sortOrder?: 'asc' | 'desc';
+    limit?: number; offset?: number;
+  }): Product[] { return this.catalog.getProducts(filter); }
+  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); }
+
+  // ==================== DISCOUNTS (delegated) ====================
+
+  addDiscount(input: DiscountInput): Discount { return this.catalog.addDiscount(input); }
+  getDiscount(code: string): Discount | undefined { return this.catalog.getDiscount(code); }
+  isDiscountValid(code: string, subtotal: number): boolean { return this.catalog.isDiscountValid(code, subtotal); }
+  useDiscount(code: string): void { this.catalog.useDiscount(code); }
+
+  // ==================== CART ====================
+
+  /** Create a new shopping cart */
+  createCart(): RotateCart {
+    return new RotateCart(this, this.sdk, this.config);
+  }
+
+  // ==================== BATCH LINK CREATION ====================
+
+  /**
+   * Create payment links for every active product in the catalog.
+   * Useful for generating a "Buy Now" link per product upfront.
+   * Processes sequentially to respect Solana transaction ordering.
+   */
+  async createLinksForAllProducts(options?: {
+    expiresIn?: number;
+    productIds?: string[];
+    concurrency?: number;
+  }): Promise<BatchLinkResult[]> {
+    const products = options?.productIds
+      ? options.productIds.map((id) => this.catalog.getProduct(id)).filter(Boolean) as Product[]
+      : this.getProducts({ active: true });
+
+    const results: BatchLinkResult[] = [];
+    const concurrency = options?.concurrency || 1; // sequential by default for Solana
+
+    // Process in batches
+    for (let i = 0; i < products.length; i += concurrency) {
+      const batch = products.slice(i, i + concurrency);
+      const batchResults = await Promise.all(
+        batch.map(async (product) => {
+          const amountMicro = BigInt(Math.floor(product.price * 1_000_000));
+          const expiresAt = options?.expiresIn
+            ? Math.floor(Date.now() / 1000) + options.expiresIn
+            : 0;
+
+          const result = await this.sdk.createLinkUsd({
+            merchantId: this.config.merchantId,
+            platformId: this.config.platformId,
+            amount: amountMicro,
+            expiresAt,
+            allowTips: this.config.allowTips,
+            allowPartial: false,
+            orderRef: product.id,
+            description: product.name,
+          });
+
+          return {
+            productId: product.id,
+            linkId: result.linkId,
+            tx: result.tx,
+            paymentUrl: this.sdk.getPaymentUrl(result.linkId),
+          };
+        })
+      );
+      results.push(...batchResults);
+    }
+
+    return results;
+  }
+
+  // ==================== SERIALIZATION ====================
+
+  /** Export the full catalog as JSON (for persistence / API) */
+  exportCatalog(): { products: Product[]; discounts: Discount[] } {
+    return {
+      products: this.catalog.exportProducts(),
+      discounts: this.catalog.exportDiscounts(),
+    };
+  }
+
+  /** Import a catalog from JSON */
+  importCatalog(data: { products: Product[]; discounts?: Discount[] }): void {
+    this.catalog.importProducts(data.products);
+    if (data.discounts) {
+      this.catalog.importDiscounts(data.discounts);
+    }
+  }
+}
+
+// ==================== ROTATE CART ====================
+
+export class RotateCart {
+  private store: RotateStore;
+  private sdk: RotateSDK;
+  private config: Required<StoreConfig>;
+  private items: Map<string, LineItem> = new Map();
+  private appliedDiscounts: string[] = [];
+  private _metadata: Record<string, string> = {};
+
+  /** @internal */
+  constructor(store: RotateStore, sdk: RotateSDK, config: Required<StoreConfig>) {
+    this.store = store;
+    this.sdk = sdk;
+    this.config = config;
+  }
+
+  // ==================== LINE ITEMS ====================
+
+  /** Add a product to the cart */
+  addItem(productId: string, quantity: number = 1): LineItem {
+    if (quantity <= 0) throw new Error('Quantity must be positive');
+
+    const product = this.store.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.store.isInStock(productId, newQty)) {
+      throw new Error(`Insufficient stock for '${productId}'`);
+    }
+
+    const item: LineItem = {
+      product,
+      quantity: newQty,
+      unitPrice: product.price,
+    };
+    this.items.set(productId, item);
+    return item;
+  }
+
+  /** Set exact quantity for a product */
+  setItemQuantity(productId: string, quantity: number): LineItem | null {
+    if (quantity <= 0) {
+      this.removeItem(productId);
+      return null;
+    }
+
+    const product = this.store.getProduct(productId);
+    if (!product) throw new Error(`Product '${productId}' not found`);
+
+    if (!this.store.isInStock(productId, quantity)) {
+      throw new Error(`Insufficient stock for '${productId}'`);
+    }
+
+    const item: LineItem = {
+      product,
+      quantity,
+      unitPrice: product.price,
+    };
+    this.items.set(productId, item);
+    return item;
+  }
+
+  /** Remove a product from the cart entirely */
+  removeItem(productId: string): boolean {
+    return this.items.delete(productId);
+  }
+
+  /** Clear all items */
+  clear(): void {
+    this.items.clear();
+    this.appliedDiscounts = [];
+    this._metadata = {};
+  }
+
+  /** Get all line items */
+  getItems(): LineItem[] {
+    return Array.from(this.items.values());
+  }
+
+  /** Check if cart is empty */
+  get isEmpty(): boolean {
+    return this.items.size === 0;
+  }
+
+  // ==================== DISCOUNTS ====================
+
+  /** Apply a discount code */
+  applyDiscount(code: string): boolean {
+    const upperCode = code.toUpperCase();
+    if (this.appliedDiscounts.includes(upperCode)) return false;
+
+    const subtotal = this.calculateSubtotal();
+    if (!this.store.isDiscountValid(upperCode, subtotal)) return false;
+
+    this.appliedDiscounts.push(upperCode);
+    return true;
+  }
+
+  /** Remove a discount code */
+  removeDiscount(code: string): boolean {
+    const idx = this.appliedDiscounts.indexOf(code.toUpperCase());
+    if (idx === -1) return false;
+    this.appliedDiscounts.splice(idx, 1);
+    return true;
+  }
+
+  // ==================== METADATA ====================
+
+  /** Attach metadata to the order (customer email, shipping address, notes, etc.) */
+  setMetadata(key: string, value: string): void {
+    this._metadata[key] = value;
+  }
+
+  getMetadata(): Record<string, string> {
+    return { ...this._metadata };
+  }
+
+  // ==================== TOTALS ====================
+
+  private calculateSubtotal(): number {
+    let subtotal = 0;
+    for (const item of this.items.values()) {
+      subtotal += item.unitPrice * item.quantity;
+    }
+    return Math.round(subtotal * 100) / 100; // round to cents
+  }
+
+  private calculateDiscountAmount(subtotal: number): number {
+    let totalDiscount = 0;
+
+    for (const code of this.appliedDiscounts) {
+      const d = this.store.getDiscount(code);
+      if (!d || !d.active) continue;
+
+      if (d.productIds && d.productIds.length > 0) {
+        // Product-specific discount
+        for (const item of this.items.values()) {
+          if (!d.productIds.includes(item.product.id)) continue;
+          const lineTotal = item.unitPrice * item.quantity;
+          if (d.type === 'percent') {
+            totalDiscount += lineTotal * (d.value / 100);
+          } else {
+            totalDiscount += Math.min(d.value, lineTotal);
+          }
+        }
+      } else {
+        // Cart-wide discount
+        if (d.type === 'percent') {
+          totalDiscount += subtotal * (d.value / 100);
+        } else {
+          totalDiscount += d.value;
+        }
+      }
+    }
+
+    return Math.min(Math.round(totalDiscount * 100) / 100, subtotal);
+  }
+
+  /** Calculate full cart totals */
+  getTotals(): CartTotals {
+    const lines: CartTotals['lines'] = [];
+    let subtotal = 0;
+    let totalQuantity = 0;
+
+    for (const item of this.items.values()) {
+      const lineTotal = Math.round(item.unitPrice * item.quantity * 100) / 100;
+      subtotal += lineTotal;
+      totalQuantity += item.quantity;
+      lines.push({
+        productId: item.product.id,
+        name: item.product.name,
+        quantity: item.quantity,
+        unitPrice: item.unitPrice,
+        lineTotal,
+      });
+    }
+
+    subtotal = Math.round(subtotal * 100) / 100;
+
+    const discountAmount = this.calculateDiscountAmount(subtotal);
+    let afterDiscount = Math.round((subtotal - discountAmount) * 100) / 100;
+    if (afterDiscount < 0) afterDiscount = 0;
+
+    // Convert to micro-units for fee calculation
+    const amountMicro = Math.floor(afterDiscount * 1_000_000);
+    const feesResult = calculateFees(amountMicro, this.config.platformFeeBps);
+
+    // Convert fees back to dollars
+    const fees = feesResult.buyerFeeShare / 1_000_000;
+    const total = Math.round((afterDiscount + fees) * 100) / 100;
+    const merchantReceives = feesResult.merchantReceives / 1_000_000;
+
+    return {
+      itemCount: this.items.size,
+      totalQuantity,
+      subtotal,
+      discountAmount,
+      afterDiscount,
+      fees: Math.round(fees * 100) / 100,
+      total: Math.round(total * 100) / 100,
+      merchantReceives: Math.round(merchantReceives * 100) / 100,
+      lines,
+    };
+  }
+
+  // ==================== CHECKOUT ====================
+
+  /**
+   * Finalize the cart and create an on-chain payment link.
+   * Returns everything needed to present the payment to the buyer.
+   */
+  async checkout(options?: {
+    /** Override expiration (seconds from now, 0 = no expiry) */
+    expiresIn?: number;
+    /** Override currency */
+    currency?: Currency;
+    /** Override tips flag */
+    allowTips?: boolean;
+    /** Custom order reference (default: auto-generated) */
+    orderRef?: string;
+    /** Custom description (default: auto-generated from cart items) */
+    description?: string;
+  }): Promise<CheckoutResult> {
+    if (this.isEmpty) throw new Error('Cart is empty');
+
+    const totals = this.getTotals();
+    if (totals.afterDiscount <= 0) throw new Error('Cart total must be greater than zero');
+
+    // Validate all items are still in stock
+    for (const item of this.items.values()) {
+      if (!this.store.isInStock(item.product.id, item.quantity)) {
+        throw new Error(`'${item.product.name}' is out of stock`);
+      }
+    }
+
+    const currency = options?.currency || this.config.currency;
+    const orderRef = options?.orderRef || `order_${Date.now()}_${Math.random().toString(36).substr(2, 6)}`;
+    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;
+
+    // Auto-generate description from cart items (e.g. "2x Logo Tee, 1x Zip Hoodie")
+    const description = options?.description || totals.lines.map(l => `${l.quantity}x ${l.name}`).join(', ');
+
+    // Convert total to micro-units
+    const amountMicro = BigInt(Math.floor(totals.afterDiscount * 1_000_000));
+
+    let result: { tx: string; linkId: number };
+
+    if (currency === 'SOL') {
+      // SOL-denominated link (amount is in lamports)
+      const solPrice = await this.sdk.getSolPrice();
+      const lamports = BigInt(Math.floor((totals.afterDiscount / solPrice) * 1_000_000_000));
+      result = await this.sdk.createLinkSol({
+        merchantId: this.config.merchantId,
+        platformId: this.config.platformId,
+        amount: lamports,
+        expiresAt,
+        allowTips,
+        allowPartial: false,
+        orderRef,
+        description,
+      });
+    } else if (currency === 'USDC' || currency === 'USDT') {
+      result = await this.sdk.createLinkToken({
+        merchantId: this.config.merchantId,
+        platformId: this.config.platformId,
+        amount: amountMicro,
+        expiresAt,
+        allowTips,
+        allowPartial: false,
+        orderRef,
+        currency,
+        description,
+      });
+    } else {
+      // USD-denominated (buyer picks SOL / USDC / USDT at pay time)
+      result = await this.sdk.createLinkUsd({
+        merchantId: this.config.merchantId,
+        platformId: this.config.platformId,
+        amount: amountMicro,
+        expiresAt,
+        allowTips,
+        allowPartial: false,
+        orderRef,
+        description,
+      });
+    }
+
+    // Reserve inventory
+    for (const item of this.items.values()) {
+      this.store.reserveInventory(item.product.id, item.quantity);
+    }
+
+    // Increment discount usage
+    for (const code of this.appliedDiscounts) {
+      this.store.useDiscount(code);
+    }
+
+    return {
+      linkId: result.linkId,
+      tx: result.tx,
+      paymentUrl: this.sdk.getPaymentUrl(result.linkId),
+      qrCodeUrl: this.sdk.getQRCodeUrl(result.linkId),
+      totals,
+      orderRef,
+      createdAt: Date.now(),
+    };
+  }
+}
+
+// ==================== EXPORTS ====================
+
+export default RotateStore;