@xcitedbs/client 0.1.0 → 0.2.5

package/llms.txt

@@ -0,0 +1,274 @@
+# XciteDB
+
+> XciteDB is a versioned XML and JSON document database delivered as a Backend-as-a-Service (BaaS). It provides Git-like branching, commits, time-travel, and hierarchical document identifiers over a high-performance embedded LMDB engine, exposed through a REST + WebSocket API.
+
+## Important: Non-Standard Conventions
+
+These are the most common sources of confusion for developers and AI assistants:
+
+1. **The default branch is the empty string `""`, not `"main"`.** When no `X-Branch` header is sent (or `context.branch` is omitted/empty in the SDK), the server operates on the root timeline. A branch named `"main"` may exist as a user-created branch, but it is not required or special.
+
+2. **Identifiers are hierarchical, path-like strings** — e.g. `/us/bills/hr1`, `/manual/v2/chapter3`. They are NOT auto-generated UUIDs. The leading `/` is part of the identifier. Parent/child relationships are derived from the path structure (like a filesystem). The server indexes this hierarchy natively.
+
+3. **Documents are XML or JSON, not arbitrary blobs.** XML documents are the primary document type, stored with structural shredding. JSON documents are a parallel store keyed by identifier string. Both are fully versioned.
+
+4. **Context (branch + date) travels as HTTP headers**, not URL path segments. Use `X-Branch` and `X-Date` headers (or the SDK `context` option) to select which branch and point-in-time you are reading/writing.
+
+5. **XML documents carry their identifier inside the XML** — specifically via a `db:identifier` attribute on the root element (e.g. `<chapter db:identifier="/book/ch1">...</chapter>`). When writing XML, the server extracts the identifier from the document body.
+
+6. **Authentication has two tiers.** Platform operators (site admins) log in via `/api/v1/platform/auth/*` and use `X-Project-Id` to select a tenant project. Application end-users log in via `/api/v1/app/auth/*` and are scoped to a single project. API keys bypass login for server-to-server use.
+
+7. **The query model is NOT SQL.** Listing/filtering documents uses query parameters on REST endpoints (`match`, `match_start`, `contains`, `regex`, `prefix`). Advanced analytics use **Unquery**, a JSON-defined declarative DSL posted to `POST /api/v1/unquery`.
+
+8. **Project vs tenant id.** In the SDK, prefer `context.project_id` (and `listMyProjects` / `switchProject`). Many JSON bodies and JWT claims still use the field name `tenant_id` for the same value — the client sends that wire name automatically.
+
+## JavaScript/TypeScript SDK (`@xcitedbs/client`)
+
+Install: `npm install @xcitedbs/client`
+
+### Quick Start
+
+```typescript
+import { XCiteDBClient } from '@xcitedbs/client';
+
+const client = new XCiteDBClient({
+  baseUrl: 'http://localhost:8080',
+  apiKey: 'your-api-key',
+  // branch: '' means root timeline (the default); omit or use '' for default
+  context: { branch: '', date: '' },
+});
+
+// Health check (no auth required)
+await client.health();
+
+// List all branches
+const branches = await client.listBranches();
+
+// Query documents by identifier prefix
+const docs = await client.queryDocuments({ match_start: '/manual/' });
+
+// Read a single document by exact identifier
+const xml = await client.queryByIdentifier('/manual/v1/intro', 'FirstMatch');
+
+// Write an XML document (identifier is inside the XML body)
+await client.writeXmlDocument(
+  '<chapter db:identifier="/manual/v1/intro"><title>Introduction</title></chapter>'
+);
+
+// Write a JSON document
+await client.writeJsonDocument('app.settings', { theme: 'dark', locale: 'en' });
+
+// Read a JSON document
+const settings = await client.readJsonDocument('app.settings');
+
+// Quick JSON CRUD aliases (same as writeJsonDocument / readJsonDocument / deleteJsonDocument / listJsonDocuments)
+await client.put('app.prefs', { theme: 'dark' });
+const prefs = await client.get<Record<string, unknown>>('app.prefs');
+await client.remove('app.prefs');
+const keys = await client.list(undefined, 50, 0);
+
+// Branch helper: create branch, run work, commit, merge back (restores context)
+await client.withBranch('feature-x', async (c) => {
+  await c.writeJsonDocument('app.settings', { theme: 'light' });
+  return 'ok';
+}, { message: 'Light theme', autoMerge: true, fromBranch: '' });
+
+// Create a branch, make changes, commit, merge
+await client.createBranch('feature-x');
+client.setContext({ branch: 'feature-x' });
+await client.writeJsonDocument('app.settings', { theme: 'light' });
+const commit = await client.createCommit('Switch to light theme');
+await client.mergeBranch('', 'feature-x'); // merge into root (default) branch
+
+// Attach JSON metadata to a document
+await client.addMeta('/manual/v1/intro', { status: 'draft', owner: 'alice' });
+
+// Acquire a cooperative lock
+const lock = await client.acquireLock('/manual/v1/intro');
+// ... edit ...
+await client.releaseLock('/manual/v1/intro', lock.lock_id);
+
+// Full-text search (requires Meilisearch or Elasticsearch backend)
+const results = await client.search({ query: 'installation guide', limit: 20 });
+
+// Subscribe to real-time changes via WebSocket
+const sub = client.subscribe(
+  { pattern: '/manual/*', event_type: '*' },
+  (event) => console.log('Change:', event)
+);
+```
+
+### Constructor Options
+
+```typescript
+interface XCiteDBClientOptions {
+  baseUrl: string;              // Server URL, e.g. 'http://localhost:8080'
+  apiKey?: string;              // Project API key (secret or public)
+  accessToken?: string;         // Platform JWT (from platformLogin)
+  appUserAccessToken?: string;  // End-user JWT (from loginAppUser)
+  context?: {
+    branch?: string;   // Branch name; '' = default/root timeline
+    date?: string;     // Point-in-time (ISO-like or internal date key)
+    prefix?: string;   // Optional identifier prefix filter
+    project_id?: string; // Preferred: project id for app-user public auth (`tenant_id` on wire)
+    tenant_id?: string; // Deprecated alias of project_id
+  };
+  platformConsole?: boolean;    // true = use X-Project-Id header
+  projectId?: string;           // Active project for platform console mode
+}
+```
+
+### Key Methods Reference
+
+**Health & Auth:**
+- `health()` — Liveness check (no auth)
+- `version()` — Server version info
+- `platformLogin(email, password)` — Platform operator sign-in
+- `loginAppUser(email, password)` — App end-user sign-in
+- `setContext(ctx)` — Update branch/date context
+- `setProjectId(id)` — Switch active project (platform console)
+
+**XML Documents:**
+- `writeXmlDocument(xml, options?)` — Store XML via JSON body (identifier inside XML). Deprecated alias: `writeDocumentJson`.
+- `writeXML(xml)` — Store raw XML with `Content-Type: application/xml`
+- `queryByIdentifier(id, flags?, filter?)` — Get document(s) by identifier
+- `queryDocuments(query, flags?)` — List/filter documents
+- `deleteDocument(identifier)` — Delete by identifier
+- `listIdentifiers(query)` — List known identifiers with pagination
+- `listIdentifierChildren(parentPath?)` — Navigate identifier hierarchy
+
+**JSON Documents:**
+- `writeJsonDocument(identifier, data)` — Store a JSON document
+- `readJsonDocument(identifier)` — Read a JSON document (generic `readJsonDocument<T>()` supported)
+- `deleteJsonDocument(identifier)` — Delete a JSON document
+- `listJsonDocuments(match?, limit?, offset?)` — List JSON document keys
+- **Quick JSON aliases:** `put`, `get`, `remove`, `list` — same as the four methods above
+
+**Metadata (JSON on XML):**
+- `addMeta(identifier, value, path?)` — Set metadata on a document
+- `appendMeta(identifier, value, path?)` — Append to metadata
+- `queryMeta(identifier, path?)` — Read metadata
+- `clearMeta(query)` — Remove metadata
+
+**Versioning:**
+- `withBranch(name, fn, options?)` — Create branch, run callback on client, commit, merge back (optional `autoMerge: false`)
+- `createBranch(name, fromBranch?, fromDate?)` — Create branch
+- `listBranches()` — List all branches
+- `mergeBranch(target, source, options?)` — Merge branches
+- `deleteBranch(name)` — Delete branch
+- `createCommit(message, author?)` — Commit current state
+- `listCommits(options?)` — List commits
+- `rollbackToCommit(commitId)` — Rollback to prior commit
+- `cherryPick(commitId, message?)` — Cherry-pick a commit
+- `diff(from, to, includeContent?)` — Diff between revisions
+- `createTag(name, commitId, message?)` — Tag a commit
+- `listTags()` / `deleteTag(name)` — Manage tags
+
+**Locks:**
+- `acquireLock(identifier, expires?)` — Acquire cooperative lock
+- `releaseLock(identifier, lockId)` — Release lock
+- `findLocks(identifier)` — Query active locks
+
+**Search & Analytics:**
+- `search(query)` — Full-text search
+- `reindex()` — Rebuild search index
+- `unquery(query, unqueryDoc)` — Execute Unquery DSL
+
+**Security & Policies:**
+- `createPolicy(id, policy)` / `listPolicies()` / `updatePolicy()` / `deletePolicy()` — ABAC policies
+- `checkAccess(subject, identifier, action)` — Dry-run access check
+- `getSecurityConfig()` / `updateSecurityConfig()` — Security settings
+
+**Triggers:**
+- `upsertTrigger(id, trigger)` / `listTriggers()` / `deleteTrigger(name)` — Automation triggers
+
+**App Users (admin):**
+- `listAppUsers()` / `createAppUser()` / `deleteAppUser()` — Manage end-user accounts
+- `registerAppUser()` — Self-registration
+- `getAppAuthConfig()` — Auth configuration
+
+**WebSocket:**
+- `subscribe(options, callback, onError?)` — Real-time document change notifications
+
+### Query Flags
+
+When calling `queryByIdentifier` or `queryDocuments`, the `flags` parameter controls matching:
+- `'FirstMatch'` — Return only the first matching document
+- `'IncludeChildren'` — Include child identifiers in results
+- `'NoChildren'` — Exclude children
+- `'KeepIndexNodes'` — Include index/structural nodes
+
+### Errors
+
+All API errors throw `XCiteDBError` with `.status` (HTTP code) and `.body` (parsed response). Common codes: `401` unauthenticated, `403` forbidden by policy, `404` not found, `409` conflict (lock), `422` validation, `423` project encrypted and locked, `429` rate limited.
+
+## Python SDK (`xcitedb`)
+
+Install: `pip install xcitedb`
+
+```python
+import asyncio
+from xcitedb import XCiteDBClient, XCiteQuery, DatabaseContext, TextSearchQuery
+
+async def main():
+    async with XCiteDBClient(
+        "http://localhost:8080",
+        api_key="your-key",
+        context=DatabaseContext(branch="", date=""),
+    ) as client:
+        print(await client.health())
+        ids = await client.query_documents(XCiteQuery(match_start="/manual/"))
+        print(ids)
+        await client.write_json_document("app.settings", {"theme": "dark"})
+        print(await client.read_json_document("app.settings"))
+        print(await client.search(TextSearchQuery(query="guide", limit=10)))
+        pair = await client.platform_login("admin@localhost", "password")
+        # await client.login_app_user("user@example.com", "secret", tenant_id="...")
+
+asyncio.run(main())
+```
+
+## C++ SDK (`xcitedb`)
+
+```cpp
+#include <xcitedb/xcitedb.hpp>
+
+xcitedb::XCiteDBClientOptions opt;
+opt.base_url = "http://127.0.0.1:8080";
+opt.api_key = "your-key";
+opt.context.branch = "";  // root timeline
+
+xcitedb::XCiteDBClient client(opt);
+auto health = client.health();
+xcitedb::XCiteQuery q;
+q.match_start = "/manual/";
+auto ids = client.query_documents(q);
+```
+
+## Architecture Notes
+
+- **Multi-tenant**: Each project is an isolated tenant with its own data, users, keys, and policies.
+- **LMDB engine**: Data is memory-mapped; reads are microsecond-class on warm data.
+- **Versioning**: Every write is versioned. Branches isolate work. Commits snapshot state. Time-travel reads any historical state via `X-Date`.
+- **Two user tiers**: Platform operators manage infrastructure; App users are end-users of applications built on XciteDB.
+- **Security policies (ABAC)**: Fine-grained allow/deny rules on actions, resources, roles, and branches.
+- **WebSocket**: Real-time notifications for document changes at `/api/v1/ws`.
+
+## Documentation
+
+- **OpenAPI 3.1:** Repository file `docs/openapi.yaml` (machine-readable route map and shared schemas).
+- Full API reference is also available at your XciteDB server's `/docs` path. Key sections:
+- Getting started — Base URL, headers, errors, pagination
+- Documents — XML document CRUD, identifiers, hierarchy
+- JSON documents — JSON document CRUD
+- Metadata — JSON metadata on documents
+- Search — Full-text search
+- Unquery — Declarative query DSL
+- Branches — Branch management
+- Commits & tags — Version snapshots
+- Locks — Cooperative editing locks
+- Authentication — JWT, API keys, platform vs app users
+- Security policies — ABAC access control
+- Triggers — Automated webhooks on metadata changes
+- App authentication — End-user registration, login, OAuth
+- Project & API keys — Key management

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xcitedbs/client",
-  "version": "0.1.0",
+  "version": "0.2.5",
   "description": "XCiteDB BaaS client SDK",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -37,7 +37,9 @@
     "typescript": "^5.0.0"
   },
   "files": [
-    "dist"
+    "dist",
+    "llms.txt",
+    "llms-full.txt"
   ],
   "license": "MIT"
 }