@debros/orama 0.122.4-nightly

package/dist/index.d.ts

@@ -0,0 +1,1334 @@
+import WebSocket from 'isomorphic-ws';
+
+declare class SDKError extends Error {
+    readonly httpStatus: number;
+    readonly code: string;
+    readonly details: Record<string, any>;
+    constructor(message: string, httpStatus?: number, code?: string, details?: Record<string, any>);
+    static fromResponse(status: number, body: any, message?: string): SDKError;
+    toJSON(): {
+        name: string;
+        message: string;
+        httpStatus: number;
+        code: string;
+        details: Record<string, any>;
+    };
+}
+
+/**
+ * Context provided to the onNetworkError callback
+ */
+interface NetworkErrorContext {
+    method: "GET" | "POST" | "PUT" | "DELETE" | "WS";
+    path: string;
+    isRetry: boolean;
+    attempt: number;
+}
+/**
+ * Callback invoked when a network error occurs.
+ * Use this to trigger gateway failover or other error handling.
+ */
+type NetworkErrorCallback = (error: SDKError, context: NetworkErrorContext) => void;
+interface HttpClientConfig {
+    baseURL: string;
+    timeout?: number;
+    maxRetries?: number;
+    retryDelayMs?: number;
+    fetch?: typeof fetch;
+    /**
+     * Enable debug logging (includes full SQL queries and args). Default: false
+     */
+    debug?: boolean;
+    /**
+     * Callback invoked on network errors (after all retries exhausted).
+     * Use this to trigger gateway failover at the application layer.
+     */
+    onNetworkError?: NetworkErrorCallback;
+}
+declare class HttpClient {
+    private baseURL;
+    private timeout;
+    private maxRetries;
+    private retryDelayMs;
+    private fetch;
+    private apiKey?;
+    private jwt?;
+    private debug;
+    private onNetworkError?;
+    constructor(config: HttpClientConfig);
+    /**
+     * Set the network error callback
+     */
+    setOnNetworkError(callback: NetworkErrorCallback | undefined): void;
+    setApiKey(apiKey?: string): void;
+    setJwt(jwt?: string): void;
+    private getAuthHeaders;
+    private getAuthToken;
+    getApiKey(): string | undefined;
+    /**
+     * Get the base URL
+     */
+    getBaseURL(): string;
+    request<T = any>(method: "GET" | "POST" | "PUT" | "DELETE", path: string, options?: {
+        body?: any;
+        headers?: Record<string, string>;
+        query?: Record<string, string | number | boolean>;
+        timeout?: number;
+    }): Promise<T>;
+    private requestWithRetry;
+    get<T = any>(path: string, options?: Omit<Parameters<typeof this.request>[2], "body">): Promise<T>;
+    post<T = any>(path: string, body?: any, options?: Omit<Parameters<typeof this.request>[2], "body">): Promise<T>;
+    put<T = any>(path: string, body?: any, options?: Omit<Parameters<typeof this.request>[2], "body">): Promise<T>;
+    delete<T = any>(path: string, options?: Omit<Parameters<typeof this.request>[2], "body">): Promise<T>;
+    /**
+     * Upload a file using multipart/form-data
+     * This is a special method for file uploads that bypasses JSON serialization
+     */
+    uploadFile<T = any>(path: string, formData: FormData, options?: {
+        timeout?: number;
+    }): Promise<T>;
+    /**
+     * Get a binary response (returns Response object for streaming)
+     */
+    getBinary(path: string): Promise<Response>;
+    getToken(): string | undefined;
+}
+
+interface AuthConfig {
+    apiKey?: string;
+    jwt?: string;
+}
+interface WhoAmI {
+    address?: string;
+    namespace?: string;
+    authenticated: boolean;
+}
+interface StorageAdapter {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string): Promise<void>;
+    clear(): Promise<void>;
+}
+declare class MemoryStorage implements StorageAdapter {
+    private storage;
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string): Promise<void>;
+    clear(): Promise<void>;
+}
+declare class LocalStorageAdapter implements StorageAdapter {
+    private prefix;
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string): Promise<void>;
+    clear(): Promise<void>;
+}
+
+declare class AuthClient$1 {
+    private httpClient;
+    private storage;
+    private currentApiKey?;
+    private currentJwt?;
+    constructor(config: {
+        httpClient: HttpClient;
+        storage?: StorageAdapter;
+        apiKey?: string;
+        jwt?: string;
+    });
+    setApiKey(apiKey: string): void;
+    setJwt(jwt: string): void;
+    getToken(): string | undefined;
+    whoami(): Promise<WhoAmI>;
+    /**
+     * Exchange a stored refresh token for a fresh access token.
+     *
+     * Pulls the refresh token (and the namespace it was issued for) out of
+     * storage — both are persisted by `verify()` after a successful wallet
+     * sign-in. The gateway returns a new access token and may rotate the
+     * refresh token; we persist the rotated one if present.
+     *
+     * Bug #239: previously this method (a) sent no body and (b) read the
+     * wrong response field, so the call always 400-ed AND silently wrote
+     * `undefined` as the in-memory JWT. Both issues fixed.
+     */
+    refresh(): Promise<string>;
+    /**
+     * Logout user and clear JWT, but preserve API key
+     * Use this for user logout in apps where API key is app-level credential
+     */
+    logoutUser(): Promise<void>;
+    /**
+     * Full logout - clears both JWT and API key
+     * Use this to completely reset authentication state
+     */
+    logout(): Promise<void>;
+    clear(): Promise<void>;
+    /**
+     * Request a challenge nonce for wallet authentication
+     */
+    challenge(params: {
+        wallet: string;
+        purpose?: string;
+        namespace?: string;
+    }): Promise<{
+        nonce: string;
+        wallet: string;
+        namespace: string;
+        expires_at: string;
+    }>;
+    /**
+     * Verify wallet signature and get JWT token
+     */
+    verify(params: {
+        wallet: string;
+        nonce: string;
+        signature: string;
+        namespace?: string;
+        chain_type?: "ETH" | "SOL";
+    }): Promise<{
+        access_token: string;
+        refresh_token?: string;
+        subject: string;
+        namespace: string;
+        api_key?: string;
+        expires_in?: number;
+        token_type?: string;
+    }>;
+    /**
+     * Get API key for wallet (creates namespace ownership)
+     */
+    getApiKey(params: {
+        wallet: string;
+        nonce: string;
+        signature: string;
+        namespace?: string;
+        chain_type?: "ETH" | "SOL";
+    }): Promise<{
+        api_key: string;
+        namespace: string;
+        wallet: string;
+    }>;
+}
+
+declare class QueryBuilder {
+    private httpClient;
+    private table;
+    private options;
+    constructor(httpClient: HttpClient, table: string);
+    select(...columns: string[]): this;
+    innerJoin(table: string, on: string): this;
+    leftJoin(table: string, on: string): this;
+    rightJoin(table: string, on: string): this;
+    where(expr: string, args?: any[]): this;
+    andWhere(expr: string, args?: any[]): this;
+    orWhere(expr: string, args?: any[]): this;
+    groupBy(...columns: string[]): this;
+    orderBy(...columns: string[]): this;
+    limit(n: number): this;
+    offset(n: number): this;
+    getMany<T = any>(ctx?: any): Promise<T[]>;
+    getOne<T = any>(ctx?: any): Promise<T | null>;
+    count(): Promise<number>;
+}
+
+interface Entity {
+    TableName(): string;
+}
+interface QueryResponse {
+    columns?: string[];
+    rows?: any[][];
+    count?: number;
+    items?: any[];
+}
+interface TransactionOp {
+    kind: "exec" | "query";
+    sql: string;
+    args?: any[];
+}
+interface TransactionRequest {
+    statements?: string[];
+    ops?: TransactionOp[];
+    return_results?: boolean;
+}
+interface SelectOptions {
+    select?: string[];
+    joins?: Array<{
+        kind: "INNER" | "LEFT" | "RIGHT" | "FULL";
+        table: string;
+        on: string;
+    }>;
+    where?: Array<{
+        conj?: "AND" | "OR";
+        expr: string;
+        args?: any[];
+    }>;
+    group_by?: string[];
+    order_by?: string[];
+    limit?: number;
+    offset?: number;
+    one?: boolean;
+}
+type FindOptions = Omit<SelectOptions, "select" | "joins" | "one">;
+interface ColumnDefinition {
+    name: string;
+    isPrimaryKey?: boolean;
+    isAutoIncrement?: boolean;
+}
+declare function extractTableName(entity: Entity | string): string;
+declare function extractPrimaryKey(entity: any): string | undefined;
+
+declare class Repository<T extends Record<string, any>> {
+    private httpClient;
+    private tableName;
+    private primaryKey;
+    constructor(httpClient: HttpClient, tableName: string, primaryKey?: string);
+    createQueryBuilder(): QueryBuilder;
+    find(criteria?: Record<string, any>, options?: FindOptions): Promise<T[]>;
+    findOne(criteria: Record<string, any>): Promise<T | null>;
+    save(entity: T): Promise<T>;
+    remove(entity: T | Record<string, any>): Promise<void>;
+    private buildInsertSql;
+    private buildInsertArgs;
+    private buildUpdateSql;
+    private buildUpdateArgs;
+}
+
+declare class DBClient {
+    private httpClient;
+    constructor(httpClient: HttpClient);
+    /**
+     * Execute a write/DDL SQL statement.
+     */
+    exec(sql: string, args?: any[]): Promise<{
+        rows_affected: number;
+        last_insert_id?: number;
+    }>;
+    /**
+     * Execute a SELECT query.
+     */
+    query<T = any>(sql: string, args?: any[]): Promise<T[]>;
+    /**
+     * Find rows with map-based criteria.
+     */
+    find<T = any>(table: string, criteria?: Record<string, any>, options?: FindOptions): Promise<T[]>;
+    /**
+     * Find a single row with map-based criteria.
+     */
+    findOne<T = any>(table: string, criteria: Record<string, any>): Promise<T | null>;
+    /**
+     * Create a fluent QueryBuilder for complex SELECT queries.
+     */
+    createQueryBuilder(table: string): QueryBuilder;
+    /**
+     * Create a Repository for entity-based operations.
+     */
+    repository<T extends Record<string, any>>(tableName: string, primaryKey?: string): Repository<T>;
+    /**
+     * Execute multiple operations atomically.
+     */
+    transaction(ops: TransactionOp[], returnResults?: boolean): Promise<any[]>;
+    /**
+     * Create a table from DDL SQL.
+     */
+    createTable(schema: string): Promise<void>;
+    /**
+     * Drop a table.
+     */
+    dropTable(table: string): Promise<void>;
+    /**
+     * Get current database schema.
+     */
+    getSchema(): Promise<any>;
+}
+
+interface WSClientConfig {
+    wsURL: string;
+    timeout?: number;
+    authToken?: string;
+    WebSocket?: typeof WebSocket;
+    /**
+     * Callback invoked on WebSocket errors.
+     * Use this to trigger gateway failover at the application layer.
+     */
+    onNetworkError?: NetworkErrorCallback;
+}
+type WSMessageHandler = (data: string) => void;
+type WSErrorHandler = (error: Error) => void;
+type WSCloseHandler = (code: number, reason: string) => void;
+type WSOpenHandler = () => void;
+/**
+ * Simple WebSocket client with minimal abstractions
+ * No complex reconnection, no failover - keep it simple
+ * Gateway failover is handled at the application layer
+ */
+declare class WSClient {
+    private wsURL;
+    private timeout;
+    private authToken?;
+    private WebSocketClass;
+    private onNetworkError?;
+    private ws?;
+    private messageHandlers;
+    private errorHandlers;
+    private closeHandlers;
+    private openHandlers;
+    private isClosed;
+    constructor(config: WSClientConfig);
+    /**
+     * Set the network error callback
+     */
+    setOnNetworkError(callback: NetworkErrorCallback | undefined): void;
+    /**
+     * Get the current WebSocket URL
+     */
+    get url(): string;
+    /**
+     * Connect to WebSocket server
+     */
+    connect(): Promise<void>;
+    /**
+     * Build WebSocket URL with auth token
+     */
+    private buildWSUrl;
+    /**
+     * Register message handler
+     */
+    onMessage(handler: WSMessageHandler): () => void;
+    /**
+     * Unregister message handler
+     */
+    offMessage(handler: WSMessageHandler): void;
+    /**
+     * Register error handler
+     */
+    onError(handler: WSErrorHandler): () => void;
+    /**
+     * Unregister error handler
+     */
+    offError(handler: WSErrorHandler): void;
+    /**
+     * Register close handler
+     */
+    onClose(handler: WSCloseHandler): () => void;
+    /**
+     * Unregister close handler
+     */
+    offClose(handler: WSCloseHandler): void;
+    /**
+     * Register open handler
+     */
+    onOpen(handler: WSOpenHandler): () => void;
+    /**
+     * Send data through WebSocket
+     */
+    send(data: string): void;
+    /**
+     * Close WebSocket connection
+     */
+    close(): void;
+    /**
+     * Check if WebSocket is connected
+     */
+    isConnected(): boolean;
+    /**
+     * Update auth token
+     */
+    setAuthToken(token?: string): void;
+}
+
+interface PubSubMessage {
+    data: string;
+    topic: string;
+    timestamp: number;
+}
+interface PresenceMember {
+    memberId: string;
+    joinedAt: number;
+    meta?: Record<string, unknown>;
+}
+interface PresenceResponse {
+    topic: string;
+    members: PresenceMember[];
+    count: number;
+}
+interface PresenceOptions {
+    enabled: boolean;
+    memberId: string;
+    meta?: Record<string, unknown>;
+    onJoin?: (member: PresenceMember) => void;
+    onLeave?: (member: PresenceMember) => void;
+}
+interface SubscribeOptions {
+    onMessage?: MessageHandler;
+    onError?: ErrorHandler;
+    onClose?: CloseHandler;
+    presence?: PresenceOptions;
+}
+type MessageHandler = (message: PubSubMessage) => void;
+type ErrorHandler = (error: Error) => void;
+type CloseHandler = (code: number, reason: string) => void;
+
+/**
+ * Simple PubSub client - one WebSocket connection per topic
+ * Gateway failover is handled at the application layer
+ */
+declare class PubSubClient {
+    private httpClient;
+    private wsConfig;
+    constructor(httpClient: HttpClient, wsConfig?: Partial<WSClientConfig>);
+    /**
+     * Publish a message to a topic via HTTP
+     */
+    publish(topic: string, data: string | Uint8Array): Promise<void>;
+    /**
+     * List active topics in the current namespace
+     */
+    topics(): Promise<string[]>;
+    /**
+     * Get current presence for a topic without subscribing
+     */
+    getPresence(topic: string): Promise<PresenceResponse>;
+    /**
+     * Subscribe to a topic via WebSocket
+     * Creates one WebSocket connection per topic
+     */
+    subscribe(topic: string, options?: SubscribeOptions): Promise<Subscription>;
+}
+/**
+ * Subscription represents an active WebSocket subscription to a topic
+ */
+declare class Subscription {
+    private wsClient;
+    private topic;
+    private presenceOptions?;
+    private messageHandlers;
+    private errorHandlers;
+    private closeHandlers;
+    private isClosed;
+    private wsMessageHandler;
+    private wsErrorHandler;
+    private wsCloseHandler;
+    private getPresenceFn;
+    constructor(wsClient: WSClient, topic: string, presenceOptions: PresenceOptions | undefined, getPresenceFn: () => Promise<PresenceResponse>);
+    /**
+     * Get current presence (requires presence.enabled on subscribe)
+     */
+    getPresence(): Promise<PresenceMember[]>;
+    /**
+     * Check if presence is enabled for this subscription
+     */
+    hasPresence(): boolean;
+    /**
+     * Register message handler
+     */
+    onMessage(handler: MessageHandler): () => void;
+    /**
+     * Register error handler
+     */
+    onError(handler: ErrorHandler): () => void;
+    /**
+     * Register close handler
+     */
+    onClose(handler: CloseHandler): () => void;
+    /**
+     * Close subscription and underlying WebSocket
+     */
+    close(): void;
+    /**
+     * Check if subscription is active
+     */
+    isConnected(): boolean;
+}
+
+interface PeerInfo {
+    id: string;
+    addresses: string[];
+    lastSeen?: string;
+}
+interface NetworkStatus {
+    node_id: string;
+    connected: boolean;
+    peer_count: number;
+    database_size: number;
+    uptime: number;
+}
+interface ProxyRequest {
+    url: string;
+    method: string;
+    headers?: Record<string, string>;
+    body?: string;
+}
+interface ProxyResponse {
+    status_code: number;
+    headers: Record<string, string>;
+    body: string;
+    error?: string;
+}
+declare class NetworkClient {
+    private httpClient;
+    constructor(httpClient: HttpClient);
+    /**
+     * Check gateway health.
+     */
+    health(): Promise<boolean>;
+    /**
+     * Get network status.
+     */
+    status(): Promise<NetworkStatus>;
+    /**
+     * Get connected peers.
+     */
+    peers(): Promise<PeerInfo[]>;
+    /**
+     * Connect to a peer.
+     */
+    connect(peerAddr: string): Promise<void>;
+    /**
+     * Disconnect from a peer.
+     */
+    disconnect(peerId: string): Promise<void>;
+    /**
+     * 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
+     * ```
+     */
+    proxyAnon(request: ProxyRequest): Promise<ProxyResponse>;
+}
+
+interface CacheGetRequest {
+    dmap: string;
+    key: string;
+}
+interface CacheGetResponse {
+    key: string;
+    value: any;
+    dmap: string;
+}
+interface CachePutRequest {
+    dmap: string;
+    key: string;
+    value: any;
+    ttl?: string;
+}
+interface CachePutResponse {
+    status: string;
+    key: string;
+    dmap: string;
+}
+interface CacheDeleteRequest {
+    dmap: string;
+    key: string;
+}
+interface CacheDeleteResponse {
+    status: string;
+    key: string;
+    dmap: string;
+}
+interface CacheMultiGetRequest {
+    dmap: string;
+    keys: string[];
+}
+interface CacheMultiGetResponse {
+    results: Array<{
+        key: string;
+        value: any;
+    }>;
+    dmap: string;
+}
+interface CacheScanRequest {
+    dmap: string;
+    match?: string;
+}
+interface CacheScanResponse {
+    keys: string[];
+    count: number;
+    dmap: string;
+}
+interface CacheHealthResponse {
+    status: string;
+    service: string;
+}
+declare class CacheClient {
+    private httpClient;
+    constructor(httpClient: HttpClient);
+    /**
+     * Check cache service health
+     */
+    health(): Promise<CacheHealthResponse>;
+    /**
+     * Get a value from cache
+     * Returns null if the key is not found (cache miss/expired), which is normal behavior
+     */
+    get(dmap: string, key: string): Promise<CacheGetResponse | null>;
+    /**
+     * Put a value into cache
+     */
+    put(dmap: string, key: string, value: any, ttl?: string): Promise<CachePutResponse>;
+    /**
+     * Delete a value from cache
+     */
+    delete(dmap: string, key: string): Promise<CacheDeleteResponse>;
+    /**
+     * Get multiple values from cache in a single request
+     * Returns a map of key -> value (or null if not found)
+     * Gracefully handles 404 errors (endpoint not implemented) by returning empty results
+     */
+    multiGet(dmap: string, keys: string[]): Promise<Map<string, any | null>>;
+    /**
+     * Scan keys in a distributed map, optionally matching a regex pattern
+     */
+    scan(dmap: string, match?: string): Promise<CacheScanResponse>;
+}
+
+interface StorageUploadResponse {
+    cid: string;
+    name: string;
+    size: number;
+}
+interface StoragePinRequest {
+    cid: string;
+    name?: string;
+}
+interface StoragePinResponse {
+    cid: string;
+    name: string;
+}
+interface StorageStatus {
+    cid: string;
+    name: string;
+    status: string;
+    replication_min: number;
+    replication_max: number;
+    replication_factor: number;
+    peers: string[];
+    error?: string;
+}
+declare class StorageClient {
+    private httpClient;
+    constructor(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 });
+     * ```
+     */
+    upload(file: File | Blob | ArrayBuffer | Uint8Array | ReadableStream<Uint8Array>, name?: string, options?: {
+        pin?: boolean;
+    }): Promise<StorageUploadResponse>;
+    /**
+     * Pin an existing CID
+     *
+     * @param cid - Content ID to pin
+     * @param name - Optional name for the pin
+     * @returns Pin result
+     */
+    pin(cid: string, name?: string): Promise<StoragePinResponse>;
+    /**
+     * Get the pin status for a CID
+     *
+     * @param cid - Content ID to check
+     * @returns Pin status information
+     */
+    status(cid: string): Promise<StorageStatus>;
+    /**
+     * 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
+     * }
+     * ```
+     */
+    get(cid: string): Promise<ReadableStream<Uint8Array>>;
+    /**
+     * 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
+     * ```
+     */
+    getBinary(cid: string): Promise<Response>;
+    /**
+     * Unpin a CID
+     *
+     * @param cid - Content ID to unpin
+     */
+    unpin(cid: string): Promise<void>;
+}
+
+/**
+ * Functions Client
+ * Client for calling serverless functions on the Orama Network
+ */
+
+interface FunctionsClientConfig {
+    /**
+     * Base URL for the functions gateway
+     * Defaults to using the same baseURL as the HTTP client
+     */
+    gatewayURL?: string;
+    /**
+     * Namespace for the functions
+     */
+    namespace: string;
+}
+declare class FunctionsClient {
+    private httpClient;
+    private gatewayURL?;
+    private namespace;
+    constructor(httpClient: HttpClient, config?: FunctionsClientConfig);
+    /**
+     * Invoke a serverless function by name
+     *
+     * @param functionName - Name of the function to invoke
+     * @param input - Input payload for the function
+     * @returns The function response
+     */
+    invoke<TInput = any, TOutput = any>(functionName: string, input: TInput): Promise<TOutput>;
+}
+
+/** A guardian node endpoint. */
+interface GuardianEndpoint {
+    address: string;
+    port: number;
+}
+/** V1 push response. */
+interface PushResponse {
+    status: string;
+}
+/** V1 pull response. */
+interface PullResponse {
+    share: string;
+}
+/** V2 store response. */
+interface StoreSecretResponse {
+    status: string;
+    name: string;
+    version: number;
+}
+/** V2 get response. */
+interface GetSecretResponse {
+    share: string;
+    name: string;
+    version: number;
+    created_ns: number;
+    updated_ns: number;
+}
+/** V2 delete response. */
+interface DeleteSecretResponse {
+    status: string;
+    name: string;
+}
+/** V2 list response. */
+interface ListSecretsResponse {
+    secrets: SecretEntry[];
+}
+/** An entry in the list secrets response. */
+interface SecretEntry {
+    name: string;
+    version: number;
+    size: number;
+}
+/** Health check response. */
+interface HealthResponse {
+    status: string;
+    version: string;
+}
+/** Status response. */
+interface StatusResponse {
+    status: string;
+    version: string;
+    data_dir: string;
+    client_port: number;
+    peer_port: number;
+}
+/** Guardian info response. */
+interface GuardianInfo {
+    guardians: Array<{
+        address: string;
+        port: number;
+    }>;
+    threshold: number;
+    total: number;
+}
+/** Challenge response from auth endpoint. */
+interface ChallengeResponse {
+    nonce: string;
+    created_ns: number;
+    tag: string;
+}
+/** Session token response from auth endpoint. */
+interface SessionResponse {
+    identity: string;
+    expiry_ns: number;
+    tag: string;
+}
+/** Error classification codes. */
+type GuardianErrorCode = 'TIMEOUT' | 'NOT_FOUND' | 'AUTH' | 'SERVER_ERROR' | 'NETWORK' | 'CONFLICT';
+/** Fan-out result for a single guardian. */
+interface FanOutResult<T> {
+    endpoint: GuardianEndpoint;
+    result: T | null;
+    error: string | null;
+    errorCode?: GuardianErrorCode;
+}
+
+/** Configuration for VaultClient. */
+interface VaultConfig {
+    /** Guardian endpoints to connect to. */
+    guardians: GuardianEndpoint[];
+    /** HMAC key for authentication (derived from user's secret). */
+    hmacKey: Uint8Array;
+    /** Identity hash (hex string, 64 chars). */
+    identityHex: string;
+    /** Request timeout in ms (default: 10000). */
+    timeoutMs?: number;
+}
+/** Metadata for a stored secret. */
+interface SecretMeta {
+    name: string;
+    version: number;
+    size: number;
+}
+/** Result of a store operation. */
+interface StoreResult {
+    /** Number of guardians that acknowledged. */
+    ackCount: number;
+    /** Total guardians contacted. */
+    totalContacted: number;
+    /** Number of failures. */
+    failCount: number;
+    /** Whether write quorum was met. */
+    quorumMet: boolean;
+    /** Per-guardian results. */
+    guardianResults: GuardianResult[];
+}
+/** Result of a retrieve operation. */
+interface RetrieveResult {
+    /** The reconstructed secret data. */
+    data: Uint8Array;
+    /** Number of shares collected. */
+    sharesCollected: number;
+}
+/** Result of a list operation. */
+interface ListResult {
+    secrets: SecretMeta[];
+}
+/** Result of a delete operation. */
+interface DeleteResult {
+    /** Number of guardians that acknowledged. */
+    ackCount: number;
+    totalContacted: number;
+    quorumMet: boolean;
+}
+/** Per-guardian operation result. */
+interface GuardianResult {
+    endpoint: string;
+    success: boolean;
+    error?: string;
+}
+
+/**
+ * High-level client for the orama-vault distributed secrets store.
+ *
+ * Handles:
+ * - Authentication with guardian nodes
+ * - Shamir split/combine for data distribution
+ * - Quorum-based writes and reads
+ * - V2 CRUD operations (store, retrieve, list, delete)
+ */
+declare class VaultClient {
+    private config;
+    private auth;
+    constructor(config: VaultConfig);
+    /**
+     * Store a secret across guardian nodes using Shamir splitting.
+     *
+     * @param name - Secret name (alphanumeric, _, -, max 128 chars)
+     * @param data - Secret data to store
+     * @param version - Monotonic version number (must be > previous)
+     */
+    store(name: string, data: Uint8Array, version: number): Promise<StoreResult>;
+    /**
+     * Retrieve and reconstruct a secret from guardian nodes.
+     *
+     * @param name - Secret name
+     */
+    retrieve(name: string): Promise<RetrieveResult>;
+    /**
+     * List all secrets for this identity.
+     * Queries the first reachable guardian (metadata is replicated).
+     */
+    list(): Promise<ListResult>;
+    /**
+     * Delete a secret from all guardian nodes.
+     *
+     * @param name - Secret name to delete
+     */
+    delete(name: string): Promise<DeleteResult>;
+    /** Clear all cached auth sessions. */
+    clearSessions(): void;
+}
+
+/**
+ * Serverless Functions Types
+ * Type definitions for calling serverless functions on the Orama Network
+ */
+/**
+ * Generic response from a serverless function
+ */
+interface FunctionResponse<T = unknown> {
+    success: boolean;
+    error?: string;
+    data?: T;
+}
+/**
+ * Standard success/error response used by many functions
+ */
+interface SuccessResponse {
+    success: boolean;
+    error?: string;
+}
+
+declare class GuardianError extends Error {
+    readonly code: GuardianErrorCode;
+    constructor(code: GuardianErrorCode, message: string);
+}
+/**
+ * HTTP client for a single orama-vault guardian node.
+ * Supports V1 (push/pull) and V2 (CRUD secrets) endpoints.
+ */
+declare class GuardianClient {
+    private baseUrl;
+    private timeoutMs;
+    private sessionToken;
+    constructor(endpoint: GuardianEndpoint, timeoutMs?: number);
+    /** Set a session token for authenticated V2 requests. */
+    setSessionToken(token: string): void;
+    /** Get the current session token. */
+    getSessionToken(): string | null;
+    /** Clear the session token. */
+    clearSessionToken(): void;
+    /** GET /v1/vault/health */
+    health(): Promise<HealthResponse>;
+    /** GET /v1/vault/status */
+    status(): Promise<StatusResponse>;
+    /** GET /v1/vault/guardians */
+    guardians(): Promise<GuardianInfo>;
+    /** POST /v1/vault/push — store a share (V1). */
+    push(identity: string, share: Uint8Array): Promise<PushResponse>;
+    /** POST /v1/vault/pull — retrieve a share (V1). */
+    pull(identity: string): Promise<Uint8Array>;
+    /** Check if this guardian is reachable. */
+    isReachable(): Promise<boolean>;
+    /** POST /v2/vault/auth/challenge — request an auth challenge. */
+    requestChallenge(identity: string): Promise<ChallengeResponse>;
+    /** POST /v2/vault/auth/session — exchange challenge for session token. */
+    createSession(identity: string, nonce: string, created_ns: number, tag: string): Promise<SessionResponse>;
+    /** PUT /v2/vault/secrets/{name} — store a secret. Requires session token. */
+    putSecret(name: string, share: Uint8Array, version: number): Promise<StoreSecretResponse>;
+    /** GET /v2/vault/secrets/{name} — retrieve a secret. Requires session token. */
+    getSecret(name: string): Promise<{
+        share: Uint8Array;
+        name: string;
+        version: number;
+        created_ns: number;
+        updated_ns: number;
+    }>;
+    /** DELETE /v2/vault/secrets/{name} — delete a secret. Requires session token. */
+    deleteSecret(name: string): Promise<DeleteSecretResponse>;
+    /** GET /v2/vault/secrets — list all secrets. Requires session token. */
+    listSecrets(): Promise<ListSecretsResponse>;
+    private authedRequest;
+    private get;
+    private post;
+}
+
+/**
+ * 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>`
+ */
+declare class AuthClient {
+    private sessions;
+    private identityHex;
+    private timeoutMs;
+    constructor(identityHex: string, timeoutMs?: number);
+    /**
+     * Authenticate with a guardian and cache the session token.
+     * Returns a GuardianClient with the session token set.
+     */
+    authenticate(endpoint: GuardianEndpoint): Promise<GuardianClient>;
+    /**
+     * Authenticate with multiple guardians in parallel.
+     * Returns authenticated GuardianClients for all that succeed.
+     */
+    authenticateAll(endpoints: GuardianEndpoint[]): Promise<{
+        client: GuardianClient;
+        endpoint: GuardianEndpoint;
+    }[]>;
+    /** Clear all cached sessions. */
+    clearSessions(): void;
+    /** Get the identity hex string. */
+    getIdentityHex(): string;
+}
+
+/**
+ * Fan out an operation to multiple guardians in parallel.
+ * Returns results from all guardians (both successes and failures).
+ */
+declare function fanOut<T>(guardians: GuardianEndpoint[], operation: (client: GuardianClient) => Promise<T>): Promise<FanOutResult<T>[]>;
+/**
+ * Fan out an indexed operation to multiple guardians in parallel.
+ * The operation receives the index so each guardian can get a different share.
+ */
+declare function fanOutIndexed<T>(guardians: GuardianEndpoint[], operation: (client: GuardianClient, index: number) => Promise<T>): Promise<FanOutResult<T>[]>;
+/**
+ * Race a promise against a timeout.
+ */
+declare function withTimeout<T>(promise: Promise<T>, ms: number): Promise<T>;
+/**
+ * Retry a function with exponential backoff.
+ * Does not retry auth or not-found errors.
+ */
+declare function withRetry<T>(fn: () => Promise<T>, attempts?: number): Promise<T>;
+
+/**
+ * Quorum calculations for distributed vault operations.
+ * Must match orama-vault (Zig side).
+ */
+/** Adaptive Shamir threshold: max(3, floor(N/3)). */
+declare function adaptiveThreshold(n: number): number;
+/** Write quorum: ceil(2N/3). Requires majority for consistency. */
+declare function writeQuorum(n: number): number;
+
+/**
+ * AES-256-GCM Encryption
+ *
+ * Implements authenticated encryption using AES-256 in Galois/Counter Mode.
+ * Uses @noble/ciphers for platform-agnostic, audited cryptographic operations.
+ *
+ * Features:
+ * - Authenticated encryption (confidentiality + integrity)
+ * - 256-bit keys for strong security
+ * - 96-bit nonces (randomly generated)
+ * - 128-bit authentication tags
+ *
+ * Security considerations:
+ * - Never reuse a nonce with the same key
+ * - Nonces are randomly generated and prepended to ciphertext
+ * - Authentication tags are verified before decryption
+ */
+/**
+ * Size constants
+ */
+declare const KEY_SIZE = 32;
+declare const NONCE_SIZE = 12;
+declare const TAG_SIZE = 16;
+/**
+ * Encrypted data structure
+ */
+interface EncryptedData {
+    /** Ciphertext including authentication tag */
+    ciphertext: Uint8Array;
+    /** Nonce used for encryption */
+    nonce: Uint8Array;
+    /** Additional authenticated data (optional) */
+    aad?: Uint8Array;
+}
+/**
+ * Serialized encrypted data (nonce prepended to ciphertext)
+ */
+interface SerializedEncryptedData {
+    /** Combined nonce + ciphertext + tag */
+    data: Uint8Array;
+    /** Additional authenticated data (optional) */
+    aad?: Uint8Array;
+}
+/**
+ * Encrypts data using AES-256-GCM
+ */
+declare function encrypt(plaintext: Uint8Array, key: Uint8Array, aad?: Uint8Array): EncryptedData;
+/**
+ * Decrypts data using AES-256-GCM
+ */
+declare function decrypt(encryptedData: EncryptedData, key: Uint8Array): Uint8Array;
+/**
+ * Encrypts a string message
+ */
+declare function encryptString(message: string, key: Uint8Array, aad?: Uint8Array): EncryptedData;
+/**
+ * Decrypts to a string message
+ */
+declare function decryptString(encryptedData: EncryptedData, key: Uint8Array): string;
+/**
+ * Serializes encrypted data (prepends nonce to ciphertext)
+ */
+declare function serialize(encryptedData: EncryptedData): SerializedEncryptedData;
+/**
+ * Deserializes encrypted data
+ */
+declare function deserialize(serialized: SerializedEncryptedData): EncryptedData;
+/**
+ * Encrypts and serializes data in one step
+ */
+declare function encryptAndSerialize(plaintext: Uint8Array, key: Uint8Array, aad?: Uint8Array): SerializedEncryptedData;
+/**
+ * Deserializes and decrypts data in one step
+ */
+declare function deserializeAndDecrypt(serialized: SerializedEncryptedData, key: Uint8Array): Uint8Array;
+/**
+ * Converts encrypted data to hex string
+ */
+declare function toHex(encryptedData: EncryptedData): string;
+/**
+ * Parses encrypted data from hex string
+ */
+declare function fromHex(hex: string, aad?: Uint8Array): EncryptedData;
+/**
+ * Converts encrypted data to base64 string
+ */
+declare function toBase64(encryptedData: EncryptedData): string;
+/**
+ * Parses encrypted data from base64 string
+ */
+declare function fromBase64(base64: string, aad?: Uint8Array): EncryptedData;
+/**
+ * Generates a random encryption key
+ */
+declare function generateKey(): Uint8Array;
+/**
+ * Generates a random nonce
+ */
+declare function generateNonce(): Uint8Array;
+/**
+ * Securely clears a key from memory
+ */
+declare function clearKey(key: Uint8Array): void;
+/**
+ * Checks if encrypted data appears valid (basic structure check)
+ */
+declare function isValidEncryptedData(data: EncryptedData): boolean;
+
+/**
+ * HKDF Key Derivation
+ *
+ * Derives deterministic sub-keys from a master secret using HKDF-SHA256 (RFC 5869).
+ */
+/**
+ * Derives a sub-key from input key material using HKDF-SHA256.
+ *
+ * @param ikm - Input key material (e.g., wallet private key). MUST be high-entropy.
+ * @param salt - Domain separation salt. Can be a string or bytes.
+ * @param info - Context-specific info. Can be a string or bytes.
+ * @param length - Output key length in bytes (default: 32).
+ * @returns Derived key as Uint8Array. Caller MUST zero this after use.
+ */
+declare function deriveKeyHKDF(ikm: Uint8Array, salt: string | Uint8Array, info: string | Uint8Array, length?: number): Uint8Array;
+
+/** A single Shamir share */
+interface Share {
+    /** Share index (1..N, never 0) */
+    x: number;
+    /** Share data (same length as secret) */
+    y: Uint8Array;
+}
+/**
+ * Splits a secret into N shares with threshold K.
+ *
+ * @param secret - Secret bytes to split (any length)
+ * @param n - Total number of shares to create (2..255)
+ * @param k - Minimum shares needed for reconstruction (2..n)
+ * @returns Array of N shares
+ */
+declare function split(secret: Uint8Array, n: number, k: number): Share[];
+/**
+ * Reconstructs a secret from K or more shares using Lagrange interpolation.
+ *
+ * @param shares - Array of K or more shares (must all have same y.length)
+ * @returns Reconstructed secret
+ */
+declare function combine(shares: Share[]): Uint8Array;
+
+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;
+}
+interface Client {
+    auth: AuthClient$1;
+    db: DBClient;
+    pubsub: PubSubClient;
+    network: NetworkClient;
+    cache: CacheClient;
+    storage: StorageClient;
+    functions: FunctionsClient;
+    vault: VaultClient | null;
+}
+declare function createClient(config: ClientConfig): Client;
+
+export { AuthClient$1 as AuthClient, type AuthConfig, CacheClient, type CacheDeleteRequest, type CacheDeleteResponse, type CacheGetRequest, type CacheGetResponse, type CacheHealthResponse, type CacheMultiGetRequest, type CacheMultiGetResponse, type CachePutRequest, type CachePutResponse, type CacheScanRequest, type CacheScanResponse, type Client, type ClientConfig, type CloseHandler, type ColumnDefinition, DBClient, type DeleteResult, type DeleteSecretResponse, type EncryptedData, type Entity, type ErrorHandler, type FanOutResult, type FindOptions, type FunctionResponse, FunctionsClient, type FunctionsClientConfig, type GetSecretResponse, type ChallengeResponse as GuardianChallengeResponse, GuardianClient, type GuardianEndpoint, GuardianError, type GuardianErrorCode, type HealthResponse as GuardianHealthResponse, type GuardianInfo, type SessionResponse as GuardianSessionResponse, type StatusResponse as GuardianStatusResponse, HttpClient, KEY_SIZE, type ListResult, type ListSecretsResponse, LocalStorageAdapter, MemoryStorage, type MessageHandler, NONCE_SIZE, NetworkClient, type NetworkErrorCallback, type NetworkErrorContext, type NetworkStatus, type PeerInfo, type PresenceMember, type PresenceOptions, type PresenceResponse, type ProxyRequest, type ProxyResponse, PubSubClient, type PubSubMessage, type PullResponse, type PushResponse, QueryBuilder, type QueryResponse, Repository, type RetrieveResult, SDKError, type SecretEntry, type SecretMeta, type SelectOptions, type SerializedEncryptedData, type Share as ShamirShare, type StorageAdapter, StorageClient, type StoragePinRequest, type StoragePinResponse, type StorageStatus, type StorageUploadResponse, type StoreResult, type StoreSecretResponse, type SubscribeOptions, Subscription, type SuccessResponse, TAG_SIZE, type TransactionOp, type TransactionRequest, AuthClient as VaultAuthClient, VaultClient, type VaultConfig, type GuardianResult as VaultGuardianResult, WSClient, type WhoAmI, adaptiveThreshold, clearKey, createClient, decrypt, decryptString, deriveKeyHKDF, deserializeAndDecrypt, deserialize as deserializeEncrypted, encrypt, encryptAndSerialize, encryptString, fromBase64 as encryptedFromBase64, fromHex as encryptedFromHex, toBase64 as encryptedToBase64, toHex as encryptedToHex, extractPrimaryKey, extractTableName, fanOut, fanOutIndexed, generateKey, generateNonce, isValidEncryptedData, serialize as serializeEncrypted, combine as shamirCombine, split as shamirSplit, withRetry, withTimeout, writeQuorum };