@arke-institute/sdk 0.1.3 → 2.0.0

package/dist/graph/index.js

@@ -1,396 +0,0 @@
-// 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
-    });
-  }
-  // ---------------------------------------------------------------------------
-  // Code-based Lookups (indexed in GraphDB)
-  // ---------------------------------------------------------------------------
-  /**
-   * 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 extracted from a specific PI or multiple PIs.
-   *
-   * This returns knowledge graph entities (persons, places, events, etc.)
-   * that were extracted from the given PI(s), not the PI entity itself.
-   *
-   * @param pi - Single PI or array of PIs
-   * @param options - Filter options
-   * @returns Extracted 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.
-   *
-   * This traverses the PI hierarchy (parent_pi/children_pi relationships)
-   * which is indexed in GraphDB for fast lookups.
-   *
-   * @param pi - Source PI
-   * @param direction - 'ancestors', 'descendants', or 'both'
-   * @param maxHops - Maximum depth to traverse (default: 10)
-   * @returns Lineage data with PIs at each hop level
-   *
-   * @example
-   * ```typescript
-   * // Get ancestors (parent chain)
-   * 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 relationships for an entity from the GraphDB index.
-   *
-   * **Important distinction from ContentClient.getRelationships():**
-   * - **ContentClient.getRelationships()**: Returns OUTBOUND relationships only
-   *   (from the entity's relationships.json in IPFS - source of truth)
-   * - **GraphClient.getRelationships()**: Returns BOTH inbound AND outbound
-   *   relationships (from the indexed GraphDB mirror)
-   *
-   * Use this method when you need to find "what references this entity" (inbound)
-   * or want a complete bidirectional view.
-   *
-   * @param id - Entity identifier (works for both PIs and KG entities)
-   * @param direction - Filter by direction: 'outgoing', 'incoming', or 'both' (default)
-   * @returns Array of relationships with direction indicator
-   *
-   * @example
-   * ```typescript
-   * // Get all relationships (both directions)
-   * const all = await graph.getRelationships('01K75HQQXNTDG7BBP7PS9AWYAN');
-   *
-   * // Get only inbound relationships ("who references this entity?")
-   * const incoming = await graph.getRelationships('01K75HQQXNTDG7BBP7PS9AWYAN', 'incoming');
-   *
-   * // Get only outbound relationships (similar to IPFS, but from index)
-   * const outgoing = await graph.getRelationships('01K75HQQXNTDG7BBP7PS9AWYAN', 'outgoing');
-   *
-   * // Process by direction
-   * const rels = await graph.getRelationships('entity-id');
-   * rels.forEach(r => {
-   *   if (r.direction === 'incoming') {
-   *     console.log(`${r.target_label} references this entity via ${r.predicate}`);
-   *   } else {
-   *     console.log(`This entity ${r.predicate} -> ${r.target_label}`);
-   *   }
-   * });
-   * ```
-   */
-  async getRelationships(id, direction = "both") {
-    const response = await this.request(`/graphdb/relationships/${encodeURIComponent(id)}`);
-    if (!response.found || !response.relationships) {
-      return [];
-    }
-    let relationships = response.relationships;
-    if (direction !== "both") {
-      relationships = relationships.filter((rel) => rel.direction === direction);
-    }
-    return 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(
-   *   ['entity-alice'],
-   *   ['entity-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(
-   *   ['event-id'],
-   *   '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" });
-  }
-};
-export {
-  GraphClient,
-  GraphEntityNotFoundError,
-  GraphError,
-  NetworkError,
-  NoPathFoundError
-};
-//# sourceMappingURL=index.js.map

package/dist/graph/index.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../../src/graph/errors.ts","../../src/graph/client.ts"],"sourcesContent":["/**\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  NetworkError,\n} from './errors.js';\nimport type {\n  GraphEntity,\n  EntityWithRelationships,\n  Relationship,\n  RelationshipDirection,\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 and graph traversal from the Arke knowledge graph.\n *\n * The GraphDB is an indexed mirror of entity data stored in IPFS. Use this client for:\n * - **Bidirectional relationship queries** (IPFS only stores outbound relationships)\n * - **Path finding** between entities\n * - **Lineage queries** (PI ancestors/descendants)\n * - **Code-based lookups** (indexed for fast search)\n * - **Listing extracted entities** from a PI\n *\n * For entity CRUD operations, use ContentClient (source of truth in IPFS).\n * For write operations, use EditClient.\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 BOTH inbound and outbound relationships (GraphDB indexed)\n * const allRels = await graph.getRelationships('01K75HQQXNTDG7BBP7PS9AWYAN');\n *\n * // Get only inbound relationships (\"who references this entity?\")\n * const incoming = await graph.getRelationships('01K75HQQXNTDG7BBP7PS9AWYAN', 'incoming');\n *\n * // Find paths between entities\n * const paths = await graph.findPaths(['entity-1'], ['entity-2'], { max_depth: 4 });\n *\n * // Get PI lineage\n * const lineage = await graph.getLineage('01K75HQQXNTDG7BBP7PS9AWYAN', 'ancestors');\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  // Code-based Lookups (indexed in GraphDB)\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 extracted from a specific PI or multiple PIs.\n   *\n   * This returns knowledge graph entities (persons, places, events, etc.)\n   * that were extracted from the given PI(s), not the PI entity itself.\n   *\n   * @param pi - Single PI or array of PIs\n   * @param options - Filter options\n   * @returns Extracted 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   * This traverses the PI hierarchy (parent_pi/children_pi relationships)\n   * which is indexed in GraphDB for fast lookups.\n   *\n   * @param pi - Source PI\n   * @param direction - 'ancestors', 'descendants', or 'both'\n   * @param maxHops - Maximum depth to traverse (default: 10)\n   * @returns Lineage data with PIs at each hop level\n   *\n   * @example\n   * ```typescript\n   * // Get ancestors (parent chain)\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 relationships for an entity from the GraphDB index.\n   *\n   * **Important distinction from ContentClient.getRelationships():**\n   * - **ContentClient.getRelationships()**: Returns OUTBOUND relationships only\n   *   (from the entity's relationships.json in IPFS - source of truth)\n   * - **GraphClient.getRelationships()**: Returns BOTH inbound AND outbound\n   *   relationships (from the indexed GraphDB mirror)\n   *\n   * Use this method when you need to find \"what references this entity\" (inbound)\n   * or want a complete bidirectional view.\n   *\n   * @param id - Entity identifier (works for both PIs and KG entities)\n   * @param direction - Filter by direction: 'outgoing', 'incoming', or 'both' (default)\n   * @returns Array of relationships with direction indicator\n   *\n   * @example\n   * ```typescript\n   * // Get all relationships (both directions)\n   * const all = await graph.getRelationships('01K75HQQXNTDG7BBP7PS9AWYAN');\n   *\n   * // Get only inbound relationships (\"who references this entity?\")\n   * const incoming = await graph.getRelationships('01K75HQQXNTDG7BBP7PS9AWYAN', 'incoming');\n   *\n   * // Get only outbound relationships (similar to IPFS, but from index)\n   * const outgoing = await graph.getRelationships('01K75HQQXNTDG7BBP7PS9AWYAN', 'outgoing');\n   *\n   * // Process by direction\n   * const rels = await graph.getRelationships('entity-id');\n   * rels.forEach(r => {\n   *   if (r.direction === 'incoming') {\n   *     console.log(`${r.target_label} references this entity via ${r.predicate}`);\n   *   } else {\n   *     console.log(`This entity ${r.predicate} -> ${r.target_label}`);\n   *   }\n   * });\n   * ```\n   */\n  async getRelationships(\n    id: string,\n    direction: RelationshipDirection = 'both'\n  ): 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(id)}`);\n\n    if (!response.found || !response.relationships) {\n      return [];\n    }\n\n    let relationships = response.relationships;\n\n    // Filter by direction if specified\n    if (direction !== 'both') {\n      relationships = relationships.filter(rel => rel.direction === direction);\n    }\n\n    return 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   *   ['entity-alice'],\n   *   ['entity-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   *   ['event-id'],\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":[]}