Install tbdocs for the @web5/api package (#251)

* Install tbdocs for @web5/api --------- Co-authored-by: Frank Hinek <[email protected]>
decentralized-identity · Nov 3, 2023 · 1754dd6 · 1754dd6
1 parent d442b66
commit 1754dd6
Show file tree

Hide file tree

Showing 10 changed files with 327 additions and 37 deletions.
diff --git a/.github/workflows/tests-ci.yml b/.github/workflows/tests-ci.yml
@@ -107,3 +107,36 @@ jobs:
         run: npm run test:browser --ws -- --color
         env:
           TEST_DWN_URL: http://localhost:3000
+
+  tbdocs-reporter:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout source
+        uses: actions/checkout@8e5e7e5ab8b370d6c329ec480221332ada57f0ab # v3.5.2
+
+      - name: Set up Node.js
+        uses: actions/setup-node@64ed1c7eab4cce3362f8c340dee64e5eaeef8f7c # v3.6.0
+        with:
+          node-version: 18
+          registry-url: https://registry.npmjs.org/
+
+      - name: Install latest npm
+        run: npm install -g npm@latest
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build all workspace packages
+        run: npm run build
+
+      - name: TBDocs Reporter
+        id: tbdocs-reporter-protocol
+        uses: TBD54566975/tbdocs@main
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          report_changed_scope_only: false
+          fail_on_error: false
+          entry_points: |
+            - file: packages/api/src/index.ts
+              docsReporter: api-extractor
+              docsGenerator: typedoc-markdown
diff --git a/packages/api/src/did-api.ts b/packages/api/src/did-api.ts
@@ -28,6 +28,12 @@ import type { Web5Agent } from '@web5/agent';
 //   didMethodApis: DidMethodApi[];
 //   cache?: DidResolverCache;
 // }
+
+/**
+ * The DID API is used to create and resolve DIDs.
+ *
+ * @beta
+ */
 export class DidApi {
   // private didResolver: DidResolver;
   // private methodCreatorMap: Map<string, DidMethodCreator> = new Map();

diff --git a/packages/api/src/dwn-api.ts b/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.
- */
+   * API to interact with DWN protocols (e.g., `dwn.protocols.configure()`).
+   */
   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.
+   * API to interact with DWN records (e.g., `dwn.records.create()`).
    */
   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'

diff --git a/packages/api/src/index.ts b/packages/api/src/index.ts
@@ -1,8 +1,33 @@
+/**
+ * Making developing with Web5 components at least 5 times easier to work with.
+ *
+ * Web5 consists of the following components:
+ * - Decentralized Identifiers
+ * - Verifiable Credentials
+ * - DWeb Node personal datastores
+ *
+ * The SDK sets out to gather the most oft used functionality from all three of
+ * these pillar technologies to provide a simple library that is as close to
+ * effortless as possible.
+ *
+ * The SDK is currently still under active development, but having entered the
+ * Tech Preview phase there is now a drive to avoid unnecessary changes unless
+ * backwards compatibility is provided. Additional functionality will be added
+ * in the lead up to 1.0 final, and modifications will be made to address
+ * issues and community feedback.
+ *
+ * [Link to GitHub Repo](https://github.com/TBD54566975/web5-js)
+ *
+ * @packageDocumentation
+ */
+
 export * from './did-api.js';
 export * from './dwn-api.js';
 export * from './protocol.js';
 export * from './record.js';
-export * as utils from './utils.js';
 export * from './vc-api.js';
 export * from './web5.js';
-export * from './tech-preview.js';
+export * from './tech-preview.js';
+
+import * as utils from './utils.js';
+export { utils };
diff --git a/packages/api/src/protocol.ts b/packages/api/src/protocol.ts
@@ -2,17 +2,38 @@ 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 install (send) 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 +44,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,