Completes the api docs

packages/api/src/dwn-api.ts

@@ -20,84 +20,166 @@ import { Record } from './record.js';
 import { Protocol } from './protocol.js';
 import { dataToBlob } from './utils.js';
 
+/**
+ * Request to setup a protocol with its definitions
+ *
+ * @beta
+ */
 export type ProtocolsConfigureRequest = {
   message: Omit<ProtocolsConfigureOptions, 'authorizationSigner'>;
 }
 
+/**
+ * Response for the protocol configure request
+ *
+ * @beta
+ */
 export type ProtocolsConfigureResponse = {
   status: UnionMessageReply['status'];
   protocol?: Protocol;
 }
 
+/**
+ * Represents each entry on the protocols query reply
+ *
+ * @beta
+ */
 export type ProtocolsQueryReplyEntry = {
   descriptor: ProtocolsConfigureDescriptor;
 };
 
+/**
+ * Request to query protocols
+ *
+ * @beta
+ */
 export type ProtocolsQueryRequest = {
   from?: string;
   message: Omit<ProtocolsQueryOptions, 'authorizationSigner'>
 }
 
+/**
+ * Response with the retrieved protocols
+ *
+ * @beta
+ */
 export type ProtocolsQueryResponse = {
   protocols: Protocol[];
   status: UnionMessageReply['status'];
 }
 
+/**
+ * Type alias for {@link RecordsWriteRequest}
+ *
+ * @beta
+ */
 export type RecordsCreateRequest = RecordsWriteRequest;
 
+/**
+ * Type alias for {@link RecordsWriteResponse}
+ *
+ * @beta
+ */
 export type RecordsCreateResponse = RecordsWriteResponse;
 
+/**
+ * Request to create a record from an existing one (useful for updating an existing record)
+ *
+ * @beta
+ */
 export type RecordsCreateFromRequest = {
   author: string;
   data: unknown;
   message?: Omit<RecordsWriteOptions, 'authorizationSigner'>;
   record: Record;
 }
 
+/**
+ * Request to delete a record from the DWN
+ *
+ * @beta
+ */
 export type RecordsDeleteRequest = {
   from?: string;
   message: Omit<RecordsDeleteOptions, 'authorizationSigner'>;
 }
 
+/**
+ * Response for the delete request
+ *
+ * @beta
+ */
 export type RecordsDeleteResponse = {
   status: UnionMessageReply['status'];
 };
 
+/**
+ * Request to query records from the DWN
+ *
+ * @beta
+ */
 export type RecordsQueryRequest = {
   /** The from property indicates the DID to query from and return results. */
   from?: string;
   message: Omit<RecordsQueryOptions, 'authorizationSigner'>;
 }
 
+/**
+ * Response for the query request
+ *
+ * @beta
+ */
 export type RecordsQueryResponse = {
   status: UnionMessageReply['status'];
   records?: Record[]
 };
 
+/**
+ * Request to read a record from the DWN
+ *
+ * @beta
+ */
 export type RecordsReadRequest = {
   /** The from property indicates the DID to read from and return results fro. */
   from?: string;
   message: Omit<RecordsReadOptions, 'authorizationSigner'>;
 }
 
+/**
+ * Response for the read request
+ *
+ * @beta
+ */
 export type RecordsReadResponse = {
   status: UnionMessageReply['status'];
   record: Record;
 };
 
+/**
+ * Request to write a record to the DWN
+ *
+ * @beta
+ */
 export type RecordsWriteRequest = {
   data: unknown;
   message?: Omit<Partial<RecordsWriteOptions>, 'authorizationSigner'>;
   store?: boolean;
 }
 
+/**
+ * Response for the write request
+ *
+ * @beta
+ */
 export type RecordsWriteResponse = {
   status: UnionMessageReply['status'];
   record?: Record
 };
 
 /**
- * TODO: Document class.
+ * Interface to interact with DWN Records and Protocols
+ *
+ * @beta
  */
 export class DwnApi {
   private agent: Web5Agent;
@@ -109,12 +191,12 @@ export class DwnApi {
   }
 
   /**
- * TODO: Document namespace.
- */
+   * Retrieves the protocols manager, used to configure and query them
+   */
   get protocols() {
     return {
       /**
-       * TODO: Document method.
+       * Configure method, used to setup a new protocol (or update) with the passed definitions
        */
       configure: async (request: ProtocolsConfigureRequest): Promise<ProtocolsConfigureResponse> => {
         const agentResponse = await this.agent.processDwnRequest({
@@ -136,7 +218,7 @@ export class DwnApi {
       },
 
       /**
-       * TODO: Document method.
+       * Query the available protocols
        */
       query: async (request: ProtocolsQueryRequest): Promise<ProtocolsQueryResponse> => {
         const agentRequest = {
@@ -171,19 +253,19 @@ export class DwnApi {
   }
 
   /**
-   * TODO: Document namespace.
+   * Records manager, used to read, write, query and delete records
    */
   get records() {
     return {
       /**
-       * TODO: Document method.
+       * Alias for the `write` method
        */
       create: async (request: RecordsCreateRequest): Promise<RecordsCreateResponse> => {
         return this.records.write(request);
       },
 
       /**
-       * TODO: Document method.
+       * 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();
@@ -221,7 +303,7 @@ export class DwnApi {
       },
 
       /**
-       * TODO: Document method.
+       * Delete a record
        */
       delete: async (request: RecordsDeleteRequest): Promise<RecordsDeleteResponse> => {
         const agentRequest = {
@@ -253,7 +335,7 @@ export class DwnApi {
       },
 
       /**
-       * TODO: Document method.
+       * Query a single or multiple records based on the given filter
        */
       query: async (request: RecordsQueryRequest): Promise<RecordsQueryResponse> => {
         const agentRequest = {
@@ -287,7 +369,7 @@ export class DwnApi {
       },
 
       /**
-       * TODO: Document method.
+       * Read a single record based on the given filter
        */
       read: async (request: RecordsReadRequest): Promise<RecordsReadResponse> => {
         const agentRequest = {
@@ -331,7 +413,7 @@ export class DwnApi {
       },
 
       /**
-       * TODO: Document method.
+       * Writes a record to the DWN
        *
        * As a convenience, the Record instance returned will cache a copy of the data if the
        * data size, in bytes, is less than the DWN 'max data size allowed to be encoded'

packages/api/src/protocol.ts

@@ -2,15 +2,27 @@ import type { Web5Agent } from '@web5/agent';
 import type { ProtocolsConfigure } from '@tbd54566975/dwn-sdk-js';
 
 // TODO: export ProtocolsConfigureMessage from dwn-sdk-js
+/**
+ * The protocol configure message carries the protocol definition and is used
+ * to setup the protocol.
+ *
+ * @beta
+ */
 export type ProtocolsConfigureMessage = ProtocolsConfigure['message'];
+
+/**
+ * Metadata of the protocol
+ *
+ * @beta
+ */
 type ProtocolMetadata = {
   author: string;
   messageCid?: string;
 };
 
 /**
  * The Protocol API abstraction class. It's used to represent and retrieve a protocol and
- * also to send (install) protocols to other DIDs.
+ * also to install (send) protocols to other DIDs.
  *
  * @beta
  */

packages/api/src/record.ts

@@ -8,13 +8,24 @@ import { DataStream, DwnInterfaceName, DwnMethodName, Encoder } from '@tbd545669
 import { dataToBlob } from './utils.js';
 import type { RecordsDeleteResponse } from './dwn-api.js';
 
+/**
+ * Options that are passed to Record constructor.
+ *
+ * @beta
+ */
 export type RecordOptions = RecordsWriteMessage & {
   author: string;
   target: string;
   encodedData?: string | Blob;
   data?: Readable | ReadableStream;
 };
 
+/**
+ * Represents the record data model, without the auxiliary properties such as
+ * the `descriptor` and the `authorization`
+ *
+ * @beta
+ */
 export type RecordModel = RecordsWriteDescriptor
   & Omit<RecordsWriteMessage, 'descriptor' | 'recordId' | 'authorization'>
   & {
@@ -23,6 +34,11 @@ export type RecordModel = RecordsWriteDescriptor
     target: string;
   }
 
+/**
+ * Options that are passed to update the record on the DWN
+ *
+ * @beta
+ */
 export type RecordUpdateOptions = {
   data?: unknown;
   dataCid?: RecordsWriteDescriptor['dataCid'];
@@ -33,7 +49,8 @@ export type RecordUpdateOptions = {
 }
 
 /**
- * TODO: Document class.
+ * Record wrapper class with convenience methods to send, update,
+ * and delete itself, aside from manipulating and reading the record data.
  *
  * Note: The `messageTimestamp` of the most recent RecordsWrite message is
  *       logically equivalent to the date/time at which a Record was most
@@ -66,26 +83,64 @@ export class Record implements RecordModel {
   private _recordId: string;
 
   // Immutable DWN Record properties.
+
+  /** Record's signatures attestation */
   get attestation(): RecordsWriteMessage['attestation'] { return this._attestation; }
+
+  /** Record's context ID */
   get contextId() { return this._contextId; }
+
+  /** Record's data format */
   get dataFormat() { return this._descriptor.dataFormat; }
+
+  /** Record's creation date */
   get dateCreated() { return this._descriptor.dateCreated; }
+
+  /** Record's encryption */
   get encryption(): RecordsWriteMessage['encryption'] { return this._encryption; }
+
+  /** Record's ID */
   get id() { return this._recordId; }
+
+  /** Interface is always `Records` */
   get interface() { return this._descriptor.interface; }
+
+  /** Method is always `Write` */
   get method() { return this._descriptor.method; }
+
+  /** Record's parent ID */
   get parentId() { return this._descriptor.parentId; }
+
+  /** Record's protocol */
   get protocol() { return this._descriptor.protocol; }
+
+  /** Record's protocol path */
   get protocolPath() { return this._descriptor.protocolPath; }
+
+  /** Record's recipient */
   get recipient() { return this._descriptor.recipient; }
+
+  /** Record's schema */
   get schema() { return this._descriptor.schema; }
 
   // Mutable DWN Record properties.
+
+  /** Record's CID */
   get dataCid() { return this._descriptor.dataCid; }
+
+  /** Record's data size */
   get dataSize() { return this._descriptor.dataSize; }
+
+  /** Record's modified date */
   get dateModified() { return this._descriptor.messageTimestamp; }
+
+  /** Record's published date */
   get datePublished() { return this._descriptor.datePublished; }
+
+  /** Record's published status */
   get messageTimestamp() { return this._descriptor.messageTimestamp; }
+
+  /** Record's published status (true/false) */
   get published() { return this._descriptor.published; }
 
   constructor(agent: Web5Agent, options: RecordOptions) {