@enbox/api 0.1.0 → 0.2.0

package/src/dwn-reader-api.ts

@@ -0,0 +1,255 @@
+/**
+ * NOTE: Added reference types here to avoid a `pnpm` bug during build.
+ * https://github.com/enboxorg/enbox/pull/507
+ */
+/// <reference types="@enbox/dwn-sdk-js" />
+
+import type { AnonymousDwnApi, DwnPaginationCursor, DwnResponseStatus } from '@enbox/agent';
+import type {
+  DateSort,
+  Pagination,
+  ProtocolDefinition,
+  ProtocolsQueryFilter,
+  RecordsFilter,
+} from '@enbox/dwn-sdk-js';
+
+import { ReadOnlyRecord } from './read-only-record.js';
+
+// ---------------------------------------------------------------------------
+// Request / Response types for records
+// ---------------------------------------------------------------------------
+
+/**
+ * Request to query public records from a remote DWN.
+ *
+ * @beta
+ */
+export type ReaderRecordsQueryRequest = {
+  /** The DID of the remote DWN to query (required — reader is remote-only). */
+  from: string;
+  /** Filter criteria for the query. */
+  filter: RecordsFilter;
+  /** Sort order for results. */
+  dateSort?: DateSort;
+  /** Pagination options. */
+  pagination?: Pagination;
+};
+
+/**
+ * Response from a reader records query.
+ *
+ * @beta
+ */
+export type ReaderRecordsQueryResponse = DwnResponseStatus & {
+  /** Array of read-only records matching the query. */
+  records: ReadOnlyRecord[];
+  /** Pagination cursor for fetching the next page. */
+  cursor?: DwnPaginationCursor;
+};
+
+/**
+ * Request to read a specific public record from a remote DWN.
+ *
+ * @beta
+ */
+export type ReaderRecordsReadRequest = {
+  /** The DID of the remote DWN to read from (required — reader is remote-only). */
+  from: string;
+  /** Filter to identify the record (typically `{ recordId: '...' }`). */
+  filter: RecordsFilter;
+};
+
+/**
+ * Response from a reader records read.
+ *
+ * @beta
+ */
+export type ReaderRecordsReadResponse = DwnResponseStatus & {
+  /** The read-only record, if found. */
+  record?: ReadOnlyRecord;
+};
+
+/**
+ * Request to count public records on a remote DWN.
+ *
+ * @beta
+ */
+export type ReaderRecordsCountRequest = {
+  /** The DID of the remote DWN to count records in (required). */
+  from: string;
+  /** Filter criteria for counting. */
+  filter: RecordsFilter;
+};
+
+/**
+ * Response from a reader records count.
+ *
+ * @beta
+ */
+export type ReaderRecordsCountResponse = DwnResponseStatus & {
+  /** The number of matching public records. */
+  count?: number;
+};
+
+// ---------------------------------------------------------------------------
+// Request / Response types for protocols
+// ---------------------------------------------------------------------------
+
+/**
+ * Request to query published protocols from a remote DWN.
+ *
+ * @beta
+ */
+export type ReaderProtocolsQueryRequest = {
+  /** The DID of the remote DWN to query protocols from (required). */
+  from: string;
+  /** Optional filter for the protocol query. */
+  filter?: ProtocolsQueryFilter;
+};
+
+/**
+ * Response from a reader protocols query.
+ *
+ * @beta
+ */
+export type ReaderProtocolsQueryResponse = DwnResponseStatus & {
+  /** Array of published protocol definitions. */
+  protocols: ProtocolDefinition[];
+};
+
+// ---------------------------------------------------------------------------
+// DwnReaderApi
+// ---------------------------------------------------------------------------
+
+/**
+ * A read-only API for querying public data on remote DWNs without any identity or signing keys.
+ *
+ * This class mirrors the shape of {@link DwnApi}'s `records` and `protocols`
+ * namespaces, but restricts to read-path operations and requires a `from` DID
+ * on every call (remote-only). All messages are unsigned, so only published
+ * records and protocols are accessible.
+ *
+ * Obtain an instance via {@link Web5.anonymous | `Web5.anonymous()`}.
+ *
+ * @example
+ * ```ts
+ * const { dwn } = Web5.anonymous();
+ *
+ * const { records } = await dwn.records.query({
+ *   from: 'did:dht:alice...',
+ *   filter: { protocol: 'https://social.example/posts', protocolPath: 'post' },
+ * });
+ *
+ * for (const record of records) {
+ *   console.log(record.id, await record.data.text());
+ * }
+ * ```
+ *
+ * @beta
+ */
+export class DwnReaderApi {
+  private _anonymousDwn: AnonymousDwnApi;
+
+  constructor(anonymousDwn: AnonymousDwnApi) {
+    this._anonymousDwn = anonymousDwn;
+  }
+
+  /**
+   * API to interact with public DWN records (query, read, count).
+   */
+  get records(): {
+    query: (request: ReaderRecordsQueryRequest) => Promise<ReaderRecordsQueryResponse>;
+    read: (request: ReaderRecordsReadRequest) => Promise<ReaderRecordsReadResponse>;
+    count: (request: ReaderRecordsCountRequest) => Promise<ReaderRecordsCountResponse>;
+    } {
+    return {
+      /**
+       * Query public records from a remote DWN.
+       * Only published records are returned.
+       */
+      query: async (request: ReaderRecordsQueryRequest): Promise<ReaderRecordsQueryResponse> => {
+        const reply = await this._anonymousDwn.recordsQuery(request.from, {
+          filter     : request.filter,
+          dateSort   : request.dateSort,
+          pagination : request.pagination,
+        });
+
+        const { entries = [], status, cursor } = reply;
+
+        const records = entries.map((entry) => new ReadOnlyRecord({
+          rawMessage   : entry,
+          initialWrite : entry.initialWrite,
+          encodedData  : entry.encodedData,
+          remoteOrigin : request.from,
+          anonymousDwn : this._anonymousDwn,
+        }));
+
+        return { records, status, cursor };
+      },
+
+      /**
+       * Read a specific public record from a remote DWN.
+       * Succeeds for published records and protocol records with `{ who: 'anyone', can: ['read'] }`.
+       */
+      read: async (request: ReaderRecordsReadRequest): Promise<ReaderRecordsReadResponse> => {
+        const reply = await this._anonymousDwn.recordsRead(request.from, {
+          filter: request.filter,
+        });
+
+        const { entry, status } = reply;
+
+        let record: ReadOnlyRecord | undefined;
+        if (200 <= status.code && status.code <= 299 && entry?.recordsWrite) {
+          record = new ReadOnlyRecord({
+            rawMessage   : entry.recordsWrite,
+            initialWrite : entry.initialWrite,
+            data         : entry.data,
+            remoteOrigin : request.from,
+            anonymousDwn : this._anonymousDwn,
+          });
+        }
+
+        return { record, status };
+      },
+
+      /**
+       * Count public records on a remote DWN.
+       * Only published records are counted.
+       */
+      count: async (request: ReaderRecordsCountRequest): Promise<ReaderRecordsCountResponse> => {
+        const reply = await this._anonymousDwn.recordsCount(request.from, {
+          filter: request.filter,
+        });
+
+        const { count, status } = reply;
+
+        return { count, status };
+      },
+    };
+  }
+
+  /**
+   * API to query published protocol definitions from remote DWNs.
+   */
+  get protocols(): {
+    query: (request: ReaderProtocolsQueryRequest) => Promise<ReaderProtocolsQueryResponse>;
+    } {
+    return {
+      /**
+       * Query published protocols from a remote DWN.
+       * Only protocol definitions with `published: true` are returned.
+       */
+      query: async (request: ReaderProtocolsQueryRequest): Promise<ReaderProtocolsQueryResponse> => {
+        const reply = await this._anonymousDwn.protocolsQuery(request.from, {
+          filter: request.filter,
+        });
+
+        const { entries = [], status } = reply;
+
+        const protocols = entries.map((entry) => entry.descriptor.definition);
+
+        return { protocols, status };
+      },
+    };
+  }
+}

package/src/index.ts

@@ -23,14 +23,16 @@
 
 export * from './define-protocol.js';
 export * from './did-api.js';
-export * from './dwn-api.js';
+export * from './dwn-reader-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 './read-only-record.js';
 export * from './record.js';
-export * from './typed-dwn-api.js';
+export * from './typed-web5.js';
 export * from './vc-api.js';
 export * from './web5.js';
 

package/src/live-query.ts

@@ -0,0 +1,261 @@
+import type { DwnMessageSubscription, PermissionsApi, Web5Agent } from '@enbox/agent';
+import type { PaginationCursor, RecordsQueryReplyEntry } from '@enbox/dwn-sdk-js';
+
+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[];
+
+  /** Pagination cursor for fetching the next page of initial results. */
+  cursor?: PaginationCursor;
+
+  /** 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[];
+
+  /**
+   * Pagination cursor for fetching the next page of initial results.
+   *
+   * When the initial snapshot was limited (via `pagination.limit`), this
+   * cursor can be passed in a subsequent `records.subscribe()` call to
+   * continue from where the previous snapshot left off.
+   *
+   * `undefined` when there are no more results.
+   */
+  readonly cursor?: PaginationCursor;
+
+  /** 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,
+      cursor,
+      delegateDid,
+      protocolRole,
+      remoteOrigin,
+      permissionsApi,
+      initialEntries,
+      subscription,
+    } = options;
+
+    this._subscription = subscription;
+    this.cursor = cursor;
+
+    // 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.timestamp);
+    }
+  }
+
+  /**
+   * 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.timestamp <= 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.timestamp);
+    }
+
+    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

@@ -133,7 +133,7 @@ export type TagKeys<Tags extends ProtocolTagsDefinition> = Exclude<
 /**
  * A mapping from protocol type names to their TypeScript data shapes.
  *
- * Used as a type parameter to `defineProtocol()` and `TypedDwnApi` so that
+ * Used as a type parameter to `defineProtocol()` and `TypedWeb5` so that
  * the protocol definition JSON stays JSON-compatible while TypeScript types
  * are tracked separately.
  *
@@ -154,7 +154,7 @@ export type SchemaMap = Record<string, unknown>;
 /**
  * The return type of `defineProtocol()`. Bundles the raw protocol definition
  * with its inferred path strings and schema type map for downstream use
- * by `TypedDwnApi`.
+ * by `TypedWeb5`.
  */
 export type TypedProtocol<
   D extends ProtocolDefinition = ProtocolDefinition,