@enbox/api 0.0.1

package/dist/types/permission-request.d.ts

@@ -0,0 +1,108 @@
+import { DwnDataEncodedRecordsWriteMessage, DwnPermissionConditions, DwnPermissionScope, DwnResponseStatus, Web5Agent } from '@enbox/agent';
+import { PermissionGrant } from './permission-grant.js';
+/**
+ * Represents the structured data model of a PermissionsRequest record, encapsulating the essential fields that define
+ * the request's data and payload within a Decentralized Web Node (DWN).
+ */
+export interface PermissionRequestModel {
+    /**
+     * The ID of the permission request, which is the record ID DWN message.
+     */
+    readonly id: string;
+    /**
+     * The requester for of the permission.
+     */
+    readonly requester: string;
+    /**
+     * Optional string that communicates what the requested grant would be used for.
+     */
+    readonly description?: string;
+    /**
+     * Whether the requested grant is delegated or not.
+     * If `true`, the `requestor` will be able to act as the grantor of the permission within the scope of the requested grant.
+     */
+    readonly delegated?: boolean;
+    /**
+     * The scope of the allowed access.
+     */
+    readonly scope: DwnPermissionScope;
+    /**
+     * Optional conditions that must be met when the requested grant is used.
+     */
+    readonly conditions?: DwnPermissionConditions;
+}
+/**
+ * The `PermissionRequest` class encapsulates a permissions protocol `request` record, providing a more
+ * developer-friendly interface for working with Decentralized Web Node (DWN) records.
+ *
+ * Methods are provided to grant the request and manage the request's lifecycle, including writing to remote DWNs.
+ *
+ * @beta
+ */
+export declare class PermissionRequest implements PermissionRequestModel {
+    /** The PermissionsAPI used to interact with the underlying permission request */
+    private _permissions;
+    /** The DID to use as the author and default target for the underlying permission request */
+    private _connectedDid;
+    /** The underlying DWN `RecordsWrite` message along with encoded data that represent the request */
+    private _message;
+    /** The parsed permission request object */
+    private _request;
+    private constructor();
+    /** parses the request given an agent, connectedDid and data encoded records write message  */
+    static parse({ connectedDid, agent, message }: {
+        connectedDid: string;
+        agent: Web5Agent;
+        message: DwnDataEncodedRecordsWriteMessage;
+    }): Promise<PermissionRequest>;
+    /** The agent to use for this instantiation of the request */
+    private get agent();
+    /** The request's ID, which is also the underlying record's ID  */
+    get id(): string;
+    /** The DID that is requesting a permission */
+    get requester(): string;
+    /** (optional) Description of the permission request */
+    get description(): string;
+    /** Whether or not the permission request can be used to impersonate the grantor */
+    get delegated(): boolean;
+    /** The permission scope under which the requested grant would be valid */
+    get scope(): DwnPermissionScope;
+    /** The conditions under which the requested grant would be valid */
+    get conditions(): DwnPermissionConditions;
+    /** The `RecordsWrite` DWN message with encoded data that was used to instantiate this request */
+    get rawMessage(): DwnDataEncodedRecordsWriteMessage;
+    /**
+     * Send the current permission request to a remote DWN by specifying their DID
+     * If no DID is specified, the target is assumed to be the owner (connectedDID).
+     *
+     * @param target - the optional DID to send the permission request to, if none is set it is sent to the connectedDid
+     * @returns the status of the send permission request
+     *
+     * @beta
+     */
+    send(target?: string): Promise<DwnResponseStatus>;
+    /**
+     * Stores the current permission request to the owner's DWN.
+     *
+     * @param importGrant - if true, the permission request will signed by the owner before storing it to the owner's DWN. Defaults to false.
+     * @returns the status of the store request
+     *
+     * @beta
+     */
+    store(): Promise<DwnResponseStatus>;
+    /**
+     * Grants the permission request to the requester.
+     *
+     * @param dateExpires - the date when the permission grant will expire.
+     * @param store - if true, the permission grant will be stored in the owner's DWN. Defaults to true.
+     * @returns {PermissionGrant} the granted permission.
+     *
+     * @beta
+     */
+    grant(dateExpires: string, store?: boolean): Promise<PermissionGrant>;
+    /**
+     * @returns the JSON representation of the permission request
+     */
+    toJSON(): PermissionRequestModel;
+}
+//# sourceMappingURL=permission-request.d.ts.map

package/dist/types/permission-request.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permission-request.d.ts","sourceRoot":"","sources":["../../src/permission-request.ts"],"names":[],"mappings":"AAAA,OAAO,EAAuB,iCAAiC,EAAE,uBAAuB,EAAwB,kBAAkB,EAAE,iBAAiB,EAAkB,SAAS,EAAE,MAAM,cAAc,CAAC;AAGvM,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAExD;;;GAGG;AACH,MAAM,WAAW,sBAAsB;IACrC;;OAEG;IACH,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAEpB;;OAEG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAE3B;;OAEG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAE9B;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAE7B;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,kBAAkB,CAAC;IAEnC;;OAEG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,uBAAuB,CAAC;CAC/C;AAED;;;;;;;GAOG;AACH,qBAAa,iBAAkB,YAAW,sBAAsB;IAC9D,iFAAiF;IACjF,OAAO,CAAC,YAAY,CAAsB;IAC1C,4FAA4F;IAC5F,OAAO,CAAC,aAAa,CAAS;IAC9B,mGAAmG;IACnG,OAAO,CAAC,QAAQ,CAAoC;IACpD,2CAA2C;IAC3C,OAAO,CAAC,QAAQ,CAAuB;IAEvC,OAAO;IAgBP,8FAA8F;WACjF,KAAK,CAAC,EAAE,YAAY,EAAE,KAAK,EAAE,OAAO,EAAE,EAAC;QAClD,YAAY,EAAE,MAAM,CAAC;QACrB,KAAK,EAAE,SAAS,CAAC;QACjB,OAAO,EAAE,iCAAiC,CAAC;KAC5C,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAO9B,6DAA6D;IAC7D,OAAO,KAAK,KAAK,GAEhB;IAED,kEAAkE;IAClE,IAAI,EAAE,WAEL;IAED,8CAA8C;IAC9C,IAAI,SAAS,WAEZ;IAED,uDAAuD;IACvD,IAAI,WAAW,WAEd;IAED,mFAAmF;IACnF,IAAI,SAAS,YAEZ;IAED,0EAA0E;IAC1E,IAAI,KAAK,uBAER;IAED,oEAAoE;IACpE,IAAI,UAAU,4BAEb;IAED,iGAAiG;IACjG,IAAI,UAAU,IAAI,iCAAiC,CAElD;IAED;;;;;;;;OAQG;IACG,IAAI,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAmBvD;;;;;;;OAOG;IACG,KAAK,IAAI,OAAO,CAAC,iBAAiB,CAAC;IAgBzC;;;;;;;;OAQG;IACG,KAAK,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,GAAE,OAAc,GAAG,OAAO,CAAC,eAAe,CAAC;IAkBjF;;OAEG;IACH,MAAM,IAAI,sBAAsB;CAGjC"}

package/dist/types/protocol.d.ts

@@ -0,0 +1,59 @@
+/**
+ * NOTE: Added reference types here to avoid a `pnpm` bug during build.
+ * https://github.com/TBD54566975/web5-js/pull/507
+ */
+import type { DwnMessage, DwnResponseStatus, Web5Agent } from '@enbox/agent';
+import { DwnInterface } from '@enbox/agent';
+/**
+ * Represents metadata associated with a protocol, including the author and an optional message CID.
+ */
+export type ProtocolMetadata = {
+    /** The author of the protocol. */
+    author: string;
+    /**
+     * The Content Identifier (CID) of a ProtocolsConfigure message.
+     *
+     * This is an optional field, and is used by {@link Protocol.send}.
+     */
+    messageCid?: string;
+};
+/**
+ * Encapsulates a DWN Protocol with its associated metadata and configuration.
+ *
+ * This class primarly exists to provide developers with a convenient way to configure/install
+ * protocols on remote DWNs.
+ */
+export declare class Protocol {
+    /** The {@link Web5Agent} instance that handles DWNs requests. */
+    private _agent;
+    /** The ProtocolsConfigureMessage containing the detailed configuration for the protocol. */
+    private _metadata;
+    /** Metadata associated with the protocol, including the author and optional message CID. */
+    private _protocolsConfigureMessage;
+    /**
+     * Constructs a new instance of the Protocol class.
+     *
+     * @param agent - The Web5Agent instance used for network interactions.
+     * @param protocolsConfigureMessage - The configuration message containing the protocol details.
+     * @param metadata - Metadata associated with the protocol, including the author and optional message CID.
+     */
+    constructor(agent: Web5Agent, protocolsConfigureMessage: DwnMessage[DwnInterface.ProtocolsConfigure], metadata: ProtocolMetadata);
+    /**
+     * Retrieves the protocol definition from the protocol's configuration message.
+     * @returns The protocol definition.
+     */
+    get definition(): import("@enbox/agent").DwnProtocolDefinition;
+    /**
+     * Serializes the protocol's configuration message to JSON.
+     * @returns The serialized JSON object of the protocol's configuration message.
+     */
+    toJSON(): import("@enbox/dwn-sdk-js").ProtocolsConfigureMessage;
+    /**
+     * Sends the protocol configuration to a remote DWN identified by the target DID.
+     *
+     * @param target - The DID of the target DWN to which the protocol configuration will be installed.
+     * @returns A promise that resolves to an object containing the status of the send operation.
+     */
+    send(target: string): Promise<DwnResponseStatus>;
+}
+//# sourceMappingURL=protocol.d.ts.map

package/dist/types/protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../../src/protocol.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,iBAAiB,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAE7E,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAE5C;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,kCAAkC;IAClC,MAAM,EAAE,MAAM,CAAC;IAEf;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF;;;;;GAKG;AACH,qBAAa,QAAQ;IACnB,iEAAiE;IACjE,OAAO,CAAC,MAAM,CAAY;IAE1B,4FAA4F;IAC5F,OAAO,CAAC,SAAS,CAAmB;IAEpC,4FAA4F;IAC5F,OAAO,CAAC,0BAA0B,CAA8C;IAEhF;;;;;;OAMG;gBACS,KAAK,EAAE,SAAS,EAAE,yBAAyB,EAAE,UAAU,CAAC,YAAY,CAAC,kBAAkB,CAAC,EAAE,QAAQ,EAAE,gBAAgB;IAMhI;;;OAGG;IACH,IAAI,UAAU,iDAEb;IAED;;;OAGG;IACH,MAAM;IAIN;;;;;OAKG;IACG,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;CAUvD"}

package/dist/types/record.d.ts

@@ -0,0 +1,441 @@
+/**
+ * NOTE: Added reference types here to avoid a `pnpm` bug during build.
+ * https://github.com/TBD54566975/web5-js/pull/507
+ */
+import type { Readable } from '@enbox/common';
+import { Web5Agent, DwnInterface, DwnMessage, DwnResponseStatus, DwnMessageDescriptor, DwnDateSort, DwnPaginationCursor, PermissionsApi } from '@enbox/agent';
+/**
+ * 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 declare 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;
+    /** The {@link Web5Agent} instance that handles DWNs requests. */
+    private _agent;
+    /** The DID of the DWN tenant under which operations are being performed. */
+    private _connectedDid;
+    /** The optional DID that is delegated to act on behalf of the connectedDid */
+    private _delegateDid?;
+    /** cache for fetching a permission {@link PermissionGrant}, keyed by a specific MessageType and protocol */
+    private _permissionsApi;
+    /** Encoded data of the record, if available. */
+    private _encodedData?;
+    /** Stream of the record's data. */
+    private _readableStream?;
+    /** The origin DID if the record was fetched from a remote DWN. */
+    private _remoteOrigin?;
+    /** The DID of the entity that most recently authored or deleted the record. */
+    private _author;
+    /** The DID of the entity that originally created the record. */
+    private _creator;
+    /** Attestation JWS signature. */
+    private _attestation?;
+    /** Authorization signature(s). */
+    private _authorization?;
+    /** Context ID associated with the record. */
+    private _contextId?;
+    /** Descriptor detailing the record's schema, format, and other metadata. */
+    private _descriptor;
+    /** Encryption details for the record, if the data is encrypted. */
+    private _encryption?;
+    /** Initial state of the record before any updates. */
+    private _initialWrite;
+    /** Flag indicating if the initial write has been stored, to prevent duplicates. */
+    private _initialWriteStored;
+    /** Flag indicating if the initial write has been signed by the owner. */
+    private _initialWriteSigned;
+    /** Unique identifier of the record. */
+    private _recordId;
+    /** Role under which the record is written. */
+    private _protocolRole?;
+    /** The `RecordsWriteMessage` descriptor unless the record is in a deleted state */
+    private get _recordsWriteDescriptor();
+    /** The `RecordsWrite` descriptor from the current record or the initial write if the record is in a delete state. */
+    private get _immutableProperties();
+    /** Record's ID */
+    get id(): string;
+    /** Record's context ID. If the record is deleted, the context Id comes from the initial write */
+    get contextId(): string;
+    /** Record's creation date */
+    get dateCreated(): string;
+    /** Record's parent ID */
+    get parentId(): string;
+    /** Record's protocol */
+    get protocol(): string;
+    /** Record's protocol path */
+    get protocolPath(): string;
+    /** Record's recipient */
+    get recipient(): string;
+    /** Record's schema */
+    get schema(): string;
+    /** Record's data format */
+    get dataFormat(): string;
+    /** Record's CID */
+    get dataCid(): string;
+    /** Record's data size */
+    get dataSize(): number;
+    /** Record's published date */
+    get datePublished(): string;
+    /** Record's published status (true/false) */
+    get published(): boolean;
+    /** Tags of the record */
+    get tags(): import("@enbox/dwn-sdk-js").RecordsWriteTags;
+    /** DID that is the logical author of the Record. */
+    get author(): string;
+    /** DID that is the original creator of the Record. */
+    get creator(): string;
+    /** Record's modified date */
+    get dateModified(): string;
+    /** Record's encryption */
+    get encryption(): DwnMessage[DwnInterface.RecordsWrite]['encryption'];
+    /** Record's signatures attestation */
+    get authorization(): DwnMessage[DwnInterface.RecordsWrite | DwnInterface.RecordsDelete]['authorization'];
+    /** Record's signatures attestation */
+    get attestation(): DwnMessage[DwnInterface.RecordsWrite]['attestation'] | undefined;
+    /** Role under which the author is writing the record */
+    get protocolRole(): string;
+    /** Record's deleted state (true/false) */
+    get deleted(): boolean;
+    /** Record's initial write if the record has been updated */
+    get initialWrite(): RecordOptions['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];
+    constructor(agent: Web5Agent, options: RecordOptions, permissionsApi?: PermissionsApi);
+    /**
+     * 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(): {
+        /**
+         * 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
+         */
+        blob(): Promise<Blob>;
+        /**
+         * 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
+         */
+        bytes(): Promise<Uint8Array>;
+        /**
+         * 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
+         */
+        json(): Promise<any>;
+        /**
+         * 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
+         */
+        text(): Promise<string>;
+        /**
+         * 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
+         */
+        stream(): Promise<Readable>;
+        /**
+         * 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>): any;
+        /**
+         * 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>): any;
+    };
+    /**
+     * 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
+     */
+    store(importRecord?: boolean): Promise<DwnResponseStatus>;
+    /**
+     * 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
+     */
+    import(store?: boolean): Promise<DwnResponseStatus>;
+    /**
+     * 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
+     */
+    send(target?: string): Promise<DwnResponseStatus>;
+    /**
+     * Returns a JSON representation of the Record instance.
+     * It's called by `JSON.stringify(...)` automatically.
+     */
+    toJSON(): RecordModel;
+    /**
+     * Convenience method to return the string representation of the Record instance.
+     * Called automatically in string concatenation, String() type conversion, and template literals.
+     */
+    toString(): string;
+    /**
+     * 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.
+     */
+    paginationCursor(sort: DwnDateSort): Promise<DwnPaginationCursor | 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
+     */
+    update({ dateModified, data, protocolRole, store, ...params }: RecordUpdateParams): Promise<DwnResponseStatus>;
+    /**
+     * Delete the current record on the DWN.
+     * @param params - Parameters to delete the record.
+     * @returns the status of the delete request
+     */
+    delete(deleteParams?: RecordDeleteParams): Promise<DwnResponseStatus>;
+    /**
+     * Process the initial write, if it hasn't already been processed, with the options set for storing and/or signing as the owner.
+     */
+    private processInitialWriteIfNeeded;
+    /**
+     * 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 processRecord;
+    /**
+     * 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 readRecordData;
+    /**
+     * 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;
+    /**
+     * Checks if the descriptor is a RecordsDelete descriptor.
+     *
+     * @param descriptor a RecordsWrite or RecordsDelete descriptor
+     */
+    private isRecordsDeleteDescriptor;
+}
+//# sourceMappingURL=record.d.ts.map

package/dist/types/record.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"record.d.ts","sourceRoot":"","sources":["../../src/record.ts"],"names":[],"mappings":"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"}

package/dist/types/subscription-util.d.ts

@@ -0,0 +1,19 @@
+import { DwnRecordSubscriptionHandler, PermissionsApi, Web5Agent } from '@enbox/agent';
+import { RecordsSubscribeRequest } from './dwn-api.js';
+/**
+ * Utility class for dealing with subscriptions.
+ */
+export declare class SubscriptionUtil {
+    /**
+     * Creates a record subscription handler that can be used to process incoming {Record} messages.
+     */
+    static recordSubscriptionHandler({ agent, connectedDid, request, delegateDid, protocolRole, permissionsApi }: {
+        agent: Web5Agent;
+        connectedDid: string;
+        delegateDid?: string;
+        protocolRole?: string;
+        permissionsApi?: PermissionsApi;
+        request: RecordsSubscribeRequest;
+    }): DwnRecordSubscriptionHandler;
+}
+//# sourceMappingURL=subscription-util.d.ts.map

package/dist/types/subscription-util.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subscription-util.d.ts","sourceRoot":"","sources":["../../src/subscription-util.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,4BAA4B,EAAmB,cAAc,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACxG,OAAO,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAC;AAGvD;;GAEG;AACH,qBAAa,gBAAgB;IAC3B;;OAEG;IACH,MAAM,CAAC,yBAAyB,CAAC,EAAE,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,cAAc,EAAE,EAAC;QAC3G,KAAK,EAAE,SAAS,CAAC;QACjB,YAAY,EAAE,MAAM,CAAC;QACrB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,cAAc,CAAC,EAAE,cAAc,CAAC;QAChC,OAAO,EAAE,uBAAuB,CAAC;KAClC,GAAG,4BAA4B;CAuBjC"}