@arke-institute/sdk 0.1.3 → 2.1.0

package/README.md

@@ -1,258 +1,304 @@
-# Arke SDK
+# @arke-institute/sdk
 
-TypeScript SDK for building applications on the Arke platform.
+TypeScript SDK for the Arke API - auto-generated from OpenAPI spec.
 
 ## Installation
 
 ```bash
-npm install @arke/sdk
+npm install @arke-institute/sdk
 ```
 
 ## Quick Start
 
 ```typescript
-import { createClient } from '@arke/sdk';
+import { ArkeClient } from '@arke-institute/sdk';
 
-const arke = createClient({
+const arke = new ArkeClient({
   authToken: 'your-jwt-token',
 });
 
-// Create a collection
-const collection = await arke.collections.create({
-  title: 'My Archive',
-  slug: 'my-archive',
-});
-
-// Upload files to create a new collection
-const result = await arke.upload.createCollection({
-  files: './photos',
-  collectionMetadata: {
-    title: 'Photo Archive',
-    slug: 'photos',
+// Create an entity
+const { data, error } = await arke.api.POST('/entities', {
+  body: {
+    collection_id: '01ABC...',
+    type: 'document',
+    properties: { title: 'My Document' },
   },
 });
 
-// Query the knowledge graph
-const results = await arke.query.natural(
-  'Who are the people in photographs from Hawaii?'
-);
+if (error) {
+  console.error('Failed:', error);
+} else {
+  console.log('Created:', data.id);
+}
 ```
 
-## Packages
+## Configuration
 
-The SDK contains five packages:
+```typescript
+const arke = new ArkeClient({
+  // Base URL (default: 'https://arke-v1.arke.institute')
+  baseUrl: 'https://arke-v1.arke.institute',
 
-| Package | Purpose | Auth Required |
-|---------|---------|---------------|
-| **collections** | Create/manage collections, members, invitations | Yes |
-| **upload** | Upload files, create/add to collections | Yes |
-| **edit** | Edit entities, trigger AI regeneration | Yes |
-| **query** | Search and traverse the knowledge graph | No (public) |
-| **content** | Read entities, download content | No (public) |
+  // JWT or API key
+  authToken: 'your-token',
 
-### Package Dependency Graph
+  // Network: 'main' or 'test' (default: 'main')
+  network: 'test',
 
-```
-collections (foundational)
-       ▲
-       │
-  ┌────┴────┐
-  │         │
-upload    edit
-
-query (independent)
-content (independent)
+  // Custom headers
+  headers: {
+    'X-Custom-Header': 'value',
+  },
+});
 ```
 
-## Package Details
+## API Access
 
-### collections
+All API calls are made through the `arke.api` property, which provides full type safety:
 
 ```typescript
-// Create collection
-await arke.collections.create({ title, slug, description, visibility });
+// GET request
+const { data } = await arke.api.GET('/entities/{id}', {
+  params: { path: { id: '01XYZ...' } },
+});
 
-// List collections
-const collections = await arke.collections.list({ page: 1 });
+// POST request
+const { data } = await arke.api.POST('/entities', {
+  body: { collection_id: '...', type: 'document', properties: {} },
+});
 
-// Manage members
-await arke.members.updateRole(collectionId, userId, 'editor');
+// PUT request (update)
+const { data } = await arke.api.PUT('/entities/{id}', {
+  params: { path: { id: '01XYZ...' } },
+  body: { expect_tip: 'bafyrei...', properties_merge: { status: 'active' } },
+});
 
-// Invitations
-await arke.invitations.create(collectionId, { email, role: 'editor' });
-await arke.invitations.accept(invitationId);
+// DELETE request
+await arke.api.DELETE('/relationships', {
+  body: { source_id: '...', target_id: '...', predicate: 'contains' },
+});
 ```
 
-### upload
+## Available Endpoints
+
+The SDK provides typed access to all Arke API endpoints:
+
+| Endpoint Group | Description |
+|----------------|-------------|
+| `/auth/*` | Authentication and registration |
+| `/users/*` | User profile and API keys |
+| `/collections/*` | Collection CRUD, roles, members |
+| `/entities/*` | Entity CRUD |
+| `/relationships` | Relationship management |
+| `/files/*` | File storage and downloads |
+| `/folders/*` | Folder hierarchy |
+| `/versions/*` | Version history |
+| `/agents/*` | Agent management |
+| `/permissions/*` | Permission introspection |
+
+## Error Handling
 
 ```typescript
-// Create new collection from files (anyone authenticated)
-await arke.upload.createCollection({
-  files: './photos',
-  collectionMetadata: { title: 'My Archive', slug: 'my-archive' },
+import {
+  ArkeError,
+  CASConflictError,
+  NotFoundError,
+  parseApiError
+} from '@arke-institute/sdk';
+
+const { data, error, response } = await arke.api.GET('/entities/{id}', {
+  params: { path: { id: 'invalid-id' } },
 });
 
-// Add to existing collection (requires membership)
-await arke.upload.addToCollection({
-  files: './more-photos',
-  parentPi: 'pi:existing-root',
-});
+if (error) {
+  // Parse into typed error
+  const arkeError = parseApiError(response.status, error);
+
+  if (arkeError instanceof CASConflictError) {
+    console.log('Concurrent modification - expected:', arkeError.expectedTip);
+  } else if (arkeError instanceof NotFoundError) {
+    console.log('Entity not found');
+  }
+}
 ```
 
-### edit
+## Authentication Management
 
 ```typescript
-// Edit entity
-const session = await arke.edit.createSession('pi:abc123');
-session.setPrompt('Update the description');
-const result = await session.submit();
+const arke = new ArkeClient();
+
+// Set token after login
+arke.setAuthToken('new-token');
+
+// Check auth status
+if (arke.isAuthenticated) {
+  // Make authenticated requests
+}
 
-// Trigger AI regeneration
-await arke.edit.regenerate('pi:abc123');
+// Clear token on logout
+arke.clearAuthToken();
 ```
 
-### query
+## Test Network
+
+Use the test network for development (uses 'II' prefixed IDs):
 
 ```typescript
-// Direct path query (requires knowing syntax)
-await arke.query.path('"Hawaii" -[depicts]-> type:person');
+const arke = new ArkeClient({
+  authToken: 'your-token',
+  network: 'test',
+});
+```
+
+## 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' });
 
-// Natural language (LLM translates to path query)
-await arke.query.natural('Who photographed Pearl Harbor?');
+// Scan a local directory
+const tree = await scanDirectory('/path/to/my-folder');
 
-// Collection search
-await arke.query.searchCollection(collectionId, 'family portraits');
+// 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);
 ```
 
-### content
+### Browser (Drag & Drop)
 
 ```typescript
-// Get entity
-const entity = await arke.content.get('pi:abc123');
+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' },
+  });
+};
+```
 
-// Download content
-const blob = await arke.content.download('pi:abc123');
+### Browser (File Input)
 
-// Get version history
-const versions = await arke.content.versions('pi:abc123');
+```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' },
+  });
+};
 ```
 
-## Documentation
+### Upload Options
 
-- [Architecture Overview](./ARCHITECTURE.md)
-- [collections package](./packages/collections/PLAN.md)
-- [upload package](./packages/upload/PLAN.md)
-- [edit package](./packages/edit/PLAN.md)
-- [query package](./packages/query/PLAN.md)
-- [content package](./packages/content/PLAN.md)
+```typescript
+const result = await uploadTree(client, tree, {
+  target: {
+    // Option 1: Create new collection
+    createCollection: { label: 'New Collection' },
 
-## Project Structure
+    // 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,
+});
 ```
-arke-sdk/
-├── src/
-│   ├── index.ts              # Main entry, createClient()
-│   ├── client.ts             # Base HTTP client
-│   └── types.ts              # Shared types
-├── packages/
-│   ├── collections/
-│   │   ├── index.ts          # Package entry
-│   │   ├── collections.ts    # Collection CRUD
-│   │   ├── members.ts        # Membership operations
-│   │   ├── invitations.ts    # Invitation operations
-│   │   └── types.ts
-│   ├── upload/
-│   │   ├── index.ts
-│   │   ├── uploader.ts       # Main uploader class
-│   │   ├── create-collection.ts
-│   │   ├── add-to-collection.ts
-│   │   └── types.ts
-│   ├── edit/
-│   │   ├── index.ts
-│   │   ├── session.ts        # Edit session
-│   │   ├── diff.ts           # Diff engine
-│   │   └── types.ts
-│   ├── query/
-│   │   ├── index.ts
-│   │   ├── path-query.ts     # Direct path queries
-│   │   ├── natural-query.ts  # NL queries
-│   │   ├── collection-search.ts
-│   │   └── types.ts
-│   └── content/
-│       ├── index.ts
-│       ├── entities.ts       # Entity operations
-│       ├── download.ts       # Content download
-│       └── types.ts
-├── package.json
-├── tsconfig.json
-└── README.md
+
+### 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);
 ```
 
-## Distribution
+## Development
 
-The SDK is published to npm as `@arke/sdk`.
+### Regenerate Types
 
-### Building
+When the API changes, regenerate the types:
 
 ```bash
-npm run build
+# From production API
+npm run generate
+
+# From local dev server
+npm run generate:local
 ```
 
-### Publishing
+### Build
 
 ```bash
-npm version patch|minor|major
-npm publish
+npm run build
 ```
 
-### Imports
+### Test
 
-Users can import the full SDK or specific packages:
-
-```typescript
-// Full SDK
-import { createClient } from '@arke/sdk';
-const arke = createClient({ authToken });
-arke.collections.create(...);
-
-// Specific packages (tree-shakeable)
-import { CollectionsClient } from '@arke/sdk/collections';
-import { UploadClient } from '@arke/sdk/upload';
+```bash
+npm test
 ```
 
-## Implementation Order
+### Publish
 
-### Backend (Workers)
-1. GraphDB Gateway - Add `is_collection_root` field + update endpoint
-2. Query Links - Add filter support for `is_collection_root`
-3. **Collections Worker** (new) - Manages collections in Supabase
-
-### SDK (This Repo)
-4. collections package
-5. content package
-6. upload package (refactor existing)
-7. edit package (refactor existing)
-8. query package
+```bash
+# Dry run
+npm run publish-all:dry
 
-### Consumers
-9. CLI (`arke-cli/`)
-10. Web Frontend
+# Actual publish
+npm run publish-all
+```
 
-## Backend Architecture
+## Future Operations
 
-The SDK calls the Arke Gateway (`api.arke.institute`), which routes to workers:
+The SDK includes placeholder modules for additional high-level operations:
 
-| Route | Worker |
-|-------|--------|
-| `/collections/*`, `/me/*`, `/invitations/*` | Collections Worker |
-| `/ingest/*` | Ingest Worker |
-| `/api/*` | IPFS Wrapper |
-| `/reprocess/*` | Reprocess API |
-| `/query/*` | Query Links |
-| `/translate/*` | Query Translator |
+- **BatchOperations**: Bulk entity/relationship creation
+- **CryptoOperations**: Ed25519 key generation
 
-## Related Repositories
+## License
 
-- **Collections Worker** - Backend for collection management (new)
-- **Arke CLI** (`arke-cli/`) - Command-line interface using this SDK
-- **Arke Gateway** (`arke-gateway/`) - API gateway routing
+MIT