From 63a5616e76399c2d96553d5dc3d9501d80cded3c Mon Sep 17 00:00:00 2001 From: Leo Ribeiro Date: Tue, 31 Oct 2023 13:22:15 -0400 Subject: [PATCH] Completes the api docs --- packages/api/src/dwn-api.ts | 106 +++++++++++++++++++++++++++++++---- packages/api/src/protocol.ts | 14 ++++- packages/api/src/record.ts | 57 ++++++++++++++++++- packages/api/src/vc-api.ts | 3 + packages/api/src/web5.ts | 12 ++-- 5 files changed, 174 insertions(+), 18 deletions(-) diff --git a/packages/api/src/dwn-api.ts b/packages/api/src/dwn-api.ts index 11bccc120..7a235548f 100644 --- a/packages/api/src/dwn-api.ts +++ b/packages/api/src/dwn-api.ts @@ -20,33 +20,73 @@ 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; } +/** + * 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 } +/** + * 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; @@ -54,50 +94,92 @@ export type RecordsCreateFromRequest = { record: Record; } +/** + * Request to delete a record from the DWN + * + * @beta + */ export type RecordsDeleteRequest = { from?: string; message: Omit; } +/** + * 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; } +/** + * 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; } +/** + * 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, '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 => { 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 => { 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 => { 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 => { 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 => { 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 => { 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 => { 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/protocol.ts b/packages/api/src/protocol.ts index 48199bdfb..8d15f5c82 100644 --- a/packages/api/src/protocol.ts +++ b/packages/api/src/protocol.ts @@ -2,7 +2,19 @@ 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; @@ -10,7 +22,7 @@ type ProtocolMetadata = { /** * 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 */ diff --git a/packages/api/src/record.ts b/packages/api/src/record.ts index fb70e8966..0cb074022 100644 --- a/packages/api/src/record.ts +++ b/packages/api/src/record.ts @@ -8,6 +8,11 @@ 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; @@ -15,6 +20,12 @@ export type RecordOptions = RecordsWriteMessage & { 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 & { @@ -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) { diff --git a/packages/api/src/vc-api.ts b/packages/api/src/vc-api.ts index 622ac9730..ccf346be2 100644 --- a/packages/api/src/vc-api.ts +++ b/packages/api/src/vc-api.ts @@ -14,6 +14,9 @@ export class VcApi { this.connectedDid = options.connectedDid; } + /** + * Issues a VC (Not implemented yet) + */ async create() { // TODO: implement throw new Error('Not implemented.'); diff --git a/packages/api/src/web5.ts b/packages/api/src/web5.ts index a3de883ab..1431e0d4a 100644 --- a/packages/api/src/web5.ts +++ b/packages/api/src/web5.ts @@ -25,14 +25,18 @@ export type TechPreviewOptions = { * @beta */ export type Web5ConnectOptions = { - /** Provide a {@link Web5Agent} implementation. Defaults to creating a local - * {@link @web5/user-agent#Web5UserAgent} if one isn't provided */ + /** + * Provide a {@link @web5/agent#Web5Agent} implementation. Defaults to creating a local + * {@link @web5/user-agent#Web5UserAgent} if one isn't provided + **/ agent?: Web5Agent; - /** Provide an instance of a {@link AppDataStore} implementation. Defaults to + /** + * Provide an instance of a {@link @web5/agent#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 @web5/agent#AppDataStore} instance. */ + * their choosing, provide an initialized {@link @web5/agent#AppDataStore} instance. + **/ appData?: AppDataStore; // Specify an existing DID to connect to.