@arke-institute/sdk 0.1.1 → 0.1.3

package/dist/content/index.d.ts

@@ -0,0 +1,516 @@
+/**
+ * Content package types for the Arke SDK
+ *
+ * Types for interacting with entities and content from the IPFS Wrapper service.
+ * Based on the arke/eidos@v1 schema.
+ */
+/**
+ * Full entity manifest from IPFS Wrapper
+ */
+interface Entity {
+    /** Entity identifier (ULID or test ID with II prefix) */
+    id: string;
+    /** Entity type (e.g., "PI", "person", "place", "concept", "document") */
+    type: string;
+    /** Creation timestamp (immutable, set at v1) */
+    created_at: string;
+    /** Display name */
+    label?: string;
+    /** Human-readable description */
+    description?: string;
+    /** Version number */
+    ver: number;
+    /** Timestamp when this version was created */
+    ts: string;
+    /** CID of this manifest */
+    manifest_cid: string;
+    /** CID of the previous version (null for version 1) */
+    prev_cid: string | null;
+    /** Map of component names to their CIDs */
+    components: Record<string, string>;
+    /** IDs of child entities */
+    children_pi?: string[];
+    /** ID of parent entity */
+    parent_pi?: string;
+    /** Provenance: which PI extracted this entity */
+    source_pi?: string;
+    /** IDs of entities that have been merged into this one */
+    merged_entities?: string[];
+    /** Change note for this version */
+    note?: string;
+}
+/**
+ * Summary entity info returned when listing entities
+ */
+interface EntitySummary {
+    /** Entity identifier */
+    id: string;
+    /** Tip CID (latest manifest) */
+    tip: string;
+    /** Entity type (if include_metadata=true) */
+    type?: string;
+    /** Display name (if include_metadata=true) */
+    label?: string;
+    /** Version number (if include_metadata=true) */
+    ver?: number;
+    /** Timestamp (if include_metadata=true) */
+    ts?: string;
+    /** Change note (if include_metadata=true) */
+    note?: string;
+    /** Number of components (if include_metadata=true) */
+    component_count?: number;
+    /** Number of children (if include_metadata=true) */
+    children_count?: number;
+}
+/**
+ * Version entry in version history
+ */
+interface EntityVersion {
+    /** Version number */
+    ver: number;
+    /** CID of this version's manifest */
+    cid: string;
+    /** Timestamp when this version was created */
+    ts: string;
+    /** Change note for this version */
+    note?: string;
+}
+/**
+ * Options for listing entities
+ */
+interface ListOptions {
+    /** Maximum entities to return (1-1000, default: 100) */
+    limit?: number;
+    /** Cursor for pagination (CID, base32 starting with 'b') */
+    cursor?: string;
+    /** Whether to include full metadata for each entity */
+    include_metadata?: boolean;
+}
+/**
+ * Options for listing versions
+ */
+interface VersionsOptions {
+    /** Maximum versions to return (default: 20) */
+    limit?: number;
+    /** Cursor for pagination (CID to start from) */
+    cursor?: string;
+}
+/**
+ * Response from listing entities
+ */
+interface ListResponse {
+    /** List of entity summaries */
+    entities: EntitySummary[];
+    /** Number of entities returned (matches limit) */
+    limit: number;
+    /** Cursor for next page (null if no more) */
+    next_cursor: string | null;
+}
+/**
+ * Response from listing versions
+ */
+interface VersionsResponse {
+    /** List of versions (newest first) */
+    items: EntityVersion[];
+    /** Cursor for next page (null if reached genesis) */
+    next_cursor: string | null;
+}
+/**
+ * Response from resolving a PI
+ */
+interface ResolveResponse {
+    /** Entity identifier */
+    id: string;
+    /** Tip CID (latest manifest) */
+    tip: string;
+}
+/**
+ * A single relationship edge in the semantic graph.
+ *
+ * Represents a typed, directional relationship from the source entity
+ * to a target entity or PI.
+ */
+interface Relationship {
+    /** Relationship predicate (e.g., "authored_by", "mentions", "located_in") */
+    predicate: string;
+    /** Type of target */
+    target_type: 'pi' | 'entity';
+    /** Target entity identifier */
+    target_id: string;
+    /** Display label for the target (e.g., "Alice Austen") */
+    target_label: string;
+    /** Target entity type (e.g., "person", "place") - only if target is entity */
+    target_entity_type?: string;
+    /** Optional metadata on the relationship edge */
+    properties?: Record<string, unknown>;
+}
+/**
+ * Relationships component stored in IPFS (arke/relationships@v1 schema).
+ *
+ * Contains the semantic graph relationships for an entity.
+ */
+interface RelationshipsComponent {
+    /** Schema identifier */
+    schema: 'arke/relationships@v1';
+    /** Array of relationships */
+    relationships: Relationship[];
+    /** ISO 8601 timestamp when this component was created/updated */
+    timestamp: string;
+    /** Optional note about changes */
+    note?: string;
+}
+/**
+ * Properties component stored in IPFS.
+ *
+ * Contains arbitrary metadata properties for an entity.
+ */
+interface PropertiesComponent {
+    /** Arbitrary key-value properties */
+    [key: string]: unknown;
+}
+
+/**
+ * Configuration for ContentClient
+ */
+interface ContentClientConfig {
+    /**
+     * Gateway base URL (e.g., https://gateway.arke.institute).
+     * The client will call /api/* endpoints for IPFS Wrapper.
+     */
+    gatewayUrl: string;
+    /**
+     * Optional custom fetch implementation (useful for testing).
+     */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Client for accessing entities and content from the Arke archive.
+ *
+ * All endpoints are public and do not require authentication.
+ *
+ * @example
+ * ```typescript
+ * const content = new ContentClient({
+ *   gatewayUrl: 'https://gateway.arke.institute',
+ * });
+ *
+ * // Get an entity
+ * const entity = await content.get('01K75HQQXNTDG7BBP7PS9AWYAN');
+ *
+ * // Download content by CID
+ * const blob = await content.download('bafybeihkoviema7g3gxyt6la7vd5ho32jywf7b4c4z3qtwcabpjqxwsumu');
+ *
+ * // Get component content
+ * const pinax = await content.getComponent(entity, 'pinax');
+ * ```
+ */
+declare class ContentClient {
+    private baseUrl;
+    private fetchImpl;
+    constructor(config: ContentClientConfig);
+    private buildUrl;
+    private request;
+    /**
+     * Get an entity by its Persistent Identifier (PI).
+     *
+     * @param pi - Persistent Identifier (ULID or test PI with II prefix)
+     * @returns Full entity manifest
+     * @throws EntityNotFoundError if the entity doesn't exist
+     *
+     * @example
+     * ```typescript
+     * const entity = await content.get('01K75HQQXNTDG7BBP7PS9AWYAN');
+     * console.log('Version:', entity.ver);
+     * console.log('Components:', Object.keys(entity.components));
+     * ```
+     */
+    get(pi: string): Promise<Entity>;
+    /**
+     * List entities with pagination.
+     *
+     * @param options - Pagination and metadata options
+     * @returns Paginated list of entity summaries
+     *
+     * @example
+     * ```typescript
+     * // Get first page
+     * const page1 = await content.list({ limit: 20, include_metadata: true });
+     *
+     * // Get next page
+     * if (page1.next_cursor) {
+     *   const page2 = await content.list({ cursor: page1.next_cursor });
+     * }
+     * ```
+     */
+    list(options?: ListOptions): Promise<ListResponse>;
+    /**
+     * Get version history for an entity.
+     *
+     * @param pi - Persistent Identifier
+     * @param options - Pagination options
+     * @returns Version history (newest first)
+     *
+     * @example
+     * ```typescript
+     * const history = await content.versions('01K75HQQXNTDG7BBP7PS9AWYAN');
+     * console.log('Total versions:', history.items.length);
+     * history.items.forEach(v => {
+     *   console.log(`v${v.ver}: ${v.ts} - ${v.note || 'no note'}`);
+     * });
+     * ```
+     */
+    versions(pi: string, options?: VersionsOptions): Promise<VersionsResponse>;
+    /**
+     * Get a specific version of an entity.
+     *
+     * @param pi - Persistent Identifier
+     * @param selector - Version selector: 'ver:N' for version number or 'cid:...' for CID
+     * @returns Entity manifest for the specified version
+     *
+     * @example
+     * ```typescript
+     * // Get version 2
+     * const v2 = await content.getVersion('01K75HQQXNTDG7BBP7PS9AWYAN', 'ver:2');
+     *
+     * // Get by CID
+     * const vByCid = await content.getVersion('01K75HQQXNTDG7BBP7PS9AWYAN', 'cid:bafybeih...');
+     * ```
+     */
+    getVersion(pi: string, selector: string): Promise<Entity>;
+    /**
+     * Resolve a PI to its tip CID (fast lookup without fetching manifest).
+     *
+     * @param pi - Persistent Identifier
+     * @returns PI and tip CID
+     *
+     * @example
+     * ```typescript
+     * const { tip } = await content.resolve('01K75HQQXNTDG7BBP7PS9AWYAN');
+     * console.log('Latest manifest CID:', tip);
+     * ```
+     */
+    resolve(pi: string): Promise<ResolveResponse>;
+    /**
+     * Get the list of child PIs for an entity (fast, returns only PIs).
+     *
+     * @param pi - Persistent Identifier of parent entity
+     * @returns Array of child PIs
+     *
+     * @example
+     * ```typescript
+     * const childPis = await content.children('01K75HQQXNTDG7BBP7PS9AWYAN');
+     * console.log('Children:', childPis);
+     * ```
+     */
+    children(pi: string): Promise<string[]>;
+    /**
+     * Get all child entities for a parent (fetches full entity for each child).
+     *
+     * @param pi - Persistent Identifier of parent entity
+     * @returns Array of child entities
+     *
+     * @example
+     * ```typescript
+     * const childEntities = await content.childrenEntities('01K75HQQXNTDG7BBP7PS9AWYAN');
+     * childEntities.forEach(child => {
+     *   console.log(`${child.pi}: v${child.ver}`);
+     * });
+     * ```
+     */
+    childrenEntities(pi: string): Promise<Entity[]>;
+    /**
+     * Get the Arke origin block (root of the archive tree).
+     *
+     * @returns Arke origin entity
+     *
+     * @example
+     * ```typescript
+     * const origin = await content.arke();
+     * console.log('Arke origin:', origin.pi);
+     * ```
+     */
+    arke(): Promise<Entity>;
+    /**
+     * Download content by CID.
+     *
+     * Returns Blob in browser environments, Buffer in Node.js.
+     *
+     * @param cid - Content Identifier
+     * @returns Content as Blob (browser) or Buffer (Node)
+     * @throws ContentNotFoundError if the content doesn't exist
+     *
+     * @example
+     * ```typescript
+     * const content = await client.download('bafybeih...');
+     *
+     * // In browser
+     * const url = URL.createObjectURL(content as Blob);
+     *
+     * // In Node.js
+     * fs.writeFileSync('output.bin', content as Buffer);
+     * ```
+     */
+    download(cid: string): Promise<Blob | Buffer>;
+    /**
+     * Get a direct URL for content by CID.
+     *
+     * This is useful for embedding in img tags or for direct downloads.
+     *
+     * @param cid - Content Identifier
+     * @returns URL string
+     *
+     * @example
+     * ```typescript
+     * const url = content.getUrl('bafybeih...');
+     * // Use in img tag: <img src={url} />
+     * ```
+     */
+    getUrl(cid: string): string;
+    /**
+     * Stream content by CID.
+     *
+     * @param cid - Content Identifier
+     * @returns ReadableStream of the content
+     * @throws ContentNotFoundError if the content doesn't exist
+     *
+     * @example
+     * ```typescript
+     * const stream = await content.stream('bafybeih...');
+     * const reader = stream.getReader();
+     * while (true) {
+     *   const { done, value } = await reader.read();
+     *   if (done) break;
+     *   // Process chunk
+     * }
+     * ```
+     */
+    stream(cid: string): Promise<ReadableStream<Uint8Array>>;
+    /**
+     * Download a DAG node (JSON) by CID.
+     *
+     * Use this to fetch JSON components like properties and relationships.
+     *
+     * @param cid - Content Identifier of the DAG node
+     * @returns Parsed JSON object
+     * @throws ContentNotFoundError if the content doesn't exist
+     *
+     * @example
+     * ```typescript
+     * const relationships = await content.getDag<RelationshipsComponent>(
+     *   entity.components.relationships
+     * );
+     * console.log('Relationships:', relationships.relationships);
+     * ```
+     */
+    getDag<T = unknown>(cid: string): Promise<T>;
+    /**
+     * Download a component from an entity.
+     *
+     * @param entity - Entity containing the component
+     * @param componentName - Name of the component (e.g., 'pinax', 'description', 'source')
+     * @returns Component content as Blob (browser) or Buffer (Node)
+     * @throws ComponentNotFoundError if the component doesn't exist
+     *
+     * @example
+     * ```typescript
+     * const entity = await content.get('01K75HQQXNTDG7BBP7PS9AWYAN');
+     * const pinax = await content.getComponent(entity, 'pinax');
+     * ```
+     */
+    getComponent(entity: Entity, componentName: string): Promise<Blob | Buffer>;
+    /**
+     * Get the URL for a component from an entity.
+     *
+     * @param entity - Entity containing the component
+     * @param componentName - Name of the component
+     * @returns URL string
+     * @throws ComponentNotFoundError if the component doesn't exist
+     *
+     * @example
+     * ```typescript
+     * const entity = await content.get('01K75HQQXNTDG7BBP7PS9AWYAN');
+     * const imageUrl = content.getComponentUrl(entity, 'source');
+     * // Use in img tag: <img src={imageUrl} />
+     * ```
+     */
+    getComponentUrl(entity: Entity, componentName: string): string;
+    /**
+     * Get the properties component for an entity.
+     *
+     * @param entity - Entity containing the properties component
+     * @returns Properties object, or null if no properties component exists
+     *
+     * @example
+     * ```typescript
+     * const entity = await content.get('01K75HQQXNTDG7BBP7PS9AWYAN');
+     * const props = await content.getProperties(entity);
+     * if (props) {
+     *   console.log('Title:', props.title);
+     * }
+     * ```
+     */
+    getProperties(entity: Entity): Promise<PropertiesComponent | null>;
+    /**
+     * Get the relationships component for an entity.
+     *
+     * @param entity - Entity containing the relationships component
+     * @returns Relationships component, or null if no relationships exist
+     *
+     * @example
+     * ```typescript
+     * const entity = await content.get('01K75HQQXNTDG7BBP7PS9AWYAN');
+     * const rels = await content.getRelationships(entity);
+     * if (rels) {
+     *   rels.relationships.forEach(r => {
+     *     console.log(`${r.predicate} -> ${r.target_label}`);
+     *   });
+     * }
+     * ```
+     */
+    getRelationships(entity: Entity): Promise<RelationshipsComponent | null>;
+}
+
+/**
+ * Content package error classes for the Arke SDK
+ */
+/**
+ * Base error class for content operations
+ */
+declare class ContentError extends Error {
+    code: string;
+    details?: unknown | undefined;
+    constructor(message: string, code?: string, details?: unknown | undefined);
+}
+/**
+ * Thrown when an entity is not found by ID
+ */
+declare class EntityNotFoundError extends ContentError {
+    constructor(id: string);
+}
+/**
+ * Thrown when content is not found by CID
+ */
+declare class ContentNotFoundError extends ContentError {
+    constructor(cid: string);
+}
+/**
+ * Thrown when a component is not found on an entity
+ */
+declare class ComponentNotFoundError extends ContentError {
+    constructor(id: string, componentName: string);
+}
+/**
+ * Thrown when a version is not found
+ */
+declare class VersionNotFoundError extends ContentError {
+    constructor(id: string, selector: string);
+}
+/**
+ * Thrown when a network error occurs
+ */
+declare class NetworkError extends ContentError {
+    statusCode?: number | undefined;
+    constructor(message: string, statusCode?: number | undefined);
+}
+
+export { ComponentNotFoundError, ContentClient, type ContentClientConfig, ContentError, ContentNotFoundError, type Entity, EntityNotFoundError, type EntitySummary, type EntityVersion, type ListOptions, type ListResponse, NetworkError, type PropertiesComponent, type Relationship, type RelationshipsComponent, type ResolveResponse, VersionNotFoundError, type VersionsOptions, type VersionsResponse };