@arke-institute/sdk 2.0.0 → 2.2.0

package/README.md

@@ -151,6 +151,111 @@ const arke = new ArkeClient({
 });
 ```
 
+## Folder Upload
+
+Upload entire folder structures with automatic CID computation and relationship linking:
+
+### Node.js
+
+```typescript
+import { ArkeClient } from '@arke-institute/sdk';
+import { uploadTree, scanDirectory } from '@arke-institute/sdk/operations';
+
+const arke = new ArkeClient({ authToken: 'your-token' });
+
+// Scan a local directory
+const tree = await scanDirectory('/path/to/my-folder');
+
+// Upload to a new collection
+const result = await uploadTree(arke, tree, {
+  target: {
+    createCollection: {
+      label: 'My Upload',
+      description: 'Uploaded folder contents',
+    },
+  },
+  onProgress: (p) => {
+    console.log(`${p.phase}: ${p.completedFiles}/${p.totalFiles} files`);
+  },
+});
+
+console.log('Collection:', result.collection.id);
+console.log('Files:', result.files.length);
+console.log('Folders:', result.folders.length);
+```
+
+### Browser (Drag & Drop)
+
+```typescript
+import { uploadTree, scanFileSystemEntries } from '@arke-institute/sdk/operations';
+
+dropzone.ondrop = async (e) => {
+  e.preventDefault();
+  const entries = Array.from(e.dataTransfer.items)
+    .map(item => item.webkitGetAsEntry())
+    .filter(Boolean);
+
+  const tree = await scanFileSystemEntries(entries);
+  const result = await uploadTree(client, tree, {
+    target: { collectionId: 'existing-collection-id' },
+  });
+};
+```
+
+### Browser (File Input)
+
+```typescript
+import { uploadTree, scanFileList } from '@arke-institute/sdk/operations';
+
+// <input type="file" webkitdirectory multiple />
+input.onchange = async (e) => {
+  const tree = await scanFileList(e.target.files);
+  const result = await uploadTree(client, tree, {
+    target: { parentId: 'existing-folder-id', collectionId: 'collection-id' },
+  });
+};
+```
+
+### Upload Options
+
+```typescript
+const result = await uploadTree(client, tree, {
+  target: {
+    // Option 1: Create new collection
+    createCollection: { label: 'New Collection' },
+
+    // Option 2: Upload to existing collection root
+    collectionId: '01ABC...',
+
+    // Option 3: Upload to existing folder
+    collectionId: '01ABC...',
+    parentId: '01XYZ...',
+  },
+
+  // Progress tracking
+  onProgress: (p) => console.log(p.phase, p.completedFiles),
+
+  // Parallel uploads (default: 5)
+  concurrency: 10,
+
+  // Continue if some files fail
+  continueOnError: true,
+});
+```
+
+### CID Utilities
+
+```typescript
+import { computeCid, verifyCid } from '@arke-institute/sdk/operations';
+
+// Compute CIDv1 for any content
+const cid = await computeCid(new TextEncoder().encode('hello'));
+// => "bafkreifzjut3te2nhyekklss27nh3k72ysco7y32koao5eei66wof36n5e"
+
+// Verify content matches CID
+const isValid = await verifyCid(content, expectedCid);
+```
+
 ## Development
 
 ### Regenerate Types
@@ -187,13 +292,12 @@ npm run publish-all:dry
 npm run publish-all
 ```
 
-## Future Operations (TODO)
+## Future Operations
 
-The SDK includes placeholder modules for high-level operations:
+The SDK includes placeholder modules for additional high-level operations:
 
-- **FolderOperations**: Recursive directory upload
 - **BatchOperations**: Bulk entity/relationship creation
-- **CryptoOperations**: Ed25519 key generation, CID computation
+- **CryptoOperations**: Ed25519 key generation
 
 ## License
 

package/dist/{index-BrXke2kI.d.ts → crypto-7c990p-j.d.ts}

@@ -11,7 +11,12 @@ interface ArkeClientConfig {
      */
     baseUrl?: string;
     /**
-     * Authentication token (JWT or API key)
+     * Authentication token - accepts either:
+     * - JWT token from Supabase auth (sent as Bearer)
+     * - Agent API key with 'ak_' prefix (sent as ApiKey)
+     * - User API key with 'uk_' prefix (sent as ApiKey)
+     *
+     * The correct Authorization header format is auto-detected from the token prefix.
      */
     authToken?: string;
     /**
@@ -39,13 +44,28 @@ declare const DEFAULT_CONFIG: Required<Pick<ArkeClientConfig, 'baseUrl' | 'netwo
  */
 
 type ArkeApiClient = Client<paths>;
+/**
+ * Check if a token is an API key (starts with 'ak_' or 'uk_')
+ */
+declare function isApiKey(token: string): boolean;
+/**
+ * Get the appropriate Authorization header value for a token
+ * - API keys (ak_*, uk_*) use: ApiKey {token}
+ * - JWT tokens use: Bearer {token}
+ */
+declare function getAuthorizationHeader(token: string): string;
 /**
  * Type-safe client for the Arke API
  *
  * @example
  * ```typescript
+ * // With JWT token
  * const arke = new ArkeClient({ authToken: 'your-jwt-token' });
  *
+ * // With API key (agent or user)
+ * const arke = new ArkeClient({ authToken: 'ak_your-agent-api-key' });
+ * const arke = new ArkeClient({ authToken: 'uk_your-user-api-key' });
+ *
  * // Create an entity
  * const { data, error } = await arke.api.POST('/entities', {
  *   body: {
@@ -99,16 +119,174 @@ declare class ArkeClient {
 declare function createArkeClient(config?: ArkeClientConfig): ArkeClient;
 
 /**
- * Folder Operations
+ * 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: 'computing-cids' | 'creating' | 'backlinking' | 'uploading' | 'complete' | 'error';
+    /** Current phase index (0=computing-cids, 1=creating, 2=backlinking, 3=uploading) */
+    phaseIndex: number;
+    /** Total number of phases (4, excluding complete/error) */
+    phaseCount: number;
+    /** Progress within current phase (0-100) */
+    phasePercent: number;
+    /** Total number of entities (files + folders) */
+    totalEntities: number;
+    /** Number of entities completed */
+    completedEntities: number;
+    /** Total number of parents to backlink */
+    totalParents: number;
+    /** Number of parents backlinked */
+    completedParents: number;
+    /** Current item being processed */
+    currentItem?: string;
+    /** Error message if phase is 'error' */
+    error?: string;
+    /** Bytes uploaded so far */
+    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)
  *
- * High-level operations for working with folders and directory structures.
+ * @deprecated Use the new upload module instead:
+ * ```typescript
+ * import { uploadTree, scanDirectory } from '@arke-institute/sdk/operations';
  *
- * TODO: Implement folder operations
- * - uploadDirectory: Recursively upload a local directory
- * - createFolderHierarchy: Create folder structure from paths
- * - moveFolderContents: Move files between folders
+ * 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;
@@ -117,6 +295,9 @@ interface UploadProgress {
     completedFolders: number;
     currentFile?: string;
 }
+/**
+ * @deprecated Use UploadOptions from upload module
+ */
 interface UploadDirectoryOptions {
     /** Collection to upload into */
     collectionId: string;
@@ -127,6 +308,9 @@ interface UploadDirectoryOptions {
     /** Max concurrent uploads */
     concurrency?: number;
 }
+/**
+ * @deprecated Use UploadResult from upload module
+ */
 interface UploadDirectoryResult {
     /** Root folder entity */
     rootFolder: unknown;
@@ -138,11 +322,13 @@ interface UploadDirectoryResult {
 /**
  * Folder operations helper
  *
- * @example
+ * @deprecated Use uploadTree and scanDirectory functions instead:
  * ```typescript
- * const folders = new FolderOperations(arkeClient);
- * const result = await folders.uploadDirectory('/path/to/local/folder', {
- *   collectionId: '01ABC...',
+ * 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`),
  * });
  * ```
@@ -153,14 +339,9 @@ declare class FolderOperations {
     /**
      * Upload a local directory to Arke
      *
-     * TODO: Implement this method
-     * Steps:
-     * 1. Scan directory structure
-     * 2. Create folder hierarchy (depth-first)
-     * 3. Upload files in parallel (with concurrency limit)
-     * 4. Create bidirectional relationships (folder contains file)
+     * @deprecated Use uploadTree and scanDirectory instead
      */
-    uploadDirectory(_localPath: string, _options: UploadDirectoryOptions): Promise<UploadDirectoryResult>;
+    uploadDirectory(localPath: string, options: UploadDirectoryOptions): Promise<UploadDirectoryResult>;
 }
 
 /**
@@ -299,4 +480,4 @@ declare class CryptoOperations {
     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 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 };
+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, getAuthorizationHeader as g, type BatchResult as h, isApiKey as i, type UploadTree as j, type UploadOptions as k, type UploadResult as l, type UploadFile as m, type UploadFolder as n, type UploadTarget as o, type CreatedEntity as p };

package/dist/{index-FHcLPBSV.d.cts → crypto-El5Z3bNI.d.cts}

@@ -11,7 +11,12 @@ interface ArkeClientConfig {
      */
     baseUrl?: string;
     /**
-     * Authentication token (JWT or API key)
+     * Authentication token - accepts either:
+     * - JWT token from Supabase auth (sent as Bearer)
+     * - Agent API key with 'ak_' prefix (sent as ApiKey)
+     * - User API key with 'uk_' prefix (sent as ApiKey)
+     *
+     * The correct Authorization header format is auto-detected from the token prefix.
      */
     authToken?: string;
     /**
@@ -39,13 +44,28 @@ declare const DEFAULT_CONFIG: Required<Pick<ArkeClientConfig, 'baseUrl' | 'netwo
  */
 
 type ArkeApiClient = Client<paths>;
+/**
+ * Check if a token is an API key (starts with 'ak_' or 'uk_')
+ */
+declare function isApiKey(token: string): boolean;
+/**
+ * Get the appropriate Authorization header value for a token
+ * - API keys (ak_*, uk_*) use: ApiKey {token}
+ * - JWT tokens use: Bearer {token}
+ */
+declare function getAuthorizationHeader(token: string): string;
 /**
  * Type-safe client for the Arke API
  *
  * @example
  * ```typescript
+ * // With JWT token
  * const arke = new ArkeClient({ authToken: 'your-jwt-token' });
  *
+ * // With API key (agent or user)
+ * const arke = new ArkeClient({ authToken: 'ak_your-agent-api-key' });
+ * const arke = new ArkeClient({ authToken: 'uk_your-user-api-key' });
+ *
  * // Create an entity
  * const { data, error } = await arke.api.POST('/entities', {
  *   body: {
@@ -99,16 +119,174 @@ declare class ArkeClient {
 declare function createArkeClient(config?: ArkeClientConfig): ArkeClient;
 
 /**
- * Folder Operations
+ * 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: 'computing-cids' | 'creating' | 'backlinking' | 'uploading' | 'complete' | 'error';
+    /** Current phase index (0=computing-cids, 1=creating, 2=backlinking, 3=uploading) */
+    phaseIndex: number;
+    /** Total number of phases (4, excluding complete/error) */
+    phaseCount: number;
+    /** Progress within current phase (0-100) */
+    phasePercent: number;
+    /** Total number of entities (files + folders) */
+    totalEntities: number;
+    /** Number of entities completed */
+    completedEntities: number;
+    /** Total number of parents to backlink */
+    totalParents: number;
+    /** Number of parents backlinked */
+    completedParents: number;
+    /** Current item being processed */
+    currentItem?: string;
+    /** Error message if phase is 'error' */
+    error?: string;
+    /** Bytes uploaded so far */
+    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)
  *
- * High-level operations for working with folders and directory structures.
+ * @deprecated Use the new upload module instead:
+ * ```typescript
+ * import { uploadTree, scanDirectory } from '@arke-institute/sdk/operations';
  *
- * TODO: Implement folder operations
- * - uploadDirectory: Recursively upload a local directory
- * - createFolderHierarchy: Create folder structure from paths
- * - moveFolderContents: Move files between folders
+ * 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;
@@ -117,6 +295,9 @@ interface UploadProgress {
     completedFolders: number;
     currentFile?: string;
 }
+/**
+ * @deprecated Use UploadOptions from upload module
+ */
 interface UploadDirectoryOptions {
     /** Collection to upload into */
     collectionId: string;
@@ -127,6 +308,9 @@ interface UploadDirectoryOptions {
     /** Max concurrent uploads */
     concurrency?: number;
 }
+/**
+ * @deprecated Use UploadResult from upload module
+ */
 interface UploadDirectoryResult {
     /** Root folder entity */
     rootFolder: unknown;
@@ -138,11 +322,13 @@ interface UploadDirectoryResult {
 /**
  * Folder operations helper
  *
- * @example
+ * @deprecated Use uploadTree and scanDirectory functions instead:
  * ```typescript
- * const folders = new FolderOperations(arkeClient);
- * const result = await folders.uploadDirectory('/path/to/local/folder', {
- *   collectionId: '01ABC...',
+ * 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`),
  * });
  * ```
@@ -153,14 +339,9 @@ declare class FolderOperations {
     /**
      * Upload a local directory to Arke
      *
-     * TODO: Implement this method
-     * Steps:
-     * 1. Scan directory structure
-     * 2. Create folder hierarchy (depth-first)
-     * 3. Upload files in parallel (with concurrency limit)
-     * 4. Create bidirectional relationships (folder contains file)
+     * @deprecated Use uploadTree and scanDirectory instead
      */
-    uploadDirectory(_localPath: string, _options: UploadDirectoryOptions): Promise<UploadDirectoryResult>;
+    uploadDirectory(localPath: string, options: UploadDirectoryOptions): Promise<UploadDirectoryResult>;
 }
 
 /**
@@ -299,4 +480,4 @@ declare class CryptoOperations {
     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 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 };
+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, getAuthorizationHeader as g, type BatchResult as h, isApiKey as i, type UploadTree as j, type UploadOptions as k, type UploadResult as l, type UploadFile as m, type UploadFolder as n, type UploadTarget as o, type CreatedEntity as p };