Add web5 docs and fixes (wip)

packages/api/src/did-api.ts

@@ -28,6 +28,13 @@ import type { Web5Agent } from '@web5/agent';
 //   didMethodApis: DidMethodApi[];
 //   cache?: DidResolverCache;
 // }
+
+/**
+ * The DID API is used to create and resolve DIDs. It is the primary interface
+ * for interacting with DIDs.
+ *
+ * @beta
+ */
 export class DidApi {
   // private didResolver: DidResolver;
   // private methodCreatorMap: Map<string, DidMethodCreator> = new Map();

packages/api/src/protocol.ts

@@ -8,11 +8,20 @@ type ProtocolMetadata = {
   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.
+ *
+ * @beta
+ */
 export class Protocol {
   private _agent: Web5Agent;
   private _metadata: ProtocolMetadata;
   private _protocolsConfigureMessage: ProtocolsConfigureMessage;
 
+  /**
+   * The protocol definition: types, structure and publish status
+   */
   get definition() {
     return this._protocolsConfigureMessage.descriptor.definition;
   }
@@ -23,10 +32,18 @@ export class Protocol {
     this._protocolsConfigureMessage = protocolsConfigureMessage;
   }
 
+  /**
+   * Returns the protocol as a JSON object.
+   */
   toJSON() {
     return this._protocolsConfigureMessage;
   }
 
+  /**
+   * Sends the protocol to a remote DWN by specifying their DID
+   * @param target - the DID to send the protocol to
+   * @returns the status of the send protocols request
+   */
   async send(target: string) {
     const { reply } = await this._agent.sendDwnRequest({
       author      : this._metadata.author,

packages/api/src/record.ts

@@ -33,19 +33,27 @@ export type RecordUpdateOptions = {
 }
 
 /**
-   * TODO: Document class.
-   *
-   * Note: The `messageTimestamp` of the most recent RecordsWrite message is
-   *       logically equivalent to the date/time at which a Record was most
-   *       recently modified.  Since this Record class implementation is
-   *       intended to simplify the developer experience of working with
-   *       logical records (and not individual DWN messages) the
-   *       `messageTimestamp` is mapped to `dateModified`.
-   */
+ * TODO: Document class.
+ *
+ * Note: The `messageTimestamp` of the most recent RecordsWrite message is
+ *       logically equivalent to the date/time at which a Record was most
+ *       recently modified.  Since this Record class implementation is
+ *       intended to simplify the developer experience of working with
+ *       logical records (and not individual DWN messages) the
+ *       `messageTimestamp` is mapped to `dateModified`.
+ *
+ * @beta
+ */
 export class Record implements RecordModel {
   // mutable properties
+
+  /** Record's author */
   author: string;
+
+  /** Record's target (for sent records) */
   target: string;
+
+  /** Record deleted status */
   isDeleted = false;
 
   private _agent: Web5Agent;
@@ -107,7 +115,11 @@ export class Record implements RecordModel {
   }
 
   /**
-   * TODO: Document method.
+   * Returns the data of the current record.
+   * If the record data is null, it attempts to fetch the data from the DWN.
+   * @returns a data stream with convenience methods such as `blob()`, `json()`, `text()`, and `stream()`, similar to the fetch API response
+   * @throws `Error` if the record has already been deleted.
+   *
    */
   get data() {
     if (this.isDeleted) throw new Error('Operation failed: Attempted to access `data` of a record that has already been deleted.');
@@ -172,7 +184,9 @@ export class Record implements RecordModel {
   }
 
   /**
-   * TODO: Document method.
+   * Delete the current record from the DWN.
+   * @returns the status of the delete request
+   * @throws `Error` if the record has already been deleted.
    */
   async delete(): Promise<RecordsDeleteResponse> {
     if (this.isDeleted) throw new Error('Operation failed: Attempted to call `delete()` on a record that has already been deleted.');
@@ -196,7 +210,11 @@ export class Record implements RecordModel {
   }
 
   /**
-   * TODO: Document method.
+   * Send the current record to a remote DWN by specifying their DID
+   * (vs waiting for the regular DWN sync)
+   * @param target - the DID to send the record to
+   * @returns the status of the send record request
+   * @throws `Error` if the record has already been deleted.
    */
   async send(target: string): Promise<any> {
     if (this.isDeleted) throw new Error('Operation failed: Attempted to call `send()` on a record that has already been deleted.');
@@ -213,9 +231,8 @@ export class Record implements RecordModel {
   }
 
   /**
-   * TODO: Document method.
-   *
-   * Called by `JSON.stringify(...)` automatically.
+   * Returns a JSON representation of the Record instance.
+   * It's called by `JSON.stringify(...)` automatically.
    */
   toJSON(): RecordModel {
     return {
@@ -243,8 +260,7 @@ export class Record implements RecordModel {
   }
 
   /**
-   * TODO: Document method.
-   *
+   * Convenience method to return the string representation of the Record instance.
    * Called automatically in string concatenation, String() type conversion, and template literals.
    */
   toString() {
@@ -263,7 +279,10 @@ export class Record implements RecordModel {
   }
 
   /**
-   * TODO: Document method.
+   * Update the current record on the DWN.
+   * @param options - options to update the record, including the new data
+   * @returns the status of the update request
+   * @throws `Error` if the record has already been deleted.
    */
   async update(options: RecordUpdateOptions = {}) {
     if (this.isDeleted) throw new Error('Operation failed: Attempted to call `update()` on a record that has already been deleted.');

packages/api/src/tech-preview.ts

@@ -3,6 +3,8 @@ import * as didUtils from '@web5/dids/utils';
 /**
  * Dynamically selects up to 2 DWN endpoints that are provided
  * by default during the Tech Preview period.
+ *
+ * @beta
  */
 export async function getTechPreviewDwnEndpoints(): Promise<string[]> {
   let response: Response;

packages/api/src/utils.ts

@@ -2,6 +2,8 @@ import { Convert, universalTypeOf } from '@web5/common';
 
 /**
  * Set/detect the media type and return the data as bytes.
+ *
+ * @beta
  */
 export const dataToBlob = (data: any, dataFormat?: string) => {
   let dataBlob: Blob;

packages/api/src/vc-api.ts

@@ -1,5 +1,10 @@
 import type { Web5Agent } from '@web5/agent';
 
+/**
+ * The VC API is used to issue, present and verify VCs
+ *
+ * @beta
+ */
 export class VcApi {
   private agent: Web5Agent;
   private connectedDid: string;

packages/api/src/web5.ts

@@ -11,6 +11,8 @@ import { DidIonMethod } from '@web5/dids';
 
 /**
  * Override defaults configured during the technical preview phase.
+ *
+ * @beta
  */
 export type TechPreviewOptions = {
   // Override default dwnEndpoints provided for technical preview.
@@ -19,16 +21,18 @@ export type TechPreviewOptions = {
 
 /**
  * Optional overrides that can be provided when calling {@link Web5.connect}.
+ *
+ * @beta
  */
 export type Web5ConnectOptions = {
   /** Provide a {@link Web5Agent} implementation. Defaults to creating a local
-   * {@link Web5UserAgent} if one isn't provided */
+   * {@link @web5/user-agent#Web5UserAgent} if one isn't provided */
   agent?: Web5Agent;
 
   /** Provide an instance of a {@link AppDataStore} implementation. Defaults to
    * a LevelDB-backed store with an insecure, static unlock passphrase if one
    * isn't provided. To allow the app user to enter a secure passphrase of
-   * their choosing, provide an initialized {@link AppDataStore} instance. */
+   * their choosing, provide an initialized {@link @web5/agent#AppDataStore} instance. */
   appData?: AppDataStore;
 
   // Specify an existing DID to connect to.
@@ -45,18 +49,39 @@ export type Web5ConnectOptions = {
 }
 
 /**
+ * Options that are passed to Web5 constructor.
+ *
  * @see {@link Web5ConnectOptions}
+ * @beta
  */
 type Web5Options = {
   agent: Web5Agent;
   connectedDid: string;
 };
 
+/**
+ * The main Web5 API interface. It manages the creation of a DID if needed, the
+ * connection to the local DWN and all the web5 main foundational APIs such as VC,
+ * syncing, etc.
+ *
+ * @beta
+ */
 export class Web5 {
+  /**
+   * Web5 Agent knows how to handle DIDs, DWNs and VCs requests. The agent manages the
+   * user keys and identities, and is responsible to sign and verify messages.
+   */
   agent: Web5Agent;
+
+  /** Exposed instance to the DID APIs, allow users to create and resolve DIDs  */
   did: DidApi;
+
+  /** Exposed instance to the DWN APIs, allow users to read/write records */
   dwn: DwnApi;
+
+  /** Exposed instance to the VC APIs, allow users to issue, present and verify VCs */
   vc: VcApi;
+
   private connectedDid: string;
 
   constructor(options: Web5Options) {
@@ -69,7 +94,7 @@ export class Web5 {
   }
 
   /**
-   * Connects to a {@link Web5Agent}. Defaults to creating a local {@link Web5UserAgent}
+   * Connects to a {@link @web5/agent#Web5Agent}. Defaults to creating a local {@link @web5/user-agent#Web5UserAgent}
    * if one isn't provided.
    *
    * @param options - optional overrides