@0xkaleab/sdk-js 0.2.7

package/dist/types/cascade/task.d.ts

@@ -0,0 +1,157 @@
+import type { SNApiClient, Task } from './client';
+/**
+ * Options for TaskManager polling behavior
+ */
+export interface TaskManagerOptions {
+    /**
+     * Polling interval in milliseconds
+     * @default 2000 (2 seconds)
+     */
+    pollInterval?: number;
+    /**
+     * Timeout in milliseconds before giving up on polling
+     * @default 300000 (5 minutes)
+     */
+    timeout?: number;
+    /**
+     * Delay in milliseconds before performing the initial status check
+     * to allow the backend time to register the task.
+     * @default 500
+     */
+    initialStatusDelay?: number;
+    /**
+     * Maximum number of retries for the initial status check when the backend
+     * responds with a 404.
+     * @default 3
+     */
+    initialStatusRetryAttempts?: number;
+    /**
+     * Base delay in milliseconds between retries of the initial status check.
+     * The actual delay grows linearly with each retry attempt.
+     * @default 500
+     */
+    initialStatusRetryInterval?: number;
+}
+/**
+ * TaskManager monitors the status of a Cascade task using a polling strategy.
+ *
+ * This class provides a polling-based mechanism to track task completion,
+ * serving as a fallback to the preferred SSE (Server-Sent Events) method.
+ * It periodically queries the task status endpoint until the task reaches
+ * a terminal state (completed or failed).
+ *
+ * @example
+ * ```typescript
+ * const taskManager = new TaskManager(snapiClient, 'task-123');
+ *
+ * try {
+ *   const task = await taskManager.waitForCompletion();
+ *   console.log('Task completed:', task);
+ * } catch (error) {
+ *   console.error('Task failed:', error);
+ * }
+ * ```
+ */
+export declare class TaskManager {
+    private readonly client;
+    private readonly taskId;
+    private readonly pollInterval;
+    private readonly timeout;
+    private readonly initialStatusDelay;
+    private readonly initialStatusRetryAttempts;
+    private readonly initialStatusRetryInterval;
+    /**
+     * Create a new TaskManager
+     *
+     * @param client - SNApiClient instance for making API requests
+     * @param taskId - The ID of the task to monitor
+     * @param options - Optional configuration for polling behavior
+     */
+    constructor(client: SNApiClient, taskId: string, options?: TaskManagerOptions);
+    /**
+     * Wait for the task to complete by polling its status
+     *
+     * This method periodically checks the task status until it reaches a terminal
+     * state (completed or failed). It will continue polling at the configured
+     * interval until either:
+     * - The task completes successfully (resolves with task details)
+     * - The task fails (rejects with error)
+     * - The timeout is reached (rejects with timeout error)
+     *
+     * @returns Promise resolving to the completed task details
+     * @throws {Error} If the task fails or times out
+     *
+     * @example
+     * ```typescript
+     * const taskManager = new TaskManager(client, 'task-123', {
+     *   pollInterval: 1000,  // Poll every second
+     *   timeout: 60000       // 1 minute timeout
+     * });
+     *
+     * try {
+     *   const task = await taskManager.waitForCompletion();
+     *   console.log('Task completed successfully');
+     * } catch (error) {
+     *   console.error('Task did not complete:', error.message);
+     * }
+     * ```
+     */
+    waitForCompletion(): Promise<Task>;
+    /**
+     * Wait for download task completion using Server-Sent Events (SSE)
+     *
+     * This method provides real-time monitoring of download task status via SSE,
+     * which is more efficient than polling. It listens for the `sdk:completed` event
+     * to detect task completion, and handles error events appropriately.
+     *
+     * @returns Promise resolving when the task completes successfully
+     * @throws {Error} If the task fails or the connection closes unexpectedly
+     *
+     * @example
+     * ```typescript
+     * const taskManager = new TaskManager(client, 'task-123');
+     *
+     * try {
+     *   await taskManager.waitForDownloadCompletion();
+     *   console.log('Download task completed successfully');
+     * } catch (error) {
+     *   console.error('Download task failed:', error.message);
+     * }
+     * ```
+     */
+    waitForDownloadCompletion(): Promise<void>;
+    private parseEventPayload;
+    /**
+     * Extract status string from the API response
+     *
+     * The API may return different response structures:
+     * - Simple object with status field: { status: "sdk:failed" }
+     * - Array of status updates: [{ status: "sdk:failed", ... }]
+     * - Raw SSE format string with multiple "data:" lines
+     * - Status directly as string
+     *
+     * @param value - The API response value
+     * @returns The status string, or undefined if not found
+     */
+    private extractStatus;
+    /**
+     * Parse SSE (Server-Sent Events) formatted data
+     *
+     * SSE format is:
+     * data: {"status": "sdk:started", ...}
+     *
+     * data: {"status": "sdk:failed", ...}
+     *
+     * @param sseData - Raw SSE formatted string
+     * @returns The extracted status string, or undefined
+     */
+    private parseSSEData;
+    private extractErrorMessage;
+    /**
+     * Sleep for a specified duration
+     *
+     * @param ms - Duration in milliseconds
+     * @returns Promise that resolves after the specified duration
+     */
+    private sleep;
+}

package/dist/types/cascade/uploader.d.ts

@@ -0,0 +1,268 @@
+/**
+ * CascadeUploader - High-level API for Cascade file uploads
+ *
+ * This module provides a streamlined interface for uploading files to the
+ * Cascade storage network. It orchestrates the complete upload workflow:
+ *
+ * 1. File preprocessing (hashing, layout generation)
+ * 2. Index file construction per LEP-1 specification
+ * 3. Upload initiation via sn-api
+ * 4. Task monitoring until completion
+ *
+ * @example
+ * ```typescript
+ * const uploader = new CascadeUploader(snapiClient, blockchainParams);
+ *
+ * try {
+ *   const result = await uploader.uploadFile(fileBlob, {
+ *     actionId: 'action-123',
+ *     rq_ids_max: 10000
+ *   });
+ *   console.log('Upload successful:', result);
+ * } catch (error) {
+ *   console.error('Upload failed:', error);
+ * }
+ * ```
+ */
+import type { SNApiClient, Task } from './client';
+import type { CascadeChainPort, TxPrompter } from './ports';
+import { TaskManagerOptions } from './task';
+import type { UniversalSigner, ArbitrarySignResponse } from '../wallets/signer';
+export type CascadeSignatureKind = "layout" | "index" | "auth";
+export interface SignaturePromptContext {
+    kind: CascadeSignatureKind;
+    chainId: string;
+    signerAddress: string;
+    data: string;
+}
+export type SignaturePrompter = (context: SignaturePromptContext, sign: () => Promise<ArbitrarySignResponse>) => Promise<ArbitrarySignResponse>;
+/**
+ * Result of file preparation
+ */
+export interface PreparedFile {
+    /** File content as bytes */
+    fileBytes: Uint8Array;
+    /** BLAKE3 hash of file bytes (Base64 encoded) */
+    dataHash: string;
+}
+/**
+ * Result of action registration
+ */
+export interface RegisteredAction {
+    /** Action ID returned from blockchain transaction */
+    actionId: string;
+    /** Auth signature for upload (Base64 encoded) */
+    authSignature: string;
+}
+/**
+ * Parameters for registering an action
+ */
+export interface RegisterActionParams {
+    /** File name */
+    fileName?: string;
+    /** Whether storage is public or private */
+    isPublic?: boolean;
+    /** Expiration time for action (Unix timestamp in seconds) */
+    expirationTime: string;
+    /** Optional callback for signature prompts */
+    signaturePrompter?: SignaturePrompter;
+    /** Optional callback for transaction prompts */
+    txPrompter?: TxPrompter;
+}
+/**
+ * Parameters for sending file to supernodes
+ */
+export interface SendFileParams {
+    /** Optional task monitoring configuration */
+    taskOptions?: TaskManagerOptions;
+}
+/**
+ * Parameters required for a Cascade upload operation
+ */
+export interface UploadParams {
+    /**
+     * File name
+     */
+    fileName?: string;
+    /**
+     * Cascade is public or private storage
+     */
+    isPublic?: boolean;
+    /**
+     * Expiration time for action (Unix timestamp in seconds)
+     * The action will be invalid after this time and action fee refunded (not transaction fee!).
+     */
+    expirationTime: string;
+    /**
+     * Optional task monitoring configuration
+     */
+    taskOptions?: TaskManagerOptions;
+    /**
+     * Optional callback used to wrap wallet signature requests in a user gesture.
+     * Provide this when integrating with wallets (like Keplr) that require
+     * interactions to originate from explicit user actions.
+     */
+    signaturePrompter?: SignaturePrompter;
+    /**
+     * Optional callback used to wrap transaction submission in a user gesture.
+     * Provide this when integrating with wallets (like Keplr) that require
+     * transactions to originate from explicit user actions.
+     */
+    txPrompter?: TxPrompter;
+}
+/**
+ * Optional configuration for CascadeUploader
+ */
+export interface CascadeUploaderOptions {
+}
+/**
+ * CascadeUploader manages the complete file upload workflow.
+ *
+ * This class integrates all components of the storage layer to provide
+ * a simple, high-level API for uploading files to Cascade. It handles:
+ *
+ * - File hashing and integrity verification
+ * - RaptorQ layout generation
+ * - LEP-1 compliant index file construction
+ * - Upload task initiation and monitoring
+ */
+export declare class CascadeUploader {
+    private readonly client;
+    private readonly chainPort;
+    private readonly signerAddress;
+    private readonly signer;
+    private readonly chainId;
+    /**
+     * Create a new CascadeUploader instance
+     *
+     * @param client - SNApiClient for making sn-api requests
+     * @param chainPort - Port for accessing blockchain capabilities
+     * @param signerAddress - Bech32 address of the signer
+     * @param signer - Universal signer for signing operations
+     * @param chainId - Chain ID for signing operations
+     * @param options - Optional configuration
+     */
+    constructor(client: SNApiClient, chainPort: CascadeChainPort, signerAddress: string, signer: UniversalSigner, chainId: string, options?: CascadeUploaderOptions);
+    /**
+     * Step 1: Prepare file for upload
+     *
+     * Converts the file to bytes and calculates its BLAKE3 hash.
+     * This is required before registering an action or creating an auth signature.
+     *
+     * @param file - The file to prepare (as Blob, ArrayBuffer, or Uint8Array)
+     * @returns Promise resolving to prepared file data
+     *
+     * @example
+     * ```typescript
+     * const prepared = await uploader.prepareFile(fileBlob);
+     * console.log('File hash:', prepared.dataHash);
+     * ```
+     */
+    prepareFile(file: Blob | ArrayBuffer | Uint8Array): Promise<PreparedFile>;
+    /**
+     * Step 2: Register action on blockchain
+     *
+     * This method performs the complete action registration workflow:
+     * - Fetches action parameters from blockchain
+     * - Generates RaptorQ layout and signs it
+     * - Builds LEP-1 index file and signs it
+     * - Creates auth signature for upload
+     * - Registers the action on-chain via transaction
+     *
+     * @param preparedFile - Result from prepareFile()
+     * @param params - Registration parameters
+     * @returns Promise resolving to registered action details
+     *
+     * @example
+     * ```typescript
+     * const prepared = await uploader.prepareFile(fileBlob);
+     * const registered = await uploader.registerAction(prepared, {
+     *   fileName: 'document.pdf',
+     *   isPublic: true,
+     *   expirationTime: '1234567890'
+     * });
+     * ```
+     */
+    registerAction(preparedFile: PreparedFile, params: RegisterActionParams): Promise<RegisteredAction>;
+    /**
+     * Create auth signature for an existing action
+     *
+     * This is useful when you already have an action ID and need to create
+     * a new auth signature for uploading the file. Uses a single signature prompt.
+     *
+     * @param actionId - Existing action ID from blockchain
+     * @param dataHash - BLAKE3 hash of file (from prepareFile)
+     * @returns Promise resolving to auth signature (Base64 encoded)
+     *
+     * @example
+     * ```typescript
+     * const prepared = await uploader.prepareFile(fileBlob);
+     * const authSig = await uploader.makeAuthSignature(
+     *   'action-123',
+     *   prepared.dataHash
+     * );
+     * ```
+     */
+    makeAuthSignature(actionId: string, dataHash: string): Promise<string>;
+    /**
+     * Step 3: Send file to supernodes
+     *
+     * Initiates the upload via sn-api and monitors the task until completion.
+     *
+     * @param actionId - Action ID from registerAction()
+     * @param authSignature - Auth signature from registerAction() or makeAuthSignature()
+     * @param file - Original file or fileBytes from prepareFile()
+     * @param params - Send parameters
+     * @returns Promise resolving to completed upload task
+     *
+     * @example
+     * ```typescript
+     * const task = await uploader.sendFileToSupernodes(
+     *   registered.actionId,
+     *   registered.authSignature,
+     *   fileBlob,
+     *   { taskOptions: { timeout: 300000 } }
+     * );
+     * ```
+     */
+    sendFileToSupernodes(actionId: string, authSignature: string, file: Blob | ArrayBuffer | Uint8Array, params?: SendFileParams): Promise<Task>;
+    /**
+     * Upload a file to Cascade storage (unified workflow)
+     *
+     * This method orchestrates the complete upload workflow by calling:
+     * 1. prepareFile() - Convert to bytes and hash
+     * 2. registerAction() - Generate layout, register on-chain (handles prompter reset internally)
+     * 3. sendFileToSupernodes() - Upload and monitor
+     *
+     * @param file - The file to upload (as Blob, ArrayBuffer, or Uint8Array)
+     * @param params - Upload parameters
+     * @returns Promise resolving to the completed upload task
+     * @throws {Error} If any step of the upload workflow fails
+     *
+     * @example
+     * ```typescript
+     * const uploader = new CascadeUploader(snapiClient, chainPort);
+     *
+     * const result = await uploader.uploadFile(file, {
+     *   fileName: 'document.pdf',
+     *   isPublic: true,
+     *   expirationTime: '1234567890',
+     *   taskOptions: {
+     *     pollInterval: 2000,
+     *     timeout: 300000
+     *   }
+     * });
+     *
+     * console.log('Upload complete:', result);
+     * ```
+     */
+    uploadFile(file: Blob | ArrayBuffer | Uint8Array, params: UploadParams): Promise<Task>;
+    private requestSignature;
+    /**
+     * Convert various file formats to Uint8Array
+     *
+     * @param file - File in any supported format
+     * @returns Promise resolving to Uint8Array of file contents
+     */
+    private toBytes;
+}

package/dist/types/client.d.ts

@@ -0,0 +1,208 @@
+/**
+ * Main LumeraClient facade - unified entry point for the Lumera SDK
+ *
+ * This module provides the top-level client that composes blockchain and storage
+ * operations into a single, user-friendly interface. It handles configuration,
+ * chain presets, and initialization of all underlying clients.
+ *
+ * @module client
+ */
+import type { OfflineSigner } from "@cosmjs/proto-signing";
+import { type BlockchainClient } from "./blockchain/client";
+import { SNApiClient } from "./cascade/client";
+import { CascadeUploader } from "./cascade/uploader";
+import { CascadeDownloader } from "./cascade/downloader";
+/**
+ * Chain preset configuration for Lumera networks
+ */
+export interface ChainPreset {
+    /** Blockchain network identifier */
+    chainId: string;
+    /** Tendermint RPC endpoint URL */
+    rpcUrl: string;
+    /** LCD REST API endpoint URL (optional) */
+    lcdUrl?: string;
+    /** SN-API base URL for Cascade storage */
+    snapiUrl: string;
+    /** Address prefix for bech32 addresses */
+    prefix: string;
+}
+/**
+ * Predefined chain presets for Lumera networks
+ */
+export declare const CHAIN_PRESETS: {
+    readonly testnet: ChainPreset;
+    readonly mainnet: ChainPreset;
+};
+/**
+ * Configuration options for LumeraClient
+ */
+export interface LumeraClientConfig {
+    /**
+     * Chain preset to use ("testnet" or "mainnet")
+     * Alternatively, provide custom rpcUrl, lcdUrl, chainId, and snapiUrl
+     */
+    preset?: keyof typeof CHAIN_PRESETS;
+    /**
+     * Custom Tendermint RPC URL (overrides preset)
+     */
+    rpcUrl?: string;
+    /**
+     * Custom LCD REST API URL (overrides preset)
+     */
+    lcdUrl?: string;
+    /**
+     * Custom blockchain network identifier (overrides preset)
+     */
+    chainId?: string;
+    /**
+     * Custom SN-API base URL (overrides preset)
+     */
+    snapiUrl?: string;
+    /**
+     * CosmJS offline signer (wallet) for transaction signing
+     */
+    signer: OfflineSigner;
+    /**
+     * Bech32 address of the signing account
+     */
+    address: string;
+    /**
+     * Gas price string (e.g., "0.025ulume")
+     * @default "0.025ulume"
+     */
+    gasPrice?: string;
+    /**
+     * HTTP client configuration for sn-api requests
+     */
+    http?: {
+        /** Request timeout in milliseconds @default 30000 */
+        timeout?: number;
+        /** Maximum retry attempts @default 3 */
+        maxRetries?: number;
+    };
+}
+/**
+ * Main LumeraClient facade
+ *
+ * The primary entry point for the Lumera SDK, composing blockchain and storage
+ * operations into a unified interface. This client provides:
+ *
+ * - `Blockchain`: Full blockchain client (transactions and queries)
+ * - `Cascade.uploader`: File upload operations
+ * - `Cascade.downloader`: File download operations
+ *
+ * @example
+ * ```typescript
+ * import { createLumeraClient } from "@lumera-protocol/sdk-js";
+ * import { DirectSecp256k1HdWallet } from "@cosmjs/proto-signing";
+ *
+ * // Create a wallet
+ * const wallet = await DirectSecp256k1HdWallet.fromMnemonic(mnemonic, {
+ *   prefix: "lumera"
+ * });
+ * const [account] = await wallet.getAccounts();
+ *
+ * // Create the client using testnet preset
+ * const client = await createLumeraClient({
+ *   preset: "testnet",
+ *   signer: wallet,
+ *   address: account.address
+ * });
+ *
+ * // Query blockchain
+ * const params = await client.Blockchain.Action.getParams();
+ *
+ * // Upload a file to Cascade
+ * const result = await client.Cascade.uploader.uploadFile(file, {
+ *   actionId: "action-123",
+ *   rq_ids_ic: 1000,
+ *   rq_ids_max: params.rq_ids_max
+ * });
+ *
+ * // Download a file from Cascade
+ * const stream = await client.Cascade.downloader.download("action-456");
+ * ```
+ */
+export declare class LumeraClient {
+    /**
+     * Blockchain client for transaction and query operations
+     */
+    readonly Blockchain: BlockchainClient;
+    /**
+     * Cascade storage clients
+     */
+    readonly Cascade: {
+        /** File uploader for Cascade storage */
+        uploader: CascadeUploader;
+        /** File downloader for Cascade storage */
+        downloader: CascadeDownloader;
+    };
+    /**
+     * Create a new LumeraClient instance
+     *
+     * @param blockchain - Initialized blockchain client
+     * @param snapiClient - Initialized SN-API client
+     * @param chainPort - Port for Cascade to access blockchain capabilities
+     * @param signerAddress - Bech32 address of the signer
+     * @param signer - Universal signer for signing operations
+     * @param chainId - Chain ID for signing operations
+     *
+     * @remarks
+     * This constructor is typically not called directly. Use the `createLumeraClient`
+     * factory function instead, which handles all initialization automatically.
+     */
+    constructor(blockchain: BlockchainClient, snapiClient: SNApiClient, chainPort: import("./cascade/ports").CascadeChainPort, signerAddress: string, signer: import("./wallets/signer").UniversalSigner, chainId: string);
+}
+/**
+ * Create a new LumeraClient with automatic configuration
+ *
+ * This factory function simplifies client creation by:
+ * - Applying chain presets (testnet/mainnet)
+ * - Initializing all sub-clients
+ * - Configuring HTTP settings
+ * - Connecting to blockchain and storage endpoints
+ *
+ * @param config - Client configuration options
+ * @returns Promise resolving to a fully initialized LumeraClient
+ * @throws {Error} If configuration is invalid or connection fails
+ *
+ * @example
+ * Using a chain preset:
+ * ```typescript
+ * const client = await createLumeraClient({
+ *   preset: "testnet",
+ *   signer: wallet,
+ *   address: account.address
+ * });
+ * ```
+ *
+ * @example
+ * Using custom endpoints:
+ * ```typescript
+ * const client = await createLumeraClient({
+ *   rpcUrl: "https://custom-rpc.example.com",
+ *   lcdUrl: "https://custom-lcd.example.com",
+ *   chainId: "lumera-custom-1",
+ *   snapiUrl: "https://custom-snapi.example.com",
+ *   signer: wallet,
+ *   address: account.address,
+ *   gasPrice: "0.05ulume"
+ * });
+ * ```
+ *
+ * @example
+ * With custom HTTP settings:
+ * ```typescript
+ * const client = await createLumeraClient({
+ *   preset: "mainnet",
+ *   signer: wallet,
+ *   address: account.address,
+ *   http: {
+ *     timeout: 60000,
+ *     maxRetries: 5
+ *   }
+ * });
+ * ```
+ */
+export declare function createLumeraClient(config: LumeraClientConfig): Promise<LumeraClient>;

package/dist/types/codegen/amino/amino.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/codegen/amino/bundle.d.ts

@@ -0,0 +1 @@
+export declare const amino: {};