Port the SDK to the AIngle Cortex REST API (v0.2.0)

.github/workflows/ci.yml

@@ -0,0 +1,18 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+      - run: npm install
+      - run: npx tsc --noEmit
+      - run: npm run build

README.md

@@ -1,157 +1,159 @@
-# AIngle SDK for JavaScript/TypeScript
+# AIngle Cortex SDK for JavaScript/TypeScript
 
-Official JavaScript/TypeScript SDK for [AIngle](https://apilium.com) - the ultra-light distributed ledger for IoT devices.
+The official JavaScript and TypeScript SDK for [AIngle](https://github.com/ApiliumCode/aingle-sdk-js), the verifiable memory cortex for AI agents. AIngle is a semantic graph plus vector memory served over a REST API, so your agents can remember, recall, and reason over durable, queryable knowledge.
+
+The SDK is a thin, typed HTTP client. It uses the native `fetch` available in Node.js 18 and later, and it ships with zero runtime dependencies.
 
 ## Installation
 
 ```bash
-npm install @anthropic/aingle-sdk
+npm install @apilium/aingle-sdk
 # or
-yarn add @anthropic/aingle-sdk
+yarn add @apilium/aingle-sdk
 # or
-pnpm add @anthropic/aingle-sdk
+pnpm add @apilium/aingle-sdk
 ```
 
 ## Quick Start
 
-### Connect to an AIngle Node
+Construct a client, remember a note, then recall it.
 
 ```typescript
-import { AIngleClient } from '@anthropic/aingle-sdk';
+import { AIngleClient } from '@apilium/aingle-sdk';
 
 const client = new AIngleClient({
-  nodeUrl: 'http://localhost:8080',
+  baseUrl: 'http://127.0.0.1:19090',
 });
 
-// Create an entry
-const hash = await client.createEntry({
-  type: 'sensor_reading',
-  value: 23.5,
-  unit: 'celsius',
+// Remember a note.
+const { id } = await client.remember('note', {
+  text: 'The launch is scheduled for Friday.',
+}, {
+  tags: ['launch', 'planning'],
+  importance: 0.8,
 });
 
-console.log(`Created entry: ${hash}`);
-
-// Retrieve an entry
-const entry = await client.getEntry(hash);
-console.log(entry);
-```
+console.log(`Remembered entry: ${id}`);
 
-### Run an Embedded Node (Browser/Node.js)
-
-```typescript
-import { AIngleNode } from '@anthropic/aingle-sdk';
-
-const node = new AIngleNode({
-  enableWebRtc: true,
-  bootstrapPeers: ['wss://bootstrap.aingle.network'],
+// Recall it by text.
+const results = await client.recall({
+  text: 'When is the launch?',
+  limit: 5,
 });
 
-await node.start();
-
-// Create entries directly on the embedded node
-const hash = await node.createEntry({
-  sensor: 'temperature',
-  value: 23.5,
-});
+for (const result of results) {
+  console.log(result.relevance, result.data);
+}
+```
 
-// Get node statistics
-const stats = await node.getStats();
-console.log(`Entries: ${stats.entriesCount}, Peers: ${stats.peersCount}`);
+## Configuration
 
-// Stop the node
-await node.stop();
-```
+Pass a config object to the constructor. Every field is optional.
 
-### Subscribe to Real-time Updates
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `baseUrl` | `string` | `http://127.0.0.1:19090` | Base URL of the AIngle Cortex server. |
+| `token` | `string` | none | Bearer token sent as `Authorization: Bearer <token>`. |
+| `timeoutMs` | `number` | none | Per-request timeout in milliseconds, enforced with `AbortController`. |
 
 ```typescript
-const unsubscribe = client.subscribe((entry) => {
-  console.log('New entry:', entry);
+const client = new AIngleClient({
+  baseUrl: 'https://cortex.example.com',
+  token: process.env.AINGLE_TOKEN,
+  timeoutMs: 10_000,
 });
-
-// Later, unsubscribe
-unsubscribe();
 ```
 
 ## API Reference
 
-### AIngleClient
+### Health and stats
 
 | Method | Description |
-|--------|-------------|
-| `connect()` | Connect to the AIngle node |
-| `disconnect()` | Disconnect from the node |
-| `createEntry(data)` | Create a new entry |
-| `getEntry(hash)` | Retrieve an entry by hash |
-| `getNodeInfo()` | Get node information |
-| `subscribe(callback)` | Subscribe to real-time updates |
+| --- | --- |
+| `health()` | Server health and component status. |
+| `stats()` | Graph and server statistics. |
 
-### AIngleNode
+### Memory
 
 | Method | Description |
-|--------|-------------|
-| `start()` | Start the embedded node |
-| `stop()` | Stop the embedded node |
-| `isRunning()` | Check if node is running |
-| `createEntry(data)` | Create a new entry |
-| `getEntry(hash)` | Get an entry by hash |
-| `getPeers()` | Get connected peers |
-| `getStats()` | Get node statistics |
+| --- | --- |
+| `remember(entryType, data, options?)` | Store a memory entry, returns `{ id }`. |
+| `recall(options?)` | Recall entries by text, tags, type, or importance. |
+| `search(options)` | Vector search over an embedding, returns ranked results. |
+| `memoryStats()` | Short-term and long-term memory counters. |
+| `forget(id)` | Delete a memory entry by id. |
 
-## Configuration
+### Triples (semantic graph)
 
-### AIngleClientConfig
+| Method | Description |
+| --- | --- |
+| `createTriple(subject, predicate, object)` | Insert a single triple. |
+| `createTriples(triples)` | Batch insert triples. |
+| `listTriples(options?)` | List triples filtered by subject, predicate, or object. |
+| `getTriple(id)` | Fetch one triple by id. |
+| `deleteTriple(id)` | Delete a triple by id. |
 
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `nodeUrl` | `string` | `http://localhost:8080` | Node URL |
-| `wsUrl` | `string` | `ws://localhost:8081` | WebSocket URL |
-| `timeout` | `number` | `30000` | Request timeout (ms) |
-| `debug` | `boolean` | `false` | Enable debug logging |
+### Query
 
-### NodeConfig
+| Method | Description |
+| --- | --- |
+| `query(options?)` | Match triples against a subject, predicate, object pattern. |
+| `subjects(options?)` | List distinct subjects, optionally filtered by predicate. |
+| `predicates(options?)` | List distinct predicates, optionally filtered by subject. |
 
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `storagePath` | `string` | `aingle-data` | Storage location |
-| `enableCoap` | `boolean` | `false` | Enable CoAP transport |
-| `enableWebRtc` | `boolean` | `true` | Enable WebRTC transport |
-| `bootstrapPeers` | `string[]` | `[]` | Bootstrap peer URLs |
-| `memoryLimit` | `number` | `524288` | Memory limit (bytes) |
-
-## Platform Support
-
-| Platform | Client | Embedded Node |
-|----------|--------|---------------|
-| Node.js 18+ | ✅ | ✅ |
-| Browser (Chrome, Firefox, Safari) | ✅ | ✅ (WebAssembly) |
-| React Native | ✅ | 🚧 Coming soon |
-| Deno | ✅ | ✅ |
-| Bun | ✅ | ✅ |
+### The triple object value
+
+A triple's `object` is an untagged union. Serialize it as the raw JSON value.
+
+```typescript
+await client.createTriple('agent:1', 'name', 'Ada');        // string
+await client.createTriple('agent:1', 'trust_score', 0.92);  // number
+await client.createTriple('agent:1', 'is_verified', true);  // boolean
+await client.createTriple('agent:1', 'knows', {             // node reference (IRI)
+  node: 'http://example.org/agent/2',
+});
+```
+
+### Error handling
+
+Any non-2xx response, timeout, or transport failure throws a typed `AIngleError` with a `status` (the HTTP status, or `0` for timeouts and network errors) and a `message`.
+
+```typescript
+import { AIngleClient, AIngleError } from '@apilium/aingle-sdk';
+
+try {
+  await client.getTriple('does-not-exist');
+} catch (err) {
+  if (err instanceof AIngleError) {
+    console.error(err.status, err.message);
+  }
+}
+```
 
 ## Development
 
 ```bash
 # Install dependencies
 npm install
 
-# Run tests
-npm test
+# Type-check
+npm run typecheck
 
 # Build
 npm run build
 
+# Run tests
+npm test
+
 # Lint
 npm run lint
 ```
 
 ## License
 
-Apache-2.0 - see [LICENSE](LICENSE)
+Apache-2.0, see [LICENSE](LICENSE).
 
 ## Links
 
 - [AIngle Core](https://github.com/ApiliumCode/aingle)
 - [Documentation](https://docs.apilium.com)
-- [Discord](https://discord.gg/apilium)