@enbox/api 0.0.8 → 0.1.1

package/src/dwn-api.ts

@@ -8,9 +8,7 @@ import type {
   CreateGrantParams,
   CreateRequestParams,
   DwnMessage,
-  DwnMessageParams
-  ,
-  DwnMessageSubscription,
+  DwnMessageParams,
   DwnPaginationCursor,
   DwnResponse,
   DwnResponseStatus,
@@ -26,12 +24,17 @@ import {
 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).
@@ -221,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;
 };
 
 /**
@@ -331,6 +323,30 @@ 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
    *
@@ -660,6 +676,7 @@ export class DwnApi {
 
         return { status };
       },
+
       /**
        * Query a single or multiple records based on the given filter
        */
@@ -846,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) {
@@ -917,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

@@ -21,13 +21,17 @@
  * @packageDocumentation
  */
 
+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';
+export * from './protocol-types.js';
 export * from './record.js';
+export * from './typed-dwn-api.js';
 export * from './vc-api.js';
 export * from './web5.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/protocol-types.ts

@@ -0,0 +1,171 @@
+/**
+ * Type-level utilities for extracting typed paths, type names, schemas,
+ * data formats, and tag shapes from a {@link ProtocolDefinition}.
+ *
+ * These types are purely compile-time — they produce no runtime code.
+ */
+
+import type { ProtocolDefinition, ProtocolRuleSet, ProtocolTagsDefinition, ProtocolType } from '@enbox/dwn-sdk-js';
+
+// ---------------------------------------------------------------------------
+// Path extraction
+// ---------------------------------------------------------------------------
+
+/**
+ * Recursively extracts all valid protocol path strings from a `ProtocolRuleSet`.
+ *
+ * Given a structure like `{ foo: { bar: { ... } } }`, this produces
+ * `'foo' | 'foo/bar'`.  Directive keys (starting with `$`) are excluded.
+ */
+export type RuleSetPaths<R, Prefix extends string = ''> = {
+  [K in Extract<keyof R, string>]: K extends `$${string}`
+    ? never
+    : R[K] extends ProtocolRuleSet
+      ? `${Prefix}${K}` | RuleSetPaths<R[K], `${Prefix}${K}/`>
+      : never;
+}[Extract<keyof R, string>];
+
+/**
+ * All valid protocol path strings for a given `ProtocolDefinition`.
+ *
+ * @example
+ * ```ts
+ * type Paths = ProtocolPaths<typeof myDef>;
+ * // 'friend' | 'friend/message' | 'group' | 'group/member'
+ * ```
+ */
+export type ProtocolPaths<D extends ProtocolDefinition> = RuleSetPaths<D['structure']>;
+
+// ---------------------------------------------------------------------------
+// Type-name extraction
+// ---------------------------------------------------------------------------
+
+/**
+ * Extracts the last segment (type name) from a protocol path string.
+ *
+ * @example
+ * ```ts
+ * type T = TypeNameAtPath<'group/member'>; // 'member'
+ * ```
+ */
+export type TypeNameAtPath<Path extends string> =
+  Path extends `${string}/${infer Rest}`
+    ? TypeNameAtPath<Rest>
+    : Path;
+
+// ---------------------------------------------------------------------------
+// Schema & data-format lookup
+// ---------------------------------------------------------------------------
+
+/**
+ * The type names declared in the `types` map of a `ProtocolDefinition`.
+ */
+export type TypeNames<D extends ProtocolDefinition> = Extract<keyof D['types'], string>;
+
+/**
+ * Looks up the `schema` URI for a given type name in the protocol definition.
+ * Returns `undefined` if the type does not declare a schema.
+ */
+export type SchemaForType<D extends ProtocolDefinition, TypeName extends string> =
+  TypeName extends keyof D['types']
+    ? D['types'][TypeName] extends ProtocolType
+      ? D['types'][TypeName]['schema']
+      : undefined
+    : undefined;
+
+/**
+ * Looks up the `dataFormats` array for a given type name in the protocol definition.
+ * Returns `undefined` if the type does not declare dataFormats.
+ */
+export type DataFormatsForType<D extends ProtocolDefinition, TypeName extends string> =
+  TypeName extends keyof D['types']
+    ? D['types'][TypeName] extends ProtocolType
+      ? D['types'][TypeName]['dataFormats']
+      : undefined
+    : undefined;
+
+// ---------------------------------------------------------------------------
+// Tag extraction helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Navigates a `ProtocolRuleSet` tree to the node at the given slash-delimited path.
+ */
+type RuleSetAtPath<R, Path extends string> =
+  Path extends `${infer Head}/${infer Tail}`
+    ? Head extends keyof R
+      ? R[Head] extends ProtocolRuleSet
+        ? RuleSetAtPath<R[Head], Tail>
+        : never
+      : never
+    : Path extends keyof R
+      ? R[Path] extends ProtocolRuleSet
+        ? R[Path]
+        : never
+      : never;
+
+/**
+ * Extracts the `$tags` definition for a given protocol path.
+ * Returns `never` if the path does not declare `$tags`.
+ */
+export type TagsAtPath<D extends ProtocolDefinition, Path extends string> =
+  RuleSetAtPath<D['structure'], Path> extends infer RS
+    ? RS extends ProtocolRuleSet
+      ? RS['$tags'] extends ProtocolTagsDefinition
+        ? RS['$tags']
+        : never
+      : never
+    : never;
+
+/**
+ * Extracts the user-defined tag keys (excluding `$`-prefixed meta-keys)
+ * from a `ProtocolTagsDefinition`.
+ */
+export type TagKeys<Tags extends ProtocolTagsDefinition> = Exclude<
+  Extract<keyof Tags, string>,
+  `$${string}`
+>;
+
+// ---------------------------------------------------------------------------
+// Schema map — associates TypeScript data types with protocol type names
+// ---------------------------------------------------------------------------
+
+/**
+ * A mapping from protocol type names to their TypeScript data shapes.
+ *
+ * Used as a type parameter to `defineProtocol()` and `TypedDwnApi` so that
+ * the protocol definition JSON stays JSON-compatible while TypeScript types
+ * are tracked separately.
+ *
+ * @example
+ * ```ts
+ * type MySchemaMap = {
+ *   profile : { displayName: string; bio?: string };
+ *   avatar  : Blob;
+ * };
+ * ```
+ */
+export type SchemaMap = Record<string, unknown>;
+
+// ---------------------------------------------------------------------------
+// Typed protocol — output of defineProtocol()
+// ---------------------------------------------------------------------------
+
+/**
+ * The return type of `defineProtocol()`. Bundles the raw protocol definition
+ * with its inferred path strings and schema type map for downstream use
+ * by `TypedDwnApi`.
+ */
+export type TypedProtocol<
+  D extends ProtocolDefinition = ProtocolDefinition,
+  M extends SchemaMap = SchemaMap,
+> = {
+  /** The raw DWN protocol definition (JSON-compatible). */
+  readonly definition: D;
+
+  /**
+   * Phantom property carrying the schema map type. Not present at runtime;
+   * used only by TypeScript to thread the generic through.
+   */
+  readonly _schemaMap?: M;
+};

package/src/record.ts

@@ -445,7 +445,7 @@ export class Record implements RecordModel {
   get data(): {
       blob: () => Promise<Blob>;
       bytes: () => Promise<Uint8Array>;
-      json: () => Promise<any>;
+      json: <T = unknown>() => Promise<T>;
       text: () => Promise<string>;
       stream: () => Promise<ReadableStream>;
       then: (
@@ -489,8 +489,8 @@ export class Record implements RecordModel {
        *
        * @beta
        */
-      async json(): Promise<any> {
-        return await Stream.consumeToJson({ readableStream: await this.stream() });
+      async json<T = unknown>(): Promise<T> {
+        return await Stream.consumeToJson({ readableStream: await this.stream() }) as T;
       },
 
       /**