@smoothsend/sdk 1.0.0

package/dist/core/SmoothSendSDK.d.ts

@@ -0,0 +1,261 @@
+import { SupportedChain, ChainEcosystem, TransferRequest, SignedTransferData, TransferResult, SmoothSendConfig, EventListener, HealthResponse, FeeEstimate, UsageMetadata } from '../types';
+export declare class SmoothSendSDK {
+    private adapters;
+    private eventListeners;
+    private config;
+    private keyType;
+    private hasWarnedAboutSecretKey;
+    constructor(config: SmoothSendConfig);
+    /**
+     * Detect key type from API key prefix
+     * Supports pk_nogas_* (public), sk_nogas_* (secret), and no_gas_* (legacy)
+     */
+    private detectKeyType;
+    /**
+     * Check if running in browser environment
+     * Used for conditional warnings and Origin header logic
+     */
+    private isBrowserEnvironment;
+    /**
+     * Warn if secret key is used in browser environment
+     * Only warns once per SDK instance
+     */
+    private warnIfSecretKeyInBrowser;
+    /**
+     * Determine if Origin header should be included in requests
+     * Include Origin header only for public keys in browser environment
+     */
+    private shouldIncludeOrigin;
+    /**
+     * Get or create adapter for a specific chain on-demand
+     */
+    private getOrCreateAdapter;
+    addEventListener(listener: EventListener): void;
+    removeEventListener(listener: EventListener): void;
+    private emitEvent;
+    estimateFee(request: TransferRequest): Promise<FeeEstimate & {
+        metadata?: UsageMetadata;
+    }>;
+    executeGaslessTransfer(signedData: SignedTransferData): Promise<TransferResult>;
+    /**
+     * Convenience method for complete transfer flow
+     * Combines estimateFee and executeGaslessTransfer into a single call
+     *
+     * @param request Transfer request with from, to, token, amount, chain
+     * @param wallet Wallet instance that can build and sign transactions
+     * @returns Transfer result with transaction hash and usage metadata
+     *
+     * Note: The wallet parameter should have methods:
+     * - buildTransaction(params): Build transaction from parameters
+     * - signTransaction(transaction): Sign and serialize transaction
+     *
+     * The wallet's signTransaction should return an object with:
+     * - transactionBytes: number[] - Serialized transaction
+     * - authenticatorBytes: number[] - Serialized authenticator
+     */
+    transfer(request: TransferRequest, wallet: {
+        buildTransaction: (params: any) => Promise<any>;
+        signTransaction: (transaction: any) => Promise<{
+            transactionBytes: number[];
+            authenticatorBytes: number[];
+        }>;
+    }): Promise<TransferResult>;
+    /**
+     * Get transaction status for a specific transaction
+     * Routes through proxy to chain-specific status endpoint
+     *
+     * @param chain Chain where the transaction was executed
+     * @param txHash Transaction hash to query
+     * @returns Transaction status information
+     * @throws SmoothSendError if chain is not supported or status check fails
+     *
+     * @example
+     * ```typescript
+     * const status = await sdk.getTransactionStatus('aptos-testnet', '0x123...');
+     * console.log('Transaction status:', status);
+     * ```
+     */
+    getTransactionStatus(chain: SupportedChain, txHash: string): Promise<any>;
+    validateAddress(chain: SupportedChain, address: string): boolean;
+    validateAmount(chain: SupportedChain, amount: string): boolean;
+    /**
+     * Check proxy worker health status
+     * Routes directly to proxy's /health endpoint (not chain-specific)
+     *
+     * @returns Health response with status, version, and timestamp
+     * @throws NetworkError if proxy is unavailable
+     * @throws SmoothSendError for other errors
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   const health = await sdk.getHealth();
+     *   console.log('Proxy status:', health.status);
+     *   console.log('Version:', health.version);
+     * } catch (error) {
+     *   if (error instanceof NetworkError) {
+     *     console.error('Proxy unavailable. Please retry later.');
+     *   }
+     * }
+     * ```
+     */
+    getHealth(): Promise<HealthResponse>;
+    /**
+     * Get list of supported chains (static list)
+     * For dynamic list from proxy, use getSupportedChainsFromProxy()
+     *
+     * @returns Array of supported chain identifiers
+     *
+     * @example
+     * ```typescript
+     * const chains = sdk.getSupportedChains();
+     * console.log('Supported chains:', chains);
+     * // Output: ['aptos-testnet', 'aptos-mainnet']
+     * ```
+     */
+    getSupportedChains(): SupportedChain[];
+    /**
+     * Get list of supported chains from proxy worker (dynamic)
+     * Queries the proxy for the current list of supported chains
+     *
+     * @returns Promise with array of chain information including status
+     * @throws SmoothSendError if unable to fetch chains from proxy
+     *
+     * @example
+     * ```typescript
+     * const chains = await sdk.getSupportedChainsFromProxy();
+     * chains.forEach(chain => {
+     *   console.log(`${chain.name} (${chain.id}): ${chain.status}`);
+     * });
+     * ```
+     */
+    getSupportedChainsFromProxy(): Promise<Array<{
+        id: string;
+        name: string;
+        ecosystem: string;
+        network: string;
+        status: string;
+    }>>;
+    /**
+     * Check if a specific chain is currently supported
+     *
+     * @param chain Chain identifier to check
+     * @returns true if chain is supported, false otherwise
+     *
+     * @example
+     * ```typescript
+     * if (sdk.isChainSupported('aptos-testnet')) {
+     *   console.log('Aptos testnet is supported');
+     * } else {
+     *   console.log('Chain not supported');
+     * }
+     * ```
+     */
+    isChainSupported(chain: string): boolean;
+    /**
+     * Check health status of a specific chain's relayer
+     * Routes through proxy to chain-specific health endpoint
+     *
+     * @param chain Chain identifier to check
+     * @returns Health response for the specific chain
+     * @throws SmoothSendError if chain is not supported or health check fails
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   const health = await sdk.getChainHealth('aptos-testnet');
+     *   console.log('Aptos testnet status:', health.status);
+     * } catch (error) {
+     *   console.error('Chain health check failed:', error.message);
+     * }
+     * ```
+     */
+    getChainHealth(chain: SupportedChain): Promise<HealthResponse>;
+    /**
+     * Get current usage statistics without making a transfer
+     * Makes a lightweight health check request to retrieve usage metadata
+     *
+     * @returns Usage metadata with rate limit and monthly usage information
+     * @throws Error if unable to retrieve usage stats
+     *
+     * @example
+     * ```typescript
+     * const usage = await sdk.getUsageStats();
+     * console.log('Rate limit:', usage.rateLimit);
+     * console.log('Monthly usage:', usage.monthly);
+     * console.log('Request ID:', usage.requestId);
+     *
+     * // Check if approaching limits
+     * if (parseInt(usage.rateLimit.remaining) < 2) {
+     *   console.warn('Approaching rate limit!');
+     * }
+     * ```
+     */
+    getUsageStats(): Promise<UsageMetadata>;
+    /**
+     * Extract request ID from a transfer result for debugging and support
+     *
+     * @param result Transfer result from executeGaslessTransfer or transfer
+     * @returns Request ID if available, undefined otherwise
+     *
+     * @example
+     * ```typescript
+     * const result = await sdk.executeGaslessTransfer(signedData);
+     * const requestId = sdk.getRequestId(result);
+     * if (requestId) {
+     *   console.log('Request ID for support:', requestId);
+     * }
+     * ```
+     */
+    getRequestId(result: TransferResult): string | undefined;
+    /**
+     * Check if approaching rate limit based on transfer result metadata
+     *
+     * @param result Transfer result with metadata
+     * @param threshold Percentage threshold (0-100) to consider as "approaching" (default: 20)
+     * @returns true if remaining requests are below threshold percentage
+     *
+     * @example
+     * ```typescript
+     * const result = await sdk.transfer(request, wallet);
+     * if (sdk.isApproachingRateLimit(result)) {
+     *   console.warn('Approaching rate limit, consider slowing down requests');
+     * }
+     * ```
+     */
+    isApproachingRateLimit(result: TransferResult, threshold?: number): boolean;
+    /**
+     * Check if approaching monthly usage limit based on transfer result metadata
+     *
+     * @param result Transfer result with metadata
+     * @param threshold Percentage threshold (0-100) to consider as "approaching" (default: 90)
+     * @returns true if monthly usage is above threshold percentage
+     *
+     * @example
+     * ```typescript
+     * const result = await sdk.transfer(request, wallet);
+     * if (sdk.isApproachingMonthlyLimit(result)) {
+     *   console.warn('Approaching monthly limit, consider upgrading plan');
+     * }
+     * ```
+     */
+    isApproachingMonthlyLimit(result: TransferResult, threshold?: number): boolean;
+    /**
+     * Check if a chain belongs to a specific ecosystem
+     */
+    getChainEcosystem(chain: SupportedChain): ChainEcosystem;
+    /**
+     * Get list of supported chains (static method)
+     * Can be called without instantiating the SDK
+     *
+     * @returns Array of supported chain identifiers
+     *
+     * @example
+     * ```typescript
+     * const chains = SmoothSendSDK.getSupportedChains();
+     * console.log('Supported chains:', chains);
+     * ```
+     */
+    static getSupportedChains(): SupportedChain[];
+}
+//# sourceMappingURL=SmoothSendSDK.d.ts.map

package/dist/core/SmoothSendSDK.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SmoothSendSDK.d.ts","sourceRoot":"","sources":["../../src/core/SmoothSendSDK.ts"],"names":[],"mappings":"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"}