@z3rno/sdk 0.8.1 → 0.23.0

package/Cargo.toml

@@ -0,0 +1,23 @@
+[workspace]
+
+[package]
+name = "z3rno-sdk-native"
+version = "0.23.0"
+edition = "2021"
+license = "Apache-2.0"
+publish = false
+
+[lib]
+crate-type = ["cdylib", "rlib"]
+
+[dependencies]
+napi = { version = "2", default-features = false, features = ["napi4", "tokio_rt", "serde-json"] }
+napi-derive = "2"
+z3rno-engine = { path = "../../engine" }
+uuid = { version = "1", features = ["v4"] }
+serde_json = "1"
+anyhow = "1"
+chrono = "0.4"
+
+[build-dependencies]
+napi-build = "2"

package/README.md

@@ -1,77 +1,73 @@
-# @z3rno/sdk (TypeScript)
+# bindings/typescript
 
-[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
-[![CI](https://github.com/the-ai-project-co/z3rno-sdk-typescript/actions/workflows/ci.yml/badge.svg)](https://github.com/the-ai-project-co/z3rno-sdk-typescript/actions/workflows/ci.yml)
-[![npm](https://img.shields.io/npm/v/@z3rno/sdk)](https://www.npmjs.com/package/@z3rno/sdk)
+TypeScript/Node bindings for z3rno, built with [napi-rs](https://napi.rs) —
+native compiled bindings over `z3rno-engine`, not a thin HTTP client. The SDK
+*is* the engine.
 
-TypeScript SDK for Z3rno -- native fetch client with Zod validation.
+The API is **async-only**: every I/O method (`store`, `recall`, `forget`,
+`advanced.audit`) returns a native `Promise`, run on napi-rs's managed Tokio
+runtime. `tier()` is the one exception — no I/O, so it's a plain sync getter.
 
-## Installation
+## Local development
 
-```bash
-npm install @z3rno/sdk
-```
-
-## Quickstart
-
-```typescript
-import { Z3rnoClient } from "@z3rno/sdk";
+Not yet published to npm (that's a later slice). To build and test locally
+from this directory:
 
-const client = new Z3rnoClient({ baseUrl: "https://api.z3rno.dev", apiKey: "z3rno_sk_..." });
-const memory = await client.store({ agentId: "agent-1", content: "User prefers dark mode", memoryType: "semantic" });
-const results = await client.recall({ agentId: "agent-1", query: "What does the user prefer?", topK: 5 });
-await client.forget({ agentId: "agent-1", memoryId: memory.id });
+```bash
+npm install
+npm run build   # napi build --platform --release — compiles the native addon
+npm test        # node test.js — store -> recall -> forget -> audit against the embedded backend
 ```
 
-## CJS + ESM Support
+`npm run build` regenerates `index.d.ts` and `index.js` from the Rust
+`#[napi(...)]` annotations in `src/lib.rs` — don't hand-edit those two files.
 
-The SDK ships as a dual build via tsup. Both CommonJS and ES module entry points are provided:
+## Usage
 
-```jsonc
-// package.json exports
-{
-  "import": "./dist/index.js",   // ESM
-  "require": "./dist/index.cjs"  // CJS
-}
-```
+```ts
+import { Client } from "@z3rno/sdk";
 
-Works in Node.js 18+, Bun, Deno, and browsers.
+// Embedded backend (default): opens/creates "z3rno.db" in the cwd.
+const client = await Client.connect();
 
-## Methods
+const memory = await client.store({
+  tenantId: "t1",
+  tier: "episodic", // "working" | "episodic" | "semantic" | "procedural"
+  content: "hello",
+  embedding: [0.1, 0.2, 0.3], // optional — omit if this memory shouldn't be recallable by similarity search
+  metadata: { source: "chat" },
+  links: [], // optional graph edges: { targetId, relationship }[]
+});
 
-| Method | Description |
-|--------|-------------|
-| `store(request)` | Store a new memory with optional type, metadata, relationships, TTL, and importance |
-| `recall(params)` | Recall memories by semantic similarity query |
-| `forget(params)` | Soft-delete a memory by ID |
-| `audit(params?)` | Query the audit trail with optional filters and pagination |
+const memories = await client.recall({ tenantId: "t1", query: [0.1, 0.2, 0.3], k: 5 });
 
-## Features
+const proof = await client.forget({ tenantId: "t1", id: memory.id });
+// proof is `{ auditEventId, hash }`, or `null` if there was nothing to forget
 
-- **Zero runtime dependencies** -- only `zod` for request/response validation. No `axios`, no database drivers.
-- **Native fetch** -- works in every modern JavaScript runtime without polyfills.
-- **Runtime-validated responses** -- every API response is parsed through a Zod schema, giving both compile-time and runtime type safety.
-- **Typed errors** -- `Z3rnoAuthenticationError`, `Z3rnoRateLimitError` (with `retryAfter`), `Z3rnoValidationError`.
-- **Tree-shakeable** -- ESM build with clean exports for optimal bundling.
-
-For a detailed step-by-step setup, see [QUICKSTART.md](QUICKSTART.md).
-
-## API Documentation
+client.tier(); // "embedded" or "postgres" — sync, no I/O
+```
 
-Full API reference: [astron-bb4261fd.mintlify.app/sdk/typescript](https://astron-bb4261fd.mintlify.app/sdk/typescript)
+## Advanced
 
-## Development
+`client.advanced` exposes operations kept out of the top-level verb surface.
+Today that's just the append-only, hash-chained audit log:
 
-```bash
-npm install
-npm run typecheck
-npm run format:check
-npm test
-npm run build
+```ts
+const events = await client.advanced.audit("t1");
+// each event: { id, tenantId, operation, memoryId, at, prevHash, hash }
+// operation is "store" | "forget"; prevHash is undefined on the first event
 ```
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for the full workflow.
+## Production backend
 
-## License
+The embedded backend (SQLite + an in-process vector index + an in-process
+graph) is the zero-infra default, with no external services required. For a
+production, multi-tenant deployment, connect to the Postgres + pgvector +
+Apache AGE backend instead:
 
-Apache 2.0 -- see [LICENSE](LICENSE).
+```ts
+const client = await Client.connect({
+  backend: "postgres",
+  connectionString: "postgres://user:pass@host:5432/z3rno",
+});
+```

package/build.rs

@@ -0,0 +1,5 @@
+extern crate napi_build;
+
+fn main() {
+    napi_build::setup();
+}

package/index.d.ts

@@ -0,0 +1,97 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/* auto-generated by NAPI-RS */
+
+/**
+ * `client.store(...)` input. `embedding` and `links` are optional (a
+ * memory with no embedding simply isn't recallable by similarity search;
+ * no links means no graph edges).
+ */
+export interface StoreOptions {
+  tenantId: string
+  /** One of "working" | "episodic" | "semantic" | "procedural". */
+  tier: string
+  content: string
+  embedding?: Array<number>
+  metadata: JsonValue
+  links?: Array<LinkInput>
+}
+/** One graph edge from the memory being stored to an existing memory. */
+export interface LinkInput {
+  targetId: string
+  relationship: string
+}
+/** `client.recall(...)` input. */
+export interface RecallOptions {
+  tenantId: string
+  query: Array<number>
+  k: number
+}
+/** `client.forget(...)` input. */
+export interface ForgetOptions {
+  tenantId: string
+  id: string
+}
+/**
+ * `Client.connect(...)` input. `backend` defaults to `"embedded"`; `path`
+ * defaults to `"z3rno.db"` in the current working directory when the
+ * embedded backend is used and `path` is omitted.
+ */
+export interface ConnectOptions {
+  /** One of "embedded" | "postgres". Defaults to "embedded". */
+  backend?: string
+  path?: string
+  connectionString?: string
+}
+export interface MemoryDto {
+  id: string
+  tenantId: string
+  tier: string
+  content: string
+  metadata: JsonValue
+  /** RFC 3339 timestamp. */
+  createdAt: string
+}
+export interface ForgetProofDto {
+  auditEventId: string
+  hash: string
+}
+export interface AuditEventDto {
+  id: string
+  tenantId: string
+  /** "store" | "forget". */
+  operation: string
+  memoryId: string
+  /** RFC 3339 timestamp. */
+  at: string
+  prevHash?: string
+  hash: string
+}
+/**
+ * A connected z3rno client. Construct with `Client.connect(...)`, never
+ * `new Client()` — connecting the embedded backend is sync but connecting
+ * Postgres needs an `await`, so both go through one consistent async
+ * factory rather than a sync constructor plus a separate async path.
+ */
+export declare class Client {
+  static connect(options?: ConnectOptions | undefined | null): Promise<Client>
+  /**
+   * Which tenant-isolation guarantee this client's backend provides:
+   * "embedded" or "postgres". No I/O, so this is sync (not a Promise).
+   */
+  tier(): string
+  store(options: StoreOptions): Promise<MemoryDto>
+  recall(options: RecallOptions): Promise<Array<MemoryDto>>
+  forget(options: ForgetOptions): Promise<ForgetProofDto | null>
+  /**
+   * Advanced operations namespace — currently just `.audit(tenantId)`,
+   * the one advanced operation the engine has. Mirrors the engine's own
+   * `MemoryEngine::advanced()` two-tier verb surface.
+   */
+  get advanced(): Advanced
+}
+export declare class Advanced {
+  /** The tenant's full audit chain, oldest first. */
+  audit(tenantId: string): Promise<Array<AuditEventDto>>
+}

package/index.js

@@ -0,0 +1,316 @@
+/* tslint:disable */
+/* eslint-disable */
+/* prettier-ignore */
+
+/* auto-generated by NAPI-RS */
+
+const { existsSync, readFileSync } = require('fs')
+const { join } = require('path')
+
+const { platform, arch } = process
+
+let nativeBinding = null
+let localFileExisted = false
+let loadError = null
+
+function isMusl() {
+  // For Node 10
+  if (!process.report || typeof process.report.getReport !== 'function') {
+    try {
+      const lddPath = require('child_process').execSync('which ldd').toString().trim()
+      return readFileSync(lddPath, 'utf8').includes('musl')
+    } catch (e) {
+      return true
+    }
+  } else {
+    const { glibcVersionRuntime } = process.report.getReport().header
+    return !glibcVersionRuntime
+  }
+}
+
+switch (platform) {
+  case 'android':
+    switch (arch) {
+      case 'arm64':
+        localFileExisted = existsSync(join(__dirname, 'z3rno-sdk-native.android-arm64.node'))
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./z3rno-sdk-native.android-arm64.node')
+          } else {
+            nativeBinding = require('@z3rno/sdk-android-arm64')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'arm':
+        localFileExisted = existsSync(join(__dirname, 'z3rno-sdk-native.android-arm-eabi.node'))
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./z3rno-sdk-native.android-arm-eabi.node')
+          } else {
+            nativeBinding = require('@z3rno/sdk-android-arm-eabi')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on Android ${arch}`)
+    }
+    break
+  case 'win32':
+    switch (arch) {
+      case 'x64':
+        localFileExisted = existsSync(
+          join(__dirname, 'z3rno-sdk-native.win32-x64-msvc.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./z3rno-sdk-native.win32-x64-msvc.node')
+          } else {
+            nativeBinding = require('@z3rno/sdk-win32-x64-msvc')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'ia32':
+        localFileExisted = existsSync(
+          join(__dirname, 'z3rno-sdk-native.win32-ia32-msvc.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./z3rno-sdk-native.win32-ia32-msvc.node')
+          } else {
+            nativeBinding = require('@z3rno/sdk-win32-ia32-msvc')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'arm64':
+        localFileExisted = existsSync(
+          join(__dirname, 'z3rno-sdk-native.win32-arm64-msvc.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./z3rno-sdk-native.win32-arm64-msvc.node')
+          } else {
+            nativeBinding = require('@z3rno/sdk-win32-arm64-msvc')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on Windows: ${arch}`)
+    }
+    break
+  case 'darwin':
+    localFileExisted = existsSync(join(__dirname, 'z3rno-sdk-native.darwin-universal.node'))
+    try {
+      if (localFileExisted) {
+        nativeBinding = require('./z3rno-sdk-native.darwin-universal.node')
+      } else {
+        nativeBinding = require('@z3rno/sdk-darwin-universal')
+      }
+      break
+    } catch {}
+    switch (arch) {
+      case 'x64':
+        localFileExisted = existsSync(join(__dirname, 'z3rno-sdk-native.darwin-x64.node'))
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./z3rno-sdk-native.darwin-x64.node')
+          } else {
+            nativeBinding = require('@z3rno/sdk-darwin-x64')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'arm64':
+        localFileExisted = existsSync(
+          join(__dirname, 'z3rno-sdk-native.darwin-arm64.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./z3rno-sdk-native.darwin-arm64.node')
+          } else {
+            nativeBinding = require('@z3rno/sdk-darwin-arm64')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on macOS: ${arch}`)
+    }
+    break
+  case 'freebsd':
+    if (arch !== 'x64') {
+      throw new Error(`Unsupported architecture on FreeBSD: ${arch}`)
+    }
+    localFileExisted = existsSync(join(__dirname, 'z3rno-sdk-native.freebsd-x64.node'))
+    try {
+      if (localFileExisted) {
+        nativeBinding = require('./z3rno-sdk-native.freebsd-x64.node')
+      } else {
+        nativeBinding = require('@z3rno/sdk-freebsd-x64')
+      }
+    } catch (e) {
+      loadError = e
+    }
+    break
+  case 'linux':
+    switch (arch) {
+      case 'x64':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'z3rno-sdk-native.linux-x64-musl.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./z3rno-sdk-native.linux-x64-musl.node')
+            } else {
+              nativeBinding = require('@z3rno/sdk-linux-x64-musl')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'z3rno-sdk-native.linux-x64-gnu.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./z3rno-sdk-native.linux-x64-gnu.node')
+            } else {
+              nativeBinding = require('@z3rno/sdk-linux-x64-gnu')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 'arm64':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'z3rno-sdk-native.linux-arm64-musl.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./z3rno-sdk-native.linux-arm64-musl.node')
+            } else {
+              nativeBinding = require('@z3rno/sdk-linux-arm64-musl')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'z3rno-sdk-native.linux-arm64-gnu.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./z3rno-sdk-native.linux-arm64-gnu.node')
+            } else {
+              nativeBinding = require('@z3rno/sdk-linux-arm64-gnu')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 'arm':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'z3rno-sdk-native.linux-arm-musleabihf.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./z3rno-sdk-native.linux-arm-musleabihf.node')
+            } else {
+              nativeBinding = require('@z3rno/sdk-linux-arm-musleabihf')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'z3rno-sdk-native.linux-arm-gnueabihf.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./z3rno-sdk-native.linux-arm-gnueabihf.node')
+            } else {
+              nativeBinding = require('@z3rno/sdk-linux-arm-gnueabihf')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 'riscv64':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'z3rno-sdk-native.linux-riscv64-musl.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./z3rno-sdk-native.linux-riscv64-musl.node')
+            } else {
+              nativeBinding = require('@z3rno/sdk-linux-riscv64-musl')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'z3rno-sdk-native.linux-riscv64-gnu.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./z3rno-sdk-native.linux-riscv64-gnu.node')
+            } else {
+              nativeBinding = require('@z3rno/sdk-linux-riscv64-gnu')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 's390x':
+        localFileExisted = existsSync(
+          join(__dirname, 'z3rno-sdk-native.linux-s390x-gnu.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./z3rno-sdk-native.linux-s390x-gnu.node')
+          } else {
+            nativeBinding = require('@z3rno/sdk-linux-s390x-gnu')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on Linux: ${arch}`)
+    }
+    break
+  default:
+    throw new Error(`Unsupported OS: ${platform}, architecture: ${arch}`)
+}
+
+if (!nativeBinding) {
+  if (loadError) {
+    throw loadError
+  }
+  throw new Error(`Failed to load native binding`)
+}
+
+const { Client, Advanced } = nativeBinding
+
+module.exports.Client = Client
+module.exports.Advanced = Advanced

package/npm/darwin-arm64/README.md

@@ -0,0 +1,3 @@
+# `@z3rno/sdk-darwin-arm64`
+
+This is the **aarch64-apple-darwin** binary for `@z3rno/sdk`

package/npm/darwin-arm64/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@z3rno/sdk-darwin-arm64",
+  "version": "0.23.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/the-ai-project-co/z3rno"
+  },
+  "os": [
+    "darwin"
+  ],
+  "cpu": [
+    "arm64"
+  ],
+  "main": "z3rno-sdk-native.darwin-arm64.node",
+  "files": [
+    "z3rno-sdk-native.darwin-arm64.node"
+  ],
+  "license": "Apache-2.0",
+  "engines": {
+    "node": ">= 18"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}

package/npm/darwin-x64/README.md

@@ -0,0 +1,3 @@
+# `@z3rno/sdk-darwin-x64`
+
+This is the **x86_64-apple-darwin** binary for `@z3rno/sdk`

package/npm/darwin-x64/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@z3rno/sdk-darwin-x64",
+  "version": "0.23.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/the-ai-project-co/z3rno"
+  },
+  "os": [
+    "darwin"
+  ],
+  "cpu": [
+    "x64"
+  ],
+  "main": "z3rno-sdk-native.darwin-x64.node",
+  "files": [
+    "z3rno-sdk-native.darwin-x64.node"
+  ],
+  "license": "Apache-2.0",
+  "engines": {
+    "node": ">= 18"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}

package/npm/linux-arm64-gnu/README.md

@@ -0,0 +1,3 @@
+# `@z3rno/sdk-linux-arm64-gnu`
+
+This is the **aarch64-unknown-linux-gnu** binary for `@z3rno/sdk`

package/npm/linux-arm64-gnu/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@z3rno/sdk-linux-arm64-gnu",
+  "version": "0.23.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/the-ai-project-co/z3rno"
+  },
+  "os": [
+    "linux"
+  ],
+  "cpu": [
+    "arm64"
+  ],
+  "main": "z3rno-sdk-native.linux-arm64-gnu.node",
+  "files": [
+    "z3rno-sdk-native.linux-arm64-gnu.node"
+  ],
+  "license": "Apache-2.0",
+  "engines": {
+    "node": ">= 18"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "libc": [
+    "glibc"
+  ]
+}

package/npm/linux-x64-gnu/README.md

@@ -0,0 +1,3 @@
+# `@z3rno/sdk-linux-x64-gnu`
+
+This is the **x86_64-unknown-linux-gnu** binary for `@z3rno/sdk`