@debros/network-ts-sdk 0.1.5 → 0.3.1

package/src/pubsub/client.ts

@@ -4,13 +4,64 @@ import { WSClient, WSClientConfig } from "../core/ws";
 export interface Message {
   data: string;
   topic: string;
-  timestamp?: number;
+  timestamp: number;
+}
+
+export interface RawEnvelope {
+  data: string; // base64-encoded
+  timestamp: number;
+  topic: string;
+}
+
+// Cross-platform base64 encoding/decoding utilities
+function base64Encode(str: string): string {
+  if (typeof Buffer !== "undefined") {
+    return Buffer.from(str).toString("base64");
+  } else if (typeof btoa !== "undefined") {
+    return btoa(
+      encodeURIComponent(str).replace(/%([0-9A-F]{2})/g, (match, p1) =>
+        String.fromCharCode(parseInt(p1, 16))
+      )
+    );
+  }
+  throw new Error("No base64 encoding method available");
+}
+
+function base64EncodeBytes(bytes: Uint8Array): string {
+  if (typeof Buffer !== "undefined") {
+    return Buffer.from(bytes).toString("base64");
+  } else if (typeof btoa !== "undefined") {
+    let binary = "";
+    for (let i = 0; i < bytes.length; i++) {
+      binary += String.fromCharCode(bytes[i]);
+    }
+    return btoa(binary);
+  }
+  throw new Error("No base64 encoding method available");
+}
+
+function base64Decode(b64: string): string {
+  if (typeof Buffer !== "undefined") {
+    return Buffer.from(b64, "base64").toString("utf-8");
+  } else if (typeof atob !== "undefined") {
+    const binary = atob(b64);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) {
+      bytes[i] = binary.charCodeAt(i);
+    }
+    return new TextDecoder().decode(bytes);
+  }
+  throw new Error("No base64 decoding method available");
 }
 
 export type MessageHandler = (message: Message) => void;
 export type ErrorHandler = (error: Error) => void;
 export type CloseHandler = () => void;
 
+/**
+ * Simple PubSub client - one WebSocket connection per topic
+ * No connection pooling, no reference counting - keep it simple
+ */
 export class PubSubClient {
   private httpClient: HttpClient;
   private wsConfig: Partial<WSClientConfig>;
@@ -21,20 +72,30 @@ export class PubSubClient {
   }
 
   /**
-   * Publish a message to a topic.
+   * Publish a message to a topic via HTTP
    */
   async publish(topic: string, data: string | Uint8Array): Promise<void> {
-    const dataBase64 =
-      typeof data === "string" ? Buffer.from(data).toString("base64") : Buffer.from(data).toString("base64");
+    let dataBase64: string;
+    if (typeof data === "string") {
+      dataBase64 = base64Encode(data);
+    } else {
+      dataBase64 = base64EncodeBytes(data);
+    }
 
-    await this.httpClient.post("/v1/pubsub/publish", {
-      topic,
-      data_base64: dataBase64,
-    });
+    await this.httpClient.post(
+      "/v1/pubsub/publish",
+      {
+        topic,
+        data_base64: dataBase64,
+      },
+      {
+        timeout: 30000,
+      }
+    );
   }
 
   /**
-   * List active topics in the current namespace.
+   * List active topics in the current namespace
    */
   async topics(): Promise<string[]> {
     const response = await this.httpClient.get<{ topics: string[] }>(
@@ -44,8 +105,8 @@ export class PubSubClient {
   }
 
   /**
-   * Subscribe to a topic via WebSocket.
-   * Returns a subscription object with event handlers.
+   * Subscribe to a topic via WebSocket
+   * Creates one WebSocket connection per topic
    */
   async subscribe(
     topic: string,
@@ -55,16 +116,23 @@ export class PubSubClient {
       onClose?: CloseHandler;
     } = {}
   ): Promise<Subscription> {
-    const wsUrl = new URL(this.wsConfig.wsURL || "ws://localhost:6001");
+    // Build WebSocket URL for this topic
+    const wsUrl = new URL(this.wsConfig.wsURL || "ws://127.0.0.1:6001");
     wsUrl.pathname = "/v1/pubsub/ws";
     wsUrl.searchParams.set("topic", topic);
 
+    const authToken = this.httpClient.getApiKey() ?? this.httpClient.getToken();
+
+    // Create WebSocket client
     const wsClient = new WSClient({
       ...this.wsConfig,
       wsURL: wsUrl.toString(),
-      authToken: this.httpClient.getToken(),
+      authToken,
     });
 
+    await wsClient.connect();
+
+    // Create subscription wrapper
     const subscription = new Subscription(wsClient, topic);
 
     if (handlers.onMessage) {
@@ -77,66 +145,144 @@ export class PubSubClient {
       subscription.onClose(handlers.onClose);
     }
 
-    await wsClient.connect();
     return subscription;
   }
 }
 
+/**
+ * Subscription represents an active WebSocket subscription to a topic
+ */
 export class Subscription {
   private wsClient: WSClient;
   private topic: string;
   private messageHandlers: Set<MessageHandler> = new Set();
   private errorHandlers: Set<ErrorHandler> = new Set();
   private closeHandlers: Set<CloseHandler> = new Set();
+  private isClosed = false;
+  private wsMessageHandler: ((data: string) => void) | null = null;
+  private wsErrorHandler: ((error: Error) => void) | null = null;
+  private wsCloseHandler: (() => void) | null = null;
 
   constructor(wsClient: WSClient, topic: string) {
     this.wsClient = wsClient;
     this.topic = topic;
 
-    this.wsClient.onMessage((data) => {
+    // Register message handler
+    this.wsMessageHandler = (data) => {
       try {
+        // Parse gateway JSON envelope: {data: base64String, timestamp, topic}
+        const envelope: RawEnvelope = JSON.parse(data);
+
+        // Validate envelope structure
+        if (!envelope || typeof envelope !== "object") {
+          throw new Error("Invalid envelope: not an object");
+        }
+        if (!envelope.data || typeof envelope.data !== "string") {
+          throw new Error("Invalid envelope: missing or invalid data field");
+        }
+        if (!envelope.topic || typeof envelope.topic !== "string") {
+          throw new Error("Invalid envelope: missing or invalid topic field");
+        }
+        if (typeof envelope.timestamp !== "number") {
+          throw new Error(
+            "Invalid envelope: missing or invalid timestamp field"
+          );
+        }
+
+        // Decode base64 data
+        const messageData = base64Decode(envelope.data);
+
         const message: Message = {
-          topic: this.topic,
-          data: data,
-          timestamp: Date.now(),
+          topic: envelope.topic,
+          data: messageData,
+          timestamp: envelope.timestamp,
         };
+
+        console.log("[Subscription] Received message on topic:", this.topic);
         this.messageHandlers.forEach((handler) => handler(message));
       } catch (error) {
+        console.error("[Subscription] Error processing message:", error);
         this.errorHandlers.forEach((handler) =>
           handler(error instanceof Error ? error : new Error(String(error)))
         );
       }
-    });
+    };
+
+    this.wsClient.onMessage(this.wsMessageHandler);
 
-    this.wsClient.onError((error) => {
+    // Register error handler
+    this.wsErrorHandler = (error) => {
       this.errorHandlers.forEach((handler) => handler(error));
-    });
+    };
+    this.wsClient.onError(this.wsErrorHandler);
 
-    this.wsClient.onClose(() => {
+    // Register close handler
+    this.wsCloseHandler = () => {
       this.closeHandlers.forEach((handler) => handler());
-    });
+    };
+    this.wsClient.onClose(this.wsCloseHandler);
   }
 
-  onMessage(handler: MessageHandler) {
+  /**
+   * Register message handler
+   */
+  onMessage(handler: MessageHandler): () => void {
     this.messageHandlers.add(handler);
     return () => this.messageHandlers.delete(handler);
   }
 
-  onError(handler: ErrorHandler) {
+  /**
+   * Register error handler
+   */
+  onError(handler: ErrorHandler): () => void {
     this.errorHandlers.add(handler);
     return () => this.errorHandlers.delete(handler);
   }
 
-  onClose(handler: CloseHandler) {
+  /**
+   * Register close handler
+   */
+  onClose(handler: CloseHandler): () => void {
     this.closeHandlers.add(handler);
     return () => this.closeHandlers.delete(handler);
   }
 
-  close() {
+  /**
+   * Close subscription and underlying WebSocket
+   */
+  close(): void {
+    if (this.isClosed) {
+      return;
+    }
+    this.isClosed = true;
+
+    // Remove handlers from WSClient
+    if (this.wsMessageHandler) {
+      this.wsClient.offMessage(this.wsMessageHandler);
+      this.wsMessageHandler = null;
+    }
+    if (this.wsErrorHandler) {
+      this.wsClient.offError(this.wsErrorHandler);
+      this.wsErrorHandler = null;
+    }
+    if (this.wsCloseHandler) {
+      this.wsClient.offClose(this.wsCloseHandler);
+      this.wsCloseHandler = null;
+    }
+
+    // Clear all local handlers
+    this.messageHandlers.clear();
+    this.errorHandlers.clear();
+    this.closeHandlers.clear();
+
+    // Close WebSocket connection
     this.wsClient.close();
   }
 
+  /**
+   * Check if subscription is active
+   */
   isConnected(): boolean {
-    return this.wsClient.isConnected();
+    return !this.isClosed && this.wsClient.isConnected();
   }
 }

package/src/storage/client.ts

@@ -0,0 +1,270 @@
+import { HttpClient } from "../core/http";
+
+export interface StorageUploadResponse {
+  cid: string;
+  name: string;
+  size: number;
+}
+
+export interface StoragePinRequest {
+  cid: string;
+  name?: string;
+}
+
+export interface StoragePinResponse {
+  cid: string;
+  name: string;
+}
+
+export interface StorageStatus {
+  cid: string;
+  name: string;
+  status: string; // "pinned", "pinning", "queued", "unpinned", "error"
+  replication_min: number;
+  replication_max: number;
+  replication_factor: number;
+  peers: string[];
+  error?: string;
+}
+
+export class StorageClient {
+  private httpClient: HttpClient;
+
+  constructor(httpClient: HttpClient) {
+    this.httpClient = httpClient;
+  }
+
+  /**
+   * Upload content to IPFS and optionally pin it.
+   * Supports both File objects (browser) and Buffer/ReadableStream (Node.js).
+   *
+   * @param file - File to upload (File, Blob, or Buffer)
+   * @param name - Optional filename
+   * @param options - Optional upload options
+   * @param options.pin - Whether to pin the content (default: true). Pinning happens asynchronously on the backend.
+   * @returns Upload result with CID
+   *
+   * @example
+   * ```ts
+   * // Browser
+   * const fileInput = document.querySelector('input[type="file"]');
+   * const file = fileInput.files[0];
+   * const result = await client.storage.upload(file, file.name);
+   * console.log(result.cid);
+   *
+   * // Node.js
+   * const fs = require('fs');
+   * const fileBuffer = fs.readFileSync('image.jpg');
+   * const result = await client.storage.upload(fileBuffer, 'image.jpg', { pin: true });
+   * ```
+   */
+  async upload(
+    file: File | Blob | ArrayBuffer | Uint8Array | ReadableStream<Uint8Array>,
+    name?: string,
+    options?: {
+      pin?: boolean;
+    }
+  ): Promise<StorageUploadResponse> {
+    // Create FormData for multipart upload
+    const formData = new FormData();
+
+    // Handle different input types
+    if (file instanceof File) {
+      formData.append("file", file);
+    } else if (file instanceof Blob) {
+      formData.append("file", file, name);
+    } else if (file instanceof ArrayBuffer) {
+      const blob = new Blob([file]);
+      formData.append("file", blob, name);
+    } else if (file instanceof Uint8Array) {
+      // Convert Uint8Array to ArrayBuffer for Blob constructor
+      const buffer = file.buffer.slice(
+        file.byteOffset,
+        file.byteOffset + file.byteLength
+      ) as ArrayBuffer;
+      const blob = new Blob([buffer], { type: "application/octet-stream" });
+      formData.append("file", blob, name);
+    } else if (file instanceof ReadableStream) {
+      // For ReadableStream, we need to read it into a blob first
+      // This is a limitation - in practice, pass File/Blob/Buffer
+      const chunks: ArrayBuffer[] = [];
+      const reader = file.getReader();
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        const buffer = value.buffer.slice(
+          value.byteOffset,
+          value.byteOffset + value.byteLength
+        ) as ArrayBuffer;
+        chunks.push(buffer);
+      }
+      const blob = new Blob(chunks);
+      formData.append("file", blob, name);
+    } else {
+      throw new Error(
+        "Unsupported file type. Use File, Blob, ArrayBuffer, Uint8Array, or ReadableStream."
+      );
+    }
+
+    // Add pin flag (default: true)
+    const shouldPin = options?.pin !== false; // Default to true
+    formData.append("pin", shouldPin ? "true" : "false");
+
+    return this.httpClient.uploadFile<StorageUploadResponse>(
+      "/v1/storage/upload",
+      formData,
+      { timeout: 300000 } // 5 minute timeout for large files
+    );
+  }
+
+  /**
+   * Pin an existing CID
+   *
+   * @param cid - Content ID to pin
+   * @param name - Optional name for the pin
+   * @returns Pin result
+   */
+  async pin(cid: string, name?: string): Promise<StoragePinResponse> {
+    return this.httpClient.post<StoragePinResponse>("/v1/storage/pin", {
+      cid,
+      name,
+    });
+  }
+
+  /**
+   * Get the pin status for a CID
+   *
+   * @param cid - Content ID to check
+   * @returns Pin status information
+   */
+  async status(cid: string): Promise<StorageStatus> {
+    return this.httpClient.get<StorageStatus>(`/v1/storage/status/${cid}`);
+  }
+
+  /**
+   * Retrieve content from IPFS by CID
+   *
+   * @param cid - Content ID to retrieve
+   * @returns ReadableStream of the content
+   *
+   * @example
+   * ```ts
+   * const stream = await client.storage.get(cid);
+   * const reader = stream.getReader();
+   * while (true) {
+   *   const { done, value } = await reader.read();
+   *   if (done) break;
+   *   // Process chunk
+   * }
+   * ```
+   */
+  async get(cid: string): Promise<ReadableStream<Uint8Array>> {
+    // Retry logic for content retrieval - content may not be immediately available
+    // after upload due to eventual consistency in IPFS Cluster
+    // IPFS Cluster pins can take 2-3+ seconds to complete across all nodes
+    const maxAttempts = 8;
+    let lastError: Error | null = null;
+
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+      try {
+        const response = await this.httpClient.getBinary(
+          `/v1/storage/get/${cid}`
+        );
+
+        if (!response.body) {
+          throw new Error("Response body is null");
+        }
+
+        return response.body;
+      } catch (error: any) {
+        lastError = error;
+
+        // Check if this is a 404 error (content not found)
+        const isNotFound =
+          error?.httpStatus === 404 ||
+          error?.message?.includes("not found") ||
+          error?.message?.includes("404");
+
+        // If it's not a 404 error, or this is the last attempt, give up
+        if (!isNotFound || attempt === maxAttempts) {
+          throw error;
+        }
+
+        // Wait before retrying (exponential backoff: 400ms, 800ms, 1200ms, etc.)
+        // This gives up to ~12 seconds total wait time, covering typical pin completion
+        const backoffMs = attempt * 2500;
+        await new Promise((resolve) => setTimeout(resolve, backoffMs));
+      }
+    }
+
+    // This should never be reached, but TypeScript needs it
+    throw lastError || new Error("Failed to retrieve content");
+  }
+
+  /**
+   * Retrieve content from IPFS by CID and return the full Response object
+   * Useful when you need access to response headers (e.g., content-length)
+   *
+   * @param cid - Content ID to retrieve
+   * @returns Response object with body stream and headers
+   *
+   * @example
+   * ```ts
+   * const response = await client.storage.getBinary(cid);
+   * const contentLength = response.headers.get('content-length');
+   * const reader = response.body.getReader();
+   * // ... read stream
+   * ```
+   */
+  async getBinary(cid: string): Promise<Response> {
+    // Retry logic for content retrieval - content may not be immediately available
+    // after upload due to eventual consistency in IPFS Cluster
+    // IPFS Cluster pins can take 2-3+ seconds to complete across all nodes
+    const maxAttempts = 8;
+    let lastError: Error | null = null;
+
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+      try {
+        const response = await this.httpClient.getBinary(
+          `/v1/storage/get/${cid}`
+        );
+
+        if (!response) {
+          throw new Error("Response is null");
+        }
+
+        return response;
+      } catch (error: any) {
+        lastError = error;
+
+        // Check if this is a 404 error (content not found)
+        const isNotFound =
+          error?.httpStatus === 404 ||
+          error?.message?.includes("not found") ||
+          error?.message?.includes("404");
+
+        // If it's not a 404 error, or this is the last attempt, give up
+        if (!isNotFound || attempt === maxAttempts) {
+          throw error;
+        }
+
+        // Wait before retrying (exponential backoff: 400ms, 800ms, 1200ms, etc.)
+        // This gives up to ~12 seconds total wait time, covering typical pin completion
+        const backoffMs = attempt * 2500;
+        await new Promise((resolve) => setTimeout(resolve, backoffMs));
+      }
+    }
+
+    // This should never be reached, but TypeScript needs it
+    throw lastError || new Error("Failed to retrieve content");
+  }
+
+  /**
+   * Unpin a CID
+   *
+   * @param cid - Content ID to unpin
+   */
+  async unpin(cid: string): Promise<void> {
+    await this.httpClient.delete(`/v1/storage/unpin/${cid}`);
+  }
+}