@enbox/api 0.1.0 → 0.1.1

package/dist/types/typed-dwn-api.d.ts

@@ -7,11 +7,12 @@
  * Every method delegates to the corresponding `dwn.records.*` method,
  * injecting the protocol URI, protocolPath, and schema automatically.
  */
+import type { DwnApi } from './dwn-api.js';
+import type { LiveQuery } from './live-query.js';
 import type { Protocol } from './protocol.js';
 import type { Record } from './record.js';
 import type { DateSort, ProtocolDefinition, ProtocolType, RecordsFilter } from '@enbox/dwn-sdk-js';
-import type { DwnApi, RecordsSubscriptionHandler } from './dwn-api.js';
-import type { DwnMessageSubscription, DwnPaginationCursor, DwnResponseStatus } from '@enbox/agent';
+import type { DwnPaginationCursor, DwnResponseStatus } from '@enbox/agent';
 import type { ProtocolPaths, SchemaMap, TypedProtocol, TypeNameAtPath } from './protocol-types.js';
 /**
  * Resolves the TypeScript data type for a given protocol path.
@@ -104,13 +105,11 @@ export type TypedSubscribeRequest = {
     /** Subscription filter (protocol, protocolPath, schema are injected). */
     filter?: TypedQueryFilter;
     protocolRole?: string;
-    subscriptionHandler: RecordsSubscriptionHandler;
-    /** When true, indicates encryption is active. */
-    encryption?: boolean;
 };
 /** Response from `TypedDwnApi.subscribe()`. */
 export type TypedSubscribeResponse = DwnResponseStatus & {
-    subscription?: DwnMessageSubscription;
+    /** The live query instance, or `undefined` if the request failed. */
+    liveQuery?: LiveQuery;
 };
 /**
  * A protocol-scoped wrapper around `DwnApi` that automatically injects
@@ -182,10 +181,13 @@ export declare class TypedDwnApi<D extends ProtocolDefinition = ProtocolDefiniti
     /**
      * Subscribe to records at the given protocol path.
      *
+     * Returns a {@link LiveQuery} that atomically provides an initial snapshot
+     * and a real-time stream of deduplicated change events.
+     *
      * @param path - The protocol path to subscribe to.
-     * @param request - Subscribe options including the subscription handler.
+     * @param request - Subscribe options including optional filter and role.
      */
-    subscribe<Path extends ProtocolPaths<D> & string>(path: Path, request: TypedSubscribeRequest): Promise<TypedSubscribeResponse>;
+    subscribe<Path extends ProtocolPaths<D> & string>(path: Path, request?: TypedSubscribeRequest): Promise<TypedSubscribeResponse>;
 }
 export {};
 //# sourceMappingURL=typed-dwn-api.d.ts.map

package/dist/types/typed-dwn-api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"typed-dwn-api.d.ts","sourceRoot":"","sources":["../../src/typed-dwn-api.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"typed-dwn-api.d.ts","sourceRoot":"","sources":["../../src/typed-dwn-api.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enbox/api",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "SDK for accessing the features and capabilities of Web5",
   "type": "module",
   "main": "./dist/esm/index.js",
@@ -77,14 +77,14 @@
     "bun": ">=1.0.0"
   },
   "dependencies": {
-    "@enbox/agent": "0.1.4",
+    "@enbox/agent": "0.1.5",
     "@enbox/common": "0.0.3",
-    "@enbox/dwn-clients": "0.0.2"
+    "@enbox/dwn-clients": "0.0.3"
   },
   "devDependencies": {
-    "@enbox/crypto": "0.0.3",
-    "@enbox/dids": "0.0.3",
-    "@enbox/dwn-sdk-js": "0.0.5",
+    "@enbox/crypto": "0.0.4",
+    "@enbox/dids": "0.0.4",
+    "@enbox/dwn-sdk-js": "0.0.6",
     "@types/node": "20.14.8",
     "@types/sinon": "17.0.3",
     "@typescript-eslint/eslint-plugin": "8.32.1",

package/src/dwn-api.ts

@@ -8,9 +8,7 @@ import type {
   CreateGrantParams,
   CreateRequestParams,
   DwnMessage,
-  DwnMessageParams
-  ,
-  DwnMessageSubscription,
+  DwnMessageParams,
   DwnPaginationCursor,
   DwnResponse,
   DwnResponseStatus,
@@ -31,11 +29,11 @@ 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';
 
 /**
@@ -226,39 +224,28 @@ 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 = {
   /** Optional DID specifying the remote target DWN tenant to subscribe from. */
   from?: string;
 
-  /** Records must be scoped to a specific protocol */
+  /** Records must be scoped to a specific protocol. */
   protocol?: string;
 
-  /** The parameters for the subscription operation, detailing the criteria for the subscription filter */
+  /** 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;
 };
 
 /**
@@ -689,6 +676,7 @@ export class DwnApi {
 
         return { status };
       },
+
       /**
        * Query a single or multiple records based on the given filter
        */
@@ -875,38 +863,46 @@ 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> => {
+        // 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 = request.from;
+        const protocolRole = request.message.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> = {
-          /**
-           * 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,
-
-          /**
-           * 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
-          })
+          subscriptionHandler,
         };
 
         if (this.delegateDid) {
@@ -946,9 +942,22 @@ export class DwnApi {
         }
 
         const reply = agentResponse.reply;
-        const { status, subscription } = reply;
+        const { status, subscription, entries = [] } = reply;
+
+        if (subscription) {
+          liveQuery = new LiveQuery({
+            agent          : this.agent,
+            connectedDid   : this.connectedDid,
+            delegateDid    : this.delegateDid,
+            protocolRole,
+            remoteOrigin,
+            permissionsApi : this.permissionsApi,
+            initialEntries : entries,
+            subscription,
+          });
+        }
 
-        return { status, subscription };
+        return { status, liveQuery };
       },
 
       /**

package/src/index.ts

@@ -25,6 +25,7 @@ export * from './define-protocol.js';
 export * from './did-api.js';
 export * from './dwn-api.js';
 export * from './grant-revocation.js';
+export * from './live-query.js';
 export * from './permission-grant.js';
 export * from './permission-request.js';
 export * from './protocol.js';

package/src/live-query.ts

@@ -0,0 +1,245 @@
+import type { RecordsQueryReplyEntry } from '@enbox/dwn-sdk-js';
+import type { DwnMessageSubscription, PermissionsApi, Web5Agent } from '@enbox/agent';
+
+import { getRecordAuthor } from '@enbox/agent';
+
+import { Record } from './record.js';
+
+/**
+ * The type of change that occurred to a record.
+ */
+export type RecordChangeType = 'create' | 'update' | 'delete';
+
+/**
+ * Describes a change to a record in a {@link LiveQuery}.
+ */
+export type RecordChange = {
+  /** Whether the record was created, updated, or deleted. */
+  type: RecordChangeType;
+
+  /** The record affected by the change. */
+  record: Record;
+};
+
+/**
+ * A `CustomEvent` subclass carrying a {@link RecordChange} as its `detail`.
+ *
+ * Dispatched on the {@link LiveQuery} `EventTarget` for both the specific
+ * change-type event (`create`, `update`, `delete`) and the catch-all `change`
+ * event.
+ */
+export class RecordChangeEvent extends CustomEvent<RecordChange> {
+  constructor(change: RecordChange) {
+    super(change.type, { detail: change });
+  }
+}
+
+/**
+ * Options for creating a {@link LiveQuery}.
+ * @internal — Constructed by `DwnApi.records.subscribe()`, not by end users.
+ */
+export type LiveQueryOptions = {
+  /** The agent instance used to construct Record objects. */
+  agent: Web5Agent;
+
+  /** The DID of the connected user. */
+  connectedDid: string;
+
+  /** Optional delegate DID for permission-delegated access. */
+  delegateDid?: string;
+
+  /** Optional protocol role for role-authorized access. */
+  protocolRole?: string;
+
+  /** Optional remote DWN origin if subscribing to a remote DWN. */
+  remoteOrigin?: string;
+
+  /** The permissions API instance for constructing Record objects. */
+  permissionsApi?: PermissionsApi;
+
+  /** The initial snapshot entries from the subscribe reply. */
+  initialEntries: RecordsQueryReplyEntry[];
+
+  /** The underlying DWN subscription handle. */
+  subscription: DwnMessageSubscription;
+};
+
+/**
+ * A live query that combines an initial snapshot of matching records with a
+ * real-time stream of deduplicated, semantically-typed change events.
+ *
+ * `LiveQuery` extends `EventTarget` so that standard `addEventListener` /
+ * `removeEventListener` work out of the box. For convenience, the typed
+ * {@link LiveQuery.on | `.on()`} method provides a cleaner API that returns an
+ * unsubscribe function.
+ *
+ * ### Events
+ *
+ * | Event name | `detail` type | Description |
+ * |---|---|---|
+ * | `create` | {@link RecordChange} | A new record was written |
+ * | `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 |
+ *
+ * @example
+ * ```ts
+ * const { liveQuery } = await dwn.records.subscribe({
+ *   message: {
+ *     filter: {
+ *       protocol     : chatProtocol.protocol,
+ *       protocolPath : 'thread/message',
+ *     }
+ *   }
+ * });
+ *
+ * // Initial state
+ * for (const record of liveQuery.records) {
+ *   renderMessage(record);
+ * }
+ *
+ * // Real-time changes
+ * liveQuery.on('create', (record) => appendMessage(record));
+ * 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}`);
+ * });
+ *
+ * // Cleanup
+ * await liveQuery.close();
+ * ```
+ */
+export class LiveQuery extends EventTarget {
+  /** The initial snapshot of matching records. */
+  readonly records: Record[];
+
+  /** The underlying DWN subscription handle. */
+  private _subscription: DwnMessageSubscription;
+
+  /** Tracks known record states for dedup and change-type classification. */
+  private _knownRecords: Map<string, string>;
+
+  /** Whether the live query has been closed. */
+  private _closed = false;
+
+  constructor(options: LiveQueryOptions) {
+    super();
+
+    const {
+      agent,
+      connectedDid,
+      delegateDid,
+      protocolRole,
+      remoteOrigin,
+      permissionsApi,
+      initialEntries,
+      subscription,
+    } = options;
+
+    this._subscription = subscription;
+
+    // Build Record objects from the initial snapshot entries (same logic as records.query()).
+    this.records = initialEntries.map((entry) => new Record(agent, {
+      author: getRecordAuthor(entry),
+      connectedDid,
+      remoteOrigin,
+      delegateDid,
+      protocolRole,
+      ...entry,
+    }, permissionsApi));
+
+    // Seed the known-records map with recordId -> messageTimestamp for dedup.
+    this._knownRecords = new Map();
+    for (const record of this.records) {
+      this._knownRecords.set(record.id, record.dateModified);
+    }
+  }
+
+  /**
+   * Process an incoming live event from the DWN subscription.
+   * Deduplicates against the initial snapshot and classifies the change type.
+   *
+   * @internal — Called by `DwnApi.records.subscribe()` when wiring up the subscription handler.
+   */
+  public handleEvent(record: Record): void {
+    if (this._closed) {
+      return;
+    }
+
+    let changeType: RecordChangeType;
+
+    if (record.deleted) {
+      changeType = 'delete';
+      this._knownRecords.delete(record.id);
+    } else {
+      const knownTimestamp = this._knownRecords.get(record.id);
+
+      if (knownTimestamp !== undefined) {
+        // We've seen this recordId before (either from snapshot or a prior event).
+        if (record.dateModified <= knownTimestamp) {
+          // Duplicate or stale event from the overlap window — skip.
+          return;
+        }
+        changeType = 'update';
+      } else {
+        changeType = 'create';
+      }
+
+      // Update the known state.
+      this._knownRecords.set(record.id, record.dateModified);
+    }
+
+    const change: RecordChange = { type: changeType, record };
+
+    // Dispatch the specific event (create/update/delete).
+    this.dispatchEvent(new RecordChangeEvent(change));
+
+    // Dispatch the catch-all change event.
+    this.dispatchEvent(new CustomEvent('change', { detail: change }));
+  }
+
+  /**
+   * Register a typed event handler. Returns an unsubscribe function.
+   *
+   * @param event - The event type to listen for.
+   * @param handler - The handler function.
+   * @returns A function that removes the handler when called.
+   *
+   * @example
+   * ```ts
+   * const off = live.on('create', (record) => console.log(record.id));
+   * off(); // stop listening
+   * ```
+   */
+  on(event: 'change', handler: (change: RecordChange) => void): () => void;
+  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 {
+    const wrapper = (e: Event): void => {
+      const detail = (e as CustomEvent<RecordChange>).detail;
+      if (event === 'change') {
+        (handler as (change: RecordChange) => void)(detail);
+      } else {
+        (handler as (record: Record) => void)(detail.record);
+      }
+    };
+
+    this.addEventListener(event, wrapper);
+    return (): void => { this.removeEventListener(event, wrapper); };
+  }
+
+  /**
+   * Close the underlying subscription and stop dispatching events.
+   */
+  async close(): Promise<void> {
+    if (this._closed) {
+      return;
+    }
+    this._closed = true;
+    await this._subscription.close();
+  }
+}

package/src/typed-dwn-api.ts

@@ -8,11 +8,13 @@
  * injecting the protocol URI, protocolPath, and schema automatically.
  */
 
+import type { DwnApi } from './dwn-api.js';
+import type { LiveQuery } from './live-query.js';
 import type { Protocol } from './protocol.js';
 import type { Record } from './record.js';
+
 import type { DateSort, ProtocolDefinition, ProtocolType, RecordsFilter } from '@enbox/dwn-sdk-js';
-import type { DwnApi, RecordsSubscriptionHandler } from './dwn-api.js';
-import type { DwnMessageSubscription, DwnPaginationCursor, DwnResponseStatus } from '@enbox/agent';
+import type { DwnPaginationCursor, DwnResponseStatus } from '@enbox/agent';
 import type { ProtocolPaths, SchemaMap, TypedProtocol, TypeNameAtPath } from './protocol-types.js';
 
 // ---------------------------------------------------------------------------
@@ -151,15 +153,12 @@ export type TypedSubscribeRequest = {
   /** Subscription filter (protocol, protocolPath, schema are injected). */
   filter? : TypedQueryFilter;
   protocolRole? : string;
-  subscriptionHandler : RecordsSubscriptionHandler;
-
-  /** When true, indicates encryption is active. */
-  encryption?: boolean;
 };
 
 /** Response from `TypedDwnApi.subscribe()`. */
 export type TypedSubscribeResponse = DwnResponseStatus & {
-  subscription?: DwnMessageSubscription;
+  /** The live query instance, or `undefined` if the request failed. */
+  liveQuery?: LiveQuery;
 };
 
 // ---------------------------------------------------------------------------
@@ -329,29 +328,30 @@ export class TypedDwnApi<
   /**
    * Subscribe to records at the given protocol path.
    *
+   * Returns a {@link LiveQuery} that atomically provides an initial snapshot
+   * and a real-time stream of deduplicated change events.
+   *
    * @param path - The protocol path to subscribe to.
-   * @param request - Subscribe options including the subscription handler.
+   * @param request - Subscribe options including optional filter and role.
    */
   public async subscribe<Path extends ProtocolPaths<D> & string>(
     path : Path,
-    request : TypedSubscribeRequest,
+    request? : TypedSubscribeRequest,
   ): Promise<TypedSubscribeResponse> {
     const typeName = lastSegment(path);
     const typeEntry = this._definition.types[typeName] as ProtocolType | undefined;
 
     return this._dwn.records.subscribe({
-      from                : request.from,
-      protocol            : this._definition.protocol,
-      encryption          : request.encryption,
-      subscriptionHandler : request.subscriptionHandler,
-      message             : {
+      from     : request?.from,
+      protocol : this._definition.protocol,
+      message  : {
         filter: {
-          ...request.filter,
+          ...request?.filter,
           protocol     : this._definition.protocol,
           protocolPath : path,
           schema       : typeEntry?.schema,
         },
-        protocolRole: request.protocolRole,
+        protocolRole: request?.protocolRole,
       },
     });
   }

package/dist/esm/subscription-util.js

@@ -1,35 +0,0 @@
-var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
-    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
-    return new (P || (P = Promise))(function (resolve, reject) {
-        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
-        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
-        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
-        step((generator = generator.apply(thisArg, _arguments || [])).next());
-    });
-};
-import { getRecordAuthor } from '@enbox/agent';
-import { Record } from './record.js';
-/**
- * Utility class for dealing with subscriptions.
- */
-export class SubscriptionUtil {
-    /**
-     * Creates a record subscription handler that can be used to process incoming {Record} messages.
-     */
-    static recordSubscriptionHandler({ agent, connectedDid, request, delegateDid, protocolRole, permissionsApi }) {
-        const { subscriptionHandler, from: remoteOrigin } = request;
-        return (event) => __awaiter(this, void 0, void 0, function* () {
-            const { message, initialWrite } = event;
-            const author = getRecordAuthor(message);
-            const recordOptions = {
-                author,
-                connectedDid,
-                remoteOrigin,
-                initialWrite
-            };
-            const record = new Record(agent, Object.assign(Object.assign(Object.assign({}, message), recordOptions), { protocolRole, delegateDid: delegateDid }), permissionsApi);
-            subscriptionHandler(record);
-        });
-    }
-}
-//# sourceMappingURL=subscription-util.js.map

package/dist/esm/subscription-util.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"subscription-util.js","sourceRoot":"","sources":["../../src/subscription-util.ts"],"names":[],"mappings":";;;;;;;;;AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAG/C,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAGrC;;GAEG;AACH,MAAM,OAAO,gBAAgB;IAC3B;;OAEG;IACH,MAAM,CAAC,yBAAyB,CAAC,EAAE,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,cAAc,EAOzG;QACC,MAAM,EAAE,mBAAmB,EAAE,IAAI,EAAE,YAAY,EAAE,GAAG,OAAO,CAAC;QAE5D,OAAO,CAAO,KAAK,EAAE,EAAE;YACrB,MAAM,EAAE,OAAO,EAAE,YAAY,EAAE,GAAG,KAAK,CAAC;YACxC,MAAM,MAAM,GAAG,eAAe,CAAC,OAAO,CAAC,CAAC;YACxC,MAAM,aAAa,GAAG;gBACpB,MAAM;gBACN,YAAY;gBACZ,YAAY;gBACZ,YAAY;aACb,CAAC;YAEF,MAAM,MAAM,GAAG,IAAI,MAAM,CAAC,KAAK,gDAC1B,OAAO,GACP,aAAa,KAChB,YAAY,EACZ,WAAW,EAAE,WAAW,KACvB,cAAc,CAAC,CAAC;YAEnB,mBAAmB,CAAC,MAAM,CAAC,CAAC;QAC9B,CAAC,CAAA,CAAC;IACJ,CAAC;CACF"}

package/dist/types/subscription-util.d.ts

@@ -1,19 +0,0 @@
-import type { DwnRecordSubscriptionHandler, PermissionsApi, Web5Agent } from '@enbox/agent';
-import type { RecordsSubscribeRequest } from './dwn-api.js';
-/**
- * Utility class for dealing with subscriptions.
- */
-export declare class SubscriptionUtil {
-    /**
-     * Creates a record subscription handler that can be used to process incoming {Record} messages.
-     */
-    static recordSubscriptionHandler({ agent, connectedDid, request, delegateDid, protocolRole, permissionsApi }: {
-        agent: Web5Agent;
-        connectedDid: string;
-        delegateDid?: string;
-        protocolRole?: string;
-        permissionsApi?: PermissionsApi;
-        request: RecordsSubscribeRequest;
-    }): DwnRecordSubscriptionHandler;
-}
-//# sourceMappingURL=subscription-util.d.ts.map

package/dist/types/subscription-util.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"subscription-util.d.ts","sourceRoot":"","sources":["../../src/subscription-util.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,4BAA4B,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAG5F,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAC;AAE5D;;GAEG;AACH,qBAAa,gBAAgB;IAC3B;;OAEG;IACH,MAAM,CAAC,yBAAyB,CAAC,EAAE,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,cAAc,EAAE,EAAC;QAC3G,KAAK,EAAE,SAAS,CAAC;QACjB,YAAY,EAAE,MAAM,CAAC;QACrB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,cAAc,CAAC,EAAE,cAAc,CAAC;QAChC,OAAO,EAAE,uBAAuB,CAAC;KAClC,GAAG,4BAA4B;CAuBjC"}