@enbox/api 0.2.3 → 0.3.0

package/src/live-query.ts

@@ -67,6 +67,21 @@ export type LiveQueryOptions = {
   subscription: DwnMessageSubscription;
 };
 
+/**
+ * Catch-all event type that fires for any record change (create, update, or delete).
+ */
+export type RecordCatchAllEvent = 'change';
+
+/**
+ * Lifecycle event type for connection state changes.
+ */
+export type LiveQueryLifecycleEvent = 'disconnected' | 'reconnecting' | 'reconnected' | 'eose';
+
+/**
+ * Union of all event types emitted by {@link LiveQuery}.
+ */
+export type LiveQueryEventType = RecordChangeType | RecordCatchAllEvent | LiveQueryLifecycleEvent;
+
 /**
  * A live query that combines an initial snapshot of matching records with a
  * real-time stream of deduplicated, semantically-typed change events.
@@ -84,6 +99,10 @@ export type LiveQueryOptions = {
  * | `update` | {@link RecordChange} | An existing record was updated |
  * | `delete` | {@link RecordChange} | A record was deleted |
  * | `change` | {@link RecordChange} | Catch-all for any of the above |
+ * | `disconnected` | — | Transport connection lost |
+ * | `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 |
  *
  * @example
  * ```ts
@@ -106,10 +125,10 @@ export type LiveQueryOptions = {
  * liveQuery.on('update', (record) => refreshMessage(record));
  * liveQuery.on('delete', (record) => removeMessage(record));
  *
- * // Or use the catch-all
- * liveQuery.on('change', ({ type, record }) => {
- *   console.log(`${type}: ${record.id}`);
- * });
+ * // Connection lifecycle
+ * liveQuery.on('disconnected', () => showOfflineIndicator());
+ * liveQuery.on('reconnected', () => hideOfflineIndicator());
+ * liveQuery.on('eose', () => console.log('catch-up complete'));
  *
  * // Cleanup
  * await liveQuery.close();
@@ -139,6 +158,9 @@ export class LiveQuery extends EventTarget {
   /** Whether the live query has been closed. */
   private _closed = false;
 
+  /** Whether the transport connection is currently active. */
+  private _connected = true;
+
   constructor(options: LiveQueryOptions) {
     super();
 
@@ -174,6 +196,11 @@ export class LiveQuery extends EventTarget {
     }
   }
 
+  /** Whether the transport connection is currently active. */
+  public get isConnected(): boolean {
+    return this._connected;
+  }
+
   /**
    * Process an incoming live event from the DWN subscription.
    * Deduplicates against the initial snapshot and classifies the change type.
@@ -217,6 +244,31 @@ export class LiveQuery extends EventTarget {
     this.dispatchEvent(new CustomEvent('change', { detail: change }));
   }
 
+  /**
+   * Handle a transport lifecycle event (disconnected, reconnecting, reconnected)
+   * or an EOSE marker from the subscription.
+   *
+   * @internal — Called by `DwnApi.records.subscribe()` when the handler receives
+   * non-record subscription messages.
+   */
+  public handleLifecycleEvent(type: 'disconnected'): void;
+  public handleLifecycleEvent(type: 'reconnecting', detail: { attempt: number }): void;
+  public handleLifecycleEvent(type: 'reconnected'): void;
+  public handleLifecycleEvent(type: 'eose'): void;
+  public handleLifecycleEvent(type: LiveQueryLifecycleEvent, detail?: { attempt: number }): void {
+    if (this._closed) {
+      return;
+    }
+
+    if (type === 'disconnected') {
+      this._connected = false;
+    } else if (type === 'reconnected') {
+      this._connected = true;
+    }
+
+    this.dispatchEvent(new CustomEvent(type, { detail }));
+  }
+
   /**
    * Register a typed event handler. Returns an unsubscribe function.
    *
@@ -234,13 +286,25 @@ export class LiveQuery extends EventTarget {
   on(event: 'create', handler: (record: Record) => void): () => void;
   on(event: 'update', handler: (record: Record) => void): () => void;
   on(event: 'delete', handler: (record: Record) => void): () => void;
-  on(event: 'change' | 'create' | 'update' | 'delete', handler: ((change: RecordChange) => void) | ((record: Record) => void)): () => void {
+  on(event: 'disconnected', handler: () => void): () => void;
+  on(event: 'reconnecting', handler: (detail: { attempt: number }) => void): () => void;
+  on(event: 'reconnected', handler: () => void): () => void;
+  on(event: 'eose', handler: () => void): () => void;
+  on(
+    event: LiveQueryEventType,
+    handler: ((change: RecordChange) => void) | ((record: Record) => void) | ((detail: { attempt: number }) => void) | (() => void),
+  ): () => void {
     const wrapper = (e: Event): void => {
-      const detail = (e as CustomEvent<RecordChange>).detail;
+      const detail = (e as CustomEvent).detail;
       if (event === 'change') {
         (handler as (change: RecordChange) => void)(detail);
-      } else {
+      } else if (event === 'create' || event === 'update' || event === 'delete') {
         (handler as (record: Record) => void)(detail.record);
+      } else if (event === 'reconnecting') {
+        (handler as (detail: { attempt: number }) => void)(detail);
+      } else {
+        // disconnected, reconnected, eose — no payload
+        (handler as () => void)();
       }
     };
 

package/src/permission-grant.ts

@@ -120,9 +120,8 @@ export class PermissionGrant implements PermissionGrantModel {
   }
 
   /** parses the grant given an agent, connectedDid and data encoded records write message  */
-  static async parse(options: PermissionGrantOptions): Promise<PermissionGrant> {
-    //TODO: this does not have to be async https://github.com/enboxorg/enbox/pull/831/files
-    const grant = await DwnPermissionGrant.parse(options.message);
+  static parse(options: PermissionGrantOptions): PermissionGrant {
+    const grant = DwnPermissionGrant.parse(options.message);
     const api = new AgentPermissionsApi({ agent: options.agent });
     return new PermissionGrant({ ...options, grant, api });
   }

package/src/permission-request.ts

@@ -84,13 +84,12 @@ export class PermissionRequest implements PermissionRequestModel {
   }
 
   /** parses the request given an agent, connectedDid and data encoded records write message  */
-  static async parse({ connectedDid, agent, message }:{
+  static parse({ connectedDid, agent, message }:{
     connectedDid: string;
     agent: Web5Agent;
     message: DwnDataEncodedRecordsWriteMessage;
-  }): Promise<PermissionRequest> {
-    //TODO: this does not have to be async https://github.com/enboxorg/enbox/pull/831/files
-    const request = await DwnPermissionRequest.parse(message);
+  }): PermissionRequest {
+    const request = DwnPermissionRequest.parse(message);
     const api = new AgentPermissionsApi({ agent });
     return new PermissionRequest({ api, connectedDid, message, request });
   }

package/src/record-data.ts

@@ -0,0 +1,155 @@
+/**
+ * Data-access helpers for the {@link Record} class.
+ *
+ * `RecordData` is the object returned by `Record.data`. It wraps a lazily
+ * evaluated `stream()` function with convenience accessors that mirror the
+ * Fetch `Response` API (`blob()`, `bytes()`, `json()`, `text()`).
+ *
+ * Extracted from `record.ts` so the convenience-method boilerplate lives in
+ * its own module while the stream-resolution logic (which is tightly coupled
+ * to `Record` internals) stays inside the `Record` class.
+ *
+ * @module
+ */
+
+import { Stream } from '@enbox/common';
+
+/**
+ * A thenable data accessor returned by {@link Record.data}.
+ *
+ * Provides convenience methods for consuming the record's data in various
+ * formats, plus `then`/`catch` so the object can be awaited directly to
+ * obtain the underlying `ReadableStream`.
+ *
+ * @beta
+ */
+export type RecordData = {
+  /** Consume the data as a `Blob`. */
+  blob: () => Promise<Blob>;
+  /** Consume the data as raw bytes. */
+  bytes: () => Promise<Uint8Array>;
+  /** Parse the data as JSON. */
+  json: <T = unknown>() => Promise<T>;
+  /** Consume the data as a UTF-8 string. */
+  text: () => Promise<string>;
+  /** Obtain the underlying Web `ReadableStream`. */
+  stream: () => Promise<ReadableStream>;
+  /** Proxy for `stream().then(...)` so the object is directly awaitable. */
+  then: (
+    onFulfilled?: (value: ReadableStream) => ReadableStream | PromiseLike<ReadableStream>,
+    onRejected?: (reason: any) => PromiseLike<never>,
+  ) => Promise<ReadableStream>;
+  /** Proxy for `stream().catch(...)`. */
+  catch: (onRejected?: (reason: any) => PromiseLike<never>) => Promise<ReadableStream>;
+};
+
+/**
+ * Create a {@link RecordData} wrapper around a `stream` provider function.
+ *
+ * @param streamFn   - A function that returns a `Promise<ReadableStream>` for the record data.
+ * @param dataFormat - The MIME type used when constructing Blobs.
+ * @returns A {@link RecordData} object with convenience accessors.
+ *
+ * @beta
+ */
+export function createRecordData(streamFn: () => Promise<ReadableStream>, dataFormat: string | undefined): RecordData {
+  const dataObj: RecordData = {
+
+    /**
+     * Returns the data of the current record as a `Blob`.
+     *
+     * @returns A promise that resolves to a Blob containing the record's data.
+     * @throws If the record data is not available or cannot be converted to a `Blob`.
+     *
+     * @beta
+     */
+    async blob(): Promise<Blob> {
+      return new Blob([await Stream.consumeToBytes({ readableStream: await this.stream() })], { type: dataFormat });
+    },
+
+    /**
+     * Returns the data of the current record as a `Uint8Array`.
+     *
+     * @returns A Promise that resolves to a `Uint8Array` containing the record's data bytes.
+     * @throws If the record data is not available or cannot be converted to a byte array.
+     *
+     * @beta
+     */
+    async bytes(): Promise<Uint8Array> {
+      return await Stream.consumeToBytes({ readableStream: await this.stream() });
+    },
+
+    /**
+     * Parses the data of the current record as JSON and returns it as a JavaScript object.
+     *
+     * @returns A Promise that resolves to a JavaScript object parsed from the record's JSON data.
+     * @throws If the record data is not available, not in JSON format, or cannot be parsed.
+     *
+     * @beta
+     */
+    async json<T = unknown>(): Promise<T> {
+      return await Stream.consumeToJson({ readableStream: await this.stream() }) as T;
+    },
+
+    /**
+     * Returns the data of the current record as a `string`.
+     *
+     * @returns A promise that resolves to a `string` containing the record's text data.
+     * @throws If the record data is not available or cannot be converted to text.
+     *
+     * @beta
+     */
+    async text(): Promise<string> {
+      return await Stream.consumeToText({ readableStream: await this.stream() });
+    },
+
+    /**
+     * Provides a Web `ReadableStream` containing the record's data.
+     *
+     * Uses the standard Web Streams API for cross-platform compatibility across
+     * browsers, Node.js, Bun, and Deno.
+     *
+     * @returns A promise that resolves to a Web `ReadableStream` of the record's data.
+     * @throws If the record data is not available in-memory and cannot be fetched.
+     *
+     * @beta
+     */
+    stream: streamFn,
+
+    /**
+     * Attaches callbacks for the resolution and/or rejection of the `Promise` returned by
+     * `stream()`.
+     *
+     * This method is a proxy to the `then` method of the `Promise` returned by `stream()`,
+     * allowing for a seamless integration with promise-based workflows.
+     * @param onFulfilled - A function to asynchronously execute when the `stream()` promise
+     *                      becomes fulfilled.
+     * @param onRejected - A function to asynchronously execute when the `stream()` promise
+     *                     becomes rejected.
+     * @returns A `Promise` for the completion of which ever callback is executed.
+     */
+    then(
+      onFulfilled?: (value: ReadableStream) => ReadableStream | PromiseLike<ReadableStream>,
+      onRejected?: (reason: any) => PromiseLike<never>,
+    ): Promise<ReadableStream> {
+      return this.stream().then(onFulfilled, onRejected);
+    },
+
+    /**
+     * Attaches a rejection handler callback to the `Promise` returned by the `stream()` method.
+     * This method is a shorthand for `.then(undefined, onRejected)`, specifically designed for handling
+     * rejection cases in the promise chain initiated by accessing the record's data. It ensures that
+     * errors during data retrieval or processing can be caught and handled appropriately.
+     *
+     * @param onRejected - A function to asynchronously execute when the `stream()` promise
+     *                     becomes rejected.
+     * @returns A `Promise` that resolves to the value of the callback if it is called, or to its
+     *          original fulfillment value if the promise is instead fulfilled.
+     */
+    catch(onRejected?: (reason: any) => PromiseLike<never>): Promise<ReadableStream> {
+      return this.stream().catch(onRejected);
+    }
+  };
+
+  return dataObj;
+}

package/src/record-types.ts

@@ -0,0 +1,188 @@
+/**
+ * Type definitions for the {@link Record} class.
+ *
+ * Extracted from `record.ts` to keep the main module focused on behaviour.
+ *
+ * @module
+ */
+
+import type {
+  DwnMessage,
+  DwnMessageDescriptor,
+} from '@enbox/agent';
+
+import type { DwnInterface } from '@enbox/agent';
+
+/**
+ * Represents Immutable Record properties that cannot be changed after the record is created.
+ *
+ * @beta
+ * */
+export type ImmutableRecordProperties =
+  Pick<DwnMessageDescriptor[DwnInterface.RecordsWrite], 'dateCreated' | 'parentId' | 'protocol' | 'protocolPath' | 'recipient' | 'schema'>;
+
+/**
+ * Represents Optional Record properties that depend on the Record's current state.
+ *
+ * @beta
+*/
+export type OptionalRecordProperties =
+  Pick<DwnMessage[DwnInterface.RecordsWrite], 'authorization' | 'attestation' | 'encryption' | 'contextId' > &
+  Pick<DwnMessageDescriptor[DwnInterface.RecordsWrite], 'dataFormat' | 'dataCid' | 'dataSize' | 'datePublished' | 'published' | 'tags'>;
+
+/**
+ * Represents the structured data model of a record, encapsulating the essential fields that define
+ * the record's metadata and payload within a Decentralized Web Node (DWN).
+ *
+ * @beta
+ */
+export type RecordModel = ImmutableRecordProperties & OptionalRecordProperties & {
+
+  /** The logical author of the record. */
+  author: string;
+
+  /** The unique identifier of the record. */
+  recordId?: string;
+
+  /** The message timestamp (time of creation, most recent update, or deletion). */
+  timestamp?: string;
+
+  /** The protocol role under which this record is written. */
+  protocolRole?: RecordOptions['protocolRole'];
+};
+
+/**
+ * Options for configuring a {@link Record} instance, extending the base `RecordsWriteMessage` with
+ * additional properties.
+ *
+ * This type combines the standard fields required for writing DWN records with additional metadata
+ * and configuration options used specifically in the {@link Record} class.
+ *
+ * @beta
+ */
+export type RecordOptions = DwnMessage[DwnInterface.RecordsWrite | DwnInterface.RecordsDelete] & {
+  /** The DID that signed the record. */
+  author: string;
+
+  /** The attestation signature(s) for the record. */
+  attestation?: DwnMessage[DwnInterface.RecordsWrite]['attestation'];
+
+  /** The encryption information for the record. */
+  encryption?: DwnMessage[DwnInterface.RecordsWrite]['encryption'];
+
+  /** The contextId associated with the record. */
+  contextId?: string;
+
+  /** The unique identifier of the record */
+  recordId?: string;
+
+  /** The DID of the DWN tenant under which record operations are being performed. */
+  connectedDid: string;
+
+  /** The optional DID that will sign the records on behalf of the connectedDid  */
+  delegateDid?: string;
+
+  /** The data of the record, either as a Base64 URL encoded string or a Blob. */
+  encodedData?: string | Blob;
+
+  /**
+   * A stream of data, conforming to the Web `ReadableStream` interface, providing a mechanism
+   * to read the record's data sequentially. This is particularly useful for handling large
+   * datasets that should not be loaded entirely in memory, allowing for efficient, chunked
+   * processing of the record's data.
+   *
+   * The DWN SDK now returns Web `ReadableStream` natively, so no conversion is needed.
+   */
+  data?: ReadableStream;
+
+  /** The initial `RecordsWriteMessage` that represents the initial state/version of the record. */
+  initialWrite?: DwnMessage[DwnInterface.RecordsWrite];
+
+  /** The protocol role under which this record is written. */
+  protocolRole?: string;
+
+  /** The remote tenant DID if the record was queried or read from a remote DWN. */
+  remoteOrigin?: string;
+};
+
+/**
+ * Parameters for updating a DWN record.
+ *
+ * This type specifies the set of properties that can be updated on an existing record. It is used
+ * to convey the new state or changes to be applied to the record.
+ *
+ * @beta
+ */
+export type RecordUpdateParams = {
+  /**
+   * The new data for the record, which can be of any type. This data will replace the existing
+   * data of the record. It's essential to ensure that this data is compatible with the record's
+   * schema or data format expectations.
+   */
+  data?: unknown;
+
+  /**
+   * The Content Identifier (CID) of the data. Updating this value changes the reference to the data
+   * associated with the record.
+   */
+  dataCid?: DwnMessageDescriptor[DwnInterface.RecordsWrite]['dataCid'];
+
+  /** Whether or not to store the updated message. */
+  store?: boolean;
+
+  /** The data format/MIME type of the supplied data */
+  dataFormat?: string;
+
+  /** The size of the data in bytes. */
+  dataSize?: DwnMessageDescriptor[DwnInterface.RecordsWrite]['dataSize'];
+
+  /** The timestamp of the update message. */
+  timestamp?: DwnMessageDescriptor[DwnInterface.RecordsWrite]['messageTimestamp'];
+
+  /** The timestamp indicating when the record was published. */
+  datePublished?: DwnMessageDescriptor[DwnInterface.RecordsWrite]['datePublished'];
+
+  /** The protocol role under which this record is written. */
+  protocolRole?: RecordOptions['protocolRole'];
+
+  /** The published status of the record. */
+  published?: DwnMessageDescriptor[DwnInterface.RecordsWrite]['published'];
+
+
+  /** The tags associated with the updated record */
+  tags?: DwnMessageDescriptor[DwnInterface.RecordsWrite]['tags'];
+
+  /**
+   * Controls whether the updated record should be auto-encrypted.
+   *
+   * If omitted, auto-detected from the original record: if the record was
+   * originally encrypted, the update is automatically re-encrypted with a
+   * fresh DEK. Set to `false` explicitly to skip encryption on the update.
+   */
+  encryption?: boolean;
+};
+
+/**
+ * Parameters for deleting a DWN record.
+ *
+ * This type specifies the set of properties that are used when deleting an existing record. It is used
+ * to convey the new state or changes to be applied to the record.
+ *
+ * @beta
+ */
+export type RecordDeleteParams = {
+  /** Whether or not to store the message. */
+  store?: boolean;
+
+  /** Whether or not to sign the delete as an owner in order to import it. */
+  signAsOwner?: boolean;
+
+  /** Whether or not to prune any children this record may have. */
+  prune?: DwnMessageDescriptor[DwnInterface.RecordsDelete]['prune'];
+
+  /** The timestamp of the delete message. */
+  timestamp?: DwnMessageDescriptor[DwnInterface.RecordsDelete]['messageTimestamp'];
+
+  /** The protocol role under which this record will be deleted. */
+  protocolRole?: string;
+};