@anvailabs/proximadb-client 0.3.0

package/dist/graph.js

@@ -0,0 +1,690 @@
+"use strict";
+/**
+ * ProximaDB TypeScript SDK - Graph Operations
+ *
+ * Provides a fluent API for graph database operations including
+ * node and edge management, traversal queries, and graph analytics.
+ *
+ * Copyright 2025 ProximaDB Contributors
+ * Licensed under the Apache License, Version 2.0
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GraphBuilder = exports.GraphHandle = exports.TraversalBuilder = exports.EdgeBuilder = exports.NodeBuilder = void 0;
+exports.createNode = createNode;
+exports.node = node;
+exports.createEdge = createEdge;
+exports.edge = edge;
+const types_1 = require("./types");
+// ============================================================================
+// NODE BUILDER
+// ============================================================================
+/**
+ * Builder for creating graph nodes
+ */
+class NodeBuilder {
+    handle;
+    nodeId = null;
+    nodeLabel = null;
+    nodeProperties = {};
+    nodeVector = null;
+    constructor(handle) {
+        this.handle = handle;
+    }
+    /**
+     * Set the node ID
+     */
+    id(nodeId) {
+        this.nodeId = nodeId;
+        return this;
+    }
+    /**
+     * Set the node label (type)
+     */
+    label(nodeLabel) {
+        this.nodeLabel = nodeLabel;
+        return this;
+    }
+    /**
+     * Add a property to the node
+     */
+    property(key, value) {
+        this.nodeProperties[key] = value;
+        return this;
+    }
+    /**
+     * Add multiple properties at once
+     */
+    properties(props) {
+        Object.assign(this.nodeProperties, props);
+        return this;
+    }
+    /**
+     * Set the embedding vector for semantic operations
+     */
+    vector(vec) {
+        this.nodeVector = vec;
+        return this;
+    }
+    /**
+     * Execute the node addition.
+     *
+     * Wire endpoint: POST /api/v2/graphs/{graph_id}/nodes
+     * OpenAPI operationId: createNode
+     *
+     * Body shape (server-true, per `CreateNodeRequest`):
+     *   `{ node: NodeInput }` — NodeInput = `{ id, labels?, properties?, embedding? }`.
+     */
+    async execute() {
+        if (this.nodeId === null) {
+            throw new Error("Node ID is required");
+        }
+        const node = { id: this.nodeId };
+        if (this.nodeLabel !== null) {
+            node.labels = [this.nodeLabel];
+        }
+        if (Object.keys(this.nodeProperties).length > 0) {
+            node.properties = this.nodeProperties;
+        }
+        if (this.nodeVector !== null) {
+            const embedding = { vector: this.nodeVector };
+            node.embedding = embedding;
+        }
+        const request = { node };
+        await this.handle.getClient().createNodeRequest(this.handle.getName(), request);
+    }
+    /**
+     * Build the node without executing
+     */
+    build() {
+        if (this.nodeId === null) {
+            throw new Error("Node ID is required");
+        }
+        return {
+            id: this.nodeId,
+            label: this.nodeLabel ?? undefined,
+            properties: this.nodeProperties,
+            vector: this.nodeVector ?? undefined,
+        };
+    }
+}
+exports.NodeBuilder = NodeBuilder;
+// ============================================================================
+// EDGE BUILDER
+// ============================================================================
+/**
+ * Builder for creating graph edges
+ */
+class EdgeBuilder {
+    handle;
+    edgeId = null;
+    sourceNode = null;
+    targetNode = null;
+    relationshipType = null;
+    edgeProperties = {};
+    edgeWeight = null;
+    constructor(handle) {
+        this.handle = handle;
+    }
+    /**
+     * Set the edge ID (required by server `EdgeInput.id`).
+     */
+    id(edgeId) {
+        this.edgeId = edgeId;
+        return this;
+    }
+    /**
+     * Set the source node ID
+     */
+    from(nodeId) {
+        this.sourceNode = nodeId;
+        return this;
+    }
+    /**
+     * Set the target node ID
+     */
+    to(nodeId) {
+        this.targetNode = nodeId;
+        return this;
+    }
+    /**
+     * Set the relationship / edge type (server field: `edge_type`).
+     */
+    relationship(relType) {
+        this.relationshipType = relType;
+        return this;
+    }
+    /**
+     * Alias for `relationship(...)` matching the server-side field name.
+     */
+    edgeType(edgeType) {
+        this.relationshipType = edgeType;
+        return this;
+    }
+    /**
+     * Add a property to the edge
+     */
+    property(key, value) {
+        this.edgeProperties[key] = value;
+        return this;
+    }
+    /**
+     * Add multiple properties at once
+     */
+    properties(props) {
+        Object.assign(this.edgeProperties, props);
+        return this;
+    }
+    /**
+     * Set the edge weight
+     */
+    weight(w) {
+        this.edgeWeight = w;
+        return this;
+    }
+    /**
+     * Execute the edge addition.
+     *
+     * Wire endpoint: POST /api/v2/graphs/{graph_id}/edges
+     * OpenAPI operationId: createEdge
+     *
+     * Body shape (server-true, per `CreateEdgeRequest`):
+     *   `{ edge: EdgeInput }` — EdgeInput = `{ id, from_node_id, to_node_id,
+     *   edge_type, properties?, weight? }`.
+     */
+    async execute() {
+        if (this.edgeId === null) {
+            throw new Error("Edge ID is required (call .id(...))");
+        }
+        if (this.sourceNode === null) {
+            throw new Error("Source node ID is required");
+        }
+        if (this.targetNode === null) {
+            throw new Error("Target node ID is required");
+        }
+        if (this.relationshipType === null) {
+            throw new Error("Edge type / relationship is required");
+        }
+        const edge = {
+            id: this.edgeId,
+            from_node_id: this.sourceNode,
+            to_node_id: this.targetNode,
+            edge_type: this.relationshipType,
+        };
+        if (Object.keys(this.edgeProperties).length > 0) {
+            edge.properties = this.edgeProperties;
+        }
+        if (this.edgeWeight !== null) {
+            edge.weight = this.edgeWeight;
+        }
+        const request = { edge };
+        await this.handle.getClient().createEdgeRequest(this.handle.getName(), request);
+    }
+    /**
+     * Build the edge without executing
+     */
+    build() {
+        if (this.sourceNode === null) {
+            throw new Error("Source node ID is required");
+        }
+        if (this.targetNode === null) {
+            throw new Error("Target node ID is required");
+        }
+        if (this.relationshipType === null) {
+            throw new Error("Relationship type is required");
+        }
+        return {
+            source: this.sourceNode,
+            target: this.targetNode,
+            relationship: this.relationshipType,
+            properties: this.edgeProperties,
+            weight: this.edgeWeight ?? undefined,
+        };
+    }
+}
+exports.EdgeBuilder = EdgeBuilder;
+// ============================================================================
+// TRAVERSAL BUILDER
+// ============================================================================
+/**
+ * Builder for graph traversal queries
+ */
+class TraversalBuilder {
+    handle;
+    startNodeId = null;
+    relationshipTypes = [];
+    nodeLabelsList = [];
+    traversalDirection = types_1.TraversalDirection.Outgoing;
+    maxDepthValue = 3;
+    limitValue = null;
+    algorithmValue = null;
+    filterExpr = null;
+    constructor(handle) {
+        this.handle = handle;
+    }
+    /**
+     * Set the starting node
+     */
+    start(nodeId) {
+        this.startNodeId = nodeId;
+        return this;
+    }
+    /**
+     * Add a relationship type to follow
+     */
+    relationship(relType) {
+        this.relationshipTypes.push(relType);
+        return this;
+    }
+    /**
+     * Add multiple relationship types
+     */
+    relationships(relTypes) {
+        this.relationshipTypes.push(...relTypes);
+        return this;
+    }
+    /**
+     * Set the traversal direction
+     */
+    direction(dir) {
+        this.traversalDirection = dir;
+        return this;
+    }
+    /**
+     * Traverse outgoing edges only
+     */
+    outgoing() {
+        this.traversalDirection = types_1.TraversalDirection.Outgoing;
+        return this;
+    }
+    /**
+     * Traverse incoming edges only
+     */
+    incoming() {
+        this.traversalDirection = types_1.TraversalDirection.Incoming;
+        return this;
+    }
+    /**
+     * Traverse both directions
+     */
+    both() {
+        this.traversalDirection = types_1.TraversalDirection.Both;
+        return this;
+    }
+    /**
+     * Set the maximum traversal depth
+     */
+    maxDepth(depth) {
+        this.maxDepthValue = depth;
+        return this;
+    }
+    /**
+     * Set the maximum number of results
+     */
+    limit(lim) {
+        this.limitValue = lim;
+        return this;
+    }
+    /**
+     * Add a label to filter visited nodes by.
+     */
+    nodeLabel(label) {
+        this.nodeLabelsList.push(label);
+        return this;
+    }
+    /**
+     * Replace the set of node-label filters.
+     */
+    nodeLabels(labels) {
+        this.nodeLabelsList = [...labels];
+        return this;
+    }
+    /**
+     * Select traversal algorithm (server accepts `bfs`, `dfs`, or `shortest_path`).
+     */
+    algorithm(name) {
+        this.algorithmValue = name;
+        return this;
+    }
+    /**
+     * Add a filter expression for nodes (client-side helper, not sent on wire).
+     */
+    filter(filterStr) {
+        this.filterExpr = filterStr;
+        return this;
+    }
+    /**
+     * Execute the traversal.
+     *
+     * Wire endpoint: POST /api/v2/graphs/{graph_id}/traverse
+     * OpenAPI operationId: traverseGraph
+     *
+     * Body shape (server-true, per `TraverseRequest`):
+     *   `{ start_node_id, max_depth, edge_types?, node_labels?, algorithm?, limit? }`.
+     *   Note: spec is flat (no `graph` wrapper — `graph_id` is the URL path
+     *   parameter) and has no `direction` field; legacy `direction` /
+     *   `start_node` / `relationships` keys are intentionally not sent.
+     */
+    async execute() {
+        if (this.startNodeId === null) {
+            throw new Error("Start node is required for traversal");
+        }
+        const request = {
+            start_node_id: this.startNodeId,
+            max_depth: this.maxDepthValue,
+        };
+        if (this.relationshipTypes.length > 0) {
+            request.edge_types = this.relationshipTypes;
+        }
+        if (this.nodeLabelsList.length > 0) {
+            request.node_labels = this.nodeLabelsList;
+        }
+        if (this.algorithmValue !== null) {
+            request.algorithm = this.algorithmValue;
+        }
+        if (this.limitValue !== null) {
+            request.limit = this.limitValue;
+        }
+        // Note: direction (this.traversalDirection) and filter (this.filterExpr)
+        // are intentionally NOT sent — the server `TraverseRequest` does not
+        // accept them. The setters remain for SDK ergonomic continuity.
+        void this.traversalDirection;
+        void this.filterExpr;
+        const data = await this.handle.getClient().traverseGraphRequest(this.handle.getName(), request);
+        return data;
+    }
+}
+exports.TraversalBuilder = TraversalBuilder;
+// ============================================================================
+// GRAPH HANDLE
+// ============================================================================
+/**
+ * Handle to a graph for fluent operations
+ */
+class GraphHandle {
+    client;
+    graphName;
+    constructor(client, name) {
+        this.client = client;
+        this.graphName = name;
+    }
+    /**
+     * Get the graph name
+     */
+    getName() {
+        return this.graphName;
+    }
+    /**
+     * Get the HTTP client (internal use)
+     */
+    getClient() {
+        return this.client;
+    }
+    /**
+     * Start building a node addition
+     */
+    addNode() {
+        return new NodeBuilder(this);
+    }
+    /**
+     * Start building an edge addition
+     */
+    addEdge() {
+        return new EdgeBuilder(this);
+    }
+    /**
+     * Start building a traversal query
+     */
+    traverse() {
+        return new TraversalBuilder(this);
+    }
+    /**
+     * Add a batch of nodes.
+     *
+     * Wire endpoint: POST /api/v2/graphs/{graph_id}/nodes/batch
+     * OpenAPI operationId: batchCreateNodes
+     *
+     * Body shape (server-true, per `BatchCreateNodesRequest`):
+     *   `{ nodes: [NodeInput, ...] }`. `graph_id` lives in the URL path.
+     *
+     * Accepts either spec-true `NodeInput[]` or legacy `GraphNode[]`; the
+     * latter is normalized (singular `label` → `labels: [label]`,
+     * `vector` → `embedding.vector`).
+     */
+    async addNodes(nodes) {
+        const normalized = nodes.map(n => normalizeNodeInput(n));
+        const request = { nodes: normalized };
+        const response = (await this.client.batchCreateNodesRequest(this.graphName, request));
+        return response?.data?.count ?? response?.count ?? normalized.length;
+    }
+    /**
+     * Add a batch of edges.
+     *
+     * Wire endpoint: POST /api/v2/graphs/{graph_id}/edges/batch
+     * OpenAPI operationId: batchCreateEdges
+     *
+     * Body shape (server-true, per `BatchCreateEdgesRequest`):
+     *   `{ edges: [EdgeInput, ...] }`. `graph_id` lives in the URL path.
+     *
+     * Accepts either spec-true `EdgeInput[]` or legacy `GraphEdge[]`; the
+     * latter is normalized (`source` → `from_node_id`, `target` →
+     * `to_node_id`, `relationship` → `edge_type`). Legacy `GraphEdge` has no
+     * `id` field; callers MUST upgrade to `EdgeInput` for batch use (the
+     * normalizer throws if `id` is missing).
+     */
+    async addEdges(edges) {
+        const normalized = edges.map(e => normalizeEdgeInput(e));
+        const request = { edges: normalized };
+        const response = (await this.client.batchCreateEdgesRequest(this.graphName, request));
+        return response?.data?.count ?? response?.count ?? normalized.length;
+    }
+    /**
+     * Get a node by ID
+     */
+    async getNode(nodeId) {
+        try {
+            const data = await this.client.getNodeRequest(this.graphName, nodeId);
+            return data;
+        }
+        catch (e) {
+            // The facade maps a 404 to a ProximaDBError (statusCode 404, message =
+            // server body). Treat "not found" as a null result, preserving the
+            // pre-rebase behavior; match on status or the body text.
+            const status = e.statusCode;
+            if (status === 404) {
+                return null;
+            }
+            if (e instanceof Error && e.message.includes("404")) {
+                return null;
+            }
+            throw e;
+        }
+    }
+    /**
+     * Delete a node by ID
+     */
+    async deleteNode(nodeId) {
+        await this.client.deleteNodeRequest(this.graphName, nodeId);
+    }
+    // deleteEdge is intentionally LEFT facade-built (generic URL path): the
+    // generated REST client has no matching typed op for this 3-segment route
+    // shape. The OpenAPI spec / generated client model edge deletion as
+    // `DELETE /api/v2/graphs/{graph_id}/edges/{edge_id}` (single `edge_id`),
+    // whereas this SDK's public signature is `(source, target, relationship)` →
+    // `/edges/{source}/{target}/{relationship}`. Until the SDK signature is
+    // reconciled to `{edge_id}` (separate change), this cannot route through the
+    // generated client. Tracked separately.
+    /**
+     * Delete an edge
+     */
+    async deleteEdge(source, target, relationship) {
+        const url = this.client.url() + "/api/v2/graphs/" + this.graphName + "/edges/" + source + "/" + target + "/" + relationship;
+        await this.client.delete(url);
+    }
+    /**
+     * Get graph statistics.
+     *
+     * Routed through the generated typed transport (TD-126 Phase 4).
+     * Wire endpoint: GET /api/v2/graphs/{graph_id} (getGraph)
+     */
+    async info() {
+        const data = await this.client.getGraphRequest(this.graphName);
+        return data;
+    }
+}
+exports.GraphHandle = GraphHandle;
+// ============================================================================
+// GRAPH BUILDER
+// ============================================================================
+/**
+ * Builder for creating graphs
+ */
+class GraphBuilder {
+    client;
+    graphId;
+    graphDisplayName = null;
+    graphDescription = null;
+    constructor(client, graphId) {
+        this.client = client;
+        this.graphId = graphId;
+    }
+    /**
+     * Set an optional human-readable name (defaults server-side to graph_id).
+     */
+    name(displayName) {
+        this.graphDisplayName = displayName;
+        return this;
+    }
+    /**
+     * Set the graph description
+     */
+    description(desc) {
+        this.graphDescription = desc;
+        return this;
+    }
+    /**
+     * Execute the graph creation.
+     *
+     * Wire endpoint: POST /api/v2/graphs
+     * OpenAPI operationId: createGraph
+     *
+     * Body shape (server-true, per `CreateGraphRequest`):
+     *   `{ graph_id, name?, description? }`.
+     */
+    async execute() {
+        const request = { graph_id: this.graphId };
+        if (this.graphDisplayName !== null) {
+            request.name = this.graphDisplayName;
+        }
+        if (this.graphDescription !== null) {
+            request.description = this.graphDescription;
+        }
+        await this.client.createGraphRequest(request);
+    }
+}
+exports.GraphBuilder = GraphBuilder;
+// ============================================================================
+// INTERNAL: legacy -> spec normalizers
+// ============================================================================
+function normalizeNodeInput(input) {
+    // Distinguish legacy `GraphNode` (has singular `label` and/or `vector`) from
+    // spec-true `NodeInput` (has `labels[]` / `embedding`). Field absence is
+    // fine — `NodeInput` only requires `id`.
+    const out = { id: input.id };
+    // Inline structural check avoids a hard cross-cast.
+    const legacy = input;
+    const spec = input;
+    if (spec.labels !== undefined) {
+        out.labels = spec.labels;
+    }
+    else if (legacy.label !== undefined) {
+        out.labels = [legacy.label];
+    }
+    if (spec.properties !== undefined) {
+        out.properties = spec.properties;
+    }
+    else if (legacy.properties !== undefined) {
+        out.properties = legacy.properties;
+    }
+    if (spec.embedding !== undefined) {
+        out.embedding = spec.embedding;
+    }
+    else if (legacy.vector !== undefined) {
+        out.embedding = { vector: legacy.vector };
+    }
+    return out;
+}
+function normalizeEdgeInput(input) {
+    const spec = input;
+    const legacy = input;
+    // Spec edge has `id` (required), legacy has none. If absent on a legacy
+    // value, surface a hard error — server `EdgeInput.id` is required.
+    if (spec.id === undefined) {
+        throw new Error("addEdges: edge.id is required by EdgeInput (legacy GraphEdge has no id; pass an EdgeInput)");
+    }
+    const out = {
+        id: spec.id,
+        from_node_id: spec.from_node_id ?? legacy.source,
+        to_node_id: spec.to_node_id ?? legacy.target,
+        edge_type: spec.edge_type ?? legacy.relationship,
+    };
+    if (spec.properties !== undefined) {
+        out.properties = spec.properties;
+    }
+    else if (legacy.properties !== undefined) {
+        out.properties = legacy.properties;
+    }
+    if (spec.weight !== undefined) {
+        out.weight = spec.weight;
+    }
+    else if (legacy.weight !== undefined) {
+        out.weight = legacy.weight;
+    }
+    return out;
+}
+// ============================================================================
+// CONVENIENCE FUNCTIONS
+// ============================================================================
+/**
+ * Create a new GraphNode
+ */
+function createNode(id) {
+    return {
+        id,
+        properties: {},
+    };
+}
+/**
+ * Create a new GraphNode with builder pattern
+ */
+function node(id) {
+    const n = { id, properties: {} };
+    return {
+        label: (l) => { n.label = l; return node(id); },
+        property: (k, v) => { n.properties[k] = v; return node(id); },
+        vector: (v) => { n.vector = v; return node(id); },
+        build: () => n,
+    };
+}
+/**
+ * Create a new GraphEdge
+ */
+function createEdge(source, target, relationship) {
+    return {
+        source,
+        target,
+        relationship,
+        properties: {},
+    };
+}
+/**
+ * Create a new GraphEdge with builder pattern
+ */
+function edge(source, target, relationship) {
+    const e = { source, target, relationship, properties: {} };
+    return {
+        property: (k, v) => { e.properties[k] = v; return edge(source, target, relationship); },
+        weight: (w) => { e.weight = w; return edge(source, target, relationship); },
+        build: () => e,
+    };
+}
+//# sourceMappingURL=graph.js.map