@arke-institute/sdk 0.1.2 → 2.0.0

package/dist/content/index.d.ts

@@ -1,403 +0,0 @@
-/**
- * Content package types for the Arke SDK
- *
- * Types for interacting with entities and content from the IPFS Wrapper service.
- */
-/**
- * Full entity manifest from IPFS Wrapper
- */
-interface Entity {
-    /** Persistent Identifier (ULID or test PI with II prefix) */
-    pi: 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 (undefined for version 1) */
-    prev_cid?: string;
-    /** Map of component names to their CIDs */
-    components: Record<string, string>;
-    /** PIs of child entities */
-    children_pi?: string[];
-    /** PI of parent entity */
-    parent_pi?: string;
-    /** Change note for this version */
-    note?: string;
-}
-/**
- * Summary entity info returned when listing entities
- */
-interface EntitySummary {
-    /** Persistent Identifier */
-    pi: string;
-    /** Tip CID (latest manifest) */
-    tip: 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 {
-    /** Persistent Identifier */
-    pi: string;
-    /** Tip CID (latest manifest) */
-    tip: string;
-}
-
-/**
- * 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 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;
-}
-
-/**
- * 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 PI
- */
-declare class EntityNotFoundError extends ContentError {
-    constructor(pi: 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(pi: string, componentName: string);
-}
-/**
- * Thrown when a version is not found
- */
-declare class VersionNotFoundError extends ContentError {
-    constructor(pi: 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 ResolveResponse, VersionNotFoundError, type VersionsOptions, type VersionsResponse };