@lv-agent/logdb-client 0.1.0 → 0.2.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,6 +56,8 @@ 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 |

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. */

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) {

package/package.json

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