samyama-sdk 0.6.1 → 1.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,4 +1,4 @@
1
- import type { QueryResult, ServerStatus, ClientOptions, GraphSchema, CsvImportResult, JsonImportResult } from "./types";
1
+ import type { QueryResult, ServerStatus, ClientOptions, GraphSchema, SampleRequest, SampleResult, CsvImportResult, JsonImportResult } from "./types.js";
2
2
  /**
3
3
  * Client for the Samyama Graph Database.
4
4
  *
@@ -31,27 +31,33 @@ export declare class SamyamaClient {
31
31
  */
32
32
  static connectHttp(url?: string): SamyamaClient;
33
33
  /** Execute a read-write Cypher query */
34
- query(cypher: string, _graph?: string): Promise<QueryResult>;
34
+ query(cypher: string, graph?: string): Promise<QueryResult>;
35
35
  /** Execute a read-only Cypher query */
36
- queryReadonly(cypher: string, _graph?: string): Promise<QueryResult>;
36
+ queryReadonly(cypher: string, graph?: string): Promise<QueryResult>;
37
37
  /**
38
38
  * Return the EXPLAIN plan for a Cypher query without executing it.
39
39
  * Returns the plan as text rows in the QueryResult records.
40
40
  */
41
- explain(cypher: string): Promise<QueryResult>;
41
+ explain(cypher: string, graph?: string): Promise<QueryResult>;
42
42
  /**
43
43
  * Execute a Cypher query with PROFILE instrumentation.
44
44
  * Returns plan text with actual row counts and timing per operator.
45
45
  */
46
- profile(cypher: string): Promise<QueryResult>;
46
+ profile(cypher: string, graph?: string): Promise<QueryResult>;
47
47
  /** Delete a graph (executes MATCH (n) DELETE n) */
48
- deleteGraph(_graph?: string): Promise<void>;
48
+ deleteGraph(graph?: string): Promise<void>;
49
49
  /** List graphs (OSS: always returns ["default"]) */
50
50
  listGraphs(): Promise<string[]>;
51
51
  /** Get server status */
52
52
  status(): Promise<ServerStatus>;
53
53
  /** Get graph schema (node types, edge types, indexes, constraints, statistics) */
54
54
  schema(): Promise<GraphSchema>;
55
+ /**
56
+ * Sample a subgraph for visualization.
57
+ * Returns a proportionally sampled set of nodes and edges.
58
+ * @param options - max_nodes (default 200), labels filter, graph/tenant name
59
+ */
60
+ sample(options?: SampleRequest): Promise<SampleResult>;
55
61
  /**
56
62
  * Import nodes from CSV content.
57
63
  * @param csvContent - Raw CSV string (first row = headers)
@@ -1,7 +1,4 @@
1
- "use strict";
2
- Object.defineProperty(exports, "__esModule", { value: true });
3
- exports.SamyamaClient = void 0;
4
- const http_client_1 = require("./http-client");
1
+ import { HttpTransport } from "./http-client.js";
5
2
  const DEFAULT_URL = "http://localhost:8080";
6
3
  /**
7
4
  * Client for the Samyama Graph Database.
@@ -26,10 +23,10 @@ const DEFAULT_URL = "http://localhost:8080";
26
23
  * const profile = await client.profile("MATCH (n:Person) RETURN n");
27
24
  * ```
28
25
  */
29
- class SamyamaClient {
26
+ export class SamyamaClient {
30
27
  constructor(options) {
31
28
  const url = options?.url ?? DEFAULT_URL;
32
- this.http = new http_client_1.HttpTransport(url);
29
+ this.http = new HttpTransport(url);
33
30
  }
34
31
  /**
35
32
  * Connect to a Samyama server via HTTP.
@@ -39,36 +36,36 @@ class SamyamaClient {
39
36
  return new SamyamaClient({ url });
40
37
  }
41
38
  /** Execute a read-write Cypher query */
42
- async query(cypher, _graph = "default") {
43
- return this.http.query(cypher);
39
+ async query(cypher, graph = "default") {
40
+ return this.http.query(cypher, graph);
44
41
  }
45
42
  /** Execute a read-only Cypher query */
46
- async queryReadonly(cypher, _graph = "default") {
47
- return this.http.query(cypher);
43
+ async queryReadonly(cypher, graph = "default") {
44
+ return this.http.query(cypher, graph);
48
45
  }
49
46
  /**
50
47
  * Return the EXPLAIN plan for a Cypher query without executing it.
51
48
  * Returns the plan as text rows in the QueryResult records.
52
49
  */
53
- async explain(cypher) {
50
+ async explain(cypher, graph = "default") {
54
51
  const prefixed = cypher.trimStart().toUpperCase().startsWith("EXPLAIN")
55
52
  ? cypher
56
53
  : `EXPLAIN ${cypher}`;
57
- return this.http.query(prefixed);
54
+ return this.http.query(prefixed, graph);
58
55
  }
59
56
  /**
60
57
  * Execute a Cypher query with PROFILE instrumentation.
61
58
  * Returns plan text with actual row counts and timing per operator.
62
59
  */
63
- async profile(cypher) {
60
+ async profile(cypher, graph = "default") {
64
61
  const prefixed = cypher.trimStart().toUpperCase().startsWith("PROFILE")
65
62
  ? cypher
66
63
  : `PROFILE ${cypher}`;
67
- return this.http.query(prefixed);
64
+ return this.http.query(prefixed, graph);
68
65
  }
69
66
  /** Delete a graph (executes MATCH (n) DELETE n) */
70
- async deleteGraph(_graph = "default") {
71
- await this.http.query("MATCH (n) DELETE n");
67
+ async deleteGraph(graph = "default") {
68
+ await this.http.query("MATCH (n) DELETE n", graph);
72
69
  }
73
70
  /** List graphs (OSS: always returns ["default"]) */
74
71
  async listGraphs() {
@@ -82,6 +79,14 @@ class SamyamaClient {
82
79
  async schema() {
83
80
  return this.http.schema();
84
81
  }
82
+ /**
83
+ * Sample a subgraph for visualization.
84
+ * Returns a proportionally sampled set of nodes and edges.
85
+ * @param options - max_nodes (default 200), labels filter, graph/tenant name
86
+ */
87
+ async sample(options = {}) {
88
+ return this.http.post("/api/sample", options);
89
+ }
85
90
  /**
86
91
  * Import nodes from CSV content.
87
92
  * @param csvContent - Raw CSV string (first row = headers)
@@ -108,4 +113,3 @@ class SamyamaClient {
108
113
  throw new Error(`Server unhealthy: ${s.status}`);
109
114
  }
110
115
  }
111
- exports.SamyamaClient = SamyamaClient;
@@ -1,4 +1,4 @@
1
- import type { QueryResult, ServerStatus, GraphSchema, CsvImportResult, JsonImportResult } from "./types";
1
+ import type { QueryResult, ServerStatus, GraphSchema, CsvImportResult, JsonImportResult } from "./types.js";
2
2
  /**
3
3
  * HTTP transport for the Samyama SDK.
4
4
  * Uses the native `fetch` API (works in Node.js 18+ and browsers).
@@ -7,11 +7,13 @@ export declare class HttpTransport {
7
7
  private baseUrl;
8
8
  constructor(baseUrl: string);
9
9
  /** Execute a Cypher query via POST /api/query */
10
- query(cypher: string): Promise<QueryResult>;
10
+ query(cypher: string, graph?: string): Promise<QueryResult>;
11
11
  /** Get server status via GET /api/status */
12
12
  status(): Promise<ServerStatus>;
13
13
  /** Get graph schema via GET /api/schema */
14
14
  schema(): Promise<GraphSchema>;
15
+ /** Generic POST request returning typed JSON response */
16
+ post<T>(path: string, body: unknown): Promise<T>;
15
17
  /** Import nodes from CSV via POST /api/import/csv (multipart) */
16
18
  importCsv(csvContent: string, label: string, options?: {
17
19
  idColumn?: string;
@@ -1,20 +1,17 @@
1
- "use strict";
2
- Object.defineProperty(exports, "__esModule", { value: true });
3
- exports.HttpTransport = void 0;
4
1
  /**
5
2
  * HTTP transport for the Samyama SDK.
6
3
  * Uses the native `fetch` API (works in Node.js 18+ and browsers).
7
4
  */
8
- class HttpTransport {
5
+ export class HttpTransport {
9
6
  constructor(baseUrl) {
10
7
  this.baseUrl = baseUrl.replace(/\/+$/, "");
11
8
  }
12
9
  /** Execute a Cypher query via POST /api/query */
13
- async query(cypher) {
10
+ async query(cypher, graph = "default") {
14
11
  const response = await fetch(`${this.baseUrl}/api/query`, {
15
12
  method: "POST",
16
13
  headers: { "Content-Type": "application/json" },
17
- body: JSON.stringify({ query: cypher }),
14
+ body: JSON.stringify({ query: cypher, graph }),
18
15
  });
19
16
  if (!response.ok) {
20
17
  const body = (await response.json().catch(() => ({
@@ -43,6 +40,21 @@ class HttpTransport {
43
40
  }
44
41
  return (await response.json());
45
42
  }
43
+ /** Generic POST request returning typed JSON response */
44
+ async post(path, body) {
45
+ const response = await fetch(`${this.baseUrl}${path}`, {
46
+ method: "POST",
47
+ headers: { "Content-Type": "application/json" },
48
+ body: JSON.stringify(body),
49
+ });
50
+ if (!response.ok) {
51
+ const err = (await response.json().catch(() => ({
52
+ error: `HTTP ${response.status}`,
53
+ })));
54
+ throw new Error(err.error || `HTTP ${response.status}`);
55
+ }
56
+ return (await response.json());
57
+ }
46
58
  /** Import nodes from CSV via POST /api/import/csv (multipart) */
47
59
  async importCsv(csvContent, label, options) {
48
60
  const formData = new FormData();
@@ -81,4 +93,3 @@ class HttpTransport {
81
93
  return (await response.json());
82
94
  }
83
95
  }
84
- exports.HttpTransport = HttpTransport;
@@ -1,3 +1,3 @@
1
- export { SamyamaClient } from "./client";
2
- export { HttpTransport } from "./http-client";
3
- export type { SdkNode, SdkEdge, QueryResult, ServerStatus, ErrorResponse, ClientOptions, GraphSchema, NodeType, EdgeType, IndexInfo, ConstraintInfo, CsvImportResult, JsonImportResult, } from "./types";
1
+ export { SamyamaClient } from "./client.js";
2
+ export { HttpTransport } from "./http-client.js";
3
+ export type { SdkNode, SdkEdge, QueryResult, ServerStatus, ErrorResponse, ClientOptions, GraphSchema, NodeType, EdgeType, IndexInfo, ConstraintInfo, CsvImportResult, JsonImportResult, } from "./types.js";
package/dist/src/index.js CHANGED
@@ -1,7 +1,2 @@
1
- "use strict";
2
- Object.defineProperty(exports, "__esModule", { value: true });
3
- exports.HttpTransport = exports.SamyamaClient = void 0;
4
- var client_1 = require("./client");
5
- Object.defineProperty(exports, "SamyamaClient", { enumerable: true, get: function () { return client_1.SamyamaClient; } });
6
- var http_client_1 = require("./http-client");
7
- Object.defineProperty(exports, "HttpTransport", { enumerable: true, get: function () { return http_client_1.HttpTransport; } });
1
+ export { SamyamaClient } from "./client.js";
2
+ export { HttpTransport } from "./http-client.js";
@@ -70,6 +70,39 @@ export interface GraphSchema {
70
70
  avg_out_degree: number;
71
71
  };
72
72
  }
73
+ /** Request for subgraph sampling (POST /api/sample) */
74
+ export interface SampleRequest {
75
+ /** Maximum nodes to return (default: 200, max: 1000) */
76
+ max_nodes?: number;
77
+ /** Only include these node labels (empty = all) */
78
+ labels?: string[];
79
+ /** Tenant/graph name */
80
+ graph?: string;
81
+ }
82
+ /** A sampled node for visualization */
83
+ export interface SampleNode {
84
+ id: number;
85
+ label: string;
86
+ name: string;
87
+ properties: Record<string, unknown>;
88
+ }
89
+ /** A sampled edge for visualization */
90
+ export interface SampleEdge {
91
+ id: number;
92
+ source: number;
93
+ target: number;
94
+ type: string;
95
+ properties: Record<string, unknown>;
96
+ }
97
+ /** Result of subgraph sampling */
98
+ export interface SampleResult {
99
+ nodes: SampleNode[];
100
+ edges: SampleEdge[];
101
+ total_nodes: number;
102
+ total_edges: number;
103
+ sampled_nodes: number;
104
+ sampled_edges: number;
105
+ }
73
106
  /** Result of CSV import */
74
107
  export interface CsvImportResult {
75
108
  status: string;
package/dist/src/types.js CHANGED
@@ -1,2 +1 @@
1
- "use strict";
2
- Object.defineProperty(exports, "__esModule", { value: true });
1
+ export {};
package/package.json CHANGED
@@ -1,8 +1,10 @@
1
1
  {
2
2
  "name": "samyama-sdk",
3
- "version": "0.6.1",
3
+ "version": "1.8.0",
4
4
  "description": "TypeScript SDK for the Samyama Graph Database",
5
+ "type": "module",
5
6
  "main": "dist/src/index.js",
7
+ "module": "dist/src/index.js",
6
8
  "types": "dist/src/index.d.ts",
7
9
  "files": [
8
10
  "dist/src/**/*.js",