@lv-agent/logdb-client 0.1.0 → 0.3.0

package/README.md

@@ -31,9 +31,21 @@ for (const r of records) {
 const stream = client.tail('my-app', 'main', { fromSeq: 0, consumerGroup: 'workers', consumerId: 'w1' });
 for await (const rec of stream) {
   console.log(`[${rec.seq}] ${rec.eventType}`);
-  // Commit progress
   await client.commitOffset('my-app', 'main', 'workers', 'w1', rec.seq);
 }
+
+// SQL query against cache
+const rows = await client.query('my-app', 'main',
+  "SELECT seq, event_type FROM records WHERE event_type = 'llm.call' ORDER BY seq DESC LIMIT 10");
+for (const row of rows) console.log(JSON.parse(row));
+
+// Subscribe to event types in real-time
+const sub = client.subscribe('my-app', 'main',
+  ['tool.call', 'llm.call'], 'sandbox-processors', 'worker-1');
+sub.on('data', (rec) => {
+  console.log(`[${rec.seq}] ${rec.eventType}`);
+  client.commitOffset('my-app', 'main', 'sandbox-processors', 'worker-1', rec.seq);
+});
 ```
 
 ## API
@@ -44,10 +56,14 @@ for await (const rec of stream) {
 | `read(ns, stream, seq)` | Point read |
 | `scanAll(ns, stream, fromSeq)` | Scan all records |
 | `tail(ns, stream, opts)` | Live subscription (async iterable) |
+| `query(ns, stream, sql)` | SQL SELECT against query cache |
+| `subscribe(ns, stream, eventTypes, group, id)` | Event-type push subscription |
 | `listNamespaces()` | List all namespaces |
 | `listStreams(ns)` | List streams in a namespace |
 | `status()` | Node status |
 | `verifyChain(ns, stream)` | Verify hash chain |
+| `createStream(ns, stream)` | Create a stream (admin) |
+| `deleteStream(ns, stream)` | Delete all records in a stream (admin) |
 | `commitOffset(...)` / `committedOffset(...)` | Consumer group offset management |
 
 ## TLS / mTLS
@@ -62,6 +78,17 @@ const client = new Client('logdbd.example.com:50051', {
 });
 ```
 
+## RBAC / Auth
+
+Roles: `admin` (all), `writer` (append), `reader` (read/query), `subscriber` (subscribe).
+
+```typescript
+// Pass token via ClientOptions
+const client = new Client('logdbd.example.com:50051', {
+  authToken: 'admin-secret-token',
+});
+```
+
 ## License
 
 Apache-2.0

package/dist/client.d.ts

@@ -1,3 +1,4 @@
+import * as grpc from '@grpc/grpc-js';
 import { TailStream } from './tail-stream';
 import type { AppendResult, BatchAppendResult, NamespaceInfo, LogRecord, StreamInfo, StatusResult, Watermark, VerifyResult, TailOptions } from './types';
 export interface ClientOptions {
@@ -43,8 +44,25 @@ export declare class Client {
     read(namespace: string, stream: string, seq: number): Promise<LogRecord | null>;
     /** Scan records in range. Returns array of records. */
     scanAll(namespace: string, stream: string, fromSeq: number, limit?: number): Promise<LogRecord[]>;
+    /** Subscribe to matching event types in real-time.
+     *
+     * Returns a gRPC server-streaming call.  Records are pushed as they
+     * are committed and filtered by `eventTypes`.  The consumer offset
+     * is tracked server-side.
+     *
+     * Usage:
+     *   const stream = client.subscribe('my-app', 'main', ['tool.call'], 'group', 'w1');
+     *   stream.on('data', (rec) => console.log(rec.eventType, rec.content));
+     */
+    subscribe(namespace: string, stream: string, eventTypes: string[], consumerGroup: string, consumerId: string): grpc.ClientReadableStream<any>;
     /** Subscribe to new records via Tail. */
     tail(namespace: string, stream: string, opts?: TailOptions): TailStream;
+    /** Execute a read-only SQL query against a stream's query cache.
+     *
+     * Only SELECT is allowed — enforced at the SQLite kernel level.
+     * Each row is returned as a JSON string.
+     */
+    query(namespace: string, stream: string, sql: string): Promise<string[]>;
     /** Get the watermark for a namespace/stream. */
     watermark(namespace: string, stream: string): Promise<Watermark>;
     /** List all namespaces. */
@@ -59,6 +77,17 @@ export declare class Client {
     commitOffset(namespace: string, stream: string, consumerGroup: string, consumerId: string, seq: number): Promise<void>;
     /** Get committed offset for a consumer. */
     committedOffset(namespace: string, stream: string, consumerGroup: string, consumerId: string): Promise<number>;
+    /** Create a stream (and namespace if needed). Requires admin token. */
+    createStream(namespace: string, stream: string): Promise<{
+        namespaceId: number;
+        streamId: number;
+        created: boolean;
+    }>;
+    /** Mark all records in a stream as deleted. Requires admin token. */
+    deleteStream(namespace: string, stream: string): Promise<{
+        deleted: boolean;
+        deletedCount: number;
+    }>;
     /** Close the client connection. */
     close(): void;
 }

package/dist/client.js

@@ -159,6 +159,26 @@ class Client {
             call.on('error', (err) => reject(err));
         });
     }
+    // ── Subscribe ───────────────────────────────────────────────────────
+    /** Subscribe to matching event types in real-time.
+     *
+     * Returns a gRPC server-streaming call.  Records are pushed as they
+     * are committed and filtered by `eventTypes`.  The consumer offset
+     * is tracked server-side.
+     *
+     * Usage:
+     *   const stream = client.subscribe('my-app', 'main', ['tool.call'], 'group', 'w1');
+     *   stream.on('data', (rec) => console.log(rec.eventType, rec.content));
+     */
+    subscribe(namespace, stream, eventTypes, consumerGroup, consumerId) {
+        return this.client.Subscribe({
+            namespace,
+            stream,
+            eventTypes,
+            consumerGroup,
+            consumerId,
+        });
+    }
     /** Subscribe to new records via Tail. */
     tail(namespace, stream, opts) {
         const call = this.client.Tail({
@@ -170,6 +190,21 @@ class Client {
         });
         return new tail_stream_1.TailStream(call, convertRecord);
     }
+    // ── Query ──────────────────────────────────────────────────────────
+    /** Execute a read-only SQL query against a stream's query cache.
+     *
+     * Only SELECT is allowed — enforced at the SQLite kernel level.
+     * Each row is returned as a JSON string.
+     */
+    query(namespace, stream, sql) {
+        return new Promise((resolve, reject) => {
+            this.client.Query({ namespace, stream, sql }, (err, resp) => {
+                if (err)
+                    return reject(err);
+                resolve(resp.rows || []);
+            });
+        });
+    }
     // ── Watermark ──────────────────────────────────────────────────────
     /** Get the watermark for a namespace/stream. */
     watermark(namespace, stream) {
@@ -266,6 +301,26 @@ class Client {
             });
         });
     }
+    /** Create a stream (and namespace if needed). Requires admin token. */
+    createStream(namespace, stream) {
+        return new Promise((resolve, reject) => {
+            this.client.CreateStream({ namespace, stream, maxRecords: 0, maxBytes: 0 }, (err, resp) => {
+                if (err)
+                    return reject(err);
+                resolve({ namespaceId: resp.namespaceId, streamId: resp.streamId, created: resp.created });
+            });
+        });
+    }
+    /** Mark all records in a stream as deleted. Requires admin token. */
+    deleteStream(namespace, stream) {
+        return new Promise((resolve, reject) => {
+            this.client.DeleteStream({ namespace, stream }, (err, resp) => {
+                if (err)
+                    return reject(err);
+                resolve({ deleted: resp.deleted, deletedCount: Number(resp.deletedCount) });
+            });
+        });
+    }
     /** Close the client connection. */
     close() {
         if (!this.closed) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lv-agent/logdb-client",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "TypeScript SDK for logdbd — append-only audit log database",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",