@enbox/api 0.0.1

package/src/record.ts

@@ -0,0 +1,1125 @@
+/**
+ * NOTE: Added reference types here to avoid a `pnpm` bug during build.
+ * https://github.com/TBD54566975/web5-js/pull/507
+ */
+/// <reference types="@enbox/dwn-sdk-js" />
+
+import type { Readable } from '@enbox/common';
+import {
+  Web5Agent,
+  DwnInterface,
+  DwnMessage,
+  DwnMessageParams,
+  DwnResponseStatus,
+  ProcessDwnRequest,
+  DwnMessageDescriptor,
+  getPaginationCursor,
+  getRecordAuthor,
+  DwnDateSort,
+  DwnPaginationCursor,
+  isDwnMessage,
+  SendDwnRequest,
+  PermissionsApi,
+  AgentPermissionsApi,
+  getRecordProtocolRole
+} from '@enbox/agent';
+
+import { Convert, isEmptyObject, NodeStream, removeUndefinedProperties, Stream } from '@enbox/common';
+
+import { dataToBlob, SendCache } from './utils.js';
+import { PermissionGrant } from './permission-grant.js';
+
+/**
+ * Represents Immutable Record properties that cannot be changed after the record is created.
+ *
+ * @beta
+ * */
+export type ImmutableRecordProperties =
+  Pick<DwnMessageDescriptor[DwnInterface.RecordsWrite], 'dateCreated' | 'parentId' | 'protocol' | 'protocolPath' | 'recipient' | 'schema'>;
+
+/**
+ * Represents Optional Record properties that depend on the Record's current state.
+ *
+ * @beta
+*/
+export type OptionalRecordProperties =
+  Pick<DwnMessage[DwnInterface.RecordsWrite], 'authorization' | 'attestation' | 'encryption' | 'contextId' > &
+  Pick<DwnMessageDescriptor[DwnInterface.RecordsWrite], 'dataFormat' | 'dataCid' | 'dataSize' | 'datePublished' | 'published' | 'tags'>;
+
+/**
+ * Represents the structured data model of a record, encapsulating the essential fields that define
+ * the record's metadata and payload within a Decentralized Web Node (DWN).
+ *
+ * @beta
+ */
+export type RecordModel = ImmutableRecordProperties & OptionalRecordProperties & {
+
+  /** The logical author of the record. */
+  author: string;
+
+  /** The unique identifier of the record. */
+  recordId?: string;
+
+  /** The timestamp indicating when the record was last modified. */
+  messageTimestamp?: string;
+
+  /** The protocol role under which this record is written. */
+  protocolRole?: RecordOptions['protocolRole'];
+}
+
+/**
+ * Options for configuring a {@link Record} instance, extending the base `RecordsWriteMessage` with
+ * additional properties.
+ *
+ * This type combines the standard fields required for writing DWN records with additional metadata
+ * and configuration options used specifically in the {@link Record} class.
+ *
+ * @beta
+ */
+export type RecordOptions = DwnMessage[DwnInterface.RecordsWrite | DwnInterface.RecordsDelete] & {
+  /** The DID that signed the record. */
+  author: string;
+
+  /** The attestation signature(s) for the record. */
+  attestation?: DwnMessage[DwnInterface.RecordsWrite]['attestation'];
+
+  /** The encryption information for the record. */
+  encryption?: DwnMessage[DwnInterface.RecordsWrite]['encryption'];
+
+  /** The contextId associated with the record. */
+  contextId?: string;
+
+  /** The unique identifier of the record */
+  recordId?: string;
+
+  /** The DID of the DWN tenant under which record operations are being performed. */
+  connectedDid: string;
+
+  /** The optional DID that will sign the records on behalf of the connectedDid  */
+  delegateDid?: string;
+
+  /** The data of the record, either as a Base64 URL encoded string or a Blob. */
+  encodedData?: string | Blob;
+
+  /**
+   * A stream of data, conforming to the `Readable` or `ReadableStream` interface, providing a
+   * mechanism to read the record's data sequentially. This is particularly useful for handling
+   * large datasets that should not be loaded entirely in memory, allowing for efficient, chunked
+   * processing of the record's data.
+   */
+  data?: Readable | ReadableStream;
+
+  /** The initial `RecordsWriteMessage` that represents the initial state/version of the record. */
+  initialWrite?: DwnMessage[DwnInterface.RecordsWrite];
+
+  /** The protocol role under which this record is written. */
+  protocolRole?: string;
+
+  /** The remote tenant DID if the record was queried or read from a remote DWN. */
+  remoteOrigin?: string;
+};
+
+/**
+ * Parameters for updating a DWN record.
+ *
+ * This type specifies the set of properties that can be updated on an existing record. It is used
+ * to convey the new state or changes to be applied to the record.
+ *
+ * @beta
+ */
+export type RecordUpdateParams = {
+  /**
+   * The new data for the record, which can be of any type. This data will replace the existing
+   * data of the record. It's essential to ensure that this data is compatible with the record's
+   * schema or data format expectations.
+   */
+  data?: unknown;
+
+  /**
+   * The Content Identifier (CID) of the data. Updating this value changes the reference to the data
+   * associated with the record.
+   */
+  dataCid?: DwnMessageDescriptor[DwnInterface.RecordsWrite]['dataCid'];
+
+  /** Whether or not to store the updated message. */
+  store?: boolean;
+
+  /** The data format/MIME type of the supplied data */
+  dataFormat?: string;
+
+  /** The size of the data in bytes. */
+  dataSize?: DwnMessageDescriptor[DwnInterface.RecordsWrite]['dataSize'];
+
+  /** The timestamp indicating when the record was last modified. */
+  dateModified?: DwnMessageDescriptor[DwnInterface.RecordsWrite]['messageTimestamp'];
+
+  /** The timestamp indicating when the record was published. */
+  datePublished?: DwnMessageDescriptor[DwnInterface.RecordsWrite]['datePublished'];
+
+  /** The protocol role under which this record is written. */
+  protocolRole?: RecordOptions['protocolRole'];
+
+  /** The published status of the record. */
+  published?: DwnMessageDescriptor[DwnInterface.RecordsWrite]['published'];
+
+
+  /** The tags associated with the updated record */
+  tags?: DwnMessageDescriptor[DwnInterface.RecordsWrite]['tags'];
+}
+
+/**
+ * Parameters for deleting a DWN record.
+ *
+ * This type specifies the set of properties that are used when deleting an existing record. It is used
+ * to convey the new state or changes to be applied to the record.
+ *
+ * @beta
+ */
+export type RecordDeleteParams = {
+  /** Whether or not to store the message. */
+  store?: boolean;
+
+  /** Whether or not to sign the delete as an owner in order to import it. */
+  signAsOwner?: boolean;
+
+  /** Whether or not to prune any children this record may have. */
+  prune?: DwnMessageDescriptor[DwnInterface.RecordsDelete]['prune'];
+
+  /** The timestamp indicating when the record was deleted. */
+  dateModified?: DwnMessageDescriptor[DwnInterface.RecordsDelete]['messageTimestamp'];
+
+  /** The protocol role under which this record will be deleted. */
+  protocolRole?: string;
+};
+
+/**
+ * The `Record` class encapsulates a single record's data and metadata, providing a more
+ * developer-friendly interface for working with Decentralized Web Node (DWN) records.
+ *
+ * Methods are provided to read, update, and manage the record's lifecycle, including writing to
+ * remote DWNs.
+ *
+ * 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 {
+  /**
+   * Cache to minimize the amount of redundant two-phase commits we do in store() and send()
+   * Retains awareness of the last 100 records stored/sent for up to 100 target DIDs each.
+   */
+  private static _sendCache = SendCache;
+
+  // Record instance metadata.
+
+  /** The {@link Web5Agent} instance that handles DWNs requests. */
+  private _agent: Web5Agent;
+  /** The DID of the DWN tenant under which operations are being performed. */
+  private _connectedDid: string;
+  /** The optional DID that is delegated to act on behalf of the connectedDid */
+  private _delegateDid?: string;
+  /** cache for fetching a permission {@link PermissionGrant}, keyed by a specific MessageType and protocol */
+  private _permissionsApi: PermissionsApi;
+  /** Encoded data of the record, if available. */
+  private _encodedData?: Blob;
+  /** Stream of the record's data. */
+  private _readableStream?: Readable;
+  /** The origin DID if the record was fetched from a remote DWN. */
+  private _remoteOrigin?: string;
+
+  // Private variables for DWN `RecordsWrite` message properties.
+
+  /** The DID of the entity that most recently authored or deleted the record. */
+  private _author: string;
+  /** The DID of the entity that originally created the record. */
+  private _creator: string;
+  /** Attestation JWS signature. */
+  private _attestation?: DwnMessage[DwnInterface.RecordsWrite]['attestation'];
+  /** Authorization signature(s). */
+  private _authorization?: DwnMessage[DwnInterface.RecordsWrite | DwnInterface.RecordsDelete]['authorization'];
+  /** Context ID associated with the record. */
+  private _contextId?: string;
+  /** Descriptor detailing the record's schema, format, and other metadata. */
+  private _descriptor: DwnMessageDescriptor[DwnInterface.RecordsWrite] | DwnMessageDescriptor[DwnInterface.RecordsDelete];
+  /** Encryption details for the record, if the data is encrypted. */
+  private _encryption?: DwnMessage[DwnInterface.RecordsWrite]['encryption'];
+  /** Initial state of the record before any updates. */
+  private _initialWrite: RecordOptions['initialWrite'];
+  /** Flag indicating if the initial write has been stored, to prevent duplicates. */
+  private _initialWriteStored: boolean;
+  /** Flag indicating if the initial write has been signed by the owner. */
+  private _initialWriteSigned: boolean;
+  /** Unique identifier of the record. */
+  private _recordId: string;
+  /** Role under which the record is written. */
+  private _protocolRole?: RecordOptions['protocolRole'];
+
+  /** The `RecordsWriteMessage` descriptor unless the record is in a deleted state */
+  private get _recordsWriteDescriptor() {
+    if (isDwnMessage(DwnInterface.RecordsWrite, this.rawMessage)) {
+      return this._descriptor as DwnMessageDescriptor[DwnInterface.RecordsWrite];
+    }
+
+    return undefined; // returns undefined if the descriptor does not represent a RecordsWrite message.
+  }
+
+  /** The `RecordsWrite` descriptor from the current record or the initial write if the record is in a delete state. */
+  private get _immutableProperties(): ImmutableRecordProperties {
+    return this._recordsWriteDescriptor || this._initialWrite.descriptor;
+  }
+
+  // Getters for immutable Record properties.
+  /** Record's ID */
+  get id() { return this._recordId; }
+
+  /** Record's context ID. If the record is deleted, the context Id comes from the initial write */
+  get contextId() { return this.deleted ? this._initialWrite.contextId : this._contextId; }
+
+  /** Record's creation date */
+  get dateCreated() { return this._immutableProperties.dateCreated; }
+
+  /** Record's parent ID */
+  get parentId() { return this._immutableProperties.parentId; }
+
+  /** Record's protocol */
+  get protocol() { return this._immutableProperties.protocol; }
+
+  /** Record's protocol path */
+  get protocolPath() { return this._immutableProperties.protocolPath; }
+
+  /** Record's recipient */
+  get recipient() { return this._immutableProperties.recipient; }
+
+  /** Record's schema */
+  get schema() { return this._immutableProperties.schema; }
+
+
+  // Getters for mutable DWN RecordsWrite properties that may be undefined in a deleted state.
+  /** Record's data format */
+  get dataFormat() { return this._recordsWriteDescriptor?.dataFormat; }
+
+  /** Record's CID */
+  get dataCid() { return this._recordsWriteDescriptor?.dataCid; }
+
+  /** Record's data size */
+  get dataSize() { return this._recordsWriteDescriptor?.dataSize; }
+
+  /** Record's published date */
+  get datePublished() { return this._recordsWriteDescriptor?.datePublished; }
+
+  /** Record's published status (true/false) */
+  get published() { return this._recordsWriteDescriptor?.published; }
+
+  /** Tags of the record */
+  get tags() { return this._recordsWriteDescriptor?.tags; }
+
+  // Getters for for properties that depend on the current state of the Record.
+  /** DID that is the logical author of the Record. */
+  get author(): string { return this._author; }
+
+  /** DID that is the original creator of the Record. */
+  get creator(): string { return this._creator; }
+
+  /** Record's modified date */
+  get dateModified() { return this._descriptor.messageTimestamp; }
+
+  /** Record's encryption */
+  get encryption(): DwnMessage[DwnInterface.RecordsWrite]['encryption'] { return this._encryption; }
+
+  /** Record's signatures attestation */
+  get authorization(): DwnMessage[DwnInterface.RecordsWrite | DwnInterface.RecordsDelete]['authorization'] { return this._authorization; }
+
+  /** Record's signatures attestation */
+  get attestation(): DwnMessage[DwnInterface.RecordsWrite]['attestation'] | undefined { return this._attestation; }
+
+  /** Role under which the author is writing the record */
+  get protocolRole() { return this._protocolRole; }
+
+  /** Record's deleted state (true/false) */
+  get deleted() { return isDwnMessage(DwnInterface.RecordsDelete, this.rawMessage); }
+
+  /** Record's initial write if the record has been updated */
+  get initialWrite(): RecordOptions['initialWrite'] { return this._initialWrite; }
+
+  /**
+   * Returns a copy of the raw `RecordsWriteMessage` that was used to create the current `Record` instance.
+   */
+  get rawMessage(): DwnMessage[DwnInterface.RecordsWrite] | DwnMessage[DwnInterface.RecordsDelete] {
+    const messageType = this._descriptor.interface + this._descriptor.method;
+    let message: DwnMessage[DwnInterface.RecordsWrite] | DwnMessage[DwnInterface.RecordsDelete];
+    if (messageType === DwnInterface.RecordsWrite) {
+      message = JSON.parse(JSON.stringify({
+        contextId     : this._contextId,
+        recordId      : this._recordId,
+        descriptor    : this._descriptor,
+        attestation   : this._attestation,
+        authorization : this._authorization,
+        encryption    : this._encryption,
+      }));
+    } else {
+      message = JSON.parse(JSON.stringify({
+        descriptor    : this._descriptor,
+        authorization : this._authorization,
+      }));
+    }
+
+    removeUndefinedProperties(message);
+    return message;
+  }
+
+  constructor(agent: Web5Agent, options: RecordOptions, permissionsApi?: PermissionsApi) {
+
+    this._agent = agent;
+
+    // Store the author DID that originally signed the message as a convenience for developers, so
+    // that they don't have to decode the signer's DID from the JWS.
+    this._author = options.author;
+    // The creator is the author of the initial write, or the author of the record if there is no initial write.
+    this._creator = options.initialWrite ? getRecordAuthor(options.initialWrite) : options.author;
+
+    // Store the `connectedDid`, and optionally the `delegateDid` and `permissionsApi` in order to be able
+    // to perform operations on the record (update, delete, data) as a delegate of the connected DID.
+    this._connectedDid = options.connectedDid;
+    this._delegateDid = options.delegateDid;
+    this._permissionsApi = permissionsApi ?? new AgentPermissionsApi({ agent });
+
+    // If the record was queried or read from a remote DWN, the `remoteOrigin` DID will be
+    // defined. This value is used to send subsequent read requests to the same remote DWN in the
+    // event the record's data payload was too large to be returned in query results. or must be
+    // read again (e.g., if the data stream is consumed).
+    this._remoteOrigin = options.remoteOrigin;
+
+    // RecordsWriteMessage properties.
+    this._attestation = options.attestation;
+    this._authorization = options.authorization;
+    this._contextId = options.contextId;
+    this._descriptor = options.descriptor;
+    this._encryption = options.encryption;
+    this._initialWrite = options.initialWrite;
+    this._recordId = this.isRecordsDeleteDescriptor(options.descriptor) ? options.descriptor.recordId : options.recordId;
+    this._protocolRole = options.protocolRole;
+
+    if (options.encodedData) {
+      // If `encodedData` is set, then it is expected that:
+      // type is Blob if the Record object was instantiated by dwn.records.create()/write().
+      // type is Base64 URL encoded string if the Record object was instantiated by dwn.records.query().
+      // If it is a string, we need to Base64 URL decode to bytes and instantiate a Blob.
+      this._encodedData = (typeof options.encodedData === 'string') ?
+        new Blob([Convert.base64Url(options.encodedData).toUint8Array()], { type: this.dataFormat }) :
+        options.encodedData;
+    }
+
+    if (options.data) {
+      // If the record was created from a RecordsRead reply then it will have a `data` property.
+      // If the `data` property is a web ReadableStream, convert it to a Node.js Readable.
+      this._readableStream = Stream.isReadableStream(options.data) ?
+        NodeStream.fromWebReadable({ readableStream: options.data }) :
+        options.data;
+    }
+  }
+
+  /**
+   * Returns the data of the current record.
+   * If the record data is not available, 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.
+   *
+   * @beta
+   */
+  get data() {
+    const self = this; // Capture the context of the `Record` instance.
+    const dataObj = {
+
+      /**
+       * Returns the data of the current record as a `Blob`.
+       *
+       * @returns A promise that resolves to a Blob containing the record's data.
+       * @throws If the record data is not available or cannot be converted to a `Blob`.
+       *
+       * @beta
+       */
+      async blob(): Promise<Blob> {
+        return new Blob([await NodeStream.consumeToBytes({ readable: await this.stream() })], { type: self.dataFormat });
+      },
+
+      /**
+       * Returns the data of the current record as a `Uint8Array`.
+       *
+       * @returns A Promise that resolves to a `Uint8Array` containing the record's data bytes.
+       * @throws If the record data is not available or cannot be converted to a byte array.
+       *
+       * @beta
+       */
+      async bytes(): Promise<Uint8Array> {
+        return await NodeStream.consumeToBytes({ readable: await this.stream() });
+      },
+
+      /**
+       * Parses the data of the current record as JSON and returns it as a JavaScript object.
+       *
+       * @returns A Promise that resolves to a JavaScript object parsed from the record's JSON data.
+       * @throws If the record data is not available, not in JSON format, or cannot be parsed.
+       *
+       * @beta
+       */
+      async json(): Promise<any> {
+        return await NodeStream.consumeToJson({ readable: await this.stream() });
+      },
+
+      /**
+       * Returns the data of the current record as a `string`.
+       *
+       * @returns A promise that resolves to a `string` containing the record's text data.
+       * @throws If the record data is not available or cannot be converted to text.
+       *
+       * @beta
+       */
+      async text(): Promise<string> {
+        return await NodeStream.consumeToText({ readable: await this.stream() });
+      },
+
+      /**
+       * Provides a `Readable` stream containing the record's data.
+       *
+       * @returns A promise that resolves to a Node.js `Readable` stream of the record's data.
+       * @throws If the record data is not available in-memory and cannot be fetched.
+       *
+       * @beta
+       */
+      async stream(): Promise<Readable> {
+        if (self._encodedData) {
+          /** If `encodedData` is set, it indicates that the Record was instantiated by
+           * `dwn.records.create()`/`dwn.records.write()` or the record's data payload was small
+           * enough to be returned in `dwn.records.query()` results. In either case, the data is
+           * already available in-memory and can be returned as a Node.js `Readable` stream. */
+          self._readableStream = NodeStream.fromWebReadable({ readableStream: self._encodedData.stream() });
+
+        } else if (!NodeStream.isReadable({ readable: self._readableStream })) {
+          /** If the data stream for this `Record` instance has already been partially or fully
+           * consumed, then the data must be fetched again from either: */
+          self._readableStream = self._remoteOrigin ?
+            // A. ...a remote DWN if the record was originally queried from a remote DWN.
+            await self.readRecordData({ target: self._remoteOrigin, isRemote: true }) :
+            // B. ...a local DWN if the record was originally queried from the local DWN.
+            await self.readRecordData({ target: self._connectedDid, isRemote: false });
+        }
+
+        if (!self._readableStream) {
+          throw new Error('Record data is not available.');
+        }
+
+        return self._readableStream;
+      },
+
+      /**
+       * Attaches callbacks for the resolution and/or rejection of the `Promise` returned by
+       * `stream()`.
+       *
+       * This method is a proxy to the `then` method of the `Promise` returned by `stream()`,
+       * allowing for a seamless integration with promise-based workflows.
+       * @param onFulfilled - A function to asynchronously execute when the `stream()` promise
+       *                      becomes fulfilled.
+       * @param onRejected - A function to asynchronously execute when the `stream()` promise
+       *                     becomes rejected.
+       * @returns A `Promise` for the completion of which ever callback is executed.
+       */
+      then(onFulfilled?: (value: Readable) => Readable | PromiseLike<Readable>, onRejected?: (reason: any) => PromiseLike<never>) {
+        return this.stream().then(onFulfilled, onRejected);
+      },
+
+      /**
+       * Attaches a rejection handler callback to the `Promise` returned by the `stream()` method.
+       * This method is a shorthand for `.then(undefined, onRejected)`, specifically designed for handling
+       * rejection cases in the promise chain initiated by accessing the record's data. It ensures that
+       * errors during data retrieval or processing can be caught and handled appropriately.
+       *
+       * @param onRejected - A function to asynchronously execute when the `stream()` promise
+       *                     becomes rejected.
+       * @returns A `Promise` that resolves to the value of the callback if it is called, or to its
+       *          original fulfillment value if the promise is instead fulfilled.
+       */
+      catch(onRejected?: (reason: any) => PromiseLike<never>) {
+        return this.stream().catch(onRejected);
+      }
+    };
+
+    return dataObj;
+  }
+
+  /**
+   * Stores the current record state as well as any initial write to the owner's DWN.
+   *
+   * @param importRecord - if true, the record will signed by the owner before storing it to the owner's DWN. Defaults to false.
+   * @returns the status of the store request
+   *
+   * @beta
+   */
+  async store(importRecord: boolean = false): Promise<DwnResponseStatus> {
+    // if we are importing the record we sign it as the owner
+    return this.processRecord({ signAsOwner: importRecord, store: true });
+  }
+
+  /**
+   * Signs the current record state as well as any initial write and optionally stores it to the owner's DWN.
+   * This is useful when importing a record that was signed by someone else into your own DWN.
+   *
+   * @param store - if true, the record will be stored to the owner's DWN after signing. Defaults to true.
+   * @returns the status of the import request
+   *
+   * @beta
+   */
+  async import(store: boolean = true): Promise<DwnResponseStatus> {
+    return this.processRecord({ store, signAsOwner: true });
+  }
+
+  /**
+   * Send the current record to a remote DWN by specifying their DID
+   * If no DID is specified, the target is assumed to be the owner (connectedDID).
+   *
+   * If an initial write is present and the Record class send cache has no awareness of it, the initial write is sent first
+   * (vs waiting for the regular DWN sync)
+   *
+   * @param target - the optional DID to send the record to, if none is set it is sent to the connectedDid
+   * @returns the status of the send record request
+   * @throws `Error` if the record has already been deleted.
+   *
+   * @beta
+   */
+  async send(target?: string): Promise<DwnResponseStatus> {
+    const initialWrite = this._initialWrite;
+    target ??= this._connectedDid;
+
+    // Is there an initial write? Do we know if we've already sent it to this target?
+    if (initialWrite && !Record._sendCache.check(this._recordId, target)){
+      // We do have an initial write, so prepare it for sending to the target.
+      const rawMessage = {
+        ...initialWrite
+      };
+      removeUndefinedProperties(rawMessage);
+
+      // Send the initial write to the target.
+      await this._agent.sendDwnRequest({
+        messageType : DwnInterface.RecordsWrite,
+        author      : this._connectedDid,
+        target      : target,
+        rawMessage
+      });
+
+      // Set the cache to maintain awareness that we don't need to send the initial write next time.
+      Record._sendCache.set(this._recordId, target);
+    }
+
+    let sendRequestOptions: SendDwnRequest<DwnInterface.RecordsWrite | DwnInterface.RecordsDelete>;
+    if (this.deleted) {
+      sendRequestOptions = {
+        messageType : DwnInterface.RecordsDelete,
+        author      : this._connectedDid,
+        target      : target,
+        rawMessage  : { ...this.rawMessage }
+      };
+    } else {
+      sendRequestOptions = {
+        messageType : DwnInterface.RecordsWrite,
+        author      : this._connectedDid,
+        target      : target,
+        dataStream  : await this.data.blob(),
+        rawMessage  : { ...this.rawMessage }
+      };
+    }
+
+    // Send the current/latest state to the target.
+    const { reply } = await this._agent.sendDwnRequest(sendRequestOptions);
+    return reply;
+  }
+
+  /**
+   * Returns a JSON representation of the Record instance.
+   * It's called by `JSON.stringify(...)` automatically.
+   */
+  toJSON(): RecordModel {
+    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,
+      messageTimestamp : this.dateModified,
+      datePublished    : this.datePublished,
+      encryption       : this.encryption,
+      parentId         : this.parentId,
+      protocol         : this.protocol,
+      protocolPath     : this.protocolPath,
+      protocolRole     : this.protocolRole,
+      published        : this.published,
+      recipient        : this.recipient,
+      recordId         : this.id,
+      schema           : this.schema,
+      tags             : this.tags,
+    };
+  }
+
+  /**
+   * Convenience method to return the string representation of the Record instance.
+   * Called automatically in string concatenation, String() type conversion, and template literals.
+   */
+  toString() {
+    let str = `Record: {\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` : '';
+
+    // Only display data properties if the record has not been deleted.
+    if (!this.deleted) {
+      str += `  Data CID: ${this.dataCid}\n`;
+      str += `  Data Format: ${this.dataFormat}\n`;
+      str += `  Data Size: ${this.dataSize}\n`;
+    }
+
+    str += `  Deleted: ${this.deleted}\n`;
+    str += `  Created: ${this.dateCreated}\n`;
+    str += `  Modified: ${this.dateModified}\n`;
+    str += `}`;
+    return str;
+  }
+
+  /**
+   * Returns a pagination cursor for the current record given a sort order.
+   *
+   * @param sort the sort order to use for the pagination cursor.
+   * @returns A promise that resolves to a pagination cursor for the current record.
+   */
+  async paginationCursor(sort: DwnDateSort): Promise<DwnPaginationCursor | undefined> {
+    return isDwnMessage(DwnInterface.RecordsWrite, this.rawMessage) ? getPaginationCursor(this.rawMessage, sort) : undefined;
+  }
+
+  /**
+   * Update the current record on the DWN.
+   * @param params - Parameters to update the record.
+   * @returns the status of the update request
+   * @throws `Error` if the record has already been deleted.
+   *
+   * @beta
+   */
+  async update({ dateModified, data, protocolRole, store = true, ...params }: RecordUpdateParams): Promise<DwnResponseStatus> {
+
+    if (this.deleted) {
+      throw new Error('Record: Cannot revive a deleted record.');
+    }
+
+    // if there is a parentId, we remove it from the descriptor and set a parentContextId
+    const { parentId, ...descriptor } = this._recordsWriteDescriptor;
+    const parentContextId = parentId ? this._contextId.split('/').slice(0, -1).join('/') : undefined;
+
+    // Begin assembling the update message.
+    let updateMessage: DwnMessageParams[DwnInterface.RecordsWrite] = {
+      ...descriptor,
+      ...params,
+      parentContextId,
+      protocolRole     : protocolRole ?? this._protocolRole, // Use the current protocolRole if not provided.
+      messageTimestamp : dateModified, // Map Record class `dateModified` property to DWN SDK `messageTimestamp`
+      recordId         : this._recordId
+    };
+
+    // NOTE: The original Record's tags are copied to the update message, so that the tags are not lost.
+    // However if a user passes new tags in the `RecordUpdateParams` object, they will overwrite the original tags.
+    // If the updated tag object is empty or set to null, we remove the tags property to avoid schema validation errors in the DWN SDK.
+    if (isEmptyObject(updateMessage.tags) || updateMessage.tags === null) {
+      delete updateMessage.tags;
+    }
+
+    let dataBlob: Blob;
+    if (data !== undefined) {
+      // If `data` is being updated then `dataCid` and `dataSize` must be undefined and the `data`
+      // value must be converted to a Blob and later passed as a top-level property to
+      // `agent.processDwnRequest()`.
+      delete updateMessage.dataCid;
+      delete updateMessage.dataSize;
+      ({ dataBlob } = dataToBlob(data, updateMessage.dataFormat));
+    }
+
+    // Throw an error if an attempt is made to modify immutable properties.
+    // Note: `data` and `dateModified` have already been handled.
+    const mutableDescriptorProperties = new Set(['data', 'dataCid', 'dataFormat', 'dataSize', 'datePublished', 'messageTimestamp', 'published', 'tags']);
+    Record.verifyPermittedMutation(Object.keys(params), mutableDescriptorProperties);
+
+    // If `published` is set to false, ensure that `datePublished` is undefined. Otherwise, DWN SDK's schema validation
+    // will throw an error if `published` is false but `datePublished` is set.
+    if (params.published === false && updateMessage.datePublished !== undefined) {
+      delete updateMessage.datePublished;
+    }
+
+    const requestOptions: ProcessDwnRequest<DwnInterface.RecordsWrite> = {
+      author        : this._connectedDid,
+      dataStream    : dataBlob,
+      messageParams : { ...updateMessage },
+      messageType   : DwnInterface.RecordsWrite,
+      target        : this._connectedDid,
+      store
+    };
+
+    if (this._delegateDid) {
+      const { message: delegatedGrant } = await this._permissionsApi.getPermissionForRequest({
+        connectedDid : this._connectedDid,
+        delegateDid  : this._delegateDid,
+        protocol     : this.protocol,
+        delegate     : true,
+        cached       : true,
+        messageType  : requestOptions.messageType
+      });
+      requestOptions.messageParams.delegatedGrant = delegatedGrant;
+      requestOptions.granteeDid = this._delegateDid;
+    }
+
+    const agentResponse = await this._agent.processDwnRequest(requestOptions);
+
+    const { message, reply: { status } } = agentResponse;
+    const responseMessage = message;
+
+    if (200 <= status.code && status.code <= 299) {
+      // copy the original raw message to the initial write before we update the values.
+      if (!this._initialWrite) {
+        // If there is no initial write, we need to create one from the current record state.
+        // We checked in the beginning of the function that the rawMessage is a RecordsWrite message.
+        this._initialWrite = { ...this.rawMessage as DwnMessage[DwnInterface.RecordsWrite] };
+      }
+
+      // Only update the local Record instance mutable properties if the record was successfully (over)written.
+      this._authorization = responseMessage.authorization;
+      this._protocolRole = updateMessage.protocolRole;
+      mutableDescriptorProperties.forEach(property => {
+        this._descriptor[property] = responseMessage.descriptor[property];
+      });
+
+      // Cache data.
+      if (data !== undefined) {
+        this._encodedData = dataBlob;
+      }
+    }
+
+    return { status };
+  }
+
+  /**
+   * Delete the current record on the DWN.
+   * @param params - Parameters to delete the record.
+   * @returns the status of the delete request
+   */
+  async delete(deleteParams?: RecordDeleteParams): Promise<DwnResponseStatus> {
+    const { store = true, signAsOwner, dateModified, prune = false } = deleteParams || {};
+
+    const signAsOwnerValue = signAsOwner && this._delegateDid === undefined;
+    const signAsOwnerDelegate = signAsOwner && this._delegateDid !== undefined;
+
+    if (this.deleted && !this._initialWrite) {
+      throw new Error('Record: Record is in an invalid state, initial write is missing.');
+    }
+
+    if (!this._initialWrite) {
+      // If there is no initial write, we need to create one from the current record state.
+      // We checked in the beginning of the function that the initialWrite is not set if the rawMessage is a RecordsDelete message.
+      // So we can safely assume that the rawMessage is a RecordsWrite message.
+      this._initialWrite = { ...this.rawMessage as DwnMessage[DwnInterface.RecordsWrite] };
+    }
+
+    await this.processInitialWriteIfNeeded({ store, signAsOwner });
+
+    // prepare delete options
+    let deleteOptions: ProcessDwnRequest<DwnInterface.RecordsDelete> = {
+      messageType : DwnInterface.RecordsDelete,
+      author      : this._connectedDid,
+      target      : this._connectedDid,
+      signAsOwner : signAsOwnerValue,
+      signAsOwnerDelegate,
+      store
+    };
+
+    // Check to see if the provided protocolRole within the deleteParams is different from the current protocolRole.
+    const differentRole = deleteParams?.protocolRole ? getRecordProtocolRole(this.rawMessage)  !== deleteParams.protocolRole : false;
+    // If the record is already in a deleted state but the protocolRole is different, we need to construct a delete message with the new protocolRole
+    // otherwise we can just use the existing delete message.
+    if (this.deleted && !differentRole) {
+      deleteOptions.rawMessage = this.rawMessage as DwnMessage[DwnInterface.RecordsDelete];
+    } else {
+      // otherwise we construct a delete message given the `RecordDeleteParams`
+      deleteOptions.messageParams = {
+        prune            : prune,
+        recordId         : this._recordId,
+        messageTimestamp : dateModified,
+        protocolRole     : deleteParams?.protocolRole ?? this._protocolRole // if no protocolRole is provided, use the current protocolRole
+      };
+    }
+
+    if (this._delegateDid) {
+      const { message: delegatedGrant } = await this._permissionsApi.getPermissionForRequest({
+        connectedDid : this._connectedDid,
+        delegateDid  : this._delegateDid,
+        protocol     : this.protocol,
+        delegate     : true,
+        cached       : true,
+        messageType  : deleteOptions.messageType
+      });
+
+      deleteOptions.messageParams = {
+        ...deleteOptions.messageParams,
+        delegatedGrant
+      };
+
+      deleteOptions.granteeDid = this._delegateDid;
+    }
+
+    const agentResponse = await this._agent.processDwnRequest(deleteOptions);
+    const { message, reply: { status } } = agentResponse;
+
+    if (status.code !== 202) {
+      // If the delete was not successful, return the status.
+      return { status };
+    }
+
+    // If the delete was successful, update the Record author to the author of the delete message.
+    this._author = getRecordAuthor(message);
+    this._descriptor = message.descriptor;
+    this._authorization = message.authorization;
+
+    // clear out properties that are not relevant for a deleted record
+    this._encodedData = undefined;
+    this._encryption = undefined;
+    this._attestation = undefined;
+    this._contextId = undefined;
+
+    return { status };
+  }
+
+  /**
+   * Process the initial write, if it hasn't already been processed, with the options set for storing and/or signing as the owner.
+   */
+  private async processInitialWriteIfNeeded({ store, signAsOwner }:{ store: boolean, signAsOwner: boolean }): Promise<void> {
+    if (this.initialWrite && ((signAsOwner && !this._initialWriteSigned) || (store && !this._initialWriteStored))) {
+      const signAsOwnerValue = signAsOwner && this._delegateDid === undefined;
+      const signAsOwnerDelegate = signAsOwner && this._delegateDid !== undefined;
+
+      const initialWriteRequest: ProcessDwnRequest<DwnInterface.RecordsWrite> = {
+        messageType : DwnInterface.RecordsWrite,
+        rawMessage  : this.initialWrite,
+        author      : this._connectedDid,
+        target      : this._connectedDid,
+        signAsOwner : signAsOwnerValue,
+        signAsOwnerDelegate,
+        store,
+      };
+
+      if (this._delegateDid) {
+        const { message: delegatedGrant } = await this._permissionsApi.getPermissionForRequest({
+          connectedDid : this._connectedDid,
+          delegateDid  : this._delegateDid,
+          protocol     : this.protocol,
+          delegate     : true,
+          cached       : true,
+          messageType  : initialWriteRequest.messageType
+        });
+
+        initialWriteRequest.messageParams = {
+          ...initialWriteRequest.messageParams,
+          delegatedGrant
+        };
+
+        initialWriteRequest.granteeDid = this._delegateDid;
+      }
+
+      // Process the prepared initial write, with the options set for storing and/or signing as the owner.
+      const agentResponse = await this._agent.processDwnRequest(initialWriteRequest);
+
+      const { message, reply: { status } } = agentResponse;
+      const responseMessage = message;
+
+      if (200 <= status.code && status.code <= 299) {
+        if (store) this._initialWriteStored = true;
+        if (signAsOwner) {
+          this._initialWriteSigned = true;
+          this.initialWrite.authorization = responseMessage.authorization;
+        }
+      }
+    }
+  }
+
+  /**
+   * Handles the various conditions around there being an initial write, whether to store initial/current state,
+   * and whether to add an owner signature to the initial write to enable storage when protocol rules require it.
+   */
+  private async processRecord({ store, signAsOwner }:{ store: boolean, signAsOwner: boolean }): Promise<DwnResponseStatus> {
+    const signAsOwnerValue = signAsOwner && this._delegateDid === undefined;
+    const signAsOwnerDelegate = signAsOwner && this._delegateDid !== undefined;
+
+    await this.processInitialWriteIfNeeded({ store, signAsOwner });
+
+    let requestOptions: ProcessDwnRequest<DwnInterface.RecordsWrite | DwnInterface.RecordsDelete>;
+    // Now that we've processed a potential initial write, we can process the current record state.
+    // If the record has been deleted, we need to send a delete request. Otherwise, we send a write request.
+    if (this.deleted) {
+      requestOptions = {
+        messageType : DwnInterface.RecordsDelete,
+        rawMessage  : this.rawMessage,
+        author      : this._connectedDid,
+        target      : this._connectedDid,
+        signAsOwner : signAsOwnerValue,
+        signAsOwnerDelegate,
+        store,
+      };
+    } else {
+      requestOptions = {
+        messageType : DwnInterface.RecordsWrite,
+        rawMessage  : this.rawMessage,
+        author      : this._connectedDid,
+        target      : this._connectedDid,
+        dataStream  : await this.data.blob(),
+        signAsOwner : signAsOwnerValue,
+        signAsOwnerDelegate,
+        store,
+      };
+    }
+
+    if (this._delegateDid) {
+      const { message: delegatedGrant } = await this._permissionsApi.getPermissionForRequest({
+        connectedDid : this._connectedDid,
+        delegateDid  : this._delegateDid,
+        protocol     : this.protocol,
+        delegate     : true,
+        cached       : true,
+        messageType  : requestOptions.messageType
+      });
+
+      requestOptions.messageParams = {
+        ...requestOptions.messageParams,
+        delegatedGrant
+      };
+
+      requestOptions.granteeDid = this._delegateDid;
+    }
+
+    const agentResponse = await this._agent.processDwnRequest(requestOptions);
+    const { message, reply: { status } } = agentResponse;
+    const responseMessage = message;
+
+    if (200 <= status.code && status.code <= 299) {
+      // If we are signing as the owner, make sure to update the current record state's authorization, because now it will have the owner's signature on it.
+      if (signAsOwner) this._authorization = responseMessage.authorization;
+    }
+
+    return { status };
+  }
+
+  /**
+   * Fetches the record's data from the specified DWN.
+   *
+   * This private method is called when the record data is not available in-memory
+   * and needs to be fetched from either a local or a remote DWN.
+   * It makes a read request to the specified DWN and processes the response to provide
+   * a Node.js `Readable` stream of the record's data.
+   *
+   * @param params - Parameters for fetching the record's data.
+   * @param params.target - The DID of the DWN to fetch the data from.
+   * @param params.isRemote - Indicates whether the target DWN is a remote node.
+   * @returns A Promise that resolves to a Node.js `Readable` stream of the record's data.
+   * @throws If there is an error while fetching or processing the data from the DWN.
+   *
+   * @beta
+   */
+  private async readRecordData({ target, isRemote }: { target: string, isRemote: boolean }) {
+    const readRequest: ProcessDwnRequest<DwnInterface.RecordsRead> = {
+      author        : this._connectedDid,
+      messageParams : { filter: { recordId: this.id }, protocolRole: this._protocolRole },
+      messageType   : DwnInterface.RecordsRead,
+      target,
+    };
+
+    if (this._delegateDid) {
+      // When reading the data as a delegate, if we don't find a grant we will attempt to read it with the delegate DID as the author.
+      // This allows users to read publicly available data without needing explicit grants.
+      //
+      // NOTE: When a read-only Record class is implemented, callers would have that returned instead when they don't have an explicit permission.
+      // This should fail if a permission is not found, although it should not happen in practice.
+      // TODO: https://github.com/TBD54566975/web5-js/issues/898
+      try {
+        const { message: delegatedGrant } = await this._permissionsApi.getPermissionForRequest({
+          connectedDid : this._connectedDid,
+          delegateDid  : this._delegateDid,
+          protocol     : this.protocol,
+          delegate     : true,
+          cached       : true,
+          messageType  : readRequest.messageType
+        });
+
+        readRequest.messageParams = {
+          ...readRequest.messageParams,
+          delegatedGrant
+        };
+
+        readRequest.granteeDid = this._delegateDid;
+      } catch(error) {
+        // If there is an error fetching the grant, we will attempt to read the data as the delegate.
+        readRequest.author = this._delegateDid;
+      }
+    }
+
+    const agentResponsePromise = isRemote ?
+      this._agent.sendDwnRequest(readRequest) :
+      this._agent.processDwnRequest(readRequest);
+
+    try {
+      const { reply: { status, entry }} = await agentResponsePromise;
+      if (status.code !== 200) {
+        throw new Error(`${status.code}: ${status.detail}`);
+      }
+
+      const dataStream: ReadableStream | Readable = entry.data;
+      // If the data stream is a web ReadableStream, convert it to a Node.js Readable.
+      const nodeReadable = Stream.isReadableStream(dataStream) ?
+        NodeStream.fromWebReadable({ readableStream: dataStream }) :
+        dataStream;
+      return nodeReadable;
+
+    } catch (error) {
+      throw new Error(`Error encountered while attempting to read data: ${error.message}`);
+    }
+  }
+
+  /**
+   * Verifies if the properties to be mutated are mutable.
+   *
+   * This private method is used to ensure that only mutable properties of the `Record` instance
+   * are being changed. It checks whether the properties specified for mutation are among the
+   * set of properties that are allowed to be modified. If any of the properties to be mutated
+   * are not in the set of mutable properties, the method throws an error.
+   *
+   * @param propertiesToMutate - An iterable of property names that are intended to be mutated.
+   * @param mutableDescriptorProperties - A set of property names that are allowed to be mutated.
+   *
+   * @throws If any of the properties in `propertiesToMutate` are not in `mutableDescriptorProperties`.
+   *
+   * @beta
+   */
+  private static verifyPermittedMutation(propertiesToMutate: Iterable<string>, mutableDescriptorProperties: Set<string>) {
+    for (const property of propertiesToMutate) {
+      if (!mutableDescriptorProperties.has(property)) {
+        throw new Error(`${property} is an immutable property. Its value cannot be changed.`);
+      }
+    }
+  }
+
+  /**
+   * Checks if the descriptor is a RecordsDelete descriptor.
+   *
+   * @param descriptor a RecordsWrite or RecordsDelete descriptor
+   */
+  private isRecordsDeleteDescriptor(descriptor: DwnMessageDescriptor[DwnInterface.RecordsWrite | DwnInterface.RecordsDelete]): descriptor is DwnMessageDescriptor[DwnInterface.RecordsDelete] {
+    return descriptor.interface + descriptor.method === DwnInterface.RecordsDelete;
+  }
+}