@arke-institute/sdk 0.1.3 → 2.1.0

package/dist/crypto-CQnwqWQn.d.ts

@@ -0,0 +1,459 @@
+import { Client } from 'openapi-fetch';
+import { paths } from './generated/index.js';
+
+/**
+ * SDK configuration types
+ */
+interface ArkeClientConfig {
+    /**
+     * Base URL for the Arke API
+     * @default 'https://arke-v1.arke.institute'
+     */
+    baseUrl?: string;
+    /**
+     * Authentication token (JWT or API key)
+     */
+    authToken?: string;
+    /**
+     * Network to use ('main' or 'test')
+     * Test network uses 'II' prefixed IDs and isolated data
+     * @default 'main'
+     */
+    network?: 'main' | 'test';
+    /**
+     * Callback to refresh auth token when expired
+     * Called automatically on 401 responses
+     */
+    onTokenRefresh?: () => Promise<string>;
+    /**
+     * Custom headers to include in all requests
+     */
+    headers?: Record<string, string>;
+}
+declare const DEFAULT_CONFIG: Required<Pick<ArkeClientConfig, 'baseUrl' | 'network'>>;
+
+/**
+ * Main Arke SDK Client
+ *
+ * Provides type-safe access to the Arke API using openapi-fetch.
+ */
+
+type ArkeApiClient = Client<paths>;
+/**
+ * Type-safe client for the Arke API
+ *
+ * @example
+ * ```typescript
+ * const arke = new ArkeClient({ authToken: 'your-jwt-token' });
+ *
+ * // Create an entity
+ * const { data, error } = await arke.api.POST('/entities', {
+ *   body: {
+ *     collection_id: '01ABC...',
+ *     type: 'document',
+ *     properties: { title: 'My Document' }
+ *   }
+ * });
+ *
+ * // Get an entity
+ * const { data } = await arke.api.GET('/entities/{id}', {
+ *   params: { path: { id: '01XYZ...' } }
+ * });
+ * ```
+ */
+declare class ArkeClient {
+    /**
+     * The underlying openapi-fetch client with full type safety
+     * Use this for all API calls: arke.api.GET, arke.api.POST, etc.
+     */
+    api: ArkeApiClient;
+    private config;
+    constructor(config?: ArkeClientConfig);
+    private createClient;
+    /**
+     * Update the authentication token
+     * Recreates the underlying client with new headers
+     */
+    setAuthToken(token: string): void;
+    /**
+     * Clear the authentication token
+     */
+    clearAuthToken(): void;
+    /**
+     * Get the current configuration
+     */
+    getConfig(): Readonly<ArkeClientConfig>;
+    /**
+     * Get the base URL
+     */
+    get baseUrl(): string;
+    /**
+     * Check if client is authenticated
+     */
+    get isAuthenticated(): boolean;
+}
+/**
+ * Create a new ArkeClient instance
+ * Convenience function for those who prefer functional style
+ */
+declare function createArkeClient(config?: ArkeClientConfig): ArkeClient;
+
+/**
+ * Upload Types
+ *
+ * Type definitions for the folder/file upload system.
+ */
+/**
+ * Represents a file to be uploaded.
+ * Platform-agnostic - works with browser File API or Node.js buffers.
+ */
+interface UploadFile {
+    /** Filename (e.g., "document.pdf") */
+    name: string;
+    /** Relative path from upload root (e.g., "docs/reports/document.pdf") */
+    relativePath: string;
+    /** File size in bytes */
+    size: number;
+    /** MIME type (e.g., "application/pdf") */
+    mimeType: string;
+    /**
+     * Function to retrieve the file data.
+     * Called during upload phase.
+     */
+    getData: () => Promise<ArrayBuffer | Blob | Uint8Array>;
+}
+/**
+ * Represents a folder in the upload tree.
+ */
+interface UploadFolder {
+    /** Folder name (e.g., "reports") */
+    name: string;
+    /** Relative path from upload root (e.g., "docs/reports") */
+    relativePath: string;
+}
+/**
+ * Complete tree structure to upload.
+ * Built by platform-specific scanners.
+ */
+interface UploadTree {
+    /** All files to upload */
+    files: UploadFile[];
+    /** All folders to create (sorted by depth for correct ordering) */
+    folders: UploadFolder[];
+}
+/**
+ * Target specification for upload.
+ * Determines where items will be placed.
+ */
+interface UploadTarget {
+    /**
+     * Collection ID - required for permissions.
+     * If not provided and createCollection is not set, upload will fail.
+     */
+    collectionId?: string;
+    /**
+     * Parent folder/collection ID where items will be added.
+     * If not provided, items go to collection root.
+     * Can be the same as collectionId (collection acts as folder).
+     */
+    parentId?: string;
+    /**
+     * Create a new collection for this upload.
+     * If set, collectionId is ignored.
+     */
+    createCollection?: {
+        /** Collection display name (required) */
+        label: string;
+        /** Collection description */
+        description?: string;
+        /** Custom roles (uses defaults if not provided) */
+        roles?: Record<string, string[]>;
+    };
+}
+/**
+ * Upload progress tracking.
+ */
+interface UploadProgress$1 {
+    /** Current phase of the upload */
+    phase: 'scanning' | 'computing-cids' | 'creating-folders' | 'creating-files' | 'uploading-content' | 'linking' | 'complete' | 'error';
+    /** Total number of files to upload */
+    totalFiles: number;
+    /** Number of files completed */
+    completedFiles: number;
+    /** Total number of folders to create */
+    totalFolders: number;
+    /** Number of folders completed */
+    completedFolders: number;
+    /** Current file being processed */
+    currentFile?: string;
+    /** Current folder being processed */
+    currentFolder?: string;
+    /** Error message if phase is 'error' */
+    error?: string;
+    /** Bytes uploaded so far (for content upload phase) */
+    bytesUploaded?: number;
+    /** Total bytes to upload */
+    totalBytes?: number;
+}
+/**
+ * Configuration options for upload.
+ */
+interface UploadOptions {
+    /** Where to upload */
+    target: UploadTarget;
+    /** Progress callback */
+    onProgress?: (progress: UploadProgress$1) => void;
+    /** Maximum concurrent operations (default: 5) */
+    concurrency?: number;
+    /** Continue uploading even if some files fail (default: false) */
+    continueOnError?: boolean;
+    /** Custom note to add to created entities */
+    note?: string;
+}
+/**
+ * Information about a created entity.
+ */
+interface CreatedEntity {
+    /** Entity ID (ULID) */
+    id: string;
+    /** Entity CID */
+    cid: string;
+    /** Entity type */
+    type: 'file' | 'folder' | 'collection';
+    /** Original path in upload tree */
+    relativePath: string;
+}
+/**
+ * Result of an upload operation.
+ */
+interface UploadResult {
+    /** Whether upload completed successfully */
+    success: boolean;
+    /** Collection used or created */
+    collection: {
+        id: string;
+        cid: string;
+        created: boolean;
+    };
+    /** Created folder entities */
+    folders: CreatedEntity[];
+    /** Created file entities */
+    files: CreatedEntity[];
+    /** Errors encountered (if continueOnError was true) */
+    errors: Array<{
+        path: string;
+        error: string;
+    }>;
+}
+
+/**
+ * Folder Operations (Legacy)
+ *
+ * @deprecated Use the new upload module instead:
+ * ```typescript
+ * import { uploadTree, scanDirectory } from '@arke-institute/sdk/operations';
+ *
+ * const tree = await scanDirectory('/path/to/folder');
+ * const result = await uploadTree(client, tree, {
+ *   target: { collectionId: '...' },
+ * });
+ * ```
+ */
+
+/**
+ * @deprecated Use UploadProgress from upload module
+ */
+interface UploadProgress {
+    phase: 'scanning' | 'creating-folders' | 'uploading-files' | 'linking' | 'complete';
+    totalFiles: number;
+    completedFiles: number;
+    totalFolders: number;
+    completedFolders: number;
+    currentFile?: string;
+}
+/**
+ * @deprecated Use UploadOptions from upload module
+ */
+interface UploadDirectoryOptions {
+    /** Collection to upload into */
+    collectionId: string;
+    /** Parent folder ID (optional - creates at root if not provided) */
+    parentFolderId?: string;
+    /** Progress callback */
+    onProgress?: (progress: UploadProgress) => void;
+    /** Max concurrent uploads */
+    concurrency?: number;
+}
+/**
+ * @deprecated Use UploadResult from upload module
+ */
+interface UploadDirectoryResult {
+    /** Root folder entity */
+    rootFolder: unknown;
+    /** All created folder entities */
+    folders: unknown[];
+    /** All created file entities */
+    files: unknown[];
+}
+/**
+ * Folder operations helper
+ *
+ * @deprecated Use uploadTree and scanDirectory functions instead:
+ * ```typescript
+ * import { uploadTree, scanDirectory } from '@arke-institute/sdk/operations';
+ *
+ * const tree = await scanDirectory('/path/to/folder');
+ * const result = await uploadTree(client, tree, {
+ *   target: { collectionId: '...' },
+ *   onProgress: (p) => console.log(`${p.completedFiles}/${p.totalFiles} files`),
+ * });
+ * ```
+ */
+declare class FolderOperations {
+    private client;
+    constructor(client: ArkeClient);
+    /**
+     * Upload a local directory to Arke
+     *
+     * @deprecated Use uploadTree and scanDirectory instead
+     */
+    uploadDirectory(localPath: string, options: UploadDirectoryOptions): Promise<UploadDirectoryResult>;
+}
+
+/**
+ * Batch Operations
+ *
+ * High-level operations for bulk entity and relationship management.
+ *
+ * TODO: Implement batch operations
+ * - createEntities: Create multiple entities in parallel
+ * - updateEntities: Update multiple entities in parallel
+ * - createRelationships: Create multiple relationships in parallel
+ */
+
+interface BatchCreateOptions {
+    /** Max concurrent operations */
+    concurrency?: number;
+    /** Continue on individual failures */
+    continueOnError?: boolean;
+    /** Progress callback */
+    onProgress?: (completed: number, total: number) => void;
+}
+interface BatchResult<T> {
+    /** Successfully completed operations */
+    succeeded: T[];
+    /** Failed operations with errors */
+    failed: Array<{
+        input: unknown;
+        error: Error;
+    }>;
+}
+/**
+ * Batch operations helper
+ *
+ * @example
+ * ```typescript
+ * const batch = new BatchOperations(arkeClient);
+ * const result = await batch.createEntities([
+ *   { type: 'document', properties: { title: 'Doc 1' } },
+ *   { type: 'document', properties: { title: 'Doc 2' } },
+ * ], { concurrency: 5 });
+ * ```
+ */
+declare class BatchOperations {
+    private client;
+    constructor(client: ArkeClient);
+    /**
+     * Create multiple entities in parallel
+     *
+     * TODO: Implement this method
+     */
+    createEntities(_entities: Array<{
+        collectionId: string;
+        type: string;
+        properties?: Record<string, unknown>;
+    }>, _options?: BatchCreateOptions): Promise<BatchResult<unknown>>;
+    /**
+     * Create multiple relationships in parallel
+     *
+     * TODO: Implement this method
+     */
+    createRelationships(_relationships: Array<{
+        sourceId: string;
+        targetId: string;
+        predicate: string;
+        bidirectional?: boolean;
+        properties?: Record<string, unknown>;
+    }>, _options?: BatchCreateOptions): Promise<BatchResult<unknown>>;
+}
+
+/**
+ * Crypto Operations
+ *
+ * Cryptographic utilities for agents and content addressing.
+ *
+ * TODO: Implement crypto operations
+ * - generateKeyPair: Generate Ed25519 key pair for agent authentication
+ * - signPayload: Sign a payload with agent private key
+ * - computeCID: Compute IPFS CID for content
+ */
+/**
+ * Ed25519 key pair for agent authentication
+ */
+interface KeyPair {
+    /** Public key in base64 */
+    publicKey: string;
+    /** Private key in base64 (keep secret!) */
+    privateKey: string;
+}
+/**
+ * Signed payload with signature
+ */
+interface SignedPayload {
+    /** Original payload */
+    payload: string;
+    /** Ed25519 signature in base64 */
+    signature: string;
+    /** Timestamp of signature */
+    timestamp: number;
+}
+/**
+ * Crypto operations helper
+ *
+ * @example
+ * ```typescript
+ * // Generate key pair for a new agent
+ * const { publicKey, privateKey } = await CryptoOperations.generateKeyPair();
+ *
+ * // Sign a payload
+ * const signed = await CryptoOperations.signPayload(privateKey, payload);
+ * ```
+ */
+declare class CryptoOperations {
+    /**
+     * Generate an Ed25519 key pair for agent authentication
+     *
+     * TODO: Implement using Node.js crypto or Web Crypto API
+     */
+    static generateKeyPair(): Promise<KeyPair>;
+    /**
+     * Sign a payload with an Ed25519 private key
+     *
+     * TODO: Implement signature generation
+     */
+    static signPayload(_privateKey: string, _payload: string): Promise<SignedPayload>;
+    /**
+     * Verify an Ed25519 signature
+     *
+     * TODO: Implement signature verification
+     */
+    static verifySignature(_publicKey: string, _payload: string, _signature: string): Promise<boolean>;
+    /**
+     * Compute IPFS CID for content
+     *
+     * TODO: Implement using multiformats library
+     */
+    static computeCID(_content: Uint8Array): Promise<string>;
+}
+
+export { ArkeClient as A, BatchOperations as B, CryptoOperations as C, DEFAULT_CONFIG as D, FolderOperations as F, type KeyPair as K, type SignedPayload as S, type UploadProgress$1 as U, type ArkeApiClient as a, type ArkeClientConfig as b, createArkeClient as c, type UploadDirectoryOptions as d, type UploadDirectoryResult as e, type BatchCreateOptions as f, type BatchResult as g, type UploadTree as h, type UploadOptions as i, type UploadResult as j, type UploadFile as k, type UploadFolder as l, type UploadTarget as m, type CreatedEntity as n };