@debros/orama 0.122.4-nightly

package/src/pubsub/types.ts

@@ -0,0 +1,46 @@
+export interface PubSubMessage {
+  data: string;
+  topic: string;
+  timestamp: number;
+}
+
+export interface RawEnvelope {
+  type?: string;
+  data: string; // base64-encoded
+  timestamp: number;
+  topic: string;
+  member_id?: string;
+  meta?: Record<string, unknown>;
+}
+
+export interface PresenceMember {
+  memberId: string;
+  joinedAt: number;
+  meta?: Record<string, unknown>;
+}
+
+export interface PresenceResponse {
+  topic: string;
+  members: PresenceMember[];
+  count: number;
+}
+
+export interface PresenceOptions {
+  enabled: boolean;
+  memberId: string;
+  meta?: Record<string, unknown>;
+  onJoin?: (member: PresenceMember) => void;
+  onLeave?: (member: PresenceMember) => void;
+}
+
+export interface SubscribeOptions {
+  onMessage?: MessageHandler;
+  onError?: ErrorHandler;
+  onClose?: CloseHandler;
+  presence?: PresenceOptions;
+}
+
+export type MessageHandler = (message: PubSubMessage) => void;
+export type ErrorHandler = (error: Error) => void;
+export type CloseHandler = (code: number, reason: string) => void;
+

package/src/storage/client.ts

@@ -0,0 +1,272 @@
+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 with bounded exponential backoff
+        // Max 3 seconds per retry to fit within 30s test timeout
+        // Total: 1s + 2s + 3s + 3s + 3s + 3s + 3s + 3s = 21 seconds
+        const backoffMs = Math.min(attempt * 1000, 3000);
+        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 with bounded exponential backoff
+        // Max 3 seconds per retry to fit within 30s test timeout
+        // Total: 1s + 2s + 3s + 3s + 3s + 3s + 3s + 3s = 21 seconds
+        const backoffMs = Math.min(attempt * 1000, 3000);
+        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}`);
+  }
+}

package/src/storage/index.ts

@@ -0,0 +1,7 @@
+export { StorageClient } from "./client";
+export type {
+  StorageUploadResponse,
+  StoragePinRequest,
+  StoragePinResponse,
+  StorageStatus,
+} from "./client";

package/src/utils/codec.ts

@@ -0,0 +1,68 @@
+/**
+ * Base64 Codec for cross-platform encoding/decoding
+ * Works in both Node.js and browser environments
+ */
+export class Base64Codec {
+  /**
+   * Encode string or Uint8Array to base64
+   */
+  static encode(input: string | Uint8Array): string {
+    if (typeof input === "string") {
+      return this.encodeString(input);
+    }
+    return this.encodeBytes(input);
+  }
+
+  /**
+   * Encode string to base64
+   */
+  static encodeString(str: string): string {
+    if (this.isNode()) {
+      return Buffer.from(str).toString("base64");
+    }
+    // Browser
+    return btoa(
+      encodeURIComponent(str).replace(/%([0-9A-F]{2})/g, (match, p1) =>
+        String.fromCharCode(parseInt(p1, 16))
+      )
+    );
+  }
+
+  /**
+   * Encode Uint8Array to base64
+   */
+  static encodeBytes(bytes: Uint8Array): string {
+    if (this.isNode()) {
+      return Buffer.from(bytes).toString("base64");
+    }
+    // Browser
+    let binary = "";
+    for (let i = 0; i < bytes.length; i++) {
+      binary += String.fromCharCode(bytes[i]);
+    }
+    return btoa(binary);
+  }
+
+  /**
+   * Decode base64 to string
+   */
+  static decode(b64: string): string {
+    if (this.isNode()) {
+      return Buffer.from(b64, "base64").toString("utf-8");
+    }
+    // Browser
+    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);
+  }
+
+  /**
+   * Check if running in Node.js environment
+   */
+  private static isNode(): boolean {
+    return typeof Buffer !== "undefined";
+  }
+}

package/src/utils/index.ts

@@ -0,0 +1,3 @@
+export { Base64Codec } from "./codec";
+export { retryWithBackoff, type RetryConfig } from "./retry";
+export { Platform } from "./platform";

package/src/utils/platform.ts

@@ -0,0 +1,44 @@
+/**
+ * Platform detection utilities
+ * Helps determine runtime environment (Node.js vs Browser)
+ */
+export const Platform = {
+  /**
+   * Check if running in Node.js
+   */
+  isNode: (): boolean => {
+    return typeof process !== "undefined" && !!process.versions?.node;
+  },
+
+  /**
+   * Check if running in browser
+   */
+  isBrowser: (): boolean => {
+    return typeof window !== "undefined";
+  },
+
+  /**
+   * Check if localStorage is available
+   */
+  hasLocalStorage: (): boolean => {
+    try {
+      return typeof localStorage !== "undefined" && localStorage !== null;
+    } catch {
+      return false;
+    }
+  },
+
+  /**
+   * Check if Buffer is available (Node.js)
+   */
+  hasBuffer: (): boolean => {
+    return typeof Buffer !== "undefined";
+  },
+
+  /**
+   * Check if btoa/atob are available (Browser)
+   */
+  hasBase64: (): boolean => {
+    return typeof btoa !== "undefined" && typeof atob !== "undefined";
+  },
+};

package/src/utils/retry.ts

@@ -0,0 +1,58 @@
+/**
+ * Retry configuration
+ */
+export interface RetryConfig {
+  /**
+   * Maximum number of retry attempts
+   */
+  maxAttempts: number;
+
+  /**
+   * Function to calculate backoff delay in milliseconds
+   */
+  backoffMs: (attempt: number) => number;
+
+  /**
+   * Function to determine if error should trigger retry
+   */
+  shouldRetry: (error: any) => boolean;
+}
+
+/**
+ * Retry an operation with exponential backoff
+ * @param operation - The async operation to retry
+ * @param config - Retry configuration
+ * @returns Promise resolving to operation result
+ * @throws Last error if all retries exhausted
+ */
+export async function retryWithBackoff<T>(
+  operation: () => Promise<T>,
+  config: RetryConfig
+): Promise<T> {
+  let lastError: Error | null = null;
+
+  for (let attempt = 1; attempt <= config.maxAttempts; attempt++) {
+    try {
+      return await operation();
+    } catch (error: any) {
+      lastError = error instanceof Error ? error : new Error(String(error));
+
+      // Check if we should retry this error
+      if (!config.shouldRetry(error)) {
+        throw error;
+      }
+
+      // If this was the last attempt, throw
+      if (attempt === config.maxAttempts) {
+        throw error;
+      }
+
+      // Wait before next attempt
+      const delay = config.backoffMs(attempt);
+      await new Promise((resolve) => setTimeout(resolve, delay));
+    }
+  }
+
+  // Fallback (should never reach here)
+  throw lastError || new Error("Retry failed");
+}

package/src/vault/auth.ts

@@ -0,0 +1,98 @@
+import { GuardianClient } from './transport/guardian';
+import type { GuardianEndpoint } from './transport/types';
+
+/**
+ * Handles challenge-response authentication with guardian nodes.
+ * Caches session tokens per guardian endpoint.
+ *
+ * Auth flow:
+ * 1. POST /v2/vault/auth/challenge with identity → get {nonce, created_ns, tag}
+ * 2. POST /v2/vault/auth/session with identity + challenge fields → get session token
+ * 3. Use session token as X-Session-Token header for V2 requests
+ *
+ * The session token format is: `<identity_hex>:<expiry_ns>:<tag_hex>`
+ */
+export class AuthClient {
+  private sessions = new Map<string, { token: string; expiryNs: number }>();
+  private identityHex: string;
+  private timeoutMs: number;
+
+  constructor(identityHex: string, timeoutMs = 10_000) {
+    this.identityHex = identityHex;
+    this.timeoutMs = timeoutMs;
+  }
+
+  /**
+   * Authenticate with a guardian and cache the session token.
+   * Returns a GuardianClient with the session token set.
+   */
+  async authenticate(endpoint: GuardianEndpoint): Promise<GuardianClient> {
+    const key = `${endpoint.address}:${endpoint.port}`;
+    const cached = this.sessions.get(key);
+
+    // Check if we have a valid cached session (with 30s safety margin)
+    if (cached) {
+      const nowNs = Date.now() * 1_000_000;
+      if (cached.expiryNs > nowNs + 30_000_000_000) {
+        const client = new GuardianClient(endpoint, this.timeoutMs);
+        client.setSessionToken(cached.token);
+        return client;
+      }
+      // Expired, remove
+      this.sessions.delete(key);
+    }
+
+    const client = new GuardianClient(endpoint, this.timeoutMs);
+
+    // Step 1: Request challenge
+    const challenge = await client.requestChallenge(this.identityHex);
+
+    // Step 2: Exchange for session
+    const session = await client.createSession(
+      this.identityHex,
+      challenge.nonce,
+      challenge.created_ns,
+      challenge.tag,
+    );
+
+    // Build token string: identity:expiry_ns:tag
+    const token = `${session.identity}:${session.expiry_ns}:${session.tag}`;
+    client.setSessionToken(token);
+
+    // Cache
+    this.sessions.set(key, { token, expiryNs: session.expiry_ns });
+
+    return client;
+  }
+
+  /**
+   * Authenticate with multiple guardians in parallel.
+   * Returns authenticated GuardianClients for all that succeed.
+   */
+  async authenticateAll(endpoints: GuardianEndpoint[]): Promise<{ client: GuardianClient; endpoint: GuardianEndpoint }[]> {
+    const results = await Promise.allSettled(
+      endpoints.map(async (ep) => {
+        const client = await this.authenticate(ep);
+        return { client, endpoint: ep };
+      }),
+    );
+
+    const authenticated: { client: GuardianClient; endpoint: GuardianEndpoint }[] = [];
+    for (const r of results) {
+      if (r.status === 'fulfilled') {
+        authenticated.push(r.value);
+      }
+    }
+    return authenticated;
+  }
+
+  /** Clear all cached sessions. */
+  clearSessions(): void {
+    this.sessions.clear();
+  }
+
+  /** Get the identity hex string. */
+  getIdentityHex(): string {
+    return this.identityHex;
+  }
+}