graphmind-sdk 0.6.2

package/dist/src/client.d.ts

@@ -0,0 +1,90 @@
+import type { QueryResult, ServerStatus, ClientOptions, GraphSchema, SampleRequest, SampleResult, CsvImportResult, JsonImportResult } from "./types.js";
+/**
+ * Client for the Graphmind Graph Database.
+ *
+ * @example
+ * ```ts
+ * const client = new GraphmindClient({ url: "http://localhost:8080" });
+ *
+ * // Create data
+ * await client.query('CREATE (n:Person {name: "Alice"})');
+ *
+ * // Query data
+ * const result = await client.queryReadonly("MATCH (n:Person) RETURN n.name");
+ * console.log(result.records);
+ *
+ * // Schema introspection
+ * const schema = await client.schema();
+ * console.log(schema.node_types);
+ *
+ * // EXPLAIN / PROFILE
+ * const plan = await client.explain("MATCH (n:Person) RETURN n");
+ * const profile = await client.profile("MATCH (n:Person) RETURN n");
+ * ```
+ */
+export declare class GraphmindClient {
+    private http;
+    private defaultGraph;
+    constructor(options?: ClientOptions);
+    /**
+     * Connect to a Graphmind server via HTTP.
+     * Factory method for a more readable API.
+     */
+    static connectHttp(url?: string): GraphmindClient;
+    /** Execute a read-write Cypher query */
+    query(cypher: string, graph?: string): Promise<QueryResult>;
+    /** Execute a read-only Cypher query */
+    queryReadonly(cypher: string, graph?: string): Promise<QueryResult>;
+    /**
+     * Return the EXPLAIN plan for a Cypher query without executing it.
+     * Returns the plan as text rows in the QueryResult records.
+     */
+    explain(cypher: string, graph?: string): Promise<QueryResult>;
+    /**
+     * Execute a Cypher query with PROFILE instrumentation.
+     * Returns plan text with actual row counts and timing per operator.
+     */
+    profile(cypher: string, graph?: string): Promise<QueryResult>;
+    /** Delete a graph (executes MATCH (n) DELETE n) */
+    deleteGraph(graph?: string): Promise<void>;
+    /** List graphs (fetches graph name from server status) */
+    listGraphs(): Promise<string[]>;
+    /** Get server status */
+    status(): Promise<ServerStatus>;
+    /** Get graph schema (node types, edge types, indexes, constraints, statistics) */
+    schema(): Promise<GraphSchema>;
+    /**
+     * Sample a subgraph for visualization.
+     * Returns a proportionally sampled set of nodes and edges.
+     * @param options - max_nodes (default 200), labels filter, graph/tenant name
+     */
+    sample(options?: SampleRequest): Promise<SampleResult>;
+    /**
+     * Import nodes from CSV content.
+     * @param csvContent - Raw CSV string (first row = headers)
+     * @param label - Node label to assign
+     * @param options - Optional: idColumn, delimiter
+     */
+    importCsv(csvContent: string, label: string, options?: {
+        idColumn?: string;
+        delimiter?: string;
+    }): Promise<CsvImportResult>;
+    /**
+     * Import nodes from JSON objects.
+     * @param label - Node label to assign
+     * @param nodes - Array of objects, each becoming a node
+     */
+    importJson(label: string, nodes: Record<string, unknown>[]): Promise<JsonImportResult>;
+    /**
+     * Execute a multi-statement Cypher script.
+     * Each semicolon-separated statement is executed in order.
+     */
+    executeScript(script: string, graph?: string): Promise<QueryResult[]>;
+    /**
+     * Translate a natural-language question into Cypher and execute it.
+     * Requires the server to have NLQ enabled.
+     */
+    nlq(question: string, graph?: string): Promise<QueryResult>;
+    /** Ping the server */
+    ping(): Promise<string>;
+}

package/dist/src/client.js

@@ -0,0 +1,148 @@
+import { HttpTransport } from "./http-client.js";
+const DEFAULT_URL = "http://localhost:8080";
+/**
+ * Client for the Graphmind Graph Database.
+ *
+ * @example
+ * ```ts
+ * const client = new GraphmindClient({ url: "http://localhost:8080" });
+ *
+ * // Create data
+ * await client.query('CREATE (n:Person {name: "Alice"})');
+ *
+ * // Query data
+ * const result = await client.queryReadonly("MATCH (n:Person) RETURN n.name");
+ * console.log(result.records);
+ *
+ * // Schema introspection
+ * const schema = await client.schema();
+ * console.log(schema.node_types);
+ *
+ * // EXPLAIN / PROFILE
+ * const plan = await client.explain("MATCH (n:Person) RETURN n");
+ * const profile = await client.profile("MATCH (n:Person) RETURN n");
+ * ```
+ */
+export class GraphmindClient {
+    constructor(options) {
+        const url = options?.url ?? DEFAULT_URL;
+        this.defaultGraph = options?.graph ?? "default";
+        const headers = {};
+        if (options?.token) {
+            headers["Authorization"] = `Bearer ${options.token}`;
+        }
+        this.http = new HttpTransport(url, headers);
+    }
+    /**
+     * Connect to a Graphmind server via HTTP.
+     * Factory method for a more readable API.
+     */
+    static connectHttp(url = DEFAULT_URL) {
+        return new GraphmindClient({ url });
+    }
+    /** Execute a read-write Cypher query */
+    async query(cypher, graph = "default") {
+        return this.http.query(cypher, graph);
+    }
+    /** Execute a read-only Cypher query */
+    async queryReadonly(cypher, graph = "default") {
+        return this.http.query(cypher, graph);
+    }
+    /**
+     * Return the EXPLAIN plan for a Cypher query without executing it.
+     * Returns the plan as text rows in the QueryResult records.
+     */
+    async explain(cypher, graph = "default") {
+        const prefixed = cypher.trimStart().toUpperCase().startsWith("EXPLAIN")
+            ? cypher
+            : `EXPLAIN ${cypher}`;
+        return this.http.query(prefixed, graph);
+    }
+    /**
+     * Execute a Cypher query with PROFILE instrumentation.
+     * Returns plan text with actual row counts and timing per operator.
+     */
+    async profile(cypher, graph = "default") {
+        const prefixed = cypher.trimStart().toUpperCase().startsWith("PROFILE")
+            ? cypher
+            : `PROFILE ${cypher}`;
+        return this.http.query(prefixed, graph);
+    }
+    /** Delete a graph (executes MATCH (n) DELETE n) */
+    async deleteGraph(graph = "default") {
+        await this.http.query("MATCH (n) DELETE n", graph);
+    }
+    /** List graphs (fetches graph name from server status) */
+    async listGraphs() {
+        const s = await this.http.status();
+        // OSS mode returns a single graph; use the status graph field if present
+        const graph = s.graph ?? "default";
+        return [graph];
+    }
+    /** Get server status */
+    async status() {
+        return this.http.status();
+    }
+    /** Get graph schema (node types, edge types, indexes, constraints, statistics) */
+    async schema() {
+        return this.http.schema();
+    }
+    /**
+     * Sample a subgraph for visualization.
+     * Returns a proportionally sampled set of nodes and edges.
+     * @param options - max_nodes (default 200), labels filter, graph/tenant name
+     */
+    async sample(options = {}) {
+        return this.http.post("/api/sample", options);
+    }
+    /**
+     * Import nodes from CSV content.
+     * @param csvContent - Raw CSV string (first row = headers)
+     * @param label - Node label to assign
+     * @param options - Optional: idColumn, delimiter
+     */
+    async importCsv(csvContent, label, options) {
+        return this.http.importCsv(csvContent, label, options);
+    }
+    /**
+     * Import nodes from JSON objects.
+     * @param label - Node label to assign
+     * @param nodes - Array of objects, each becoming a node
+     */
+    async importJson(label, nodes) {
+        return this.http.importJson(label, nodes);
+    }
+    /**
+     * Execute a multi-statement Cypher script.
+     * Each semicolon-separated statement is executed in order.
+     */
+    async executeScript(script, graph = this.defaultGraph) {
+        const statements = script
+            .split(";")
+            .map((s) => s.trim())
+            .filter((s) => s.length > 0);
+        const results = [];
+        for (const stmt of statements) {
+            results.push(await this.query(stmt, graph));
+        }
+        return results;
+    }
+    /**
+     * Translate a natural-language question into Cypher and execute it.
+     * Requires the server to have NLQ enabled.
+     */
+    async nlq(question, graph = this.defaultGraph) {
+        return this.http.post("/api/nlq", {
+            query: question,
+            graph,
+        });
+    }
+    /** Ping the server */
+    async ping() {
+        const s = await this.status();
+        if (s.status === "healthy") {
+            return "PONG";
+        }
+        throw new Error(`Server unhealthy: ${s.status}`);
+    }
+}

package/dist/src/http-client.d.ts

@@ -0,0 +1,25 @@
+import type { QueryResult, ServerStatus, GraphSchema, CsvImportResult, JsonImportResult } from "./types.js";
+/**
+ * HTTP transport for the Graphmind SDK.
+ * Uses the native `fetch` API (works in Node.js 18+ and browsers).
+ */
+export declare class HttpTransport {
+    private baseUrl;
+    private extraHeaders;
+    constructor(baseUrl: string, extraHeaders?: Record<string, string>);
+    /** Execute a Cypher query via POST /api/query */
+    query(cypher: string, graph?: string): Promise<QueryResult>;
+    /** Get server status via GET /api/status */
+    status(): Promise<ServerStatus>;
+    /** Get graph schema via GET /api/schema */
+    schema(): Promise<GraphSchema>;
+    /** Generic POST request returning typed JSON response */
+    post<T>(path: string, body: unknown): Promise<T>;
+    /** Import nodes from CSV via POST /api/import/csv (multipart) */
+    importCsv(csvContent: string, label: string, options?: {
+        idColumn?: string;
+        delimiter?: string;
+    }): Promise<CsvImportResult>;
+    /** Import nodes from JSON via POST /api/import/json */
+    importJson(label: string, nodes: Record<string, unknown>[]): Promise<JsonImportResult>;
+}

package/dist/src/http-client.js

@@ -0,0 +1,101 @@
+/**
+ * HTTP transport for the Graphmind SDK.
+ * Uses the native `fetch` API (works in Node.js 18+ and browsers).
+ */
+export class HttpTransport {
+    constructor(baseUrl, extraHeaders = {}) {
+        this.baseUrl = baseUrl.replace(/\/+$/, "");
+        this.extraHeaders = extraHeaders;
+    }
+    /** Execute a Cypher query via POST /api/query */
+    async query(cypher, graph = "default") {
+        const response = await fetch(`${this.baseUrl}/api/query`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json", ...this.extraHeaders },
+            body: JSON.stringify({ query: cypher, graph }),
+        });
+        if (!response.ok) {
+            const body = (await response.json().catch(() => ({
+                error: `HTTP ${response.status}`,
+            })));
+            throw new Error(body.error || `HTTP ${response.status}`);
+        }
+        return (await response.json());
+    }
+    /** Get server status via GET /api/status */
+    async status() {
+        const response = await fetch(`${this.baseUrl}/api/status`, {
+            headers: this.extraHeaders,
+        });
+        if (!response.ok) {
+            throw new Error(`Status endpoint returned ${response.status}`);
+        }
+        return (await response.json());
+    }
+    /** Get graph schema via GET /api/schema */
+    async schema() {
+        const response = await fetch(`${this.baseUrl}/api/schema`, {
+            headers: this.extraHeaders,
+        });
+        if (!response.ok) {
+            const body = (await response.json().catch(() => ({
+                error: `HTTP ${response.status}`,
+            })));
+            throw new Error(body.error || `HTTP ${response.status}`);
+        }
+        return (await response.json());
+    }
+    /** Generic POST request returning typed JSON response */
+    async post(path, body) {
+        const response = await fetch(`${this.baseUrl}${path}`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json", ...this.extraHeaders },
+            body: JSON.stringify(body),
+        });
+        if (!response.ok) {
+            const err = (await response.json().catch(() => ({
+                error: `HTTP ${response.status}`,
+            })));
+            throw new Error(err.error || `HTTP ${response.status}`);
+        }
+        return (await response.json());
+    }
+    /** Import nodes from CSV via POST /api/import/csv (multipart) */
+    async importCsv(csvContent, label, options) {
+        const formData = new FormData();
+        const blob = new Blob([csvContent], { type: "text/csv" });
+        formData.append("file", blob, "import.csv");
+        formData.append("label", label);
+        if (options?.idColumn)
+            formData.append("id_column", options.idColumn);
+        if (options?.delimiter)
+            formData.append("delimiter", options.delimiter);
+        const response = await fetch(`${this.baseUrl}/api/import/csv`, {
+            method: "POST",
+            headers: this.extraHeaders,
+            body: formData,
+        });
+        if (!response.ok) {
+            const body = (await response.json().catch(() => ({
+                error: `HTTP ${response.status}`,
+            })));
+            throw new Error(body.error || `HTTP ${response.status}`);
+        }
+        return (await response.json());
+    }
+    /** Import nodes from JSON via POST /api/import/json */
+    async importJson(label, nodes) {
+        const response = await fetch(`${this.baseUrl}/api/import/json`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json", ...this.extraHeaders },
+            body: JSON.stringify({ label, nodes }),
+        });
+        if (!response.ok) {
+            const body = (await response.json().catch(() => ({
+                error: `HTTP ${response.status}`,
+            })));
+            throw new Error(body.error || `HTTP ${response.status}`);
+        }
+        return (await response.json());
+    }
+}

package/dist/src/index.d.ts

@@ -0,0 +1,3 @@
+export { GraphmindClient } from "./client.js";
+export { HttpTransport } from "./http-client.js";
+export type { SdkNode, SdkEdge, QueryResult, ServerStatus, ErrorResponse, ClientOptions, GraphSchema, NodeType, EdgeType, IndexInfo, ConstraintInfo, CsvImportResult, JsonImportResult, } from "./types.js";

package/dist/src/index.js

@@ -0,0 +1,2 @@
+export { GraphmindClient } from "./client.js";
+export { HttpTransport } from "./http-client.js";

package/dist/src/types.d.ts

@@ -0,0 +1,127 @@
+/** A graph node returned from a query */
+export interface SdkNode {
+    id: string;
+    labels: string[];
+    properties: Record<string, unknown>;
+}
+/** A graph edge returned from a query */
+export interface SdkEdge {
+    id: string;
+    source: string;
+    target: string;
+    type: string;
+    properties: Record<string, unknown>;
+}
+/** Result of executing a Cypher query */
+export interface QueryResult {
+    nodes: SdkNode[];
+    edges: SdkEdge[];
+    columns: string[];
+    records: unknown[][];
+}
+/** Server status information */
+export interface ServerStatus {
+    status: string;
+    version: string;
+    storage: {
+        nodes: number;
+        edges: number;
+    };
+}
+/** Error response from the server */
+export interface ErrorResponse {
+    error: string;
+}
+/** Node type descriptor from schema introspection */
+export interface NodeType {
+    label: string;
+    count: number;
+    properties: Record<string, string>;
+}
+/** Edge type descriptor from schema introspection */
+export interface EdgeType {
+    type: string;
+    count: number;
+    source_labels: string[];
+    target_labels: string[];
+    properties: Record<string, string>;
+}
+/** Index descriptor from schema introspection */
+export interface IndexInfo {
+    label: string;
+    property: string;
+    type: string;
+}
+/** Constraint descriptor from schema introspection */
+export interface ConstraintInfo {
+    label: string;
+    property: string;
+    type: string;
+}
+/** Graph schema returned by GET /api/schema */
+export interface GraphSchema {
+    node_types: NodeType[];
+    edge_types: EdgeType[];
+    indexes: IndexInfo[];
+    constraints: ConstraintInfo[];
+    statistics: {
+        total_nodes: number;
+        total_edges: number;
+        avg_out_degree: number;
+    };
+}
+/** Request for subgraph sampling (POST /api/sample) */
+export interface SampleRequest {
+    /** Maximum nodes to return (default: 200, max: 1000) */
+    max_nodes?: number;
+    /** Only include these node labels (empty = all) */
+    labels?: string[];
+    /** Tenant/graph name */
+    graph?: string;
+}
+/** A sampled node for visualization */
+export interface SampleNode {
+    id: number;
+    label: string;
+    name: string;
+    properties: Record<string, unknown>;
+}
+/** A sampled edge for visualization */
+export interface SampleEdge {
+    id: number;
+    source: number;
+    target: number;
+    type: string;
+    properties: Record<string, unknown>;
+}
+/** Result of subgraph sampling */
+export interface SampleResult {
+    nodes: SampleNode[];
+    edges: SampleEdge[];
+    total_nodes: number;
+    total_edges: number;
+    sampled_nodes: number;
+    sampled_edges: number;
+}
+/** Result of CSV import */
+export interface CsvImportResult {
+    status: string;
+    nodes_created: number;
+    label: string;
+    columns: string[];
+}
+/** Result of JSON import */
+export interface JsonImportResult {
+    status: string;
+    nodes_created: number;
+    label: string;
+}
+/** Options for creating a client */
+export interface ClientOptions {
+    /** Base URL for HTTP transport (default: http://localhost:8080) */
+    url?: string;
+    /** Default graph/tenant name (default: "default") */
+    graph?: string;
+    /** Bearer token for authentication */
+    token?: string;
+}

package/dist/src/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "graphmind-sdk",
+  "version": "0.6.2",
+  "description": "TypeScript SDK for the Graphmind Graph Database",
+  "type": "module",
+  "main": "dist/src/index.js",
+  "module": "dist/src/index.js",
+  "types": "dist/src/index.d.ts",
+  "files": [
+    "dist/src/**/*.js",
+    "dist/src/**/*.d.ts"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "node --test dist/tests/*.test.js",
+    "check": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "graph",
+    "database",
+    "cypher",
+    "graphmind"
+  ],
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/fab679/graphmind"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.0",
+    "typescript": "^5.3"
+  }
+}