@0xkaleab/sdk-js 0.2.7

package/dist/types/internal/http.d.ts

@@ -0,0 +1,213 @@
+/**
+ * Platform-agnostic HTTP client for the Internal Layer.
+ * Supports Node.js (undici) and browser (native fetch) environments.
+ *
+ * Features:
+ * - Automatic retries with exponential backoff
+ * - Configurable timeouts via AbortController
+ * - Keep-alive connections (via undici in Node.js)
+ * - Context-rich error handling
+ * - JSON request/response handling
+ *
+ * @module internal/http
+ */
+/**
+ * HTTP client configuration options
+ */
+export interface HttpClientConfig {
+    /** Base URL for all requests */
+    baseUrl: string;
+    /** Default headers to include in all requests */
+    headers?: Record<string, string>;
+    /** Request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+    /** Retry configuration */
+    retry?: RetryConfig;
+}
+/**
+ * Retry configuration options
+ */
+export interface RetryConfig {
+    /** Maximum number of retry attempts (default: 3) */
+    maxAttempts?: number;
+    /** Initial delay in milliseconds before first retry (default: 1000) */
+    initialDelay?: number;
+    /** Maximum delay in milliseconds between retries (default: 30000) */
+    maxDelay?: number;
+    /** Backoff multiplier for exponential backoff (default: 2) */
+    backoffMultiplier?: number;
+    /** HTTP status codes that should trigger a retry (default: [408, 429, 500, 502, 503, 504]) */
+    retryableStatusCodes?: number[];
+}
+/**
+ * HTTP error with context information
+ *
+ * Provides detailed error information including HTTP status, endpoint,
+ * and whether the error is retryable.
+ */
+export declare class HttpError extends Error {
+    readonly statusCode: number;
+    readonly endpoint: string;
+    readonly retryable: boolean;
+    readonly responseBody?: unknown | undefined;
+    /**
+     * Create a new HttpError
+     *
+     * @param message - Error message
+     * @param statusCode - HTTP status code (0 for network/timeout errors)
+     * @param endpoint - The endpoint that failed
+     * @param retryable - Whether this error should trigger a retry
+     * @param responseBody - Optional response body for debugging
+     */
+    constructor(message: string, statusCode: number, endpoint: string, retryable: boolean, responseBody?: unknown | undefined);
+}
+/**
+ * Request options for individual HTTP requests
+ */
+export interface RequestOptions {
+    /** Query parameters to append to the URL */
+    params?: Record<string, string | number | boolean>;
+    /** Additional headers (merged with default headers) */
+    headers?: Record<string, string>;
+    /** Request timeout in milliseconds (overrides default) */
+    timeout?: number;
+    /** Disable automatic retries for this request */
+    noRetry?: boolean;
+    /** External AbortSignal to cancel the request */
+    signal?: AbortSignal;
+}
+export declare class HttpClient {
+    private readonly config;
+    private fetchImpl?;
+    /**
+     * Create a new HttpClient
+     *
+     * @param config - HTTP client configuration
+     */
+    constructor(config: HttpClientConfig);
+    /**
+     * Get the base URL for this client
+     *
+     * @returns The base URL
+     */
+    get baseUrl(): string;
+    /**
+     * Get the fetch implementation (lazy initialization)
+     * Uses undici in Node.js, native fetch in browsers
+     */
+    private getFetch;
+    /**
+     * Perform a GET request
+     *
+     * @param path - Request path (relative to baseUrl)
+     * @param options - Request options
+     * @returns Response data
+     * @throws {HttpError} If the request fails
+     */
+    get<T = unknown>(path: string, options?: RequestOptions): Promise<T>;
+    /**
+     * Perform a POST request
+     *
+     * @param path - Request path (relative to baseUrl)
+     * @param body - Request body (will be JSON stringified)
+     * @param options - Request options
+     * @returns Response data
+     * @throws {HttpError} If the request fails
+     */
+    post<T = unknown>(path: string, body?: unknown, options?: RequestOptions): Promise<T>;
+    /**
+     * Perform a PUT request
+     *
+     * @param path - Request path (relative to baseUrl)
+     * @param body - Request body (will be JSON stringified)
+     * @param options - Request options
+     * @returns Response data
+     * @throws {HttpError} If the request fails
+     */
+    put<T = unknown>(path: string, body?: unknown, options?: RequestOptions): Promise<T>;
+    /**
+     * Perform a DELETE request
+     *
+     * @param path - Request path (relative to baseUrl)
+     * @param options - Request options
+     * @returns Response data
+     * @throws {HttpError} If the request fails
+     */
+    delete<T = unknown>(path: string, options?: RequestOptions): Promise<T>;
+    /**
+     * Perform a PATCH request
+     *
+     * @param path - Request path (relative to baseUrl)
+     * @param body - Request body (will be JSON stringified)
+     * @param options - Request options
+     * @returns Response data
+     * @throws {HttpError} If the request fails
+     */
+    patch<T = unknown>(path: string, body?: unknown, options?: RequestOptions): Promise<T>;
+    /**
+     * Perform an HTTP request with streaming response support
+     *
+     * Returns the raw Response object for streaming or custom handling.
+     * The caller is responsible for reading and closing the response body.
+     *
+     * @param method - HTTP method
+     * @param path - Request path
+     * @param body - Request body
+     * @param options - Request options
+     * @returns Raw Response object
+     * @throws {HttpError} If the request fails
+     */
+    requestRaw(method: string, path: string, body?: unknown, options?: RequestOptions): Promise<Response>;
+    /**
+     * Perform an HTTP request
+     *
+     * @param method - HTTP method
+     * @param path - Request path
+     * @param body - Request body
+     * @param options - Request options
+     * @returns Response data
+     */
+    private request;
+    /**
+     * Execute a request with timeout support
+     *
+     * @param makeRequest - Function that performs the request
+     * @param url - Request URL
+     * @param timeout - Timeout in milliseconds
+     * @param externalSignal - External abort signal
+     * @returns Response data
+     */
+    private executeWithTimeout;
+    /**
+     * Execute a request with retry logic and exponential backoff
+     *
+     * @param makeRequest - Function that performs the request
+     * @param url - Request URL
+     * @param timeout - Timeout in milliseconds
+     * @param externalSignal - External abort signal
+     * @returns Response data
+     */
+    private executeWithRetry;
+    /**
+     * Handle HTTP response and parse body
+     *
+     * @param response - Fetch Response object
+     * @param url - Request URL
+     * @returns Parsed response data
+     */
+    private handleResponse;
+    /**
+     * Build full URL from path and query parameters
+     *
+     * @param path - Request path
+     * @param params - Query parameters
+     * @returns Full URL
+     */
+    private buildUrl;
+    /**
+     * Sleep for a specified duration
+     *
+     * @param ms - Duration in milliseconds
+     */
+    private sleep;
+}

package/dist/types/internal/zstd.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Compress a string using ZSTD compression
+ * @param data - The string to compress
+ * @returns The compressed data as a Uint8Array
+ */
+export declare function compress(data: string): Promise<Uint8Array>;

package/dist/types/types/snapi.gen.d.ts

@@ -0,0 +1,289 @@
+/**
+ * This file was auto-generated by openapi-typescript.
+ * Do not make direct changes to the file.
+ */
+export interface paths {
+    "/api/v1/actions/cascade": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Start an action */
+        post: operations["startCascade"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/v1/actions/cascade/{action_id}/downloads": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Request Cascade Download */
+        post: operations["requestCascadeDownload"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/v1/actions/cascade/tasks/{task_id}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Get Cascade Task */
+        get: operations["getCascadeTask"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/v1/actions/cascade/tasks/{task_id}/status": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Get Cascade Task Status */
+        get: operations["getCascadeTaskStatus"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/v1/downloads/cascade/{task_id}/file": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Download Cascade File */
+        get: operations["downloadCascadeFile"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/v1/downloads/cascade/{task_id}/status": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Get download status */
+        get: operations["watchDownloadStatus"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+}
+export type webhooks = Record<string, never>;
+export interface components {
+    schemas: {
+        StartCascadeResponse: {
+            /** @description Unique identifier for the task */
+            task_id?: string;
+        };
+        ActionStatusResponse: {
+            /** @description Status of the action */
+            status?: string;
+        };
+    };
+    responses: never;
+    parameters: never;
+    requestBodies: never;
+    headers: never;
+    pathItems: never;
+}
+export type $defs = Record<string, never>;
+export interface operations {
+    startCascade: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "multipart/form-data": {
+                    /** @description Action identifier */
+                    action_id: string;
+                    /**
+                     * Format: binary
+                     * @description File to upload
+                     */
+                    file: string;
+                    /** @description Authentication signature */
+                    signature: string;
+                };
+            };
+        };
+        responses: {
+            /** @description Accepted */
+            202: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["StartCascadeResponse"];
+                };
+            };
+        };
+    };
+    requestCascadeDownload: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                /** @description Action ID */
+                action_id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Successful response */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        /** @description Download task identifier */
+                        taskId?: string;
+                    };
+                };
+            };
+        };
+    };
+    getCascadeTask: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                /** @description Task ID */
+                task_id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Successful response */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        taskId?: string;
+                        status?: string;
+                        progress?: number;
+                    };
+                };
+            };
+        };
+    };
+    getCascadeTaskStatus: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                /** @description Task ID */
+                task_id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Successful response */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        /** @enum {string} */
+                        status?: "pending" | "processing" | "completed" | "failed";
+                        progress?: number;
+                    };
+                };
+            };
+        };
+    };
+    downloadCascadeFile: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                /** @description Task ID */
+                task_id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Successful response */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/octet-stream": string;
+                };
+            };
+        };
+    };
+    watchDownloadStatus: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                /** @description Task identifier */
+                task_id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Success */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "text/event-stream": string;
+                };
+            };
+        };
+    };
+}

package/dist/types/wallets/keplr.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Keplr wallet adapter.
+ *
+ * This module provides integration with the Keplr browser extension wallet,
+ * supporting both on-chain transaction signing (via CosmJS OfflineSigner)
+ * and off-chain message signing (via ADR-036 signArbitrary).
+ *
+ * @module wallets/keplr
+ */
+import type { UniversalSigner } from "./signer.js";
+/**
+ * Keplr wallet interface exposed on window.keplr.
+ */
+export interface KeplrWallet {
+    enable(chainId: string): Promise<void>;
+    getOfflineSigner(chainId: string): any;
+    getOfflineSignerAuto(chainId: string): Promise<any>;
+    signArbitrary(chainId: string, signer: string, data: string | Uint8Array): Promise<{
+        signature: string;
+        pub_key: {
+            type: string;
+            value: string;
+        };
+    }>;
+}
+declare global {
+    interface Window {
+        keplr?: KeplrWallet;
+    }
+}
+/**
+ * Detect if Keplr wallet is available in the browser.
+ *
+ * Checks for the presence of the Keplr extension by looking for
+ * `window.keplr`. This should be called before attempting to connect
+ * to ensure the user has Keplr installed.
+ *
+ * @returns True if Keplr is detected, false otherwise
+ *
+ * @example
+ * ```typescript
+ * if (!isKeplrAvailable()) {
+ *   alert("Please install Keplr extension");
+ *   return;
+ * }
+ * ```
+ */
+export declare function isKeplrAvailable(): boolean;
+/**
+ * Get a UniversalSigner from Keplr for the specified chain.
+ *
+ * This function:
+ * 1. Checks if Keplr is available
+ * 2. Requests user permission to connect (via enable)
+ * 3. Obtains an OfflineSigner from Keplr
+ * 4. Wraps it in a UniversalSigner adapter
+ *
+ * The returned signer can be used for both transaction signing (via CosmJS)
+ * and off-chain message signing (via ADR-036).
+ *
+ * @param chainId - Chain identifier (e.g., "lumera-testnet-2")
+ * @returns UniversalSigner instance for Keplr
+ * @throws {Error} If Keplr is not available or user denies permission
+ *
+ * @example
+ * ```typescript
+ * // Connect to Keplr
+ * const signer = await getKeplrSigner("lumera-testnet-2");
+ *
+ * // Get accounts
+ * const accounts = await signer.getAccounts();
+ * console.log("Connected:", accounts[0].address);
+ *
+ * // Sign a transaction
+ * const signDoc = { ... };
+ * const txResult = await signer.signDirect(accounts[0].address, signDoc);
+ *
+ * // Sign off-chain data (e.g., for LEP-1 layout signature)
+ * const layoutHash = "abc123...";
+ * const signature = await signer.signArbitrary(
+ *   "lumera-testnet-2",
+ *   accounts[0].address,
+ *   layoutHash
+ * );
+ * ```
+ */
+export declare function getKeplrSigner(chainId: string): Promise<UniversalSigner>;
+export {};
+/**
+ * Get a UniversalSigner from Keplr with only Amino support.
+ *
+ * Use this if you only need Amino (legacy) transaction signing.
+ * For new applications, prefer `getKeplrSigner` which supports both
+ * Amino and Direct signing.
+ *
+ * @param chainId - Chain identifier
+ * @returns UniversalSigner instance for Keplr (Amino only)
+ * @throws {Error} If Keplr is not available or user denies permission
+ */
+export declare function getKeplrAminoSigner(chainId: string): Promise<UniversalSigner>;

package/dist/types/wallets/leap.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Leap wallet adapter.
+ *
+ * This module provides integration with the Leap browser extension wallet,
+ * supporting both on-chain transaction signing (via CosmJS OfflineSigner)
+ * and off-chain message signing (via ADR-036 signArbitrary).
+ *
+ * @module wallets/leap
+ */
+import type { UniversalSigner } from "./signer.js";
+/**
+ * Leap wallet interface exposed on window.leap.
+ */
+export interface LeapWallet {
+    enable(chainId: string): Promise<void>;
+    getOfflineSigner(chainId: string): any;
+    getOfflineSignerAuto(chainId: string): Promise<any>;
+    signArbitrary(chainId: string, signer: string, data: string | Uint8Array): Promise<{
+        signature: string;
+        pub_key: {
+            type: string;
+            value: string;
+        };
+    }>;
+}
+declare global {
+    interface Window {
+        leap?: LeapWallet;
+    }
+}
+/**
+ * Detect if Leap wallet is available in the browser.
+ *
+ * Checks for the presence of the Leap extension by looking for
+ * `window.leap`. This should be called before attempting to connect
+ * to ensure the user has Leap installed.
+ *
+ * @returns True if Leap is detected, false otherwise
+ *
+ * @example
+ * ```typescript
+ * if (!isLeapAvailable()) {
+ *   alert("Please install Leap extension");
+ *   return;
+ * }
+ * ```
+ */
+export declare function isLeapAvailable(): boolean;
+/**
+ * Get a UniversalSigner from Leap for the specified chain.
+ *
+ * This function:
+ * 1. Checks if Leap is available
+ * 2. Requests user permission to connect (via enable)
+ * 3. Obtains an OfflineSigner from Leap
+ * 4. Wraps it in a UniversalSigner adapter
+ *
+ * The returned signer can be used for both transaction signing (via CosmJS)
+ * and off-chain message signing (via ADR-036).
+ *
+ * @param chainId - Chain identifier (e.g., "lumera-testnet-2")
+ * @returns UniversalSigner instance for Leap
+ * @throws {Error} If Leap is not available or user denies permission
+ *
+ * @example
+ * ```typescript
+ * // Connect to Leap
+ * const signer = await getLeapSigner("lumera-testnet-2");
+ *
+ * // Get accounts
+ * const accounts = await signer.getAccounts();
+ * console.log("Connected:", accounts[0].address);
+ *
+ * // Sign a transaction
+ * const signDoc = { ... };
+ * const txResult = await signer.signDirect(accounts[0].address, signDoc);
+ *
+ * // Sign off-chain data (e.g., for LEP-1 layout signature)
+ * const layoutHash = "abc123...";
+ * const signature = await signer.signArbitrary(
+ *   "lumera-testnet-2",
+ *   accounts[0].address,
+ *   layoutHash
+ * );
+ * ```
+ */
+export declare function getLeapSigner(chainId: string): Promise<UniversalSigner>;
+export {};
+/**
+ * Get a UniversalSigner from Leap with only Amino support.
+ *
+ * Use this if you only need Amino (legacy) transaction signing.
+ * For new applications, prefer `getLeapSigner` which supports both
+ * Amino and Direct signing.
+ *
+ * @param chainId - Chain identifier
+ * @returns UniversalSigner instance for Leap (Amino only)
+ * @throws {Error} If Leap is not available or user denies permission
+ */
+export declare function getLeapAminoSigner(chainId: string): Promise<UniversalSigner>;