@debros/orama 0.122.4-nightly

package/src/index.ts

@@ -0,0 +1,201 @@
+import { HttpClient, HttpClientConfig, NetworkErrorCallback } from "./core/http";
+import { AuthClient } from "./auth/client";
+import { DBClient } from "./db/client";
+import { PubSubClient } from "./pubsub/client";
+import { NetworkClient } from "./network/client";
+import { CacheClient } from "./cache/client";
+import { StorageClient } from "./storage/client";
+import { FunctionsClient, FunctionsClientConfig } from "./functions/client";
+import { VaultClient } from "./vault/client";
+import { WSClientConfig } from "./core/ws";
+import {
+  StorageAdapter,
+  MemoryStorage,
+  LocalStorageAdapter,
+} from "./auth/types";
+import type { VaultConfig } from "./vault/types";
+
+export interface ClientConfig extends Omit<HttpClientConfig, "fetch"> {
+  apiKey?: string;
+  jwt?: string;
+  storage?: StorageAdapter;
+  wsConfig?: Partial<Omit<WSClientConfig, "wsURL">>;
+  functionsConfig?: FunctionsClientConfig;
+  fetch?: typeof fetch;
+  /**
+   * Callback invoked on network errors (HTTP and WebSocket).
+   * Use this to trigger gateway failover at the application layer.
+   */
+  onNetworkError?: NetworkErrorCallback;
+  /** Configuration for the vault (distributed secrets store). */
+  vaultConfig?: VaultConfig;
+}
+
+export interface Client {
+  auth: AuthClient;
+  db: DBClient;
+  pubsub: PubSubClient;
+  network: NetworkClient;
+  cache: CacheClient;
+  storage: StorageClient;
+  functions: FunctionsClient;
+  vault: VaultClient | null;
+}
+
+export function createClient(config: ClientConfig): Client {
+  const httpClient = new HttpClient({
+    baseURL: config.baseURL,
+    timeout: config.timeout,
+    maxRetries: config.maxRetries,
+    retryDelayMs: config.retryDelayMs,
+    debug: config.debug,
+    fetch: config.fetch,
+    onNetworkError: config.onNetworkError,
+  });
+
+  const auth = new AuthClient({
+    httpClient,
+    storage: config.storage,
+    apiKey: config.apiKey,
+    jwt: config.jwt,
+  });
+
+  // Derive WebSocket URL from baseURL
+  const wsURL = config.baseURL.replace(/^http/, "ws").replace(/\/$/, "");
+
+  const db = new DBClient(httpClient);
+  const pubsub = new PubSubClient(httpClient, {
+    ...config.wsConfig,
+    wsURL,
+    onNetworkError: config.onNetworkError,
+  });
+  const network = new NetworkClient(httpClient);
+  const cache = new CacheClient(httpClient);
+  const storage = new StorageClient(httpClient);
+  const functions = new FunctionsClient(httpClient, config.functionsConfig);
+  const vault = config.vaultConfig
+    ? new VaultClient(config.vaultConfig)
+    : null;
+
+  return {
+    auth,
+    db,
+    pubsub,
+    network,
+    cache,
+    storage,
+    functions,
+    vault,
+  };
+}
+
+export { HttpClient } from "./core/http";
+export type { NetworkErrorCallback, NetworkErrorContext } from "./core/http";
+export { WSClient } from "./core/ws";
+export { AuthClient } from "./auth/client";
+export { DBClient } from "./db/client";
+export { QueryBuilder } from "./db/qb";
+export { Repository } from "./db/repository";
+export { PubSubClient, Subscription } from "./pubsub/client";
+export { NetworkClient } from "./network/client";
+export { CacheClient } from "./cache/client";
+export { StorageClient } from "./storage/client";
+export { FunctionsClient } from "./functions/client";
+export { SDKError } from "./errors";
+export { MemoryStorage, LocalStorageAdapter } from "./auth/types";
+export type { StorageAdapter, AuthConfig, WhoAmI } from "./auth/types";
+export type * from "./db/types";
+export type {
+  MessageHandler,
+  ErrorHandler,
+  CloseHandler,
+  PresenceMember,
+  PresenceResponse,
+  PresenceOptions,
+  SubscribeOptions,
+} from "./pubsub/types";
+export { type PubSubMessage } from "./pubsub/types";
+export type {
+  PeerInfo,
+  NetworkStatus,
+  ProxyRequest,
+  ProxyResponse,
+} from "./network/client";
+export type {
+  CacheGetRequest,
+  CacheGetResponse,
+  CachePutRequest,
+  CachePutResponse,
+  CacheDeleteRequest,
+  CacheDeleteResponse,
+  CacheMultiGetRequest,
+  CacheMultiGetResponse,
+  CacheScanRequest,
+  CacheScanResponse,
+  CacheHealthResponse,
+} from "./cache/client";
+export type {
+  StorageUploadResponse,
+  StoragePinRequest,
+  StoragePinResponse,
+  StorageStatus,
+} from "./storage/client";
+export type { FunctionsClientConfig } from "./functions/client";
+export type * from "./functions/types";
+// Vault module
+export { VaultClient } from "./vault/client";
+export { AuthClient as VaultAuthClient } from "./vault/auth";
+export { GuardianClient, GuardianError } from "./vault/transport";
+export { fanOut, fanOutIndexed, withTimeout, withRetry } from "./vault/transport";
+export { adaptiveThreshold, writeQuorum } from "./vault/quorum";
+export {
+  encrypt,
+  decrypt,
+  encryptString,
+  decryptString,
+  serializeEncrypted,
+  deserializeEncrypted,
+  encryptAndSerialize,
+  deserializeAndDecrypt,
+  encryptedToHex,
+  encryptedFromHex,
+  encryptedToBase64,
+  encryptedFromBase64,
+  generateKey,
+  generateNonce,
+  clearKey,
+  isValidEncryptedData,
+  KEY_SIZE,
+  NONCE_SIZE,
+  TAG_SIZE,
+  deriveKeyHKDF,
+  shamirSplit,
+  shamirCombine,
+} from "./vault";
+export type {
+  VaultConfig,
+  SecretMeta,
+  StoreResult,
+  RetrieveResult,
+  ListResult,
+  DeleteResult,
+  GuardianResult as VaultGuardianResult,
+  EncryptedData,
+  SerializedEncryptedData,
+  ShamirShare,
+  GuardianEndpoint,
+  GuardianErrorCode,
+  GuardianInfo,
+  GuardianHealthResponse,
+  GuardianStatusResponse,
+  PushResponse,
+  PullResponse,
+  StoreSecretResponse,
+  GetSecretResponse,
+  DeleteSecretResponse,
+  ListSecretsResponse,
+  SecretEntry,
+  GuardianChallengeResponse,
+  GuardianSessionResponse,
+  FanOutResult,
+} from "./vault";

package/src/network/client.ts

@@ -0,0 +1,119 @@
+import { HttpClient } from "../core/http";
+
+export interface PeerInfo {
+  id: string;
+  addresses: string[];
+  lastSeen?: string;
+}
+
+export interface NetworkStatus {
+  node_id: string;
+  connected: boolean;
+  peer_count: number;
+  database_size: number;
+  uptime: number;
+}
+
+export interface ProxyRequest {
+  url: string;
+  method: string;
+  headers?: Record<string, string>;
+  body?: string;
+}
+
+export interface ProxyResponse {
+  status_code: number;
+  headers: Record<string, string>;
+  body: string;
+  error?: string;
+}
+
+export class NetworkClient {
+  private httpClient: HttpClient;
+
+  constructor(httpClient: HttpClient) {
+    this.httpClient = httpClient;
+  }
+
+  /**
+   * Check gateway health.
+   */
+  async health(): Promise<boolean> {
+    try {
+      await this.httpClient.get("/v1/health");
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Get network status.
+   */
+  async status(): Promise<NetworkStatus> {
+    const response = await this.httpClient.get<NetworkStatus>(
+      "/v1/network/status"
+    );
+    return response;
+  }
+
+  /**
+   * Get connected peers.
+   */
+  async peers(): Promise<PeerInfo[]> {
+    const response = await this.httpClient.get<{ peers: PeerInfo[] }>(
+      "/v1/network/peers"
+    );
+    return response.peers || [];
+  }
+
+  /**
+   * Connect to a peer.
+   */
+  async connect(peerAddr: string): Promise<void> {
+    await this.httpClient.post("/v1/network/connect", { peer_addr: peerAddr });
+  }
+
+  /**
+   * Disconnect from a peer.
+   */
+  async disconnect(peerId: string): Promise<void> {
+    await this.httpClient.post("/v1/network/disconnect", { peer_id: peerId });
+  }
+
+  /**
+   * Proxy an HTTP request through the Anyone network.
+   * Requires authentication (API key or JWT).
+   *
+   * @param request - The proxy request configuration
+   * @returns The proxied response
+   * @throws {SDKError} If the Anyone proxy is not available or the request fails
+   *
+   * @example
+   * ```ts
+   * const response = await client.network.proxyAnon({
+   *   url: 'https://api.example.com/data',
+   *   method: 'GET',
+   *   headers: {
+   *     'Accept': 'application/json'
+   *   }
+   * });
+   *
+   * console.log(response.status_code); // 200
+   * console.log(response.body); // Response data
+   * ```
+   */
+  async proxyAnon(request: ProxyRequest): Promise<ProxyResponse> {
+    const response = await this.httpClient.post<ProxyResponse>(
+      "/v1/proxy/anon",
+      request
+    );
+
+    // Check if the response contains an error
+    if (response.error) {
+      throw new Error(`Proxy request failed: ${response.error}`);
+    }
+
+    return response;
+  }
+}

package/src/network/index.ts

@@ -0,0 +1,7 @@
+export { NetworkClient } from "./client";
+export type {
+  PeerInfo,
+  NetworkStatus,
+  ProxyRequest,
+  ProxyResponse,
+} from "./client";

package/src/pubsub/client.ts

@@ -0,0 +1,361 @@
+import { HttpClient } from "../core/http";
+import { WSClient, WSClientConfig } from "../core/ws";
+import {
+  PubSubMessage,
+  RawEnvelope,
+  MessageHandler,
+  ErrorHandler,
+  CloseHandler,
+  SubscribeOptions,
+  PresenceResponse,
+  PresenceMember,
+  PresenceOptions,
+} from "./types";
+
+// 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");
+}
+
+/**
+ * Simple PubSub client - one WebSocket connection per topic
+ * Gateway failover is handled at the application layer
+ */
+export class PubSubClient {
+  private httpClient: HttpClient;
+  private wsConfig: Partial<WSClientConfig>;
+
+  constructor(httpClient: HttpClient, wsConfig: Partial<WSClientConfig> = {}) {
+    this.httpClient = httpClient;
+    this.wsConfig = wsConfig;
+  }
+
+  /**
+   * Publish a message to a topic via HTTP
+   */
+  async publish(topic: string, data: string | Uint8Array): Promise<void> {
+    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,
+      },
+      {
+        timeout: 30000,
+      }
+    );
+  }
+
+  /**
+   * List active topics in the current namespace
+   */
+  async topics(): Promise<string[]> {
+    const response = await this.httpClient.get<{ topics: string[] }>(
+      "/v1/pubsub/topics"
+    );
+    return response.topics || [];
+  }
+
+  /**
+   * Get current presence for a topic without subscribing
+   */
+  async getPresence(topic: string): Promise<PresenceResponse> {
+    const response = await this.httpClient.get<PresenceResponse>(
+      `/v1/pubsub/presence?topic=${encodeURIComponent(topic)}`
+    );
+    return response;
+  }
+
+  /**
+   * Subscribe to a topic via WebSocket
+   * Creates one WebSocket connection per topic
+   */
+  async subscribe(
+    topic: string,
+    options: SubscribeOptions = {}
+  ): Promise<Subscription> {
+    // 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);
+
+    // Handle presence options
+    let presence: PresenceOptions | undefined;
+    if (options.presence?.enabled) {
+      presence = options.presence;
+      wsUrl.searchParams.set("presence", "true");
+      wsUrl.searchParams.set("member_id", presence.memberId);
+      if (presence.meta) {
+        wsUrl.searchParams.set("member_meta", JSON.stringify(presence.meta));
+      }
+    }
+
+    const authToken = this.httpClient.getApiKey() ?? this.httpClient.getToken();
+
+    // Create WebSocket client
+    const wsClient = new WSClient({
+      ...this.wsConfig,
+      wsURL: wsUrl.toString(),
+      authToken,
+    });
+
+    await wsClient.connect();
+
+    // Create subscription wrapper
+    const subscription = new Subscription(wsClient, topic, presence, () =>
+      this.getPresence(topic)
+    );
+
+    if (options.onMessage) {
+      subscription.onMessage(options.onMessage);
+    }
+    if (options.onError) {
+      subscription.onError(options.onError);
+    }
+    if (options.onClose) {
+      subscription.onClose(options.onClose);
+    }
+
+    return subscription;
+  }
+}
+
+/**
+ * Subscription represents an active WebSocket subscription to a topic
+ */
+export class Subscription {
+  private wsClient: WSClient;
+  private topic: string;
+  private presenceOptions?: PresenceOptions;
+  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: ((code: number, reason: string) => void) | null = null;
+  private getPresenceFn: () => Promise<PresenceResponse>;
+
+  constructor(
+    wsClient: WSClient,
+    topic: string,
+    presenceOptions: PresenceOptions | undefined,
+    getPresenceFn: () => Promise<PresenceResponse>
+  ) {
+    this.wsClient = wsClient;
+    this.topic = topic;
+    this.presenceOptions = presenceOptions;
+    this.getPresenceFn = getPresenceFn;
+
+    // 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");
+        }
+
+        // Handle presence events
+        if (
+          envelope.type === "presence.join" ||
+          envelope.type === "presence.leave"
+        ) {
+          if (!envelope.member_id) {
+            console.warn("[Subscription] Presence event missing member_id");
+            return;
+          }
+
+          const presenceMember: PresenceMember = {
+            memberId: envelope.member_id,
+            joinedAt: envelope.timestamp,
+            meta: envelope.meta,
+          };
+
+          if (
+            envelope.type === "presence.join" &&
+            this.presenceOptions?.onJoin
+          ) {
+            this.presenceOptions.onJoin(presenceMember);
+          } else if (
+            envelope.type === "presence.leave" &&
+            this.presenceOptions?.onLeave
+          ) {
+            this.presenceOptions.onLeave(presenceMember);
+          }
+          return; // Don't call regular onMessage for presence events
+        }
+
+        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: PubSubMessage = {
+          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);
+
+    // Register error handler
+    this.wsErrorHandler = (error) => {
+      this.errorHandlers.forEach((handler) => handler(error));
+    };
+    this.wsClient.onError(this.wsErrorHandler);
+
+    // Register close handler
+    this.wsCloseHandler = (code: number, reason: string) => {
+      this.closeHandlers.forEach((handler) => handler(code, reason));
+    };
+    this.wsClient.onClose(this.wsCloseHandler);
+  }
+
+  /**
+   * Get current presence (requires presence.enabled on subscribe)
+   */
+  async getPresence(): Promise<PresenceMember[]> {
+    if (!this.presenceOptions?.enabled) {
+      throw new Error("Presence is not enabled for this subscription");
+    }
+
+    const response = await this.getPresenceFn();
+    return response.members;
+  }
+
+  /**
+   * Check if presence is enabled for this subscription
+   */
+  hasPresence(): boolean {
+    return !!this.presenceOptions?.enabled;
+  }
+
+  /**
+   * Register message handler
+   */
+  onMessage(handler: MessageHandler): () => void {
+    this.messageHandlers.add(handler);
+    return () => this.messageHandlers.delete(handler);
+  }
+
+  /**
+   * Register error handler
+   */
+  onError(handler: ErrorHandler): () => void {
+    this.errorHandlers.add(handler);
+    return () => this.errorHandlers.delete(handler);
+  }
+
+  /**
+   * Register close handler
+   */
+  onClose(handler: CloseHandler): () => void {
+    this.closeHandlers.add(handler);
+    return () => this.closeHandlers.delete(handler);
+  }
+
+  /**
+   * 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.isClosed && this.wsClient.isConnected();
+  }
+}

package/src/pubsub/index.ts

@@ -0,0 +1,12 @@
+export { PubSubClient, Subscription } from "./client";
+export type {
+  PubSubMessage,
+  RawEnvelope,
+  MessageHandler,
+  ErrorHandler,
+  CloseHandler,
+  PresenceMember,
+  PresenceResponse,
+  PresenceOptions,
+  SubscribeOptions,
+} from "./types";