@0xkaleab/sdk-js 0.2.7

package/dist/esm/cascade/downloader.js

@@ -0,0 +1,196 @@
+/**
+ * CascadeDownloader - High-level API for Cascade file downloads
+ *
+ * This module provides a streamlined interface for downloading files from the
+ * Cascade storage network. It orchestrates the complete download workflow:
+ *
+ * 1. Authentication signature preparation (for private files)
+ * 2. Download task initiation via sn-api
+ * 3. Task monitoring until file is ready
+ * 4. File stream retrieval
+ *
+ * @example
+ * ```typescript
+ * const downloader = new CascadeDownloader(snapiClient);
+ *
+ * try {
+ *   const stream = await downloader.downloadFile('action-123');
+ *   // Process the stream...
+ *   const reader = stream.getReader();
+ *   while (true) {
+ *     const { done, value } = await reader.read();
+ *     if (done) break;
+ *     // Handle chunk...
+ *   }
+ * } catch (error) {
+ *   console.error('Download failed:', error);
+ * }
+ * ```
+ */
+import { TaskManager } from './task';
+/**
+ * CascadeDownloader manages the complete file download workflow.
+ *
+ * This class integrates the SNApiClient and TaskManager to provide
+ * a simple, high-level API for downloading files from Cascade. It handles:
+ *
+ * - Download authentication for private files
+ * - Download task initiation
+ * - Task status monitoring until file is ready
+ * - File stream retrieval
+ *
+ * @remarks
+ * The current implementation uses a simulated signature for `download_auth`.
+ * In production, this should be replaced with a real wallet signature over
+ * the action ID using ADR-036 signArbitrary for private downloads.
+ */
+export class CascadeDownloader {
+    /**
+     * Create a new CascadeDownloader instance
+     *
+     * @param client - SNApiClient for making sn-api requests
+     * @param signerAddress - Bech32 address of the signer
+     * @param signer - Universal signer for signing operations
+     * @param chainId - Chain ID for signing operations
+     */
+    constructor(client, signerAddress, signer, chainId) {
+        this.client = client;
+        this.signerAddress = signerAddress;
+        this.signer = signer;
+        this.chainId = chainId;
+    }
+    /**
+     * Download a file from Cascade storage
+     *
+     * This method orchestrates the complete download workflow:
+     *
+     * 1. Prepares the download_auth signature (for private downloads)
+     * 2. Initiates a download task via sn-api
+     * 3. Monitors the task using SSE until the file is ready
+     * 4. Retrieves and returns the file as a ReadableStream
+     *
+     * The returned stream can be processed incrementally, making it suitable
+     * for large files without loading them entirely into memory.
+     *
+     * @param params - Download parameters including action ID and options
+     * @returns Promise resolving to a ReadableStream of the file data
+     * @throws {Error} If any step of the download workflow fails
+     *
+     * @example
+     * ```typescript
+     * const downloader = new CascadeDownloader(snapiClient, signerAddress, signer, chainId);
+     *
+     * // Download a public file
+     * const stream = await downloader.downloadFile({
+     *   actionId: 'action-123'
+     * });
+     *
+     * // Download a private file (requires authentication)
+     * const privateStream = await downloader.downloadFile({
+     *   actionId: 'action-456',
+     *   taskOptions: {
+     *     pollInterval: 2000,
+     *     timeout: 300000
+     *   }
+     * });
+     *
+     * // Process the stream
+     * const reader = stream.getReader();
+     * const chunks: Uint8Array[] = [];
+     *
+     * while (true) {
+     *   const { done, value } = await reader.read();
+     *   if (done) break;
+     *   chunks.push(value);
+     * }
+     *
+     * // Combine chunks into a single Uint8Array
+     * const totalLength = chunks.reduce((acc, chunk) => acc + chunk.length, 0);
+     * const fileData = new Uint8Array(totalLength);
+     * let offset = 0;
+     * for (const chunk of chunks) {
+     *   fileData.set(chunk, offset);
+     *   offset += chunk.length;
+     * }
+     * ```
+     */
+    async downloadFile(params) {
+        // Step 1: Prepare download_auth signature (always required by sn-api)
+        // We sign the action ID using ADR-36 via the configured wallet. On the
+        // server side, this is validated using VerifyStringRawOrADR36, which
+        // accepts both raw and ADR-36 style signatures.
+        const downloadSignatureB64 = await this.simulateDownloadSignature(params.actionId);
+        // Step 2: Initiate download task via sn-api, including the signature
+        const response = await this.client.requestDownload(params.actionId, {
+            signature: downloadSignatureB64,
+        });
+        const rawResponse = response;
+        const downloadTaskId = rawResponse?.taskId ?? rawResponse?.task_id ?? rawResponse?.id;
+        if (!downloadTaskId) {
+            throw new Error("sn-api download request did not return a task identifier (expected one of taskId, task_id, or id)");
+        }
+        // Step 3: Monitor download task until ready using SSE
+        const taskManager = new TaskManager(this.client, downloadTaskId, params.taskOptions);
+        // Use SSE-based monitoring for real-time status updates
+        await taskManager.waitForDownloadCompletion();
+        // Step 4: Retrieve the file stream
+        const fileStream = await this.client.downloadFile(downloadTaskId);
+        return fileStream;
+    }
+    /**
+     * Convenience method to download a file by action ID
+     *
+     * This is a shorthand for calling downloadFile with just an action ID.
+     * Defaults to public download (no authentication).
+     *
+     * @param actionId - The blockchain action ID to download
+     * @param taskOptions - Optional task monitoring configuration
+     * @returns Promise resolving to a ReadableStream of the file data
+     *
+     * @example
+     * ```typescript
+     * const downloader = new CascadeDownloader(snapiClient);
+     * const stream = await downloader.download('action-123');
+     * ```
+     */
+    async download(actionId, taskOptions) {
+        return this.downloadFile({
+            actionId,
+            taskOptions,
+        });
+    }
+    /**
+     * Convenience method to download a private file
+     *
+     * This is a shorthand for downloading a file that requires authentication.
+     *
+     * @param actionId - The blockchain action ID to download
+     * @param taskOptions - Optional task monitoring configuration
+     * @returns Promise resolving to a ReadableStream of the file data
+     *
+     * @example
+     * ```typescript
+     * const downloader = new CascadeDownloader(snapiClient);
+     * const stream = await downloader.downloadPrivate('action-456');
+     * ```
+     */
+    async downloadPrivate(actionId, taskOptions) {
+        return this.downloadFile({
+            actionId,
+            taskOptions,
+        });
+    }
+    /**
+     * Generate download signature for private file authentication
+     *
+     * Signs the action ID using ADR-036 signArbitrary with the wallet.
+     * This signature authenticates the download request for private files.
+     *
+     * @param actionId - The action ID to sign
+     * @returns Promise resolving to Base64-encoded signature
+     */
+    async simulateDownloadSignature(actionId) {
+        const signatureResponse = await this.signer.signArbitrary(this.chainId, this.signerAddress, actionId);
+        return signatureResponse.signature;
+    }
+}

package/dist/esm/cascade/ports.js

@@ -0,0 +1,9 @@
+/**
+ * Port interface and DTOs for Cascade layer to access blockchain capabilities.
+ *
+ * This interface defines the minimal surface that Cascade components need from the blockchain,
+ * allowing the blockchain layer to evolve independently while keeping Cascade decoupled.
+ *
+ * @module cascade/ports
+ */
+export {};

package/dist/esm/cascade/task.js

@@ -0,0 +1,465 @@
+import { HttpError } from '../internal/http';
+const TERMINAL_SUCCESS_STATUSES = new Set([
+    'sdk:completed',
+    'sdk:upload_completed',
+]);
+const TERMINAL_FAILURE_STATUSES = new Set([
+    'sdk:failed',
+    'sdk:supernodes_unavailable',
+    'sdk:registration_failure',
+    'sdk:upload_failed',
+    'sdk:processing_failed',
+    'sdk:processing_timeout',
+    'sdk:download_failure',
+]);
+/**
+ * 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 class TaskManager {
+    /**
+     * 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, taskId, options = {}) {
+        this.client = client;
+        this.taskId = taskId;
+        this.pollInterval = options.pollInterval ?? 2000; // 2 seconds default
+        this.timeout = options.timeout ?? 300000; // 5 minutes default
+        this.initialStatusDelay = options.initialStatusDelay ?? 500;
+        this.initialStatusRetryAttempts = options.initialStatusRetryAttempts ?? 3;
+        this.initialStatusRetryInterval = options.initialStatusRetryInterval ?? 500;
+    }
+    /**
+     * 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);
+     * }
+     * ```
+     */
+    async waitForCompletion() {
+        const startTime = Date.now();
+        if (this.initialStatusDelay > 0) {
+            console.debug('TaskManager initial status delay', {
+                taskId: this.taskId,
+                delay: this.initialStatusDelay,
+            });
+            await this.sleep(this.initialStatusDelay);
+        }
+        let status;
+        let retries = 0;
+        while (true) {
+            try {
+                status = await this.client.getTaskStatus(this.taskId);
+                console.debug('TaskManager initial status fetch', {
+                    taskId: this.taskId,
+                    status: status?.status,
+                    rawStatus: status,
+                });
+                if (retries > 0) {
+                    console.debug('TaskManager initial status recovered after retries', {
+                        taskId: this.taskId,
+                        retries,
+                    });
+                }
+                break;
+            }
+            catch (error) {
+                const isRetryable404 = error instanceof HttpError &&
+                    error.statusCode === 404 &&
+                    retries < this.initialStatusRetryAttempts;
+                if (!isRetryable404) {
+                    throw error;
+                }
+                retries += 1;
+                const retryDelay = this.initialStatusRetryInterval * retries;
+                console.debug('TaskManager initial status retry after 404', {
+                    taskId: this.taskId,
+                    attempt: retries,
+                    retryDelay,
+                });
+                await this.sleep(retryDelay);
+            }
+        }
+        if (!status) {
+            throw new Error(`Unable to determine initial status for task ${this.taskId}`);
+        }
+        while (true) {
+            if (Date.now() - startTime > this.timeout) {
+                throw new Error(`Task ${this.taskId} timed out after ${this.timeout}ms`);
+            }
+            // Extract the actual status string from the response
+            // The API may return a single status object or the status field directly
+            const currentStatus = this.extractStatus(status);
+            console.debug('TaskManager evaluating status', {
+                taskId: this.taskId,
+                status: currentStatus,
+                rawStatus: status,
+            });
+            if (currentStatus && TERMINAL_SUCCESS_STATUSES.has(currentStatus)) {
+                console.debug('TaskManager observed terminal success status', {
+                    taskId: this.taskId,
+                    status: currentStatus,
+                });
+                // Fetch full task details on completion
+                return await this.client.getTask(this.taskId);
+            }
+            if (currentStatus && TERMINAL_FAILURE_STATUSES.has(currentStatus)) {
+                console.debug('TaskManager observed failure status', {
+                    taskId: this.taskId,
+                    status: currentStatus,
+                    rawStatus: status,
+                });
+                let failedTask;
+                try {
+                    failedTask = await this.client.getTask(this.taskId);
+                }
+                catch {
+                    // Ignore errors while fetching full task details; fall back to status payload.
+                }
+                // When status is an array or SSE string, find the failed item to extract error message
+                let statusPayload = status;
+                if (typeof statusPayload === 'string' && statusPayload.includes('data:')) {
+                    // Parse SSE data to find the failed item
+                    const lines = statusPayload.split('\n');
+                    for (const line of lines) {
+                        const trimmed = line.trim();
+                        if (trimmed.startsWith('data:')) {
+                            const jsonStr = trimmed.substring(5).trim();
+                            if (jsonStr) {
+                                try {
+                                    const parsed = JSON.parse(jsonStr);
+                                    if (parsed && typeof parsed === 'object' &&
+                                        typeof parsed.status === 'string' &&
+                                        TERMINAL_FAILURE_STATUSES.has(parsed.status)) {
+                                        statusPayload = parsed;
+                                        break;
+                                    }
+                                }
+                                catch (e) {
+                                    // Continue to next line
+                                }
+                            }
+                        }
+                    }
+                }
+                else if (Array.isArray(statusPayload)) {
+                    const failedItem = statusPayload.find((item) => item && typeof item === 'object' &&
+                        typeof item.status === 'string' &&
+                        TERMINAL_FAILURE_STATUSES.has(item.status));
+                    if (failedItem) {
+                        statusPayload = failedItem;
+                    }
+                }
+                const failureReason = this.extractErrorMessage(failedTask) ??
+                    this.extractErrorMessage(statusPayload) ??
+                    'Unknown error';
+                throw new Error(`Task failed with status ${failedTask?.status ?? currentStatus}: ${failureReason}`);
+            }
+            // Wait for the next poll interval before checking again
+            await this.sleep(this.pollInterval);
+            if (Date.now() - startTime > this.timeout) {
+                throw new Error(`Task ${this.taskId} timed out after ${this.timeout}ms`);
+            }
+            status = await this.client.getTaskStatus(this.taskId);
+            console.debug('TaskManager polled status update', {
+                taskId: this.taskId,
+                status: this.extractStatus(status),
+                rawStatus: status,
+            });
+        }
+    }
+    /**
+     * 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);
+     * }
+     * ```
+     */
+    async waitForDownloadCompletion() {
+        return new Promise((resolve, reject) => {
+            const eventSource = this.client.watchDownloadTask(this.taskId);
+            let settled = false;
+            const finalize = (onSettle) => {
+                if (settled) {
+                    return;
+                }
+                settled = true;
+                clearTimeout(timeoutId);
+                eventSource.close();
+                onSettle();
+            };
+            const timeoutId = setTimeout(() => {
+                finalize(() => {
+                    reject(new Error(`Download task ${this.taskId} timed out after ${this.timeout}ms`));
+                });
+            }, this.timeout);
+            const handleSuccess = (status, event) => {
+                finalize(() => {
+                    console.debug('Download task completed', {
+                        taskId: this.taskId,
+                        status,
+                        payload: this.parseEventPayload(event),
+                    });
+                    resolve();
+                });
+            };
+            const handleFailure = async (status, event) => {
+                if (settled) {
+                    return;
+                }
+                let failureStatus = status;
+                let failureReason = this.extractErrorMessage(this.parseEventPayload(event)) ?? 'Unknown error';
+                try {
+                    const failedTask = await this.client.getTask(this.taskId);
+                    failureStatus = failedTask?.status ?? failureStatus;
+                    failureReason =
+                        this.extractErrorMessage(failedTask) ??
+                            failureReason;
+                }
+                catch {
+                    // Ignore secondary errors when fetching task details.
+                }
+                finalize(() => {
+                    reject(new Error(`Download task ${this.taskId} failed with status ${failureStatus}: ${failureReason}`));
+                });
+            };
+            // sn-api emits SSE events without explicit `event:` types; the payload
+            // is an ActionStatusResponse with a `status` field. We listen for the
+            // default "message" event and derive the terminal status from its data.
+            eventSource.addEventListener('message', (event) => {
+                if (settled) {
+                    return;
+                }
+                const payload = this.parseEventPayload(event);
+                const status = this.extractStatus(payload);
+                if (!status) {
+                    return;
+                }
+                if (TERMINAL_SUCCESS_STATUSES.has(status)) {
+                    handleSuccess(status, event);
+                    return;
+                }
+                if (TERMINAL_FAILURE_STATUSES.has(status)) {
+                    void handleFailure(status, event);
+                }
+            });
+            eventSource.addEventListener('error', (event) => {
+                if (eventSource.readyState === EventSource.CLOSED) {
+                    finalize(() => {
+                        reject(new Error(`Download task ${this.taskId} connection closed unexpectedly`));
+                    });
+                    return;
+                }
+                void handleFailure('error', event);
+            });
+        });
+    }
+    parseEventPayload(event) {
+        if (!event || typeof event !== 'object') {
+            return undefined;
+        }
+        const data = event.data;
+        if (typeof data === 'string') {
+            try {
+                return JSON.parse(data);
+            }
+            catch {
+                return data;
+            }
+        }
+        return data;
+    }
+    /**
+     * 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
+     */
+    extractStatus(value) {
+        if (typeof value === 'string') {
+            // Check if this is raw SSE data (contains "data:" prefix)
+            if (value.includes('data:')) {
+                return this.parseSSEData(value);
+            }
+            return value;
+        }
+        if (!value || typeof value !== 'object') {
+            return undefined;
+        }
+        // Handle array of status updates - find the most recent or any terminal status
+        if (Array.isArray(value)) {
+            // First, prefer any terminal *success* status if present (retries may have succeeded)
+            for (const item of value) {
+                const status = this.extractStatus(item);
+                if (status && TERMINAL_SUCCESS_STATUSES.has(status)) {
+                    return status;
+                }
+            }
+            // If no success found, look for any terminal failure status
+            for (const item of value) {
+                const status = this.extractStatus(item);
+                if (status && TERMINAL_FAILURE_STATUSES.has(status)) {
+                    return status;
+                }
+            }
+            // If no terminal status found, return the last status in the array
+            if (value.length > 0) {
+                return this.extractStatus(value[value.length - 1]);
+            }
+            return undefined;
+        }
+        // Handle object with status field
+        const obj = value;
+        if ('status' in obj && typeof obj.status === 'string') {
+            return obj.status;
+        }
+        return undefined;
+    }
+    /**
+     * 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
+     */
+    parseSSEData(sseData) {
+        const lines = sseData.split('\n');
+        const statusObjects = [];
+        for (const line of lines) {
+            const trimmed = line.trim();
+            if (trimmed.startsWith('data:')) {
+                const jsonStr = trimmed.substring(5).trim();
+                if (jsonStr) {
+                    try {
+                        const parsed = JSON.parse(jsonStr);
+                        if (parsed && typeof parsed === 'object') {
+                            statusObjects.push(parsed);
+                        }
+                    }
+                    catch (e) {
+                        console.warn('Failed to parse SSE data line:', jsonStr, e);
+                    }
+                }
+            }
+        }
+        // Prefer any terminal *success* status if present (retries may have succeeded)
+        for (const obj of statusObjects) {
+            if (obj.status && TERMINAL_SUCCESS_STATUSES.has(obj.status)) {
+                return obj.status;
+            }
+        }
+        // If no success found, look for any terminal failure status
+        for (const obj of statusObjects) {
+            if (obj.status && TERMINAL_FAILURE_STATUSES.has(obj.status)) {
+                return obj.status;
+            }
+        }
+        // If no terminal status found, return the last status
+        if (statusObjects.length > 0) {
+            const lastObj = statusObjects[statusObjects.length - 1];
+            return lastObj.status;
+        }
+        return undefined;
+    }
+    extractErrorMessage(value) {
+        if (typeof value === 'string') {
+            const trimmed = value.trim();
+            return trimmed.length > 0 ? trimmed : undefined;
+        }
+        if (!value || typeof value !== 'object') {
+            return undefined;
+        }
+        const candidate = value;
+        if (candidate.data && typeof candidate.data === 'object') {
+            const nested = candidate.data;
+            if (typeof nested.error === 'string' && nested.error.trim()) {
+                return nested.error.trim();
+            }
+            if (typeof nested.message === 'string' && nested.message.trim()) {
+                return nested.message.trim();
+            }
+        }
+        if (typeof candidate.error === 'string' && candidate.error.trim()) {
+            return candidate.error.trim();
+        }
+        if (typeof candidate.message === 'string' && candidate.message.trim()) {
+            return candidate.message.trim();
+        }
+        return undefined;
+    }
+    /**
+     * Sleep for a specified duration
+     *
+     * @param ms - Duration in milliseconds
+     * @returns Promise that resolves after the specified duration
+     */
+    sleep(ms) {
+        return new Promise(resolve => setTimeout(resolve, ms));
+    }
+}