@arke-institute/sdk 0.1.2 → 2.0.0

package/README.md

@@ -1,258 +1,200 @@
-# 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 });
-
-// List collections
-const collections = await arke.collections.list({ page: 1 });
-
-// Manage members
-await arke.members.updateRole(collectionId, userId, 'editor');
-
-// Invitations
-await arke.invitations.create(collectionId, { email, role: 'editor' });
-await arke.invitations.accept(invitationId);
-```
+// GET request
+const { data } = await arke.api.GET('/entities/{id}', {
+  params: { path: { id: '01XYZ...' } },
+});
 
-### upload
+// POST request
+const { data } = await arke.api.POST('/entities', {
+  body: { collection_id: '...', type: 'document', properties: {} },
+});
 
-```typescript
-// Create new collection from files (anyone authenticated)
-await arke.upload.createCollection({
-  files: './photos',
-  collectionMetadata: { title: 'My Archive', slug: 'my-archive' },
+// PUT request (update)
+const { data } = await arke.api.PUT('/entities/{id}', {
+  params: { path: { id: '01XYZ...' } },
+  body: { expect_tip: 'bafyrei...', properties_merge: { status: 'active' } },
 });
 
-// Add to existing collection (requires membership)
-await arke.upload.addToCollection({
-  files: './more-photos',
-  parentPi: 'pi:existing-root',
+// DELETE request
+await arke.api.DELETE('/relationships', {
+  body: { source_id: '...', target_id: '...', predicate: 'contains' },
 });
 ```
 
-### edit
+## Available Endpoints
 
-```typescript
-// Edit entity
-const session = await arke.edit.createSession('pi:abc123');
-session.setPrompt('Update the description');
-const result = await session.submit();
+The SDK provides typed access to all Arke API endpoints:
 
-// Trigger AI regeneration
-await arke.edit.regenerate('pi:abc123');
-```
+| 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 |
 
-### query
+## Error Handling
 
 ```typescript
-// Direct path query (requires knowing syntax)
-await arke.query.path('"Hawaii" -[depicts]-> type:person');
+import {
+  ArkeError,
+  CASConflictError,
+  NotFoundError,
+  parseApiError
+} from '@arke-institute/sdk';
+
+const { data, error, response } = await arke.api.GET('/entities/{id}', {
+  params: { path: { id: 'invalid-id' } },
+});
 
-// Natural language (LLM translates to path query)
-await arke.query.natural('Who photographed Pearl Harbor?');
+if (error) {
+  // Parse into typed error
+  const arkeError = parseApiError(response.status, error);
 
-// Collection search
-await arke.query.searchCollection(collectionId, 'family portraits');
+  if (arkeError instanceof CASConflictError) {
+    console.log('Concurrent modification - expected:', arkeError.expectedTip);
+  } else if (arkeError instanceof NotFoundError) {
+    console.log('Entity not found');
+  }
+}
 ```
 
-### content
+## Authentication Management
 
 ```typescript
-// Get entity
-const entity = await arke.content.get('pi:abc123');
+const arke = new ArkeClient();
 
-// Download content
-const blob = await arke.content.download('pi:abc123');
+// Set token after login
+arke.setAuthToken('new-token');
 
-// Get version history
-const versions = await arke.content.versions('pi:abc123');
-```
+// Check auth status
+if (arke.isAuthenticated) {
+  // Make authenticated requests
+}
 
-## Documentation
+// Clear token on logout
+arke.clearAuthToken();
+```
 
-- [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)
+## Test Network
 
-## Project Structure
+Use the test network for development (uses 'II' prefixed IDs):
 
-```
-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
+```typescript
+const arke = new ArkeClient({
+  authToken: 'your-token',
+  network: 'test',
+});
 ```
 
-## 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
-
-Users can import the full SDK or specific packages:
+### Test
 
-```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 (TODO)
 
-The SDK calls the Arke Gateway (`api.arke.institute`), which routes to workers:
+The SDK includes placeholder modules for 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 |
+- **FolderOperations**: Recursive directory upload
+- **BatchOperations**: Bulk entity/relationship creation
+- **CryptoOperations**: Ed25519 key generation, CID computation
 
-## 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

package/dist/generated/index.cjs

@@ -0,0 +1,19 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/generated/index.ts
+var generated_exports = {};
+module.exports = __toCommonJS(generated_exports);
+//# sourceMappingURL=index.cjs.map

package/dist/generated/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/generated/index.ts"],"sourcesContent":["/**\n * Auto-generated types from OpenAPI spec\n *\n * Run `npm run generate` to regenerate these types from the API spec.\n */\n\nexport type { paths, components, operations } from './types.js';\n"],"mappings":";;;;;;;;;;;;;;;;AAAA;AAAA;","names":[]}