@swarmvault/sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,443 @@
+/**
+ * Swarm Vault SDK Types
+ */
+interface User {
+    id: string;
+    walletAddress: string;
+    twitterId: string | null;
+    twitterUsername: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+interface Swarm {
+    id: string;
+    name: string;
+    description: string;
+    createdAt: string;
+    updatedAt: string;
+    manager?: {
+        id: string;
+        walletAddress: string;
+        twitterUsername: string | null;
+    };
+    memberCount?: number;
+    isManager?: boolean;
+}
+interface SwarmMember {
+    id: string;
+    swarmId: string;
+    userId: string;
+    agentWalletAddress: string;
+    status: "ACTIVE" | "LEFT";
+    joinedAt: string;
+    user?: {
+        id: string;
+        walletAddress: string;
+    };
+}
+type TransactionStatus = "PENDING" | "PROCESSING" | "COMPLETED" | "FAILED";
+type TransactionTargetStatus = "PENDING" | "SUBMITTED" | "CONFIRMED" | "FAILED";
+interface Transaction {
+    id: string;
+    swarmId: string;
+    status: TransactionStatus;
+    template: TransactionTemplate;
+    createdAt: string;
+    updatedAt: string;
+    targets?: TransactionTarget[];
+}
+interface TransactionTarget {
+    id: string;
+    transactionId: string;
+    membershipId: string;
+    userOpHash: string | null;
+    txHash: string | null;
+    status: TransactionTargetStatus;
+    error: string | null;
+    createdAt: string;
+    updatedAt: string;
+    membership?: {
+        agentWalletAddress: string;
+        user?: {
+            walletAddress: string;
+        };
+    };
+}
+interface ABITransactionTemplate {
+    mode: "abi";
+    contractAddress: string;
+    abi: unknown[];
+    functionName: string;
+    args: unknown[];
+    value: string;
+}
+interface RawTransactionTemplate {
+    mode: "raw";
+    contractAddress: string;
+    data: string;
+    value: string;
+}
+type TransactionTemplate = ABITransactionTemplate | RawTransactionTemplate;
+interface SwapPreviewParams {
+    /** Token address to sell (use 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE for native ETH) */
+    sellToken: string;
+    /** Token address to buy */
+    buyToken: string;
+    /** Percentage of token balance to sell (1-100, default 100) */
+    sellPercentage?: number;
+    /** Slippage tolerance percentage (default 1) */
+    slippagePercentage?: number;
+}
+interface SwapExecuteParams extends SwapPreviewParams {
+}
+interface SwapMemberPreview {
+    membershipId: string;
+    userId: string;
+    userWalletAddress: string;
+    agentWalletAddress: string;
+    sellAmount: string;
+    buyAmount: string;
+    feeAmount?: string;
+    estimatedPriceImpact?: number;
+    sources?: string[];
+    error?: string;
+}
+interface SwapFeeInfo {
+    bps: number;
+    percentage: string;
+    recipientAddress: string;
+}
+interface SwapPreviewResult {
+    sellToken: string;
+    buyToken: string;
+    sellPercentage: number;
+    slippagePercentage: number;
+    members: SwapMemberPreview[];
+    totalSellAmount: string;
+    totalBuyAmount: string;
+    totalFeeAmount?: string;
+    successCount: number;
+    errorCount: number;
+    fee: SwapFeeInfo | null;
+}
+interface SwapExecuteResult {
+    transactionId: string;
+    status: "PENDING";
+    memberCount: number;
+    message: string;
+    fee: SwapFeeInfo | null;
+}
+interface TokenInfo {
+    address: string;
+    symbol: string;
+    name: string;
+    decimals: number;
+    logoUrl?: string;
+}
+interface TokenHolding extends TokenInfo {
+    totalBalance: string;
+    holderCount: number;
+}
+interface SwarmHoldings {
+    ethBalance: string;
+    tokens: TokenHolding[];
+    memberCount: number;
+    commonTokens: TokenInfo[];
+}
+interface ApiResponse<T> {
+    success: boolean;
+    data?: T;
+    error?: string;
+    errorCode?: string;
+    details?: unknown;
+}
+interface SwarmVaultClientOptions {
+    /** Base URL of the Swarm Vault API (default: https://api.swarmvault.xyz) */
+    baseUrl?: string;
+    /** API key for authentication (starts with 'svk_') */
+    apiKey?: string;
+    /** JWT token for authentication (alternative to API key) */
+    jwt?: string;
+    /** Custom fetch function (for testing or custom implementations) */
+    fetch?: (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+}
+interface WaitForTransactionOptions {
+    /** Maximum time to wait in milliseconds (default: 300000 = 5 minutes) */
+    timeoutMs?: number;
+    /** Polling interval in milliseconds (default: 3000 = 3 seconds) */
+    pollIntervalMs?: number;
+    /** Callback called on each poll with current status */
+    onPoll?: (transaction: Transaction) => void;
+}
+declare class SwarmVaultError extends Error {
+    readonly errorCode?: string;
+    readonly statusCode?: number;
+    readonly details?: unknown;
+    constructor(message: string, options?: {
+        errorCode?: string;
+        statusCode?: number;
+        details?: unknown;
+    });
+}
+/** Native ETH address used in swap APIs */
+declare const NATIVE_ETH_ADDRESS = "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE";
+/** Common token addresses on Base Mainnet */
+declare const BASE_MAINNET_TOKENS: {
+    readonly ETH: "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE";
+    readonly WETH: "0x4200000000000000000000000000000000000006";
+    readonly USDC: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
+    readonly DAI: "0x50c5725949A6F0c72E6C4a641F24049A917DB0Cb";
+    readonly USDbC: "0xd9aAEc86B65D86f6A7B5B1b0c42FFA531710b6CA";
+    readonly cbETH: "0x2Ae3F1Ec7F1F5012CFEab0185bfc7aa3cf0DEc22";
+};
+/** Common token addresses on Base Sepolia (testnet) */
+declare const BASE_SEPOLIA_TOKENS: {
+    readonly ETH: "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE";
+    readonly WETH: "0x4200000000000000000000000000000000000006";
+    readonly USDC: "0x036CbD53842c5426634e7929541eC2318f3dCF7e";
+};
+
+/**
+ * Swarm Vault SDK Client
+ *
+ * A TypeScript client for the Swarm Vault API, enabling managers to execute
+ * swaps and transactions on behalf of their swarm members.
+ *
+ * @example
+ * ```typescript
+ * import { SwarmVaultClient } from '@swarmvault/sdk';
+ *
+ * const client = new SwarmVaultClient({
+ *   apiKey: 'svk_your_api_key_here',
+ * });
+ *
+ * // Get swarm holdings
+ * const holdings = await client.getSwarmHoldings('swarm-id');
+ *
+ * // Execute a swap
+ * const result = await client.executeSwap('swarm-id', {
+ *   sellToken: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913', // USDC
+ *   buyToken: '0x4200000000000000000000000000000000000006',   // WETH
+ *   sellPercentage: 50,
+ * });
+ *
+ * // Wait for completion
+ * const tx = await client.waitForTransaction(result.transactionId);
+ * ```
+ */
+
+declare class SwarmVaultClient {
+    private baseUrl;
+    private apiKey?;
+    private jwt?;
+    private fetchFn;
+    /**
+     * Create a new Swarm Vault client.
+     *
+     * @param options - Client configuration options
+     * @param options.baseUrl - Base URL of the API (default: https://api.swarmvault.xyz)
+     * @param options.apiKey - API key for authentication (recommended)
+     * @param options.jwt - JWT token for authentication (alternative to API key)
+     */
+    constructor(options?: SwarmVaultClientOptions);
+    /**
+     * Set the API key for authentication.
+     * API keys start with 'svk_' and can be generated in the Swarm Vault settings.
+     *
+     * @param apiKey - The API key
+     */
+    setApiKey(apiKey: string): void;
+    /**
+     * Set the JWT token for authentication.
+     * JWTs are obtained through the SIWE login flow.
+     *
+     * @param jwt - The JWT token
+     */
+    setJwt(jwt: string): void;
+    /**
+     * Get the currently authenticated user.
+     *
+     * @returns The authenticated user
+     * @throws {SwarmVaultError} If not authenticated or request fails
+     */
+    getMe(): Promise<User>;
+    /**
+     * List all swarms. Returns public swarms for unauthenticated requests,
+     * or includes management status for authenticated requests.
+     *
+     * @returns Array of swarms
+     */
+    listSwarms(): Promise<Swarm[]>;
+    /**
+     * Get details of a specific swarm.
+     *
+     * @param swarmId - The swarm ID
+     * @returns Swarm details
+     * @throws {SwarmVaultError} If swarm not found
+     */
+    getSwarm(swarmId: string): Promise<Swarm>;
+    /**
+     * Get members of a swarm.
+     * **Manager only** - requires authentication as a swarm manager.
+     *
+     * @param swarmId - The swarm ID
+     * @returns Array of swarm members
+     * @throws {SwarmVaultError} If not authorized or swarm not found
+     */
+    getSwarmMembers(swarmId: string): Promise<SwarmMember[]>;
+    /**
+     * Get aggregate token holdings across all swarm members.
+     * **Manager only** - requires authentication as a swarm manager.
+     *
+     * @param swarmId - The swarm ID
+     * @returns Aggregated holdings with ETH balance, token balances, and common tokens
+     * @throws {SwarmVaultError} If not authorized or swarm not found
+     */
+    getSwarmHoldings(swarmId: string): Promise<SwarmHoldings>;
+    /**
+     * Preview a swap for all swarm members without executing it.
+     * **Manager only** - requires authentication as a swarm manager.
+     *
+     * Use this to see expected amounts before executing a swap.
+     *
+     * @param swarmId - The swarm ID
+     * @param params - Swap parameters
+     * @param params.sellToken - Token address to sell (use NATIVE_ETH_ADDRESS for ETH)
+     * @param params.buyToken - Token address to buy
+     * @param params.sellPercentage - Percentage of balance to sell (1-100, default 100)
+     * @param params.slippagePercentage - Slippage tolerance (default 1%)
+     * @returns Preview with per-member amounts and totals
+     *
+     * @example
+     * ```typescript
+     * const preview = await client.previewSwap('swarm-id', {
+     *   sellToken: BASE_MAINNET_TOKENS.USDC,
+     *   buyToken: BASE_MAINNET_TOKENS.WETH,
+     *   sellPercentage: 50,
+     *   slippagePercentage: 1,
+     * });
+     *
+     * console.log(`Total sell: ${preview.totalSellAmount}`);
+     * console.log(`Expected buy: ${preview.totalBuyAmount}`);
+     * console.log(`Success: ${preview.successCount}, Errors: ${preview.errorCount}`);
+     * ```
+     */
+    previewSwap(swarmId: string, params: SwapPreviewParams): Promise<SwapPreviewResult>;
+    /**
+     * Execute a swap for all swarm members.
+     * **Manager only** - requires authentication as a swarm manager.
+     *
+     * The swap is executed asynchronously. Use `waitForTransaction` to wait for completion.
+     *
+     * A platform fee (default 0.5%) is deducted from the buy token amount.
+     *
+     * @param swarmId - The swarm ID
+     * @param params - Swap parameters
+     * @param params.sellToken - Token address to sell
+     * @param params.buyToken - Token address to buy
+     * @param params.sellPercentage - Percentage of balance to sell (1-100, default 100)
+     * @param params.slippagePercentage - Slippage tolerance (default 1%)
+     * @returns Transaction ID and status
+     *
+     * @example
+     * ```typescript
+     * // Execute swap
+     * const result = await client.executeSwap('swarm-id', {
+     *   sellToken: BASE_MAINNET_TOKENS.USDC,
+     *   buyToken: BASE_MAINNET_TOKENS.WETH,
+     *   sellPercentage: 50,
+     * });
+     *
+     * console.log(`Transaction started: ${result.transactionId}`);
+     *
+     * // Wait for completion
+     * const tx = await client.waitForTransaction(result.transactionId, {
+     *   onPoll: (t) => console.log(`Status: ${t.status}`),
+     * });
+     *
+     * console.log(`Transaction ${tx.status}`);
+     * ```
+     */
+    executeSwap(swarmId: string, params: SwapExecuteParams): Promise<SwapExecuteResult>;
+    /**
+     * Execute a raw transaction template for all swarm members.
+     * **Manager only** - requires authentication as a swarm manager.
+     *
+     * This is an advanced method for custom transactions. For swaps, prefer `executeSwap`.
+     *
+     * @param swarmId - The swarm ID
+     * @param template - Transaction template (ABI mode or raw calldata mode)
+     * @returns Transaction ID and status
+     *
+     * @example
+     * ```typescript
+     * // ABI mode example - transfer tokens
+     * const result = await client.executeTransaction('swarm-id', {
+     *   mode: 'abi',
+     *   contractAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
+     *   abi: [{
+     *     name: 'transfer',
+     *     type: 'function',
+     *     inputs: [
+     *       { name: 'to', type: 'address' },
+     *       { name: 'amount', type: 'uint256' },
+     *     ],
+     *     outputs: [{ type: 'bool' }],
+     *   }],
+     *   functionName: 'transfer',
+     *   args: ['0xRecipient', '{{percentage:tokenBalance:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913:50}}'],
+     *   value: '0',
+     * });
+     * ```
+     */
+    executeTransaction(swarmId: string, template: TransactionTemplate): Promise<{
+        transactionId: string;
+        status: string;
+    }>;
+    /**
+     * List transactions for a swarm.
+     *
+     * @param swarmId - The swarm ID
+     * @returns Array of transactions
+     */
+    listTransactions(swarmId: string): Promise<Transaction[]>;
+    /**
+     * Get details of a specific transaction, including per-member status.
+     *
+     * @param transactionId - The transaction ID
+     * @returns Transaction details with targets
+     */
+    getTransaction(transactionId: string): Promise<Transaction>;
+    /**
+     * Wait for a transaction to complete.
+     *
+     * Polls the transaction status until it reaches COMPLETED or FAILED,
+     * or until the timeout is reached.
+     *
+     * @param transactionId - The transaction ID
+     * @param options - Wait options
+     * @param options.timeoutMs - Maximum wait time (default 5 minutes)
+     * @param options.pollIntervalMs - Polling interval (default 3 seconds)
+     * @param options.onPoll - Callback called on each poll
+     * @returns The completed transaction
+     * @throws {SwarmVaultError} If timeout is reached or transaction fails
+     *
+     * @example
+     * ```typescript
+     * const tx = await client.waitForTransaction(transactionId, {
+     *   timeoutMs: 60000, // 1 minute
+     *   pollIntervalMs: 2000, // 2 seconds
+     *   onPoll: (t) => {
+     *     const confirmed = t.targets?.filter(t => t.status === 'CONFIRMED').length ?? 0;
+     *     const total = t.targets?.length ?? 0;
+     *     console.log(`Progress: ${confirmed}/${total}`);
+     *   },
+     * });
+     * ```
+     */
+    waitForTransaction(transactionId: string, options?: WaitForTransactionOptions): Promise<Transaction>;
+    private request;
+    private sleep;
+}
+
+export { type ABITransactionTemplate, type ApiResponse, BASE_MAINNET_TOKENS, BASE_SEPOLIA_TOKENS, NATIVE_ETH_ADDRESS, type RawTransactionTemplate, type SwapExecuteParams, type SwapExecuteResult, type SwapFeeInfo, type SwapMemberPreview, type SwapPreviewParams, type SwapPreviewResult, type Swarm, type SwarmHoldings, type SwarmMember, SwarmVaultClient, type SwarmVaultClientOptions, SwarmVaultError, type TokenHolding, type TokenInfo, type Transaction, type TransactionStatus, type TransactionTarget, type TransactionTargetStatus, type TransactionTemplate, type User, type WaitForTransactionOptions };