@arke-institute/sdk 0.1.0 → 0.1.2

package/dist/graph/index.cjs

@@ -0,0 +1,433 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/graph/index.ts
+var graph_exports = {};
+__export(graph_exports, {
+  GraphClient: () => GraphClient,
+  GraphEntityNotFoundError: () => GraphEntityNotFoundError,
+  GraphError: () => GraphError,
+  NetworkError: () => NetworkError,
+  NoPathFoundError: () => NoPathFoundError
+});
+module.exports = __toCommonJS(graph_exports);
+
+// src/graph/errors.ts
+var GraphError = class extends Error {
+  constructor(message, code = "GRAPH_ERROR", details) {
+    super(message);
+    this.code = code;
+    this.details = details;
+    this.name = "GraphError";
+  }
+};
+var GraphEntityNotFoundError = class extends GraphError {
+  constructor(canonicalId) {
+    super(`Graph entity not found: ${canonicalId}`, "ENTITY_NOT_FOUND", { canonicalId });
+    this.name = "GraphEntityNotFoundError";
+  }
+};
+var NoPathFoundError = class extends GraphError {
+  constructor(sourceIds, targetIds) {
+    super(
+      `No path found between sources and targets`,
+      "NO_PATH_FOUND",
+      { sourceIds, targetIds }
+    );
+    this.name = "NoPathFoundError";
+  }
+};
+var NetworkError = class extends GraphError {
+  constructor(message, statusCode) {
+    super(message, "NETWORK_ERROR", { statusCode });
+    this.statusCode = statusCode;
+    this.name = "NetworkError";
+  }
+};
+
+// src/graph/client.ts
+var GraphClient = class {
+  constructor(config) {
+    this.baseUrl = config.gatewayUrl.replace(/\/$/, "");
+    this.fetchImpl = config.fetchImpl ?? fetch;
+  }
+  // ---------------------------------------------------------------------------
+  // Request helpers
+  // ---------------------------------------------------------------------------
+  buildUrl(path, query) {
+    const url = new URL(`${this.baseUrl}${path}`);
+    if (query) {
+      Object.entries(query).forEach(([key, value]) => {
+        if (value !== void 0 && value !== null) {
+          url.searchParams.set(key, String(value));
+        }
+      });
+    }
+    return url.toString();
+  }
+  async request(path, options = {}) {
+    const url = this.buildUrl(path, options.query);
+    const headers = new Headers({ "Content-Type": "application/json" });
+    if (options.headers) {
+      Object.entries(options.headers).forEach(([k, v]) => {
+        if (v !== void 0) headers.set(k, v);
+      });
+    }
+    let response;
+    try {
+      response = await this.fetchImpl(url, { ...options, headers });
+    } catch (err) {
+      throw new NetworkError(
+        err instanceof Error ? err.message : "Network request failed"
+      );
+    }
+    if (response.ok) {
+      const contentType = response.headers.get("content-type") || "";
+      if (contentType.includes("application/json")) {
+        return await response.json();
+      }
+      return await response.text();
+    }
+    let body;
+    const text = await response.text();
+    try {
+      body = JSON.parse(text);
+    } catch {
+      body = text;
+    }
+    if (response.status === 404) {
+      throw new GraphError(
+        body?.message || "Not found",
+        "NOT_FOUND",
+        body
+      );
+    }
+    const message = body?.error && typeof body.error === "string" ? body.error : body?.message && typeof body.message === "string" ? body.message : `Request failed with status ${response.status}`;
+    throw new GraphError(message, "HTTP_ERROR", {
+      status: response.status,
+      body
+    });
+  }
+  // ---------------------------------------------------------------------------
+  // Entity Operations
+  // ---------------------------------------------------------------------------
+  /**
+   * Get an entity by its canonical ID.
+   *
+   * @param canonicalId - Entity UUID
+   * @returns Entity data
+   * @throws GraphEntityNotFoundError if the entity doesn't exist
+   *
+   * @example
+   * ```typescript
+   * const entity = await graph.getEntity('uuid-123');
+   * console.log('Entity:', entity.label, entity.type);
+   * ```
+   */
+  async getEntity(canonicalId) {
+    const response = await this.request(
+      `/graphdb/entity/${encodeURIComponent(canonicalId)}`
+    );
+    if (!response.found || !response.entity) {
+      throw new GraphEntityNotFoundError(canonicalId);
+    }
+    return response.entity;
+  }
+  /**
+   * Check if an entity exists by its canonical ID.
+   *
+   * @param canonicalId - Entity UUID
+   * @returns True if entity exists
+   *
+   * @example
+   * ```typescript
+   * if (await graph.entityExists('uuid-123')) {
+   *   console.log('Entity exists');
+   * }
+   * ```
+   */
+  async entityExists(canonicalId) {
+    const response = await this.request(
+      `/graphdb/entity/exists/${encodeURIComponent(canonicalId)}`
+    );
+    return response.exists;
+  }
+  /**
+   * Query entities by code with optional type filter.
+   *
+   * @param code - Entity code to search for
+   * @param type - Optional entity type filter
+   * @returns Matching entities
+   *
+   * @example
+   * ```typescript
+   * // Find by code
+   * const entities = await graph.queryByCode('person_john');
+   *
+   * // With type filter
+   * const people = await graph.queryByCode('john', 'person');
+   * ```
+   */
+  async queryByCode(code, type) {
+    const response = await this.request(
+      "/graphdb/entity/query",
+      {
+        method: "POST",
+        body: JSON.stringify({ code, type })
+      }
+    );
+    if (!response.found || !response.entity) {
+      return [];
+    }
+    return [response.entity];
+  }
+  /**
+   * Look up entities by code across all PIs.
+   *
+   * @param code - Entity code to search for
+   * @param type - Optional entity type filter
+   * @returns Matching entities
+   *
+   * @example
+   * ```typescript
+   * const entities = await graph.lookupByCode('alice_austen', 'person');
+   * ```
+   */
+  async lookupByCode(code, type) {
+    const response = await this.request(
+      "/graphdb/entities/lookup-by-code",
+      {
+        method: "POST",
+        body: JSON.stringify({ code, type })
+      }
+    );
+    return response.entities || [];
+  }
+  // ---------------------------------------------------------------------------
+  // PI-based Operations
+  // ---------------------------------------------------------------------------
+  /**
+   * List entities from a specific PI or multiple PIs.
+   *
+   * @param pi - Single PI or array of PIs
+   * @param options - Filter options
+   * @returns Entities from the PI(s)
+   *
+   * @example
+   * ```typescript
+   * // From single PI
+   * const entities = await graph.listEntitiesFromPi('01K75HQQXNTDG7BBP7PS9AWYAN');
+   *
+   * // With type filter
+   * const people = await graph.listEntitiesFromPi('01K75HQQXNTDG7BBP7PS9AWYAN', { type: 'person' });
+   *
+   * // From multiple PIs
+   * const all = await graph.listEntitiesFromPi(['pi-1', 'pi-2']);
+   * ```
+   */
+  async listEntitiesFromPi(pi, options = {}) {
+    const pis = Array.isArray(pi) ? pi : [pi];
+    const response = await this.request(
+      "/graphdb/entities/list",
+      {
+        method: "POST",
+        body: JSON.stringify({
+          pis,
+          type: options.type
+        })
+      }
+    );
+    return response.entities || [];
+  }
+  /**
+   * Get entities with their relationships from a PI.
+   *
+   * This is an optimized query that returns entities along with all their
+   * relationship data in a single request.
+   *
+   * @param pi - Persistent Identifier
+   * @param type - Optional entity type filter
+   * @returns Entities with relationships
+   *
+   * @example
+   * ```typescript
+   * const entities = await graph.getEntitiesWithRelationships('01K75HQQXNTDG7BBP7PS9AWYAN');
+   * entities.forEach(e => {
+   *   console.log(`${e.label} has ${e.relationships.length} relationships`);
+   * });
+   * ```
+   */
+  async getEntitiesWithRelationships(pi, type) {
+    const response = await this.request(
+      "/graphdb/pi/entities-with-relationships",
+      {
+        method: "POST",
+        body: JSON.stringify({ pi, type })
+      }
+    );
+    return response.entities || [];
+  }
+  /**
+   * Get the lineage (ancestors and/or descendants) of a PI.
+   *
+   * @param pi - Source PI
+   * @param direction - 'ancestors', 'descendants', or 'both'
+   * @returns Lineage data
+   *
+   * @example
+   * ```typescript
+   * // Get ancestors
+   * const lineage = await graph.getLineage('01K75HQQXNTDG7BBP7PS9AWYAN', 'ancestors');
+   *
+   * // Get both directions
+   * const full = await graph.getLineage('01K75HQQXNTDG7BBP7PS9AWYAN', 'both');
+   * ```
+   */
+  async getLineage(pi, direction = "both", maxHops = 10) {
+    return this.request("/graphdb/pi/lineage", {
+      method: "POST",
+      body: JSON.stringify({ sourcePi: pi, direction, maxHops })
+    });
+  }
+  // ---------------------------------------------------------------------------
+  // Relationship Operations
+  // ---------------------------------------------------------------------------
+  /**
+   * Get all relationships for an entity.
+   *
+   * @param canonicalId - Entity UUID
+   * @returns Array of relationships
+   *
+   * @example
+   * ```typescript
+   * const relationships = await graph.getRelationships('uuid-123');
+   * relationships.forEach(r => {
+   *   console.log(`${r.direction}: ${r.predicate} -> ${r.target_label}`);
+   * });
+   * ```
+   */
+  async getRelationships(canonicalId) {
+    const response = await this.request(`/graphdb/relationships/${encodeURIComponent(canonicalId)}`);
+    if (!response.found || !response.relationships) {
+      return [];
+    }
+    return response.relationships.map((rel) => ({
+      direction: rel.direction,
+      predicate: rel.predicate,
+      target_id: rel.target_id,
+      target_code: rel.target_code || "",
+      target_label: rel.target_label,
+      target_type: rel.target_type,
+      properties: rel.properties,
+      source_pi: rel.source_pi,
+      created_at: rel.created_at
+    }));
+  }
+  // ---------------------------------------------------------------------------
+  // Path Finding
+  // ---------------------------------------------------------------------------
+  /**
+   * Find shortest paths between sets of entities.
+   *
+   * @param sourceIds - Starting entity IDs
+   * @param targetIds - Target entity IDs
+   * @param options - Path finding options
+   * @returns Found paths
+   *
+   * @example
+   * ```typescript
+   * const paths = await graph.findPaths(
+   *   ['uuid-alice'],
+   *   ['uuid-bob'],
+   *   { max_depth: 4, direction: 'both' }
+   * );
+   *
+   * paths.forEach(path => {
+   *   console.log(`Path of length ${path.length}:`);
+   *   path.edges.forEach(e => {
+   *     console.log(`  ${e.subject_label} -[${e.predicate}]-> ${e.object_label}`);
+   *   });
+   * });
+   * ```
+   */
+  async findPaths(sourceIds, targetIds, options = {}) {
+    const response = await this.request("/graphdb/paths/between", {
+      method: "POST",
+      body: JSON.stringify({
+        source_ids: sourceIds,
+        target_ids: targetIds,
+        max_depth: options.max_depth,
+        direction: options.direction,
+        limit: options.limit
+      })
+    });
+    return response.paths || [];
+  }
+  /**
+   * Find entities of a specific type reachable from starting entities.
+   *
+   * @param startIds - Starting entity IDs
+   * @param targetType - Type of entities to find
+   * @param options - Search options
+   * @returns Reachable entities of the specified type
+   *
+   * @example
+   * ```typescript
+   * // Find all people reachable from an event
+   * const people = await graph.findReachable(
+   *   ['uuid-event'],
+   *   'person',
+   *   { max_depth: 3 }
+   * );
+   * ```
+   */
+  async findReachable(startIds, targetType, options = {}) {
+    const response = await this.request(
+      "/graphdb/paths/reachable",
+      {
+        method: "POST",
+        body: JSON.stringify({
+          start_ids: startIds,
+          target_type: targetType,
+          max_depth: options.max_depth,
+          direction: options.direction,
+          limit: options.limit
+        })
+      }
+    );
+    return response.entities || [];
+  }
+  /**
+   * Check the health of the graph service.
+   *
+   * @returns Health status
+   */
+  async health() {
+    return this.request("/graphdb/health", { method: "GET" });
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  GraphClient,
+  GraphEntityNotFoundError,
+  GraphError,
+  NetworkError,
+  NoPathFoundError
+});
+//# sourceMappingURL=index.cjs.map

package/dist/graph/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/graph/index.ts","../../src/graph/errors.ts","../../src/graph/client.ts"],"sourcesContent":["/**\n * Graph package for the Arke SDK\n *\n * Provides read-only access to entity relationships from the GraphDB Gateway service.\n *\n * @example\n * ```typescript\n * import { GraphClient } from '@arke-institute/sdk/graph';\n *\n * const graph = new GraphClient({\n *   gatewayUrl: 'https://gateway.arke.institute',\n * });\n *\n * // Get entity by ID\n * const entity = await graph.getEntity('uuid-123');\n *\n * // Get entities with relationships from a PI\n * const entities = await graph.getEntitiesWithRelationships('01K75HQQXNTDG7BBP7PS9AWYAN');\n *\n * // Find paths between entities\n * const paths = await graph.findPaths(['uuid-1'], ['uuid-2']);\n * ```\n */\n\nexport { GraphClient, type GraphClientConfig } from './client.js';\nexport * from './types.js';\nexport * from './errors.js';\n","/**\n * Graph package error classes for the Arke SDK\n */\n\n/**\n * Base error class for graph operations\n */\nexport class GraphError extends Error {\n  constructor(\n    message: string,\n    public code: string = 'GRAPH_ERROR',\n    public details?: unknown\n  ) {\n    super(message);\n    this.name = 'GraphError';\n  }\n}\n\n/**\n * Thrown when an entity is not found by canonical ID\n */\nexport class GraphEntityNotFoundError extends GraphError {\n  constructor(canonicalId: string) {\n    super(`Graph entity not found: ${canonicalId}`, 'ENTITY_NOT_FOUND', { canonicalId });\n    this.name = 'GraphEntityNotFoundError';\n  }\n}\n\n/**\n * Thrown when no paths are found between entities\n */\nexport class NoPathFoundError extends GraphError {\n  constructor(sourceIds: string[], targetIds: string[]) {\n    super(\n      `No path found between sources and targets`,\n      'NO_PATH_FOUND',\n      { sourceIds, targetIds }\n    );\n    this.name = 'NoPathFoundError';\n  }\n}\n\n/**\n * Thrown when a network error occurs\n */\nexport class NetworkError extends GraphError {\n  constructor(message: string, public statusCode?: number) {\n    super(message, 'NETWORK_ERROR', { statusCode });\n    this.name = 'NetworkError';\n  }\n}\n","import {\n  GraphError,\n  GraphEntityNotFoundError,\n  NetworkError,\n} from './errors.js';\nimport type {\n  GraphEntity,\n  EntityWithRelationships,\n  Relationship,\n  Path,\n  PathOptions,\n  ReachableOptions,\n  ListFromPiOptions,\n  EntityQueryResponse,\n  EntitiesWithRelationshipsResponse,\n  PathsResponse,\n  LineageResponse,\n} from './types.js';\n\n/**\n * Configuration for GraphClient\n */\nexport interface GraphClientConfig {\n  /**\n   * Gateway base URL (e.g., https://gateway.arke.institute).\n   * The client will call /graphdb/* endpoints for GraphDB Gateway.\n   */\n  gatewayUrl: string;\n  /**\n   * Optional custom fetch implementation (useful for testing).\n   */\n  fetchImpl?: typeof fetch;\n}\n\ntype JsonBody = Record<string, unknown>;\n\n/**\n * Client for querying entity relationships from the Arke knowledge graph.\n *\n * All endpoints are public and do not require authentication.\n *\n * @example\n * ```typescript\n * const graph = new GraphClient({\n *   gatewayUrl: 'https://gateway.arke.institute',\n * });\n *\n * // Get entity by ID\n * const entity = await graph.getEntity('uuid-123');\n *\n * // Find entities by code\n * const results = await graph.queryByCode('person_john');\n *\n * // Get entities with relationships from a PI\n * const entities = await graph.getEntitiesWithRelationships('01K75HQQXNTDG7BBP7PS9AWYAN');\n *\n * // Find paths between entities\n * const paths = await graph.findPaths(['uuid-1'], ['uuid-2'], { max_depth: 4 });\n * ```\n */\nexport class GraphClient {\n  private baseUrl: string;\n  private fetchImpl: typeof fetch;\n\n  constructor(config: GraphClientConfig) {\n    this.baseUrl = config.gatewayUrl.replace(/\\/$/, '');\n    this.fetchImpl = config.fetchImpl ?? fetch;\n  }\n\n  // ---------------------------------------------------------------------------\n  // Request helpers\n  // ---------------------------------------------------------------------------\n\n  private buildUrl(path: string, query?: Record<string, string | number | boolean | undefined>) {\n    const url = new URL(`${this.baseUrl}${path}`);\n    if (query) {\n      Object.entries(query).forEach(([key, value]) => {\n        if (value !== undefined && value !== null) {\n          url.searchParams.set(key, String(value));\n        }\n      });\n    }\n    return url.toString();\n  }\n\n  private async request<T>(\n    path: string,\n    options: RequestInit & {\n      query?: Record<string, string | number | boolean | undefined>;\n    } = {}\n  ): Promise<T> {\n    const url = this.buildUrl(path, options.query);\n    const headers = new Headers({ 'Content-Type': 'application/json' });\n    if (options.headers) {\n      Object.entries(options.headers).forEach(([k, v]) => {\n        if (v !== undefined) headers.set(k, v as string);\n      });\n    }\n\n    let response: Response;\n    try {\n      response = await this.fetchImpl(url, { ...options, headers });\n    } catch (err) {\n      throw new NetworkError(\n        err instanceof Error ? err.message : 'Network request failed'\n      );\n    }\n\n    if (response.ok) {\n      const contentType = response.headers.get('content-type') || '';\n      if (contentType.includes('application/json')) {\n        return (await response.json()) as T;\n      }\n      return (await response.text()) as unknown as T;\n    }\n\n    let body: unknown;\n    const text = await response.text();\n    try {\n      body = JSON.parse(text);\n    } catch {\n      body = text;\n    }\n\n    // Handle 404 specifically\n    if (response.status === 404) {\n      throw new GraphError(\n        (body as JsonBody)?.message as string || 'Not found',\n        'NOT_FOUND',\n        body\n      );\n    }\n\n    const message =\n      (body as JsonBody)?.error && typeof (body as JsonBody).error === 'string'\n        ? ((body as JsonBody).error as string)\n        : (body as JsonBody)?.message && typeof (body as JsonBody).message === 'string'\n          ? ((body as JsonBody).message as string)\n          : `Request failed with status ${response.status}`;\n\n    throw new GraphError(message, 'HTTP_ERROR', {\n      status: response.status,\n      body,\n    });\n  }\n\n  // ---------------------------------------------------------------------------\n  // Entity Operations\n  // ---------------------------------------------------------------------------\n\n  /**\n   * Get an entity by its canonical ID.\n   *\n   * @param canonicalId - Entity UUID\n   * @returns Entity data\n   * @throws GraphEntityNotFoundError if the entity doesn't exist\n   *\n   * @example\n   * ```typescript\n   * const entity = await graph.getEntity('uuid-123');\n   * console.log('Entity:', entity.label, entity.type);\n   * ```\n   */\n  async getEntity(canonicalId: string): Promise<GraphEntity> {\n    const response = await this.request<{ found: boolean; entity?: GraphEntity }>(\n      `/graphdb/entity/${encodeURIComponent(canonicalId)}`\n    );\n\n    if (!response.found || !response.entity) {\n      throw new GraphEntityNotFoundError(canonicalId);\n    }\n\n    return response.entity;\n  }\n\n  /**\n   * Check if an entity exists by its canonical ID.\n   *\n   * @param canonicalId - Entity UUID\n   * @returns True if entity exists\n   *\n   * @example\n   * ```typescript\n   * if (await graph.entityExists('uuid-123')) {\n   *   console.log('Entity exists');\n   * }\n   * ```\n   */\n  async entityExists(canonicalId: string): Promise<boolean> {\n    const response = await this.request<{ exists: boolean }>(\n      `/graphdb/entity/exists/${encodeURIComponent(canonicalId)}`\n    );\n    return response.exists;\n  }\n\n  /**\n   * Query entities by code with optional type filter.\n   *\n   * @param code - Entity code to search for\n   * @param type - Optional entity type filter\n   * @returns Matching entities\n   *\n   * @example\n   * ```typescript\n   * // Find by code\n   * const entities = await graph.queryByCode('person_john');\n   *\n   * // With type filter\n   * const people = await graph.queryByCode('john', 'person');\n   * ```\n   */\n  async queryByCode(code: string, type?: string): Promise<GraphEntity[]> {\n    const response = await this.request<EntityQueryResponse>(\n      '/graphdb/entity/query',\n      {\n        method: 'POST',\n        body: JSON.stringify({ code, type }),\n      }\n    );\n\n    if (!response.found || !response.entity) {\n      return [];\n    }\n\n    return [response.entity];\n  }\n\n  /**\n   * Look up entities by code across all PIs.\n   *\n   * @param code - Entity code to search for\n   * @param type - Optional entity type filter\n   * @returns Matching entities\n   *\n   * @example\n   * ```typescript\n   * const entities = await graph.lookupByCode('alice_austen', 'person');\n   * ```\n   */\n  async lookupByCode(code: string, type?: string): Promise<GraphEntity[]> {\n    const response = await this.request<{ entities: GraphEntity[] }>(\n      '/graphdb/entities/lookup-by-code',\n      {\n        method: 'POST',\n        body: JSON.stringify({ code, type }),\n      }\n    );\n    return response.entities || [];\n  }\n\n  // ---------------------------------------------------------------------------\n  // PI-based Operations\n  // ---------------------------------------------------------------------------\n\n  /**\n   * List entities from a specific PI or multiple PIs.\n   *\n   * @param pi - Single PI or array of PIs\n   * @param options - Filter options\n   * @returns Entities from the PI(s)\n   *\n   * @example\n   * ```typescript\n   * // From single PI\n   * const entities = await graph.listEntitiesFromPi('01K75HQQXNTDG7BBP7PS9AWYAN');\n   *\n   * // With type filter\n   * const people = await graph.listEntitiesFromPi('01K75HQQXNTDG7BBP7PS9AWYAN', { type: 'person' });\n   *\n   * // From multiple PIs\n   * const all = await graph.listEntitiesFromPi(['pi-1', 'pi-2']);\n   * ```\n   */\n  async listEntitiesFromPi(\n    pi: string | string[],\n    options: ListFromPiOptions = {}\n  ): Promise<GraphEntity[]> {\n    const pis = Array.isArray(pi) ? pi : [pi];\n    const response = await this.request<{ entities: GraphEntity[] }>(\n      '/graphdb/entities/list',\n      {\n        method: 'POST',\n        body: JSON.stringify({\n          pis,\n          type: options.type,\n        }),\n      }\n    );\n    return response.entities || [];\n  }\n\n  /**\n   * Get entities with their relationships from a PI.\n   *\n   * This is an optimized query that returns entities along with all their\n   * relationship data in a single request.\n   *\n   * @param pi - Persistent Identifier\n   * @param type - Optional entity type filter\n   * @returns Entities with relationships\n   *\n   * @example\n   * ```typescript\n   * const entities = await graph.getEntitiesWithRelationships('01K75HQQXNTDG7BBP7PS9AWYAN');\n   * entities.forEach(e => {\n   *   console.log(`${e.label} has ${e.relationships.length} relationships`);\n   * });\n   * ```\n   */\n  async getEntitiesWithRelationships(\n    pi: string,\n    type?: string\n  ): Promise<EntityWithRelationships[]> {\n    const response = await this.request<EntitiesWithRelationshipsResponse>(\n      '/graphdb/pi/entities-with-relationships',\n      {\n        method: 'POST',\n        body: JSON.stringify({ pi, type }),\n      }\n    );\n    return response.entities || [];\n  }\n\n  /**\n   * Get the lineage (ancestors and/or descendants) of a PI.\n   *\n   * @param pi - Source PI\n   * @param direction - 'ancestors', 'descendants', or 'both'\n   * @returns Lineage data\n   *\n   * @example\n   * ```typescript\n   * // Get ancestors\n   * const lineage = await graph.getLineage('01K75HQQXNTDG7BBP7PS9AWYAN', 'ancestors');\n   *\n   * // Get both directions\n   * const full = await graph.getLineage('01K75HQQXNTDG7BBP7PS9AWYAN', 'both');\n   * ```\n   */\n  async getLineage(\n    pi: string,\n    direction: 'ancestors' | 'descendants' | 'both' = 'both',\n    maxHops: number = 10\n  ): Promise<LineageResponse> {\n    return this.request<LineageResponse>('/graphdb/pi/lineage', {\n      method: 'POST',\n      body: JSON.stringify({ sourcePi: pi, direction, maxHops }),\n    });\n  }\n\n  // ---------------------------------------------------------------------------\n  // Relationship Operations\n  // ---------------------------------------------------------------------------\n\n  /**\n   * Get all relationships for an entity.\n   *\n   * @param canonicalId - Entity UUID\n   * @returns Array of relationships\n   *\n   * @example\n   * ```typescript\n   * const relationships = await graph.getRelationships('uuid-123');\n   * relationships.forEach(r => {\n   *   console.log(`${r.direction}: ${r.predicate} -> ${r.target_label}`);\n   * });\n   * ```\n   */\n  async getRelationships(canonicalId: string): Promise<Relationship[]> {\n    const response = await this.request<{\n      found: boolean;\n      canonical_id?: string;\n      relationships?: Array<{\n        direction: 'outgoing' | 'incoming';\n        predicate: string;\n        target_id: string;\n        target_code?: string;\n        target_label: string;\n        target_type: string;\n        properties?: Record<string, unknown>;\n        source_pi?: string;\n        created_at?: string;\n      }>;\n    }>(`/graphdb/relationships/${encodeURIComponent(canonicalId)}`);\n\n    if (!response.found || !response.relationships) {\n      return [];\n    }\n\n    return response.relationships.map(rel => ({\n      direction: rel.direction,\n      predicate: rel.predicate,\n      target_id: rel.target_id,\n      target_code: rel.target_code || '',\n      target_label: rel.target_label,\n      target_type: rel.target_type,\n      properties: rel.properties,\n      source_pi: rel.source_pi,\n      created_at: rel.created_at,\n    }));\n  }\n\n  // ---------------------------------------------------------------------------\n  // Path Finding\n  // ---------------------------------------------------------------------------\n\n  /**\n   * Find shortest paths between sets of entities.\n   *\n   * @param sourceIds - Starting entity IDs\n   * @param targetIds - Target entity IDs\n   * @param options - Path finding options\n   * @returns Found paths\n   *\n   * @example\n   * ```typescript\n   * const paths = await graph.findPaths(\n   *   ['uuid-alice'],\n   *   ['uuid-bob'],\n   *   { max_depth: 4, direction: 'both' }\n   * );\n   *\n   * paths.forEach(path => {\n   *   console.log(`Path of length ${path.length}:`);\n   *   path.edges.forEach(e => {\n   *     console.log(`  ${e.subject_label} -[${e.predicate}]-> ${e.object_label}`);\n   *   });\n   * });\n   * ```\n   */\n  async findPaths(\n    sourceIds: string[],\n    targetIds: string[],\n    options: PathOptions = {}\n  ): Promise<Path[]> {\n    const response = await this.request<PathsResponse>('/graphdb/paths/between', {\n      method: 'POST',\n      body: JSON.stringify({\n        source_ids: sourceIds,\n        target_ids: targetIds,\n        max_depth: options.max_depth,\n        direction: options.direction,\n        limit: options.limit,\n      }),\n    });\n    return response.paths || [];\n  }\n\n  /**\n   * Find entities of a specific type reachable from starting entities.\n   *\n   * @param startIds - Starting entity IDs\n   * @param targetType - Type of entities to find\n   * @param options - Search options\n   * @returns Reachable entities of the specified type\n   *\n   * @example\n   * ```typescript\n   * // Find all people reachable from an event\n   * const people = await graph.findReachable(\n   *   ['uuid-event'],\n   *   'person',\n   *   { max_depth: 3 }\n   * );\n   * ```\n   */\n  async findReachable(\n    startIds: string[],\n    targetType: string,\n    options: ReachableOptions = {}\n  ): Promise<GraphEntity[]> {\n    const response = await this.request<{ entities: GraphEntity[] }>(\n      '/graphdb/paths/reachable',\n      {\n        method: 'POST',\n        body: JSON.stringify({\n          start_ids: startIds,\n          target_type: targetType,\n          max_depth: options.max_depth,\n          direction: options.direction,\n          limit: options.limit,\n        }),\n      }\n    );\n    return response.entities || [];\n  }\n\n  /**\n   * Check the health of the graph service.\n   *\n   * @returns Health status\n   */\n  async health(): Promise<{ status: string; service: string; version: string }> {\n    return this.request('/graphdb/health', { method: 'GET' });\n  }\n}\n"],"mappings":"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","names":[]}