@arke-institute/sdk 0.1.0 → 0.1.2

package/dist/graph/index.d.cts

@@ -0,0 +1,456 @@
+/**
+ * Graph package types for the Arke SDK
+ *
+ * Types for interacting with entity relationships from the GraphDB Gateway service.
+ */
+/**
+ * Entity from the knowledge graph
+ */
+interface GraphEntity {
+    /** Unique identifier (UUID) */
+    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 from the Arke knowledge graph.
+ *
+ * All endpoints are public and do not require authentication.
+ *
+ * @example
+ * ```typescript
+ * const graph = new GraphClient({
+ *   gatewayUrl: 'https://gateway.arke.institute',
+ * });
+ *
+ * // Get entity by ID
+ * const entity = await graph.getEntity('uuid-123');
+ *
+ * // Find entities by code
+ * const results = await graph.queryByCode('person_john');
+ *
+ * // Get entities with relationships from a PI
+ * const entities = await graph.getEntitiesWithRelationships('01K75HQQXNTDG7BBP7PS9AWYAN');
+ *
+ * // Find paths between entities
+ * const paths = await graph.findPaths(['uuid-1'], ['uuid-2'], { max_depth: 4 });
+ * ```
+ */
+declare class GraphClient {
+    private baseUrl;
+    private fetchImpl;
+    constructor(config: GraphClientConfig);
+    private buildUrl;
+    private request;
+    /**
+     * 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);
+     * ```
+     */
+    getEntity(canonicalId: string): Promise<GraphEntity>;
+    /**
+     * 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');
+     * }
+     * ```
+     */
+    entityExists(canonicalId: string): Promise<boolean>;
+    /**
+     * 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 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']);
+     * ```
+     */
+    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.
+     *
+     * @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');
+     * ```
+     */
+    getLineage(pi: string, direction?: 'ancestors' | 'descendants' | 'both', maxHops?: number): Promise<LineageResponse>;
+    /**
+     * 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}`);
+     * });
+     * ```
+     */
+    getRelationships(canonicalId: string): 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(
+     *   ['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}`);
+     *   });
+     * });
+     * ```
+     */
+    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(
+     *   ['uuid-event'],
+     *   '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 };