@anvailabs/proximadb-client 0.3.0

package/dist/client.js

@@ -0,0 +1,681 @@
+"use strict";
+/**
+ * ProximaDB TypeScript SDK - Client
+ *
+ * Main entry point for connecting to ProximaDB servers.
+ *
+ * Copyright 2025 ProximaDB Contributors
+ * Licensed under the Apache License, Version 2.0
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ClientBuilder = exports.ProximaDBClient = void 0;
+exports.connect = connect;
+exports.connectRest = connectRest;
+const types_1 = require("./types");
+const collection_1 = require("./collection");
+const graph_1 = require("./graph");
+const transport_1 = require("./transport");
+/**
+ * Default client configuration
+ */
+const DEFAULT_CONFIG = {
+    url: "http://localhost:5678",
+    timeoutMs: 30000,
+    maxRetries: 3,
+    apiKey: "",
+    poolConnections: true,
+    maxIdleConnections: 10,
+};
+/**
+ * Get the global fetch function
+ */
+function getFetch() {
+    if (typeof globalThis.fetch === "function") {
+        return globalThis.fetch.bind(globalThis);
+    }
+    throw new Error("No fetch implementation available. " +
+        "Node.js 18+ includes fetch natively. " +
+        "For older versions, install node-fetch.");
+}
+/**
+ * ProximaDB client for connecting to a remote server
+ */
+class ProximaDBClient {
+    config;
+    fetchFn;
+    /**
+     * Generated typed REST transport (TD-126 Phase 4). Core collection / record
+     * / search operations route through this; it owns URL/path/query/body
+     * encoding per the OpenAPI spec. Auth, retries, and error mapping are
+     * injected via the facade's own fetch (see `transportFetch`).
+     */
+    gen;
+    /**
+     * Create a new client with the given URL
+     */
+    static connect(url) {
+        return new ProximaDBClient({ url });
+    }
+    /**
+     * Create a new client builder
+     */
+    static builder() {
+        return new ClientBuilder();
+    }
+    /**
+     * Create a client with configuration
+     */
+    constructor(config = {}) {
+        this.config = { ...DEFAULT_CONFIG, ...config };
+        this.fetchFn = getFetch();
+        // Validate URL
+        try {
+            new URL(this.config.url);
+        }
+        catch {
+            throw new types_1.ProximaDBError("Invalid URL: " + this.config.url, types_1.ErrorCode.InvalidConfig);
+        }
+        // Wire the generated typed transport. Every request the generated client
+        // issues is funneled through `transportFetch`, the facade's own fetch that
+        // applies bearer auth, retries, and error mapping — exactly as the legacy
+        // generic `request<T>` path does.
+        this.gen = (0, transport_1.createTransport)(this.config.url, (req) => this.transportFetch(req));
+    }
+    /**
+     * Transport `fetch` handed to the generated client.
+     *
+     * The generated client assembles a resolved `Request` (URL + method + body);
+     * this normalizes it back to the facade's `(url, init)` retry/auth/error
+     * pipeline so the wire plumbing and transport policy compose. The returned
+     * value is a `Response`-shaped object the generated client parses; on an
+     * unsuccessful response a `ProximaDBError` is thrown (matching the generic
+     * path), so callers never see a non-2xx body.
+     */
+    async transportFetch(req) {
+        const method = (req.method || "GET").toUpperCase();
+        let body = undefined;
+        if (method !== "GET" && method !== "DELETE") {
+            const text = await req.clone().text();
+            if (text.length > 0) {
+                body = JSON.parse(text);
+            }
+        }
+        const data = await this.request(method, req.url, body);
+        // Re-wrap the already-parsed, validated body as a Response so the
+        // generated client can read `.json()`/`.ok` without re-issuing I/O.
+        return new Response(JSON.stringify(data ?? null), {
+            status: 200,
+            headers: { "Content-Type": "application/json" },
+        });
+    }
+    /**
+     * Get the server URL
+     */
+    url() {
+        return this.config.url;
+    }
+    /**
+     * Get the client configuration
+     */
+    getConfig() {
+        return { ...this.config };
+    }
+    // =========================================================================
+    // HTTP Methods
+    // =========================================================================
+    /**
+     * Make a GET request
+     */
+    async get(requestUrl) {
+        return this.request("GET", requestUrl);
+    }
+    /**
+     * Make a POST request
+     */
+    async post(requestUrl, body) {
+        return this.request("POST", requestUrl, body);
+    }
+    /**
+     * Make a PUT request
+     */
+    async put(requestUrl, body) {
+        return this.request("PUT", requestUrl, body);
+    }
+    /**
+     * Make a DELETE request
+     */
+    async delete(requestUrl) {
+        return this.request("DELETE", requestUrl);
+    }
+    /**
+     * Make an HTTP request with retry logic
+     */
+    async request(method, requestUrl, body) {
+        const headers = {
+            "Content-Type": "application/json",
+            Accept: "application/json",
+        };
+        if (this.config.apiKey) {
+            headers["Authorization"] = "Bearer " + this.config.apiKey;
+        }
+        const buildInit = (signal) => {
+            const init = {
+                method,
+                headers,
+                signal,
+            };
+            if (body !== undefined) {
+                init.body = JSON.stringify(body);
+            }
+            return init;
+        };
+        let lastError = null;
+        for (let attempt = 0; attempt <= this.config.maxRetries; attempt++) {
+            const controller = new AbortController();
+            const timeoutId = setTimeout(() => controller.abort(), this.config.timeoutMs);
+            try {
+                const response = await this.fetchFn(requestUrl, buildInit(controller.signal));
+                return await this.handleResponse(response);
+            }
+            catch (e) {
+                lastError = e instanceof Error ? e : new Error(String(e));
+                // Don't retry on client errors (4xx)
+                if (lastError instanceof types_1.ProximaDBError) {
+                    if (lastError.statusCode && lastError.statusCode >= 400 && lastError.statusCode < 500) {
+                        throw lastError;
+                    }
+                }
+                // Wait before retry with exponential backoff
+                if (attempt < this.config.maxRetries) {
+                    const delay = Math.min(1000 * Math.pow(2, attempt), 10000);
+                    await new Promise((resolve) => setTimeout(resolve, delay));
+                }
+            }
+            finally {
+                clearTimeout(timeoutId);
+            }
+        }
+        throw lastError ?? new Error("Request failed after retries");
+    }
+    /**
+     * Handle HTTP response
+     */
+    async handleResponse(response) {
+        if (response.ok) {
+            try {
+                return (await response.json());
+            }
+            catch {
+                throw new types_1.ProximaDBError("Failed to parse response JSON", types_1.ErrorCode.ServerError, response.status);
+            }
+        }
+        const statusCode = response.status;
+        let message = response.statusText;
+        try {
+            message = await response.text();
+        }
+        catch {
+            // Use statusText if text() fails
+        }
+        switch (statusCode) {
+            case 401:
+                throw new types_1.ProximaDBError(message, types_1.ErrorCode.AuthenticationFailed, statusCode);
+            case 403:
+                throw new types_1.ProximaDBError(message, types_1.ErrorCode.AuthorizationDenied, statusCode);
+            case 404:
+                throw new types_1.ProximaDBError(message, types_1.ErrorCode.CollectionNotFound, statusCode);
+            case 409:
+                throw new types_1.ProximaDBError(message, types_1.ErrorCode.CollectionExists, statusCode);
+            case 429:
+                throw new types_1.ProximaDBError(message, types_1.ErrorCode.RateLimited, statusCode);
+            default:
+                throw new types_1.ProximaDBError(message, types_1.ErrorCode.ServerError, statusCode);
+        }
+    }
+    // =========================================================================
+    // Collection Operations
+    // =========================================================================
+    /**
+     * Get a handle to a collection for fluent operations
+     */
+    collection(name) {
+        return new collection_1.CollectionHandle(this, name);
+    }
+    /**
+     * Create a collection builder
+     */
+    createCollection(name) {
+        return new collection_1.CollectionBuilder(this, name);
+    }
+    /**
+     * Delete a collection
+     *
+     * Routed through the generated typed transport (TD-126 Phase 4).
+     * Wire endpoint: DELETE /api/v2/collections/{collection_id}
+     * OpenAPI operationId: deleteCollection
+     */
+    async deleteCollection(name) {
+        await this.gen.DELETE("/api/v2/collections/{collection_id}", {
+            params: { path: { collection_id: name } },
+        });
+    }
+    /**
+     * List all collections
+     *
+     * Routed through the generated typed transport (TD-126 Phase 4).
+     * Wire endpoint: GET /api/v2/collections
+     * OpenAPI operationId: listCollections
+     */
+    async listCollections() {
+        const { data } = await this.gen.GET("/api/v2/collections", {});
+        return (data?.collections ?? []);
+    }
+    /**
+     * Get the schema for a collection
+     *
+     * Routed through the generated typed transport (TD-126 Phase 4).
+     * Wire endpoint: GET /api/v2/collections/{collection_id}/schema
+     * OpenAPI operationId: getCollectionSchema
+     */
+    async getCollectionSchema(collectionId) {
+        const { data } = await this.gen.GET("/api/v2/collections/{collection_id}/schema", { params: { path: { collection_id: collectionId } } });
+        return data;
+    }
+    /**
+     * Update the schema for a collection
+     *
+     * Routed through the generated typed transport (TD-126 Phase 4).
+     * Wire endpoint: PUT /api/v2/collections/{collection_id}/schema
+     * OpenAPI operationId: updateCollectionSchema
+     */
+    async updateCollectionSchema(collectionId, schema) {
+        const { data } = await this.gen.PUT("/api/v2/collections/{collection_id}/schema", {
+            params: { path: { collection_id: collectionId } },
+            body: schema,
+        });
+        return data;
+    }
+    // =========================================================================
+    // Query Facade (AQL / UQL)
+    // =========================================================================
+    /**
+     * Execute an AQL or UQL query through the shared query facade
+     *
+     * Wire endpoint: POST /api/v2/query
+     * OpenAPI operationId: executeQuery
+     */
+    async executeQuery(req) {
+        const { data } = await this.gen.POST("/api/v2/query", {
+            body: req,
+        });
+        return data;
+    }
+    /**
+     * Explain an AQL or UQL query through the shared query facade
+     *
+     * Wire endpoint: POST /api/v2/query/explain
+     * OpenAPI operationId: explainQuery
+     */
+    async explainQuery(req) {
+        const { data } = await this.gen.POST("/api/v2/query/explain", {
+            body: req,
+        });
+        return data;
+    }
+    // =========================================================================
+    // Typed transport for core collection / record / search ops (TD-126 Phase 4)
+    //
+    // These route the builders' wire calls through the generated typed client.
+    // The builders (collection.ts / search.ts) call these instead of hand-building
+    // URL strings, so the core CRUD + search paths are spec-generated end to end.
+    // =========================================================================
+    /**
+     * Create a collection.
+     * Wire endpoint: POST /api/v2/collections (createCollection)
+     */
+    async createCollectionRequest(body) {
+        const { data } = await this.gen.POST("/api/v2/collections", {
+            body: body,
+        });
+        return data;
+    }
+    /**
+     * Get collection details.
+     * Wire endpoint: GET /api/v2/collections/{collection_id} (getCollection)
+     */
+    async getCollectionRequest(collectionId) {
+        const { data } = await this.gen.GET("/api/v2/collections/{collection_id}", {
+            params: { path: { collection_id: collectionId } },
+        });
+        return data;
+    }
+    /**
+     * Insert / upsert records in a batch.
+     * Wire endpoint: POST /api/v2/collections/{collection_id}/records/batch (insertRecords)
+     */
+    async insertRecordsRequest(collectionId, body) {
+        const { data } = await this.gen.POST("/api/v2/collections/{collection_id}/records/batch", {
+            params: { path: { collection_id: collectionId } },
+            body: body,
+        });
+        return data;
+    }
+    /**
+     * Get a single record by ID.
+     * Wire endpoint: GET /api/v2/collections/{collection_id}/records/{record_id} (getRecord)
+     */
+    async getRecordRequest(collectionId, recordId, includeVector, includeText) {
+        const { data } = await this.gen.GET("/api/v2/collections/{collection_id}/records/{record_id}", {
+            params: {
+                path: { collection_id: collectionId, record_id: recordId },
+                query: { include_vector: includeVector, include_text: includeText },
+            },
+        });
+        return data;
+    }
+    /**
+     * Delete a single record by ID.
+     * Wire endpoint: DELETE /api/v2/collections/{collection_id}/records/{record_id} (deleteRecord)
+     */
+    async deleteRecordRequest(collectionId, recordId) {
+        await this.gen.DELETE("/api/v2/collections/{collection_id}/records/{record_id}", {
+            params: { path: { collection_id: collectionId, record_id: recordId } },
+        });
+    }
+    /**
+     * Vector similarity search.
+     * Wire endpoint: POST /api/v2/collections/{collection_id}/search (searchRecords)
+     */
+    async searchRecordsRequest(collectionId, body) {
+        const { data } = await this.gen.POST("/api/v2/collections/{collection_id}/search", {
+            params: { path: { collection_id: collectionId } },
+            body: body,
+        });
+        return data;
+    }
+    // =========================================================================
+    // Graph Operations
+    // =========================================================================
+    /**
+     * Get a handle to a graph for fluent operations
+     */
+    graph(name) {
+        return new graph_1.GraphHandle(this, name);
+    }
+    /**
+     * Create a graph builder.
+     *
+     * Wire endpoint: POST /api/v2/graphs
+     * OpenAPI operationId: createGraph
+     *
+     * The argument is the server-true `graph_id` (unique identifier). Use
+     * `.name(...)` on the returned builder to set the optional display name.
+     */
+    createGraph(graphId) {
+        return new graph_1.GraphBuilder(this, graphId);
+    }
+    /**
+     * Delete a graph
+     *
+     * Routed through the generated typed transport (TD-126 Phase 4).
+     * Wire endpoint: DELETE /api/v2/graphs/{graph_id}
+     * OpenAPI operationId: deleteGraph
+     */
+    async deleteGraph(name) {
+        await this.gen.DELETE("/api/v2/graphs/{graph_id}", {
+            params: { path: { graph_id: name } },
+        });
+    }
+    /**
+     * List all graphs
+     *
+     * Routed through the generated typed transport (TD-126 Phase 4).
+     * Wire endpoint: GET /api/v2/graphs
+     * OpenAPI operationId: listGraphs
+     */
+    async listGraphs() {
+        const { data } = await this.gen.GET("/api/v2/graphs", {});
+        return (data?.graphs ?? []);
+    }
+    // =========================================================================
+    // Typed transport for graph ops (TD-126 Phase 4)
+    //
+    // Seam methods routing the graph builders' / handle's wire calls through the
+    // generated typed client, mirroring the core collection / record / search
+    // seams above. The public graph API (graph.ts builders + handle) is
+    // unchanged; only the wire dispatch moves off hand-built URL strings.
+    // =========================================================================
+    /**
+     * Create a graph collection.
+     * Wire endpoint: POST /api/v2/graphs (createGraph)
+     */
+    async createGraphRequest(body) {
+        const { data } = await this.gen.POST("/api/v2/graphs", {
+            body: body,
+        });
+        return data;
+    }
+    /**
+     * Get a graph collection by id.
+     * Wire endpoint: GET /api/v2/graphs/{graph_id} (getGraph)
+     */
+    async getGraphRequest(graphId) {
+        const { data } = await this.gen.GET("/api/v2/graphs/{graph_id}", {
+            params: { path: { graph_id: graphId } },
+        });
+        return data;
+    }
+    /**
+     * Get graph statistics.
+     * Wire endpoint: GET /api/v2/graphs/{graph_id}/stats (getGraphStats)
+     */
+    async getGraphStatsRequest(graphId) {
+        const { data } = await this.gen.GET("/api/v2/graphs/{graph_id}/stats", {
+            params: { path: { graph_id: graphId } },
+        });
+        return data;
+    }
+    /**
+     * Create a node in a graph.
+     * Wire endpoint: POST /api/v2/graphs/{graph_id}/nodes (createNode)
+     */
+    async createNodeRequest(graphId, body) {
+        const { data } = await this.gen.POST("/api/v2/graphs/{graph_id}/nodes", {
+            params: { path: { graph_id: graphId } },
+            body: body,
+        });
+        return data;
+    }
+    /**
+     * Create multiple nodes in a single call.
+     * Wire endpoint: POST /api/v2/graphs/{graph_id}/nodes/batch (batchCreateNodes)
+     */
+    async batchCreateNodesRequest(graphId, body) {
+        const { data } = await this.gen.POST("/api/v2/graphs/{graph_id}/nodes/batch", {
+            params: { path: { graph_id: graphId } },
+            body: body,
+        });
+        return data;
+    }
+    /**
+     * Get a node by id.
+     * Wire endpoint: GET /api/v2/graphs/{graph_id}/nodes/{node_id} (getNode)
+     */
+    async getNodeRequest(graphId, nodeId) {
+        const { data } = await this.gen.GET("/api/v2/graphs/{graph_id}/nodes/{node_id}", {
+            params: { path: { graph_id: graphId, node_id: nodeId } },
+        });
+        return data;
+    }
+    /**
+     * Delete a node by id.
+     * Wire endpoint: DELETE /api/v2/graphs/{graph_id}/nodes/{node_id} (deleteNode)
+     */
+    async deleteNodeRequest(graphId, nodeId) {
+        await this.gen.DELETE("/api/v2/graphs/{graph_id}/nodes/{node_id}", {
+            params: { path: { graph_id: graphId, node_id: nodeId } },
+        });
+    }
+    /**
+     * Create an edge in a graph.
+     * Wire endpoint: POST /api/v2/graphs/{graph_id}/edges (createEdge)
+     */
+    async createEdgeRequest(graphId, body) {
+        const { data } = await this.gen.POST("/api/v2/graphs/{graph_id}/edges", {
+            params: { path: { graph_id: graphId } },
+            body: body,
+        });
+        return data;
+    }
+    /**
+     * Create multiple edges in a single call.
+     * Wire endpoint: POST /api/v2/graphs/{graph_id}/edges/batch (batchCreateEdges)
+     */
+    async batchCreateEdgesRequest(graphId, body) {
+        const { data } = await this.gen.POST("/api/v2/graphs/{graph_id}/edges/batch", {
+            params: { path: { graph_id: graphId } },
+            body: body,
+        });
+        return data;
+    }
+    /**
+     * Traverse a graph from a start node.
+     * Wire endpoint: POST /api/v2/graphs/{graph_id}/traverse (traverseGraph)
+     */
+    async traverseGraphRequest(graphId, body) {
+        const { data } = await this.gen.POST("/api/v2/graphs/{graph_id}/traverse", {
+            params: { path: { graph_id: graphId } },
+            body: body,
+        });
+        return data;
+    }
+    // =========================================================================
+    // Health and Monitoring
+    // =========================================================================
+    /**
+     * Check if the server is healthy
+     *
+     * Routed through the generated typed transport (TD-126 Phase 4).
+     * Wire endpoint: GET /health
+     * OpenAPI operationId: getHealth
+     */
+    async health() {
+        const { data } = await this.gen.GET("/health", {});
+        return data;
+    }
+    /**
+     * Kubernetes-style liveness probe
+     *
+     * Routed through the generated typed transport (TD-126 Phase 4).
+     * Wire endpoint: GET /health/live
+     * OpenAPI operationId: getLiveness
+     */
+    async healthLive() {
+        const { data } = await this.gen.GET("/health/live", {});
+        return data;
+    }
+    /**
+     * Kubernetes-style readiness probe
+     *
+     * Routed through the generated typed transport (TD-126 Phase 4).
+     * Wire endpoint: GET /health/ready
+     * OpenAPI operationId: getReadiness
+     */
+    async healthReady() {
+        const { data } = await this.gen.GET("/health/ready", {});
+        return data;
+    }
+    /**
+     * Check if the server is reachable
+     */
+    async ping() {
+        try {
+            await this.health();
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+}
+exports.ProximaDBClient = ProximaDBClient;
+// ============================================================================
+// CLIENT BUILDER
+// ============================================================================
+/**
+ * Builder for creating a ProximaDB client with custom configuration
+ */
+class ClientBuilder {
+    config = {};
+    /**
+     * Set the server URL
+     */
+    url(serverUrl) {
+        this.config.url = serverUrl;
+        return this;
+    }
+    /**
+     * Set the request timeout in milliseconds
+     */
+    timeoutMs(timeout) {
+        this.config.timeoutMs = timeout;
+        return this;
+    }
+    /**
+     * Set the maximum number of retries
+     */
+    maxRetries(retries) {
+        this.config.maxRetries = retries;
+        return this;
+    }
+    /**
+     * Set the API key for authentication
+     */
+    apiKey(key) {
+        this.config.apiKey = key;
+        return this;
+    }
+    /**
+     * Enable or disable connection pooling
+     */
+    poolConnections(enable) {
+        this.config.poolConnections = enable;
+        return this;
+    }
+    /**
+     * Set maximum idle connections in pool
+     */
+    maxIdleConnections(max) {
+        this.config.maxIdleConnections = max;
+        return this;
+    }
+    /**
+     * Build the ProximaDB client
+     */
+    build() {
+        return new ProximaDBClient(this.config);
+    }
+    /**
+     * Connect to the server (alias for build)
+     */
+    connect() {
+        return this.build();
+    }
+}
+exports.ClientBuilder = ClientBuilder;
+// ============================================================================
+// CONVENIENCE FUNCTIONS
+// ============================================================================
+/**
+ * Create a ProximaDB client connected to the given URL
+ */
+function connect(url = "http://localhost:5678") {
+    return ProximaDBClient.connect(url);
+}
+/**
+ * Create a ProximaDB client with REST protocol
+ */
+function connectRest(url = "http://localhost:5678") {
+    return ProximaDBClient.connect(url);
+}
+//# sourceMappingURL=client.js.map