@rotateprotocol/sdk 1.0.0

package/src/platform.ts

@@ -0,0 +1,403 @@
+/**
+ * Rotate Platform Manager — Merchant Onboarding & Platform Administration
+ *
+ * A high-level SDK layer for platform operators to onboard merchants,
+ * manage their accounts, and monitor platform-wide activity.
+ *
+ * The platform admin wallet is the signer — merchants don't need to
+ * interact with the SDK directly. The platform creates merchant accounts
+ * on their behalf, and merchants just receive payments to their wallet.
+ *
+ * @example
+ * ```ts
+ * import { RotateSDK, RotatePlatformManager } from '@rotateprotocol/sdk';
+ *
+ * const sdk = new RotateSDK({ connection, wallet });
+ *
+ * // Create a platform first (one-time setup)
+ * const { platformId } = await sdk.createPlatform({ feeBps: 500, wallet: adminWallet });
+ *
+ * // Then use the manager for ongoing operations
+ * const platform = new RotatePlatformManager(sdk, { platformId });
+ *
+ * // Onboard a single merchant
+ * const merchant = await platform.onboardMerchant({
+ *   wallet: new PublicKey('merchant-wallet-address'),
+ *   name: 'Coffee Shop',
+ * });
+ * console.log(`Merchant created: #${merchant.merchantId}`);
+ *
+ * // Bulk onboard merchants
+ * const results = await platform.onboardMerchants([
+ *   { wallet: walletA, name: 'Store A' },
+ *   { wallet: walletB, name: 'Store B' },
+ *   { wallet: walletC, name: 'Store C' },
+ * ]);
+ *
+ * // Get all merchants on the platform
+ * const merchants = await platform.getMerchants();
+ *
+ * // Get platform stats
+ * const stats = await platform.getStats();
+ * console.log(`Total merchants: ${stats.merchantCount}`);
+ * console.log(`Fee revenue: $${stats.feeRevenue.toFixed(2)}`);
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+import { PublicKey } from '@solana/web3.js';
+import RotateSDK, {
+  PaymentLink,
+  Platform,
+  Merchant,
+  PROTOCOL_FEE_BPS,
+} from './index';
+
+// ==================== TYPES ====================
+
+/** Configuration for the platform manager */
+export interface PlatformManagerConfig {
+  /** Your platform ID (from createPlatform) */
+  platformId: number;
+}
+
+/** Input for onboarding a single merchant */
+export interface OnboardMerchantInput {
+  /** The merchant's Solana wallet address (where they receive payments) */
+  wallet: PublicKey;
+  /** Optional display name for the merchant (stored locally, not on-chain) */
+  name?: string;
+  /** Optional metadata (e.g. email, store URL, category) */
+  metadata?: Record<string, string>;
+}
+
+/** Result of onboarding a merchant */
+export interface OnboardMerchantResult {
+  /** The assigned on-chain merchant ID */
+  merchantId: number;
+  /** Transaction signature */
+  tx: string;
+  /** The merchant's wallet address */
+  wallet: PublicKey;
+  /** Display name (if provided) */
+  name?: string;
+  /** Metadata (if provided) */
+  metadata?: Record<string, string>;
+}
+
+/** Result of a bulk onboarding operation */
+export interface BulkOnboardResult {
+  /** Successfully onboarded merchants */
+  succeeded: OnboardMerchantResult[];
+  /** Failed onboardings */
+  failed: Array<{
+    input: OnboardMerchantInput;
+    error: string;
+  }>;
+}
+
+/** Merchant info with on-chain and local data */
+export interface MerchantInfo {
+  /** On-chain merchant ID */
+  merchantId: number;
+  /** Platform ID this merchant belongs to */
+  platformId: number;
+  /** Merchant wallet address */
+  wallet: PublicKey;
+  /** Whether the merchant is active */
+  active: boolean;
+  /** Display name (local only) */
+  name?: string;
+  /** Metadata (local only) */
+  metadata?: Record<string, string>;
+}
+
+/** Platform-wide statistics */
+export interface PlatformStats {
+  /** Platform ID */
+  platformId: number;
+  /** Platform fee in basis points */
+  feeBps: number;
+  /** Platform fee as percentage string (e.g. "5.0%") */
+  feePercent: string;
+  /** Total merchants on the platform */
+  merchantCount: number;
+  /** Platform admin wallet */
+  adminWallet: PublicKey;
+  /** Platform payment wallet */
+  paymentWallet: PublicKey;
+  /** Whether the platform is active */
+  active: boolean;
+  /** Total payment links created (across all merchants tracked locally) */
+  totalLinks: number;
+  /** Total volume (USD) across tracked merchants */
+  totalVolume: number;
+  /** Estimated platform fee revenue */
+  feeRevenue: number;
+  /** Protocol fee (always 3%) */
+  protocolFeeBps: number;
+}
+
+// ==================== PLATFORM MANAGER ====================
+
+export class RotatePlatformManager {
+  private sdk: RotateSDK;
+  private platformId: number;
+  /** Local merchant directory (name + metadata). Persists only in memory. */
+  private merchantDirectory: Map<number, { name?: string; metadata?: Record<string, string> }> = new Map();
+
+  constructor(sdk: RotateSDK, config: PlatformManagerConfig) {
+    this.sdk = sdk;
+    this.platformId = config.platformId;
+  }
+
+  // ==================== MERCHANT ONBOARDING ====================
+
+  /**
+   * Onboard a single merchant onto the platform.
+   *
+   * The platform admin's wallet signs the transaction and pays the account
+   * creation fee (~0.001 SOL). The merchant just needs a wallet address.
+   *
+   * @param input - Merchant wallet and optional name/metadata
+   * @returns The created merchant's ID, tx, and details
+   */
+  async onboardMerchant(input: OnboardMerchantInput): Promise<OnboardMerchantResult> {
+    const { tx, merchantId } = await this.sdk.createMerchant({
+      platformId: this.platformId,
+      wallet: input.wallet,
+    });
+
+    // Store local directory info
+    if (input.name || input.metadata) {
+      this.merchantDirectory.set(merchantId, {
+        name: input.name,
+        metadata: input.metadata,
+      });
+    }
+
+    return {
+      merchantId,
+      tx,
+      wallet: input.wallet,
+      name: input.name,
+      metadata: input.metadata,
+    };
+  }
+
+  /**
+   * Bulk onboard multiple merchants in sequence.
+   *
+   * Each merchant gets its own transaction. If one fails, the rest continue.
+   * Returns both succeeded and failed results so the caller can handle retries.
+   *
+   * @param inputs - Array of merchant onboarding inputs
+   * @param options - Optional configuration
+   * @returns Succeeded and failed results
+   */
+  async onboardMerchants(
+    inputs: OnboardMerchantInput[],
+    options?: {
+      /** Called after each merchant (for progress tracking) */
+      onProgress?: (completed: number, total: number, latest: OnboardMerchantResult | null) => void;
+      /** Stop on first failure */
+      stopOnError?: boolean;
+    }
+  ): Promise<BulkOnboardResult> {
+    const succeeded: OnboardMerchantResult[] = [];
+    const failed: BulkOnboardResult['failed'] = [];
+
+    for (let i = 0; i < inputs.length; i++) {
+      try {
+        const result = await this.onboardMerchant(inputs[i]);
+        succeeded.push(result);
+        options?.onProgress?.(i + 1, inputs.length, result);
+      } catch (err: any) {
+        const errorMsg = err?.message || String(err);
+        failed.push({ input: inputs[i], error: errorMsg });
+        options?.onProgress?.(i + 1, inputs.length, null);
+
+        if (options?.stopOnError) break;
+      }
+    }
+
+    return { succeeded, failed };
+  }
+
+  // ==================== MERCHANT MANAGEMENT ====================
+
+  /**
+   * Get on-chain info for a specific merchant.
+   */
+  async getMerchant(merchantId: number): Promise<MerchantInfo | null> {
+    const merchant = await this.sdk.getMerchant(merchantId);
+    if (!merchant) return null;
+
+    const local = this.merchantDirectory.get(merchantId);
+
+    return {
+      merchantId: merchant.id,
+      platformId: merchant.platformId,
+      wallet: merchant.wallet,
+      active: merchant.active,
+      name: local?.name,
+      metadata: local?.metadata,
+    };
+  }
+
+  /**
+   * Fetch all merchants belonging to this platform.
+   *
+   * Uses `getProgramAccounts` with a `memcmp` filter on `platform_id`
+   * for efficient single-RPC retrieval instead of scanning every merchant
+   * PDA sequentially.
+   *
+   * @param options - Optional filters
+   * @returns Array of merchant info
+   */
+  async getMerchants(options?: {
+    /** Only return active merchants */
+    activeOnly?: boolean;
+    /** Maximum number of merchants to return */
+    limit?: number;
+  }): Promise<MerchantInfo[]> {
+    const onChainMerchants = await this.sdk.getMerchantsByPlatform(
+      this.platformId,
+      options?.activeOnly ?? false,
+    );
+
+    let results: MerchantInfo[] = onChainMerchants.map((merchant) => {
+      const local = this.merchantDirectory.get(merchant.id);
+      return {
+        merchantId: merchant.id,
+        platformId: merchant.platformId,
+        wallet: merchant.wallet,
+        active: merchant.active,
+        name: local?.name,
+        metadata: local?.metadata,
+      };
+    });
+
+    if (options?.limit) {
+      results = results.slice(0, options.limit);
+    }
+
+    return results;
+  }
+
+  /**
+   * Update the local directory entry for a merchant (name/metadata).
+   * Does NOT modify on-chain data.
+   */
+  setMerchantInfo(merchantId: number, info: { name?: string; metadata?: Record<string, string> }): void {
+    const existing = this.merchantDirectory.get(merchantId) || {};
+    this.merchantDirectory.set(merchantId, {
+      name: info.name ?? existing.name,
+      metadata: info.metadata ?? existing.metadata,
+    });
+  }
+
+  // ==================== PLATFORM INFO ====================
+
+  /**
+   * Get the on-chain platform account data.
+   */
+  async getPlatform(): Promise<Platform | null> {
+    return this.sdk.getPlatform(this.platformId);
+  }
+
+  /**
+   * Update platform fee rate and/or active status.
+   * Only the platform admin wallet can call this.
+   *
+   * @param feeBps - New fee in basis points (0-600)
+   * @param active - Whether the platform is active
+   * @param newWallet - Optional new wallet for fee collection (defaults to current)
+   */
+  async updatePlatform(feeBps: number, active: boolean = true, newWallet?: PublicKey): Promise<string> {
+    const platform = await this.getPlatform();
+    if (!platform) throw new Error(`Platform #${this.platformId} not found`);
+
+    return this.sdk.updatePlatform({
+      platformId: this.platformId,
+      feeBps,
+      active,
+      newWallet: newWallet || platform.wallet,
+    });
+  }
+
+  /**
+   * Get platform-wide statistics.
+   *
+   * Uses `getProgramAccounts` for efficient merchant counting instead of
+   * scanning every merchant ID sequentially.
+   */
+  async getStats(): Promise<PlatformStats> {
+    const platform = await this.getPlatform();
+    if (!platform) throw new Error(`Platform #${this.platformId} not found`);
+
+    // Single RPC call to get all merchants on this platform
+    const merchants = await this.sdk.getMerchantsByPlatform(this.platformId);
+
+    return {
+      platformId: this.platformId,
+      feeBps: platform.feeBps,
+      feePercent: (platform.feeBps / 100).toFixed(1) + '%',
+      merchantCount: merchants.length,
+      adminWallet: platform.admin,
+      paymentWallet: platform.wallet,
+      active: platform.active,
+      totalLinks: 0, // Would require scanning all links; 0 as placeholder
+      totalVolume: 0,
+      feeRevenue: 0,
+      protocolFeeBps: PROTOCOL_FEE_BPS,
+    };
+  }
+
+  // ==================== CONVENIENCE METHODS ====================
+
+  /**
+   * Generate a checkout URL for a merchant's payment link.
+   */
+  getCheckoutUrl(linkId: number): string {
+    return this.sdk.getPaymentUrl(linkId);
+  }
+
+  /**
+   * Get the platform ID.
+   */
+  getPlatformId(): number {
+    return this.platformId;
+  }
+
+  // ==================== DIRECTORY PERSISTENCE ====================
+
+  /**
+   * Export the local merchant directory as JSON.
+   * Use this to persist merchant names/metadata to your database.
+   */
+  exportDirectory(): Array<{ merchantId: number; name?: string; metadata?: Record<string, string> }> {
+    const entries: Array<{ merchantId: number; name?: string; metadata?: Record<string, string> }> = [];
+    for (const [merchantId, info] of this.merchantDirectory) {
+      entries.push({ merchantId, ...info });
+    }
+    return entries;
+  }
+
+  /**
+   * Import a previously exported merchant directory.
+   */
+  importDirectory(entries: Array<{ merchantId: number; name?: string; metadata?: Record<string, string> }>): void {
+    for (const entry of entries) {
+      this.merchantDirectory.set(entry.merchantId, {
+        name: entry.name,
+        metadata: entry.metadata,
+      });
+    }
+  }
+}
+
+// ==================== EXPORTS ====================
+
+export default RotatePlatformManager;