@enbox/api 0.1.1 → 0.2.1

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,15 +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

@@ -1,5 +1,5 @@
-import type { RecordsQueryReplyEntry } from '@enbox/dwn-sdk-js';
 import type { DwnMessageSubscription, PermissionsApi, Web5Agent } from '@enbox/agent';
+import type { PaginationCursor, RecordsQueryReplyEntry } from '@enbox/dwn-sdk-js';
 
 import { getRecordAuthor } from '@enbox/agent';
 
@@ -60,6 +60,9 @@ export type LiveQueryOptions = {
   /** 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;
 };
@@ -116,6 +119,17 @@ 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;
 
@@ -131,6 +145,7 @@ export class LiveQuery extends EventTarget {
     const {
       agent,
       connectedDid,
+      cursor,
       delegateDid,
       protocolRole,
       remoteOrigin,
@@ -140,6 +155,7 @@ export class LiveQuery extends EventTarget {
     } = 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, {
@@ -154,7 +170,7 @@ export class LiveQuery extends EventTarget {
     // 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);
+      this._knownRecords.set(record.id, record.timestamp);
     }
   }
 
@@ -179,7 +195,7 @@ export class LiveQuery extends EventTarget {
 
       if (knownTimestamp !== undefined) {
         // We've seen this recordId before (either from snapshot or a prior event).
-        if (record.dateModified <= knownTimestamp) {
+        if (record.timestamp <= knownTimestamp) {
           // Duplicate or stale event from the overlap window — skip.
           return;
         }
@@ -189,7 +205,7 @@ export class LiveQuery extends EventTarget {
       }
 
       // Update the known state.
-      this._knownRecords.set(record.id, record.dateModified);
+      this._knownRecords.set(record.id, record.timestamp);
     }
 
     const change: RecordChange = { type: changeType, record };

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,

package/src/read-only-record.ts

@@ -0,0 +1,328 @@
+/**
+ * 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 } from '@enbox/agent';
+import type { RecordsWriteDescriptor, RecordsWriteMessage, RecordsWriteTags } from '@enbox/dwn-sdk-js';
+
+import { getRecordAuthor } from '@enbox/agent';
+import { Convert, Stream } from '@enbox/common';
+
+/**
+ * Construction options for a {@link ReadOnlyRecord}.
+ *
+ * @beta
+ */
+export type ReadOnlyRecordOptions = {
+  /** The raw `RecordsWriteMessage` returned from a query or read reply. */
+  rawMessage: RecordsWriteMessage;
+  /** The initial write message, if the record has been updated. */
+  initialWrite?: RecordsWriteMessage;
+  /** Encoded data (Base64URL string) if the data was small enough to be inlined in the query reply. */
+  encodedData?: string;
+  /** A readable data stream, present when the record comes from a `RecordsRead` reply. */
+  data?: ReadableStream;
+  /** The DID of the remote DWN this record was fetched from. Used for data re-fetch. */
+  remoteOrigin: string;
+  /** The {@link AnonymousDwnApi} instance used to re-fetch data when needed. */
+  anonymousDwn: AnonymousDwnApi;
+};
+
+/**
+ * An immutable, read-only view of a DWN record.
+ *
+ * `ReadOnlyRecord` is returned by {@link DwnReaderApi} methods and provides
+ * access to the record's metadata and data without any mutation capabilities.
+ * There are no `update()`, `delete()`, `send()`, `store()`, or `import()`
+ * methods — the compiler prevents accidental writes.
+ *
+ * Data access works identically to the full {@link Record} class:
+ * - If the data was inlined (small payloads from query replies), it is
+ *   available immediately.
+ * - If the data was not inlined, `data.stream()` / `data.text()` / etc.
+ *   automatically perform an anonymous `RecordsRead` to fetch it.
+ *
+ * @beta
+ */
+export class ReadOnlyRecord {
+  // Private backing fields.
+  private _anonymousDwn: AnonymousDwnApi;
+  private _remoteOrigin: string;
+  private _author: string;
+  private _creator: string;
+  private _descriptor: RecordsWriteDescriptor;
+  private _recordId: string;
+  private _contextId?: string;
+  private _initialWrite?: RecordsWriteMessage;
+  private _encodedData?: Blob;
+  private _readableStream?: ReadableStream;
+  private _authorization: RecordsWriteMessage['authorization'];
+  private _attestation?: RecordsWriteMessage['attestation'];
+  private _encryption?: RecordsWriteMessage['encryption'];
+
+  constructor(options: ReadOnlyRecordOptions) {
+    const { rawMessage, initialWrite, encodedData, data, remoteOrigin, anonymousDwn } = options;
+
+    this._anonymousDwn = anonymousDwn;
+    this._remoteOrigin = remoteOrigin;
+
+    // Extract the author DID from the authorization signature. The author is
+    // the DID that signed the most recent RecordsWrite message. For records
+    // returned from anonymous queries, the authorization will be present (the
+    // remote DWN always returns the full message), but we guard against
+    // malformed messages gracefully.
+    try {
+      this._author = getRecordAuthor(rawMessage) ?? 'unknown';
+    } catch {
+      this._author = 'unknown';
+    }
+    try {
+      this._creator = initialWrite ? (getRecordAuthor(initialWrite) ?? this._author) : this._author;
+    } catch {
+      this._creator = this._author;
+    }
+    this._descriptor = rawMessage.descriptor;
+    this._recordId = rawMessage.recordId;
+    this._contextId = rawMessage.contextId;
+    this._initialWrite = initialWrite;
+    this._authorization = rawMessage.authorization;
+    this._attestation = rawMessage.attestation;
+    this._encryption = rawMessage.encryption;
+
+    if (encodedData) {
+      this._encodedData = new Blob(
+        [Convert.base64Url(encodedData).toUint8Array()],
+        { type: this.dataFormat },
+      );
+    }
+
+    if (data) {
+      this._readableStream = data;
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // Immutable record properties
+  // ---------------------------------------------------------------------------
+
+  /** Record's unique identifier. */
+  get id(): string { return this._recordId; }
+
+  /** Record's context ID. */
+  get contextId(): string | undefined { return this._contextId; }
+
+  /** Record's creation date. */
+  get dateCreated(): string { return this._descriptor.dateCreated; }
+
+  /** Record's parent ID. */
+  get parentId(): string | undefined { return this._descriptor.parentId; }
+
+  /** Record's protocol URI. */
+  get protocol(): string | undefined { return this._descriptor.protocol; }
+
+  /** Record's protocol path. */
+  get protocolPath(): string | undefined { return this._descriptor.protocolPath; }
+
+  /** Record's recipient. */
+  get recipient(): string | undefined { return this._descriptor.recipient; }
+
+  /** Record's schema. */
+  get schema(): string | undefined { return this._descriptor.schema; }
+
+  // ---------------------------------------------------------------------------
+  // Mutable descriptor properties
+  // ---------------------------------------------------------------------------
+
+  /** Record's data format / MIME type. */
+  get dataFormat(): string { return this._descriptor.dataFormat; }
+
+  /** Record's data CID. */
+  get dataCid(): string { return this._descriptor.dataCid; }
+
+  /** Record's data size in bytes. */
+  get dataSize(): number { return this._descriptor.dataSize; }
+
+  /** Record's published date. */
+  get datePublished(): string | undefined { return this._descriptor.datePublished; }
+
+  /** Whether the record is published. */
+  get published(): boolean | undefined { return this._descriptor.published; }
+
+  /** Tags associated with the record. */
+  get tags(): RecordsWriteTags | undefined { return this._descriptor.tags; }
+
+  // ---------------------------------------------------------------------------
+  // State-dependent properties
+  // ---------------------------------------------------------------------------
+
+  /** DID that is the logical author of the record. */
+  get author(): string { return this._author; }
+
+  /** DID that originally created the record. */
+  get creator(): string { return this._creator; }
+
+  /** Record's message timestamp (time of most recent create/update). */
+  get timestamp(): string { return this._descriptor.messageTimestamp; }
+
+  /** Record's encryption metadata, if encrypted. */
+  get encryption(): RecordsWriteMessage['encryption'] { return this._encryption; }
+
+  /** Record's authorization. */
+  get authorization(): RecordsWriteMessage['authorization'] { return this._authorization; }
+
+  /** Record's attestation signatures. */
+  get attestation(): RecordsWriteMessage['attestation'] { return this._attestation; }
+
+  /** The initial write message, if the record has been updated. */
+  get initialWrite(): RecordsWriteMessage | undefined { return this._initialWrite; }
+
+  /** The DID of the remote DWN this record was fetched from. */
+  get remoteOrigin(): string { return this._remoteOrigin; }
+
+  // ---------------------------------------------------------------------------
+  // Data access
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Returns the data of the current record.
+   * If the data is not available in-memory, it is fetched from the remote DWN
+   * using an anonymous `RecordsRead`.
+   *
+   * @returns A data accessor with `blob()`, `bytes()`, `json()`, `text()`, and `stream()` methods.
+   *
+   * @beta
+   */
+  get data(): {
+      blob: () => Promise<Blob>;
+      bytes: () => Promise<Uint8Array>;
+      json: <T = unknown>() => Promise<T>;
+      text: () => Promise<string>;
+      stream: () => Promise<ReadableStream>;
+      then: (
+        onFulfilled?: (value: ReadableStream) => ReadableStream | PromiseLike<ReadableStream>,
+        onRejected?: (reason: any) => PromiseLike<never>,
+      ) => Promise<ReadableStream>;
+      catch: (onRejected?: (reason: any) => PromiseLike<never>) => Promise<ReadableStream>;
+      } {
+    const self = this;
+    const dataObj = {
+      async blob(): Promise<Blob> {
+        return new Blob([await Stream.consumeToBytes({ readableStream: await this.stream() })], { type: self.dataFormat });
+      },
+
+      async bytes(): Promise<Uint8Array> {
+        return await Stream.consumeToBytes({ readableStream: await this.stream() });
+      },
+
+      async json<T = unknown>(): Promise<T> {
+        return await Stream.consumeToJson({ readableStream: await this.stream() }) as T;
+      },
+
+      async text(): Promise<string> {
+        return await Stream.consumeToText({ readableStream: await this.stream() });
+      },
+
+      async stream(): Promise<ReadableStream> {
+        if (self._encodedData) {
+          return Stream.fromBlob(self._encodedData);
+        } else if (self._readableStream) {
+          const currentStream = self._readableStream;
+          self._readableStream = undefined;
+          return currentStream;
+        } else {
+          // Re-fetch the data from the remote DWN using an anonymous RecordsRead.
+          return await self.readRecordData();
+        }
+      },
+
+      then(
+        onFulfilled?: (value: ReadableStream) => ReadableStream | PromiseLike<ReadableStream>,
+        onRejected?: (reason: any) => PromiseLike<never>,
+      ): Promise<ReadableStream> {
+        return this.stream().then(onFulfilled, onRejected);
+      },
+
+      catch(onRejected?: (reason: any) => PromiseLike<never>): Promise<ReadableStream> {
+        return this.stream().catch(onRejected);
+      },
+    };
+
+    return dataObj;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Serialization
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Returns a JSON representation of the record.
+   * Called by `JSON.stringify(...)` automatically.
+   */
+  toJSON(): Record<string, unknown> {
+    return {
+      attestation   : this.attestation,
+      author        : this.author,
+      authorization : this.authorization,
+      contextId     : this.contextId,
+      dataCid       : this.dataCid,
+      dataFormat    : this.dataFormat,
+      dataSize      : this.dataSize,
+      dateCreated   : this.dateCreated,
+      datePublished : this.datePublished,
+      encryption    : this.encryption,
+      parentId      : this.parentId,
+      protocol      : this.protocol,
+      protocolPath  : this.protocolPath,
+      published     : this.published,
+      recipient     : this.recipient,
+      recordId      : this.id,
+      schema        : this.schema,
+      tags          : this.tags,
+      timestamp     : this.timestamp,
+    };
+  }
+
+  /**
+   * Convenience string representation.
+   */
+  toString(): string {
+    let str = 'ReadOnlyRecord: {\n';
+    str += `  ID: ${this.id}\n`;
+    str += this.contextId ? `  Context ID: ${this.contextId}\n` : '';
+    str += this.protocol ? `  Protocol: ${this.protocol}\n` : '';
+    str += this.schema ? `  Schema: ${this.schema}\n` : '';
+    str += `  Data CID: ${this.dataCid}\n`;
+    str += `  Data Format: ${this.dataFormat}\n`;
+    str += `  Data Size: ${this.dataSize}\n`;
+    str += `  Created: ${this.dateCreated}\n`;
+    str += `  Timestamp: ${this.timestamp}\n`;
+    str += '}';
+    return str;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Private helpers
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Fetches the record's data from the remote DWN using an anonymous `RecordsRead`.
+   */
+  private async readRecordData(): Promise<ReadableStream> {
+    try {
+      const reply = await this._anonymousDwn.recordsRead(this._remoteOrigin, {
+        filter: { recordId: this._recordId },
+      });
+
+      if (reply.status.code !== 200 || !reply.entry?.data) {
+        throw new Error(`${reply.status.code}: ${reply.status.detail}`);
+      }
+
+      return reply.entry.data;
+    } catch (error: unknown) {
+      const message = (error instanceof Error) ? error.message : 'Unknown error';
+      throw new Error(`ReadOnlyRecord: Error reading data for record '${this._recordId}': ${message}`);
+    }
+  }
+}