@enbox/api 0.6.31 → 0.6.33

package/src/live-query.ts

@@ -1,5 +1,5 @@
 import type { DwnMessageSubscription, EnboxAgent, PermissionsApi } from '@enbox/agent';
-import type { PaginationCursor, RecordsQueryReplyEntry } from '@enbox/dwn-sdk-js';
+import type { PaginationCursor, ProgressToken, RecordsQueryReplyEntry } from '@enbox/dwn-sdk-js';
 
 import { getRecordAuthor } from '@enbox/agent';
 
@@ -21,6 +21,20 @@ export type RecordChange = {
   record: Record;
 };
 
+/**
+ * Describes a terminal DWN subscription error surfaced by a {@link LiveQuery}.
+ */
+export type LiveQueryError = {
+  /** The DWN error code associated with the terminal subscription failure. */
+  code: string;
+
+  /** Human-readable error detail from the DWN subscription. */
+  detail: string;
+
+  /** The event cursor that caused delivery to stop, when provided by the DWN. */
+  cursor?: ProgressToken;
+};
+
 /**
  * A `CustomEvent` subclass carrying a {@link RecordChange} as its `detail`.
  *
@@ -77,10 +91,15 @@ export type RecordCatchAllEvent = 'change';
  */
 export type LiveQueryLifecycleEvent = 'disconnected' | 'reconnecting' | 'reconnected' | 'eose';
 
+/**
+ * Terminal event type emitted when a DWN subscription fails after it is open.
+ */
+export type LiveQueryTerminalEvent = 'error';
+
 /**
  * Union of all event types emitted by {@link LiveQuery}.
  */
-export type LiveQueryEventType = RecordChangeType | RecordCatchAllEvent | LiveQueryLifecycleEvent;
+export type LiveQueryEventType = RecordChangeType | RecordCatchAllEvent | LiveQueryLifecycleEvent | LiveQueryTerminalEvent;
 
 /**
  * A live query that combines an initial snapshot of matching records with a
@@ -103,6 +122,7 @@ export type LiveQueryEventType = RecordChangeType | RecordCatchAllEvent | LiveQu
  * | `reconnecting` | `{ attempt: number }` | Reconnection attempt in progress |
  * | `reconnected` | — | Connection restored, subscription resubscribed |
  * | `eose` | — | End-of-stored-events: catch-up replay complete, events are now live |
+ * | `error` | {@link LiveQueryError} | Terminal subscription error; no further events will be delivered |
  *
  * @example
  * ```ts
@@ -269,6 +289,21 @@ export class LiveQuery extends EventTarget {
     this.dispatchEvent(new CustomEvent(type, { detail }));
   }
 
+  /**
+   * Handle a terminal DWN subscription error.
+   *
+   * @internal — Called by `DwnApi.records.subscribe()` before closing the
+   * underlying subscription.
+   */
+  public handleError(error: LiveQueryError): void {
+    if (this._closed) {
+      return;
+    }
+
+    this._connected = false;
+    this.dispatchEvent(new CustomEvent('error', { detail: error }));
+  }
+
   /**
    * Register a typed event handler. Returns an unsubscribe function.
    *
@@ -290,9 +325,15 @@ export class LiveQuery extends EventTarget {
   on(event: 'reconnecting', handler: (detail: { attempt: number }) => void): () => void;
   on(event: 'reconnected', handler: () => void): () => void;
   on(event: 'eose', handler: () => void): () => void;
+  on(event: 'error', handler: (error: LiveQueryError) => void): () => void;
   on(
     event: LiveQueryEventType,
-    handler: ((change: RecordChange) => void) | ((record: Record) => void) | ((detail: { attempt: number }) => void) | (() => void),
+    handler:
+      | ((change: RecordChange) => void)
+      | ((record: Record) => void)
+      | ((detail: { attempt: number }) => void)
+      | ((error: LiveQueryError) => void)
+      | (() => void),
   ): () => void {
     const wrapper = (e: Event): void => {
       const detail = (e as CustomEvent).detail;
@@ -302,6 +343,8 @@ export class LiveQuery extends EventTarget {
         (handler as (record: Record) => void)(detail.record);
       } else if (event === 'reconnecting') {
         (handler as (detail: { attempt: number }) => void)(detail);
+      } else if (event === 'error') {
+        (handler as (error: LiveQueryError) => void)(detail);
       } else {
         // disconnected, reconnected, eose — no payload
         (handler as () => void)();

package/src/typed-live-query.ts

@@ -6,7 +6,7 @@
  * - `.records` returns `TypedRecord<T>[]` instead of `Record[]`.
  * - `.on('create', handler)` provides `TypedRecord<T>` in the callback.
  * - `.on('change', handler)` provides `TypedRecordChange<T>` in the callback.
- * - `.on('disconnected' | 'reconnecting' | 'reconnected' | 'eose', handler)`
+ * - `.on('disconnected' | 'reconnecting' | 'reconnected' | 'eose' | 'error', handler)`
  *   forwards transport lifecycle events from the underlying `LiveQuery`.
  *
  * @example
@@ -30,7 +30,7 @@
  */
 
 import type { PaginationCursor } from '@enbox/dwn-sdk-js';
-import type { LiveQuery, RecordChange } from './live-query.js';
+import type { LiveQuery, LiveQueryError, RecordChange } from './live-query.js';
 
 import { TypedRecord } from './typed-record.js';
 
@@ -123,7 +123,7 @@ export class TypedLiveQuery<T> {
    *
    * Supports both record change events (`change`, `create`, `update`, `delete`)
    * and transport lifecycle events (`disconnected`, `reconnecting`,
-   * `reconnected`, `eose`).
+   * `reconnected`, `eose`, `error`).
    *
    * @param event - The event type to listen for.
    * @param handler - The handler function with typed record(s) or lifecycle data.
@@ -148,11 +148,13 @@ export class TypedLiveQuery<T> {
   public on(event: 'reconnecting', handler: (detail: { attempt: number }) => void): () => void;
   public on(event: 'reconnected', handler: () => void): () => void;
   public on(event: 'eose', handler: () => void): () => void;
+  public on(event: 'error', handler: (error: LiveQueryError) => void): () => void;
   public on(
-    event: 'change' | 'create' | 'update' | 'delete' | 'disconnected' | 'reconnecting' | 'reconnected' | 'eose',
+    event: 'change' | 'create' | 'update' | 'delete' | 'disconnected' | 'reconnecting' | 'reconnected' | 'eose' | 'error',
     handler: ((change: TypedRecordChange<T>) => void)
       | ((record: TypedRecord<T>) => void)
       | ((detail: { attempt: number }) => void)
+      | ((error: LiveQueryError) => void)
       | (() => void),
   ): () => void {
     // Lifecycle events: delegate directly to the underlying LiveQuery.
@@ -168,6 +170,9 @@ export class TypedLiveQuery<T> {
     if (event === 'reconnecting') {
       return this._liveQuery.on('reconnecting', handler as (detail: { attempt: number }) => void);
     }
+    if (event === 'error') {
+      return this._liveQuery.on('error', handler as (error: LiveQueryError) => void);
+    }
 
     // Record change events: wrap records in TypedRecord.
     if (event === 'change') {