@arke-institute/sdk 0.1.1 → 0.1.3

package/dist/graph/index.d.cts

@@ -0,0 +1,485 @@
+/**
+ * Graph package types for the Arke SDK
+ *
+ * Types for interacting with the GraphDB Gateway service.
+ *
+ * The GraphDB is an indexed mirror of entity data stored in IPFS. Entity IDs
+ * are consistent across both systems - the same ID works in ContentClient
+ * (IPFS source of truth) and GraphClient (indexed mirror).
+ *
+ * Key distinction:
+ * - IPFS stores only OUTBOUND relationships (in relationships.json)
+ * - GraphDB indexes BOTH inbound AND outbound relationships for fast bidirectional queries
+ */
+/**
+ * Direction filter for relationship queries
+ *
+ * - 'outgoing': Relationships where this entity is the source
+ * - 'incoming': Relationships where this entity is the target (only available via GraphDB)
+ * - 'both': All relationships in both directions
+ */
+type RelationshipDirection = 'outgoing' | 'incoming' | 'both';
+/**
+ * Entity from the knowledge graph (as indexed in GraphDB)
+ */
+interface GraphEntity {
+    /** Unique identifier (consistent with IPFS entity IDs) */
+    canonical_id: string;
+    /** Entity code (e.g., 'person_john', 'event_123') */
+    code: string;
+    /** Human-readable label */
+    label: string;
+    /** Entity type (e.g., 'person', 'event', 'date', 'organization') */
+    type: string;
+    /** Additional entity properties */
+    properties?: Record<string, unknown>;
+    /** PI that created this entity */
+    created_by_pi?: string;
+    /** All PIs that contributed to this entity */
+    source_pis?: string[];
+}
+/**
+ * Relationship between entities
+ */
+interface Relationship {
+    /** Direction of the relationship relative to the queried entity */
+    direction: 'outgoing' | 'incoming';
+    /** Relationship type/predicate (e.g., 'affiliated_with', 'authored', 'located_at') */
+    predicate: string;
+    /** Canonical ID of the related entity */
+    target_id: string;
+    /** Code of the related entity */
+    target_code: string;
+    /** Label of the related entity */
+    target_label: string;
+    /** Type of the related entity */
+    target_type: string;
+    /** Additional relationship properties */
+    properties?: Record<string, unknown>;
+    /** PI that created this relationship */
+    source_pi?: string;
+    /** When the relationship was created */
+    created_at?: string;
+}
+/**
+ * Entity with its relationships
+ */
+interface EntityWithRelationships extends GraphEntity {
+    /** All relationships for this entity */
+    relationships: Relationship[];
+}
+/**
+ * An edge in a path between entities
+ */
+interface PathEdge {
+    /** Subject entity ID */
+    subject_id: string;
+    /** Subject entity label */
+    subject_label: string;
+    /** Subject entity type */
+    subject_type: string;
+    /** Relationship predicate */
+    predicate: string;
+    /** Object entity ID */
+    object_id: string;
+    /** Object entity label */
+    object_label: string;
+    /** Object entity type */
+    object_type: string;
+    /** PI that contributed this edge */
+    source_pi?: string;
+}
+/**
+ * A path between two entities
+ */
+interface Path {
+    /** Starting entity ID */
+    source_id: string;
+    /** Ending entity ID */
+    target_id: string;
+    /** Number of hops in the path */
+    length: number;
+    /** Edges in the path */
+    edges: PathEdge[];
+}
+/**
+ * Options for finding paths between entities
+ */
+interface PathOptions {
+    /** Maximum traversal depth (default: 3) */
+    max_depth?: number;
+    /** Direction of traversal */
+    direction?: 'outgoing' | 'incoming' | 'both';
+    /** Maximum number of paths to return */
+    limit?: number;
+}
+/**
+ * Options for finding reachable entities
+ */
+interface ReachableOptions {
+    /** Maximum traversal depth */
+    max_depth?: number;
+    /** Direction of traversal */
+    direction?: 'outgoing' | 'incoming' | 'both';
+    /** Maximum entities to return */
+    limit?: number;
+}
+/**
+ * Options for listing entities from a PI
+ */
+interface ListFromPiOptions {
+    /** Filter by entity type */
+    type?: string;
+}
+/**
+ * Response from entity query by code
+ */
+interface EntityQueryResponse {
+    /** Whether entity was found */
+    found: boolean;
+    /** The entity (if found) */
+    entity?: GraphEntity;
+    /** Relationships (if found) */
+    relationships?: {
+        outgoing: Array<{
+            predicate: string;
+            target_id: string;
+            target_label: string;
+            target_type: string;
+        }>;
+        incoming: Array<{
+            predicate: string;
+            source_id: string;
+            source_label: string;
+            source_type: string;
+        }>;
+    };
+}
+/**
+ * Response from entities with relationships query
+ */
+interface EntitiesWithRelationshipsResponse {
+    /** PI that was queried */
+    pi: string;
+    /** Entities with their relationships */
+    entities: EntityWithRelationships[];
+    /** Total count of entities */
+    total_count: number;
+}
+/**
+ * Response from path finding
+ */
+interface PathsResponse {
+    /** Found paths */
+    paths: Path[];
+    /** Whether results were truncated */
+    truncated: boolean;
+}
+/**
+ * Lineage PI entry
+ */
+interface LineagePiEntry {
+    /** PI ID */
+    id: string;
+    /** Number of hops from source */
+    hops: number;
+    /** When the PI was created */
+    created_at?: string;
+}
+/**
+ * Lineage result set (ancestors or descendants)
+ */
+interface LineageResultSet {
+    /** List of PIs */
+    pis: LineagePiEntry[];
+    /** Total count */
+    count: number;
+    /** Whether results were truncated */
+    truncated: boolean;
+}
+/**
+ * Response from lineage query
+ */
+interface LineageResponse {
+    /** Source PI */
+    sourcePi: string;
+    /** Ancestor PIs (if requested) */
+    ancestors?: LineageResultSet;
+    /** Descendant PIs (if requested) */
+    descendants?: LineageResultSet;
+}
+
+/**
+ * Configuration for GraphClient
+ */
+interface GraphClientConfig {
+    /**
+     * Gateway base URL (e.g., https://gateway.arke.institute).
+     * The client will call /graphdb/* endpoints for GraphDB Gateway.
+     */
+    gatewayUrl: string;
+    /**
+     * Optional custom fetch implementation (useful for testing).
+     */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Client for querying entity relationships and graph traversal from the Arke knowledge graph.
+ *
+ * The GraphDB is an indexed mirror of entity data stored in IPFS. Use this client for:
+ * - **Bidirectional relationship queries** (IPFS only stores outbound relationships)
+ * - **Path finding** between entities
+ * - **Lineage queries** (PI ancestors/descendants)
+ * - **Code-based lookups** (indexed for fast search)
+ * - **Listing extracted entities** from a PI
+ *
+ * For entity CRUD operations, use ContentClient (source of truth in IPFS).
+ * For write operations, use EditClient.
+ *
+ * All endpoints are public and do not require authentication.
+ *
+ * @example
+ * ```typescript
+ * const graph = new GraphClient({
+ *   gatewayUrl: 'https://gateway.arke.institute',
+ * });
+ *
+ * // Get BOTH inbound and outbound relationships (GraphDB indexed)
+ * const allRels = await graph.getRelationships('01K75HQQXNTDG7BBP7PS9AWYAN');
+ *
+ * // Get only inbound relationships ("who references this entity?")
+ * const incoming = await graph.getRelationships('01K75HQQXNTDG7BBP7PS9AWYAN', 'incoming');
+ *
+ * // Find paths between entities
+ * const paths = await graph.findPaths(['entity-1'], ['entity-2'], { max_depth: 4 });
+ *
+ * // Get PI lineage
+ * const lineage = await graph.getLineage('01K75HQQXNTDG7BBP7PS9AWYAN', 'ancestors');
+ * ```
+ */
+declare class GraphClient {
+    private baseUrl;
+    private fetchImpl;
+    constructor(config: GraphClientConfig);
+    private buildUrl;
+    private request;
+    /**
+     * 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');
+     * ```
+     */
+    queryByCode(code: string, type?: string): Promise<GraphEntity[]>;
+    /**
+     * 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');
+     * ```
+     */
+    lookupByCode(code: string, type?: string): Promise<GraphEntity[]>;
+    /**
+     * 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']);
+     * ```
+     */
+    listEntitiesFromPi(pi: string | string[], options?: ListFromPiOptions): Promise<GraphEntity[]>;
+    /**
+     * 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`);
+     * });
+     * ```
+     */
+    getEntitiesWithRelationships(pi: string, type?: string): Promise<EntityWithRelationships[]>;
+    /**
+     * 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');
+     * ```
+     */
+    getLineage(pi: string, direction?: 'ancestors' | 'descendants' | 'both', maxHops?: number): Promise<LineageResponse>;
+    /**
+     * 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}`);
+     *   }
+     * });
+     * ```
+     */
+    getRelationships(id: string, direction?: RelationshipDirection): Promise<Relationship[]>;
+    /**
+     * 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}`);
+     *   });
+     * });
+     * ```
+     */
+    findPaths(sourceIds: string[], targetIds: string[], options?: PathOptions): Promise<Path[]>;
+    /**
+     * 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 }
+     * );
+     * ```
+     */
+    findReachable(startIds: string[], targetType: string, options?: ReachableOptions): Promise<GraphEntity[]>;
+    /**
+     * Check the health of the graph service.
+     *
+     * @returns Health status
+     */
+    health(): Promise<{
+        status: string;
+        service: string;
+        version: string;
+    }>;
+}
+
+/**
+ * Graph package error classes for the Arke SDK
+ */
+/**
+ * Base error class for graph operations
+ */
+declare class GraphError extends Error {
+    code: string;
+    details?: unknown | undefined;
+    constructor(message: string, code?: string, details?: unknown | undefined);
+}
+/**
+ * Thrown when an entity is not found by canonical ID
+ */
+declare class GraphEntityNotFoundError extends GraphError {
+    constructor(canonicalId: string);
+}
+/**
+ * Thrown when no paths are found between entities
+ */
+declare class NoPathFoundError extends GraphError {
+    constructor(sourceIds: string[], targetIds: string[]);
+}
+/**
+ * Thrown when a network error occurs
+ */
+declare class NetworkError extends GraphError {
+    statusCode?: number | undefined;
+    constructor(message: string, statusCode?: number | undefined);
+}
+
+export { type EntitiesWithRelationshipsResponse, type EntityQueryResponse, type EntityWithRelationships, GraphClient, type GraphClientConfig, type GraphEntity, GraphEntityNotFoundError, GraphError, type LineagePiEntry, type LineageResponse, type LineageResultSet, type ListFromPiOptions, NetworkError, NoPathFoundError, type Path, type PathEdge, type PathOptions, type PathsResponse, type ReachableOptions, type Relationship, type RelationshipDirection };