@enbox/api 0.1.0 → 0.2.0

package/src/dwn-api.ts

@@ -8,9 +8,7 @@ import type {
   CreateGrantParams,
   CreateRequestParams,
   DwnMessage,
-  DwnMessageParams
-  ,
-  DwnMessageSubscription,
+  DwnMessageParams,
   DwnPaginationCursor,
   DwnResponse,
   DwnResponseStatus,
@@ -23,20 +21,14 @@ import {
   AgentPermissionsApi,
 } from '@enbox/agent';
 
-import { isEmptyObject } from '@enbox/common';
 import { DwnInterface, getRecordAuthor } from '@enbox/agent';
 
-import type { ProtocolDefinition } from '@enbox/dwn-sdk-js';
-
-import type { SchemaMap, TypedProtocol } from './protocol-types.js';
-
 import { dataToBlob } from './utils.js';
+import { LiveQuery } from './live-query.js';
 import { PermissionGrant } from './permission-grant.js';
 import { PermissionRequest } from './permission-request.js';
 import { Protocol } from './protocol.js';
 import { Record } from './record.js';
-import { SubscriptionUtil } from './subscription-util.js';
-import { TypedDwnApi } from './typed-dwn-api.js';
 
 /**
  * Represents the request payload for fetching permission requests from a Decentralized Web Node (DWN).
@@ -66,9 +58,7 @@ export type FetchGrantsRequest = Omit<FetchPermissionsParams, 'author' | 'target
  *
  * This request type is used to specify the configuration options for the protocol.
  */
-export type ProtocolsConfigureRequest = {
-  /** Configuration options for the protocol. */
-  message: Omit<DwnMessageParams[DwnInterface.ProtocolsConfigure], 'signer'>;
+export type ProtocolsConfigureRequest = Omit<DwnMessageParams[DwnInterface.ProtocolsConfigure], 'signer'> & {
   /** When true, derives and injects $encryption public keys into the protocol definition. */
   encryption?: boolean;
 };
@@ -94,12 +84,9 @@ export type ProtocolsConfigureResponse = DwnResponseStatus & {
  * target the local DWN. If the `from` property is provided, the query will target the specified
  * remote DWN.
  */
-export type ProtocolsQueryRequest = {
+export type ProtocolsQueryRequest = Omit<DwnMessageParams[DwnInterface.ProtocolsQuery], 'signer'> & {
   /** Optional DID specifying the remote target DWN tenant to be queried. */
   from?: string;
-
-  /** Query filters and options that influence the results returned. */
-  message: Omit<DwnMessageParams[DwnInterface.ProtocolsQuery], 'signer'>
 };
 
 /**
@@ -111,40 +98,6 @@ export type ProtocolsQueryResponse = DwnResponseStatus & {
   protocols: Protocol[];
 };
 
-/**
- * Type alias for {@link RecordsWriteRequest}
- */
-export type RecordsCreateRequest = RecordsWriteRequest;
-
-/**
- * Type alias for {@link RecordsWriteResponse}
- */
-export type RecordsCreateResponse = RecordsWriteResponse;
-
-/**
- * Represents a request to create a new record based on an existing one.
- *
- * This request type allows specifying the new data for the record, along with any additional
- * message parameters required for the write operation.
- */
-export type RecordsCreateFromRequest = {
-  /** The DID of the entity authoring the record. */
-  author: string;
-  /** The new data for the record. */
-  data: unknown;
-  /** Optional additional parameters for the record write operation */
-  message?: Omit<DwnMessageParams[DwnInterface.RecordsWrite], 'signer'>;
-  /** The existing record instance that is being used as a basis for the new record. */
-  record: Record;
-  /**
-   * Controls whether the new record should be auto-encrypted.
-   *
-   * If omitted, auto-detected from the source record: if the source record was
-   * encrypted, the new record is automatically encrypted with a fresh DEK.
-   */
-  encryption?: boolean;
-};
-
 /**
  * Defines a request to delete a record from the Decentralized Web Node (DWN).
  *
@@ -152,15 +105,12 @@ export type RecordsCreateFromRequest = {
  * message parameters for the delete operation. If the `from` property is not provided, the record
  * will be deleted from the local DWN.
  */
-export type RecordsDeleteRequest = {
+export type RecordsDeleteRequest = Omit<DwnMessageParams[DwnInterface.RecordsDelete], 'signer'> & {
   /** Optional DID specifying the remote target DWN tenant the record will be deleted from. */
   from?: string;
 
-  /** Records must be scoped to a specific protocol */
+  /** Protocol URI for permission grant resolution. */
   protocol?: string;
-
-  /** The parameters for the delete operation. */
-  message: Omit<DwnMessageParams[DwnInterface.RecordsDelete], 'signer'>;
 };
 
 /**
@@ -170,16 +120,10 @@ export type RecordsDeleteRequest = {
  * parameters, and optionally the target DWN to query from. If the `from` property is not provided,
  * the query will target the local DWN.
  */
-export type RecordsQueryRequest = {
+export type RecordsQueryRequest = Omit<DwnMessageParams[DwnInterface.RecordsQuery], 'signer'> & {
   /** Optional DID specifying the remote target DWN tenant to query from and return results. */
   from?: string;
 
-  /** Records must be scoped to a specific protocol */
-  protocol?: string;
-
-  /** The parameters for the query operation, detailing the criteria for selecting records. */
-  message: Omit<DwnMessageParams[DwnInterface.RecordsQuery], 'signer'>;
-
   /** When true, automatically decrypts encrypted records in the query results. */
   encryption?: boolean;
 };
@@ -190,7 +134,7 @@ export type RecordsQueryRequest = {
  */
 export type RecordsQueryResponse = DwnResponseStatus & {
   /** Array of records matching the query. */
-  records?: Record[]
+  records: Record[];
 
   /** If there are additional results, the messageCid of the last record will be returned as a pagination cursor. */
   cursor?: DwnPaginationCursor;
@@ -203,16 +147,13 @@ export type RecordsQueryResponse = DwnResponseStatus & {
  * additional parameters for the read operation. It's useful for fetching the details of a single
  * record by its identifier or other criteria.
  */
-export type RecordsReadRequest = {
+export type RecordsReadRequest = Omit<DwnMessageParams[DwnInterface.RecordsRead], 'signer'> & {
   /** Optional DID specifying the remote target DWN tenant the record will be read from. */
   from?: string;
 
-  /** Records must be scoped to a specific protocol */
+  /** Protocol URI for permission grant resolution. */
   protocol?: string;
 
-  /** The parameters for the read operation, detailing the criteria for selecting the record. */
-  message: Omit<DwnMessageParams[DwnInterface.RecordsRead], 'signer'>;
-
   /** When true, automatically decrypts the encrypted record data. */
   encryption?: boolean;
 };
@@ -226,39 +167,22 @@ export type RecordsReadResponse = DwnResponseStatus & {
   record: Record;
 };
 
-/** Subscription handler for Records */
-export type RecordsSubscriptionHandler = (record: Record) => void;
-
 /**
  * Represents a request to subscribe to records from a Decentralized Web Node (DWN).
  *
- * This request type is used to specify the target DWN from which records matching the subscription
- * criteria should be emitted. It's useful for being notified in real time when records are written, deleted or modified.
+ * Returns a {@link LiveQuery} that atomically provides an initial snapshot of
+ * matching records alongside a real-time stream of deduplicated, semantically-
+ * typed change events (`create`, `update`, `delete`).
  */
-export type RecordsSubscribeRequest = {
+export type RecordsSubscribeRequest = Omit<DwnMessageParams[DwnInterface.RecordsSubscribe], 'signer'> & {
   /** Optional DID specifying the remote target DWN tenant to subscribe from. */
   from?: string;
-
-  /** Records must be scoped to a specific protocol */
-  protocol?: string;
-
-  /** The parameters for the subscription operation, detailing the criteria for the subscription filter */
-  message: Omit<DwnMessageParams[DwnInterface.RecordsSubscribe], 'signer'>;
-
-  /** The handler to process the subscription events */
-  subscriptionHandler: RecordsSubscriptionHandler;
-
-  /** When true, indicates encryption is active (decryption happens on subsequent reads). */
-  encryption?: boolean;
 };
 
-/** Encapsulates the response from a DWN RecordsSubscriptionRequest */
+/** Encapsulates the response from a DWN RecordsSubscribeRequest. */
 export type RecordsSubscribeResponse = DwnResponseStatus & {
-  /**
-   * Represents the subscription that was created. Includes an ID and the close method to stop the subscription.
-   *
-   * */
-  subscription?: DwnMessageSubscription;
+  /** The live query instance, or `undefined` if the request failed. */
+  liveQuery?: LiveQuery;
 };
 
 /**
@@ -267,18 +191,11 @@ export type RecordsSubscribeResponse = DwnResponseStatus & {
  * This request type allows specifying the data for the new or updated record, along with any
  * additional message parameters required for the write operation, and an optional flag to indicate
  * whether the record should be immediately stored.
- *
- * @param data -
- * @param message - , excluding the signer.
- * @param store -
  */
-export type RecordsWriteRequest = {
+export type RecordsWriteRequest = Omit<Partial<DwnMessageParams[DwnInterface.RecordsWrite]>, 'signer' | 'data'> & {
   /** The data payload for the record, which can be of any type. */
   data: unknown;
 
-  /** Optional additional parameters for the record write operation. */
-  message?: Omit<Partial<DwnMessageParams[DwnInterface.RecordsWrite]>, 'signer'>;
-
   /**
    * Optional flag indicating whether the record should be immediately stored. If true, the record
    * is persisted in the DWN as part of the write operation. If false, the record is created,
@@ -307,7 +224,7 @@ export type RecordsWriteResponse = DwnResponseStatus & {
    * The `Record` instance representing the record that was successfully written to the
    * DWN as a result of the write operation.
    */
-  record?: Record
+  record: Record;
 };
 
 /**
@@ -336,30 +253,6 @@ export class DwnApi {
     this.permissionsApi = new AgentPermissionsApi({ agent: this.agent });
   }
 
-  /**
-   * Returns a {@link TypedDwnApi} scoped to the given typed protocol.
-   *
-   * The returned API provides path autocompletion, typed data payloads,
-   * and automatically injects the protocol URI and protocolPath into every
-   * DWN operation.
-   *
-   * @param protocol - A typed protocol created via `defineProtocol()`.
-   * @returns A `TypedDwnApi` instance bound to the given protocol.
-   *
-   * @example
-   * ```ts
-   * const social = dwn.using(SocialGraphProtocol);
-   * const { record } = await social.write('friend', {
-   *   data: { did: 'did:example:alice' },
-   * });
-   * ```
-   */
-  public using<D extends ProtocolDefinition, M extends SchemaMap>(
-    protocol: TypedProtocol<D, M>,
-  ): TypedDwnApi<D, M> {
-    return new TypedDwnApi<D, M>(this, protocol);
-  }
-
   /**
    * API to interact with Grants
    *
@@ -485,20 +378,21 @@ export class DwnApi {
        * Configure method, used to setup a new protocol (or update) with the passed definitions
        */
       configure: async (request: ProtocolsConfigureRequest): Promise<ProtocolsConfigureResponse> => {
-
-        const agentRequest:ProcessDwnRequest<DwnInterface.ProtocolsConfigure> = {
-          author        : this.connectedDid,
-          messageParams : request.message,
-          messageType   : DwnInterface.ProtocolsConfigure,
-          target        : this.connectedDid,
-          encryption    : request.encryption,
+        const { encryption, ...messageParams } = request;
+
+        const agentRequest: ProcessDwnRequest<DwnInterface.ProtocolsConfigure> = {
+          author      : this.connectedDid,
+          messageParams,
+          messageType : DwnInterface.ProtocolsConfigure,
+          target      : this.connectedDid,
+          encryption,
         };
 
         if (this.delegateDid) {
           const { message: delegatedGrant } = await this.permissionsApi.getPermissionForRequest({
             connectedDid : this.connectedDid,
             delegateDid  : this.delegateDid,
-            protocol     : request.message.definition.protocol,
+            protocol     : messageParams.definition.protocol,
             delegate     : true,
             cached       : true,
             messageType  : agentRequest.messageType
@@ -528,11 +422,13 @@ export class DwnApi {
        * Query the available protocols
        */
       query: async (request: ProtocolsQueryRequest): Promise<ProtocolsQueryResponse> => {
+        const { from, ...messageParams } = request;
+
         const agentRequest: ProcessDwnRequest<DwnInterface.ProtocolsQuery> = {
-          author        : this.connectedDid,
-          messageParams : request.message,
-          messageType   : DwnInterface.ProtocolsQuery,
-          target        : request.from || this.connectedDid
+          author      : this.connectedDid,
+          messageParams,
+          messageType : DwnInterface.ProtocolsQuery,
+          target      : from || this.connectedDid,
         };
 
         if (this.delegateDid) {
@@ -543,7 +439,7 @@ export class DwnApi {
             const { grant: { id: permissionGrantId } } = await this.permissionsApi.getPermissionForRequest({
               connectedDid : this.connectedDid,
               delegateDid  : this.delegateDid,
-              protocol     : request.message.filter.protocol,
+              protocol     : messageParams.filter.protocol,
               cached       : true,
               messageType  : agentRequest.messageType
             });
@@ -561,7 +457,7 @@ export class DwnApi {
 
         let agentResponse: DwnResponse<DwnInterface.ProtocolsQuery>;
 
-        if (request.from) {
+        if (from) {
           agentResponse = await this.agent.sendDwnRequest(agentRequest);
         } else {
           agentResponse = await this.agent.processDwnRequest(agentRequest);
@@ -581,11 +477,9 @@ export class DwnApi {
   }
 
   /**
-   * API to interact with DWN records (e.g., `dwn.records.create()`).
+   * API to interact with DWN records (e.g., `dwn.records.write()`).
    */
   get records(): {
-      create: (request: RecordsCreateRequest) => Promise<RecordsCreateResponse>;
-      createFrom: (request: RecordsCreateFromRequest) => Promise<RecordsWriteResponse>;
       delete: (request: RecordsDeleteRequest) => Promise<DwnResponseStatus>;
       query: (request: RecordsQueryRequest) => Promise<RecordsQueryResponse>;
       read: (request: RecordsReadRequest) => Promise<RecordsReadResponse>;
@@ -594,77 +488,33 @@ export class DwnApi {
       } {
 
     return {
-      /**
-       * Alias for the `write` method
-       */
-      create: async (request: RecordsCreateRequest): Promise<RecordsCreateResponse> => {
-        return this.records.write(request);
-      },
-
-      /**
-       * Write a record based on an existing one (useful for updating an existing record)
-       */
-      createFrom: async (request: RecordsCreateFromRequest): Promise<RecordsWriteResponse> => {
-        const { author: inheritedAuthor, ...inheritedProperties } = request.record.toJSON();
-
-        // If `data` is being updated then `dataCid` and `dataSize` must not be present.
-        if (request.data !== undefined) {
-          delete inheritedProperties.dataCid;
-          delete inheritedProperties.dataSize;
-        }
-
-        // If `published` is set to false, ensure that `datePublished` is undefined. Otherwise, DWN SDK's schema validation
-        // will throw an error if `published` is false but `datePublished` is set.
-        if (request.message?.published === false && inheritedProperties.datePublished !== undefined) {
-          delete inheritedProperties.datePublished;
-          delete inheritedProperties.published;
-        }
-
-        // If the request changes the `author` or message `descriptor` then the deterministic `recordId` will change.
-        // As a result, we will discard the `recordId` if either of these changes occur.
-        if (!isEmptyObject(request.message) || (request.author && request.author !== inheritedAuthor)) {
-          delete inheritedProperties.recordId;
-        }
-
-        // Auto-detect encryption from the source record if not explicitly set.
-        const shouldEncrypt = request.encryption
-          ?? (request.record.encryption !== undefined);
-
-        return this.records.write({
-          data    : request.data,
-          message : {
-            ...inheritedProperties,
-            ...request.message,
-          },
-          encryption: shouldEncrypt || undefined,
-        });
-      },
-
       /**
        * Delete a record
        */
       delete: async (request: RecordsDeleteRequest): Promise<DwnResponseStatus> => {
+        const { from, protocol, ...messageParams } = request;
+
         const agentRequest: ProcessDwnRequest<DwnInterface.RecordsDelete> = {
           /**
            * The `author` is the DID that will sign the message and must be the DID the Web5 app is
            * connected with and is authorized to access the signing private key of.
            */
-          author        : this.connectedDid,
-          messageParams : request.message,
-          messageType   : DwnInterface.RecordsDelete,
+          author      : this.connectedDid,
+          messageParams,
+          messageType : DwnInterface.RecordsDelete,
           /**
            * The `target` is the DID of the DWN tenant under which the delete will be executed.
            * If `from` is provided, the delete operation will be executed on a remote DWN.
            * Otherwise, the record will be deleted on the local DWN.
            */
-          target        : request.from || this.connectedDid
+          target      : from || this.connectedDid,
         };
 
         if (this.delegateDid) {
           const { message: delegatedGrant } = await this.permissionsApi.getPermissionForRequest({
             connectedDid : this.connectedDid,
             delegateDid  : this.delegateDid,
-            protocol     : request.protocol,
+            protocol,
             delegate     : true,
             cached       : true,
             messageType  : agentRequest.messageType
@@ -679,7 +529,7 @@ export class DwnApi {
 
         let agentResponse: DwnResponse<DwnInterface.RecordsDelete>;
 
-        if (request.from) {
+        if (from) {
           agentResponse = await this.agent.sendDwnRequest(agentRequest);
         } else {
           agentResponse = await this.agent.processDwnRequest(agentRequest);
@@ -689,39 +539,41 @@ export class DwnApi {
 
         return { status };
       },
+
       /**
        * Query a single or multiple records based on the given filter
        */
       query: async (request: RecordsQueryRequest): Promise<RecordsQueryResponse> => {
+        const { from, encryption, ...messageParams } = request;
+
         const agentRequest: ProcessDwnRequest<DwnInterface.RecordsQuery> = {
           /**
            * The `author` is the DID that will sign the message and must be the DID the Web5 app is
            * connected with and is authorized to access the signing private key of.
            */
-          author        : this.connectedDid,
-          messageParams : request.message,
-          messageType   : DwnInterface.RecordsQuery,
+          author      : this.connectedDid,
+          messageParams,
+          messageType : DwnInterface.RecordsQuery,
           /**
            * The `target` is the DID of the DWN tenant under which the query will be executed.
            * If `from` is provided, the query operation will be executed on a remote DWN.
            * Otherwise, the local DWN will be queried.
            */
-          target        : request.from || this.connectedDid,
-          encryption    : request.encryption,
+          target      : from || this.connectedDid,
+          encryption,
         };
 
         if (this.delegateDid) {
           // if we don't find a delegated grant, we will attempt to query signing as the delegated DID
           // This is to allow the API caller to query public records without needing to impersonate the delegate.
           //
-          // NOTE: When a read-only DwnApi is implemented, callers should use that instead when they don't have an explicit permission.
-          // This should fail if a permission is not found.
-          // TODO: https://github.com/enboxorg/enbox/issues/898
+          // NOTE: For anonymous/public queries without explicit permissions, callers can use `DwnReaderApi` via `Web5.anonymous()`.
+          // See: https://github.com/enboxorg/enbox/issues/898
           try {
             const { message: delegatedGrant } = await this.permissionsApi.getPermissionForRequest({
               connectedDid : this.connectedDid,
               delegateDid  : this.delegateDid,
-              protocol     : request.protocol,
+              protocol     : messageParams.filter?.protocol,
               delegate     : true,
               cached       : true,
               messageType  : agentRequest.messageType
@@ -738,10 +590,9 @@ export class DwnApi {
           }
         }
 
-
         let agentResponse: DwnResponse<DwnInterface.RecordsQuery>;
 
-        if (request.from) {
+        if (from) {
           agentResponse = await this.agent.sendDwnRequest(agentRequest);
         } else {
           agentResponse = await this.agent.processDwnRequest(agentRequest);
@@ -751,7 +602,6 @@ export class DwnApi {
         const { entries = [], status, cursor } = reply;
 
         const records = entries.map((entry) => {
-
           const recordOptions = {
             /**
              * Extract the `author` DID from the record entry since records may be signed by the
@@ -770,7 +620,7 @@ export class DwnApi {
              * to determine which DWN to send subsequent read requests to in the event the data
              * payload exceeds the threshold for being returned with queries.
              */
-            remoteOrigin : request.from,
+            remoteOrigin : from,
             delegateDid  : this.delegateDid,
             protocolRole : agentRequest.messageParams.protocolRole,
             ...entry as DwnMessage[DwnInterface.RecordsWrite]
@@ -786,35 +636,37 @@ export class DwnApi {
        * Read a single record based on the given filter
        */
       read: async (request: RecordsReadRequest): Promise<RecordsReadResponse> => {
+        const { from, protocol, encryption, ...messageParams } = request;
+
         const agentRequest: ProcessDwnRequest<DwnInterface.RecordsRead> = {
           /**
            * The `author` is the DID that will sign the message and must be the DID the Web5 app is
            * connected with and is authorized to access the signing private key of.
            */
-          author        : this.connectedDid,
-          messageParams : request.message,
-          messageType   : DwnInterface.RecordsRead,
+          author      : this.connectedDid,
+          messageParams,
+          messageType : DwnInterface.RecordsRead,
           /**
            * The `target` is the DID of the DWN tenant under which the read will be executed.
            * If `from` is provided, the read operation will be executed on a remote DWN.
            * Otherwise, the read will occur on the local DWN.
            */
-          target        : request.from || this.connectedDid,
-          encryption    : request.encryption,
+          target      : from || this.connectedDid,
+          encryption,
         };
+
         if (this.delegateDid) {
           // if we don't find a delegated grant, we will attempt to read signing as the delegated DID
           // This is to allow the API caller to read public records without needing to impersonate the delegate.
           //
-          // NOTE: When a read-only DwnApi is implemented, callers should use that instead when they don't have an explicit permission.
-          // This should fail if a permission is not found.
-          // TODO: https://github.com/enboxorg/enbox/issues/898
+          // NOTE: For anonymous/public reads without explicit permissions, callers can use `DwnReaderApi` via `Web5.anonymous()`.
+          // See: https://github.com/enboxorg/enbox/issues/898
 
           try {
             const { message: delegatedGrant } = await this.permissionsApi.getPermissionForRequest({
               connectedDid : this.connectedDid,
               delegateDid  : this.delegateDid,
-              protocol     : request.protocol,
+              protocol,
               delegate     : true,
               cached       : true,
               messageType  : agentRequest.messageType
@@ -833,7 +685,7 @@ export class DwnApi {
 
         let agentResponse: DwnResponse<DwnInterface.RecordsRead>;
 
-        if (request.from) {
+        if (from) {
           agentResponse = await this.agent.sendDwnRequest(agentRequest);
         } else {
           agentResponse = await this.agent.processDwnRequest(agentRequest);
@@ -861,7 +713,7 @@ export class DwnApi {
              * to determine which DWN to send subsequent read requests to in the event the data
              * payload must be read again (e.g., if the data stream is consumed).
              */
-            remoteOrigin : request.from,
+            remoteOrigin : from,
             delegateDid  : this.delegateDid,
             data         : entry.data,
             initialWrite : entry.initialWrite,
@@ -875,52 +727,61 @@ export class DwnApi {
       },
 
       /**
-       * Subscribes to records based on the given filter and emits events to the `subscriptionHandler`.
+       * Subscribe to records matching the given filter.
        *
-       * @param request must include the `message` with the subscription filter and the `subscriptionHandler` to process the events.
-       * @returns the subscription status and the subscription object used to close the subscription.
+       * Returns a {@link LiveQuery} that atomically provides an initial snapshot
+       * of matching records and a real-time stream of deduplicated, semantically-
+       * typed change events (`create`, `update`, `delete`).
        */
       subscribe: async (request: RecordsSubscribeRequest): Promise<RecordsSubscribeResponse> => {
-        const agentRequest: ProcessDwnRequest<DwnInterface.RecordsSubscribe> = {
-          /**
-           * The `author` is the DID that will sign the message and must be the DID the Web5 app is
-           * connected with and is authorized to access the signing private key of.
-           */
-          author        : this.connectedDid,
-          messageParams : request.message,
-          messageType   : DwnInterface.RecordsSubscribe,
-          /**
-           * The `target` is the DID of the DWN tenant under which the subscribe operation will be executed.
-           * If `from` is provided, the subscribe operation will be executed on a remote DWN.
-           * Otherwise, the local DWN will execute the subscribe operation.
-           */
-          target        : request.from || this.connectedDid,
+        const { from, ...messageParams } = request;
 
-          /**
-           * The handler to process the subscription events.
-           */
-          subscriptionHandler: SubscriptionUtil.recordSubscriptionHandler({
-            agent          : this.agent,
-            connectedDid   : this.connectedDid,
-            delegateDid    : this.delegateDid,
-            permissionsApi : this.permissionsApi,
-            protocolRole   : request.message.protocolRole,
-            request
-          })
+        // Build a DWN-level subscription handler that wraps raw RecordEvents
+        // into Record objects and feeds them into the LiveQuery.
+        let liveQuery: LiveQuery | undefined;
+
+        const remoteOrigin = from;
+        const protocolRole = messageParams.protocolRole;
+
+        type RecordEvent = {
+          message: DwnMessage[DwnInterface.RecordsWrite];
+          initialWrite?: DwnMessage[DwnInterface.RecordsWrite];
+        };
+
+        const subscriptionHandler = async (event: RecordEvent): Promise<void> => {
+          const { message, initialWrite } = event;
+          const record = new Record(this.agent, {
+            ...message,
+            author       : getRecordAuthor(message),
+            connectedDid : this.connectedDid,
+            remoteOrigin,
+            initialWrite,
+            protocolRole,
+            delegateDid  : this.delegateDid,
+          }, this.permissionsApi);
+
+          liveQuery?.handleEvent(record);
+        };
+
+        const agentRequest: ProcessDwnRequest<DwnInterface.RecordsSubscribe> = {
+          author      : this.connectedDid,
+          messageParams,
+          messageType : DwnInterface.RecordsSubscribe,
+          target      : from || this.connectedDid,
+          subscriptionHandler,
         };
 
         if (this.delegateDid) {
           // if we don't find a delegated grant, we will attempt to subscribe signing as the delegated DID
           // This is to allow the API caller to subscribe to public records without needing to impersonate the delegate.
           //
-          // NOTE: When a read-only DwnApi is implemented, callers should use that instead when they don't have an explicit permission.
-          // This should fail if a permission is not found.
-          // TODO: https://github.com/enboxorg/enbox/issues/898
+          // NOTE: For anonymous/public subscriptions without explicit permissions, callers can use `DwnReaderApi` via `Web5.anonymous()`.
+          // See: https://github.com/enboxorg/enbox/issues/898
           try {
             const { message: delegatedGrant } = await this.permissionsApi.getPermissionForRequest({
               connectedDid : this.connectedDid,
               delegateDid  : this.delegateDid,
-              protocol     : request.protocol,
+              protocol     : messageParams.filter?.protocol,
               delegate     : true,
               cached       : true,
               messageType  : agentRequest.messageType
@@ -939,16 +800,30 @@ export class DwnApi {
 
         let agentResponse: DwnResponse<DwnInterface.RecordsSubscribe>;
 
-        if (request.from) {
+        if (from) {
           agentResponse = await this.agent.sendDwnRequest(agentRequest);
         } else {
           agentResponse = await this.agent.processDwnRequest(agentRequest);
         }
 
         const reply = agentResponse.reply;
-        const { status, subscription } = reply;
+        const { status, subscription, entries = [], cursor } = reply;
+
+        if (subscription) {
+          liveQuery = new LiveQuery({
+            agent          : this.agent,
+            connectedDid   : this.connectedDid,
+            delegateDid    : this.delegateDid,
+            protocolRole,
+            remoteOrigin,
+            permissionsApi : this.permissionsApi,
+            initialEntries : entries,
+            cursor,
+            subscription,
+          });
+        }
 
-        return { status, subscription };
+        return { status, liveQuery };
       },
 
       /**
@@ -961,19 +836,19 @@ export class DwnApi {
        * requires fetching from the DWN datastore.
        */
       write: async (request: RecordsWriteRequest): Promise<RecordsWriteResponse> => {
-        const { dataBlob, dataFormat } = dataToBlob(request.data, request.message?.dataFormat);
+        const { data, store, encryption, ...restParams } = request;
+        const { dataBlob, dataFormat } = dataToBlob(data, restParams.dataFormat);
+
+        const messageParams = { ...restParams, dataFormat };
 
         const dwnRequestParams: ProcessDwnRequest<DwnInterface.RecordsWrite> = {
-          store         : request.store,
-          messageType   : DwnInterface.RecordsWrite,
-          messageParams : {
-            ...request.message,
-            dataFormat
-          },
-          author     : this.connectedDid,
-          target     : this.connectedDid,
-          dataStream : dataBlob,
-          encryption : request.encryption,
+          store,
+          messageType : DwnInterface.RecordsWrite,
+          messageParams,
+          author      : this.connectedDid,
+          target      : this.connectedDid,
+          dataStream  : dataBlob,
+          encryption,
         };
 
         // if impersonation is enabled, fetch the delegated grant to use with the write operation
@@ -981,7 +856,7 @@ export class DwnApi {
           const { message: delegatedGrant } = await this.permissionsApi.getPermissionForRequest({
             connectedDid : this.connectedDid,
             delegateDid  : this.delegateDid,
-            protocol     : request.message.protocol,
+            protocol     : messageParams.protocol,
             delegate     : true,
             cached       : true,
             messageType  : dwnRequestParams.messageType