@dwn-protocol/id-sdk 0.2.5 → 0.2.6

package/src/dwn-api.ts

@@ -1,584 +0,0 @@
-import type { DwnResponse, IDAgent } from './agent/index.js';
-import type {
-  RecordsReadOptions,
-  RecordsQueryOptions,
-  RecordsWriteMessage,
-  RecordsWriteOptions,
-  RecordsDeleteOptions,
-  ProtocolsQueryOptions,
-  RecordsQueryReplyEntry,
-  ProtocolsConfigureMessage,
-  ProtocolsConfigureOptions,
-  ProtocolsConfigureDescriptor,
-} from '@dwn-protocol/id';
-
-import { isEmptyObject } from './common/index.js';
-import { DwnInterfaceName, DwnMethodName, RecordsWrite } from '@dwn-protocol/id';
-
-import { Record } from './record.js';
-import { Protocol } from './protocol.js';
-import { dataToBlob } from './utils.js';
-
-import { getServiceDwnEndpoints } from './service-options.js';
-
-/**
- * Status code and detailed message for a response.
- *
- * @beta
- */
-export type ResponseStatus = {
-  status: {
-    code: number;
-    detail: string;
-  };
-};
-
-/**
- * Request to setup a protocol with its definitions
- *
- * @beta
- */
-export type ProtocolsConfigureRequest = {
-  message: Omit<ProtocolsConfigureOptions, 'signer'>;
-}
-
-/**
- * Response for the protocol configure request
- *
- * @beta
- */
-export type ProtocolsConfigureResponse = ResponseStatus & {
-  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, 'signer'>
-}
-
-/**
- * Response with the retrieved protocols
- *
- * @beta
- */
-export type ProtocolsQueryResponse = ResponseStatus & {
-  protocols: Protocol[];
-}
-
-/**
- * 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, 'signer'>;
-  record: Record;
-  target?: string;
-}
-
-/**
- * Request to delete a record from the DWN
- *
- * @beta
- */
-export type RecordsDeleteRequest = {
-  from?: string;
-  message: Omit<RecordsDeleteOptions, 'signer'>;
-}
-
-/**
- * Response for the read request
- *
- * @beta
- */
-export type RecordsQueryRequest = {
-  /** The from property indicates the DID to query from and return results. */
-  from?: string;
-  message: Omit<RecordsQueryOptions, 'signer'>;
-}
-
-/**
- * Response for the query request
- *
- * @beta
- */
-export type RecordsQueryResponse = ResponseStatus & {
-  records?: Record[],
-  /** If there are additional results, the messageCid of the last record will be returned as a pagination cursor. */
-  cursor?: string;
-};
-
-/**
- * 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, 'signer'>;
-}
-
-/**
- * Response for the read request
- *
- * @beta
- */
-export type RecordsReadResponse = ResponseStatus & {
-  record: Record;
-};
-
-/**
- * Request to write a record to the DWN
- *
- * @beta
- */
-export type RecordsWriteRequest = {
-  data: unknown;
-  message?: Omit<Partial<RecordsWriteOptions>, 'signer'>;
-  store?: boolean;
-  target?: string;
-}
-
-/**
- * Response for the write request
- *
- * @beta
- */
-export type RecordsWriteResponse = ResponseStatus & {
-  record?: Record
-};
-
-/**
- * Interface to interact with DWN Records and Protocols
- *
- * @beta
- */
-export class DwnApi {
-  private agent: IDAgent;
-  private connectedDid: string;
-
-  constructor(options: { agent: IDAgent, connectedDid: string }) {
-    this.agent = options.agent;
-    this.connectedDid = options.connectedDid;
-  }
-
-  /**
-  * API to interact with DWN protocols (e.g., `dwn.protocols.configure()`).
-  */
-  get protocols() {
-    return {
-      /**
-       * 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({
-          target         : this.connectedDid,
-          author         : this.connectedDid,
-          messageOptions : request.message,
-          messageType    : DwnInterfaceName.Protocols + DwnMethodName.Configure
-        });
-
-        const { message, messageCid, reply: { status }} = agentResponse;
-        const response: ProtocolsConfigureResponse = { status };
-
-        if (status.code < 300) {
-          const metadata = { author: this.connectedDid, messageCid };
-          response.protocol = new Protocol(this.agent, message as ProtocolsConfigureMessage, metadata);
-        }
-
-        return response;
-      },
-
-      /**
-       * Query the available protocols
-       */
-      query: async (request: ProtocolsQueryRequest): Promise<ProtocolsQueryResponse> => {
-        const agentRequest = {
-          author         : this.connectedDid,
-          messageOptions : request.message,
-          messageType    : DwnInterfaceName.Protocols + DwnMethodName.Query,
-          target         : request.from || this.connectedDid
-        };
-
-        let agentResponse: DwnResponse;
-
-        if (request.from) {
-          agentResponse = await this.agent.sendDwnRequest(agentRequest);
-        } else {
-          agentResponse = await this.agent.processDwnRequest(agentRequest);
-        }
-
-        const { reply: { entries = [], status } } = agentResponse;
-
-        const protocols = entries.map((entry: ProtocolsQueryReplyEntry) => {
-          const metadata = { author: this.connectedDid, };
-          //@ts-ignore
-          return new Protocol(this.agent, entry as ProtocolsConfigureMessage, metadata);
-          // @todo fix the type, then remove `as ProtocolsConfigureMessage ^
-        });
-
-        return { protocols, status };
-      }
-    };
-  }
-
-  /**
-   * API to interact with DWN records (e.g., `dwn.records.create()`).
-   */
-  get records() {
-    return {
-      /**
-       * Alias for the `write` method
-       */
-      create: async (request: RecordsCreateRequest): Promise<RecordsCreateResponse> => {
-        return this.records.write(request);
-      },
-
-      /**
-       * 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();
-
-        // Remove target from inherited properties since target is being explicitly defined in method parameters.
-        delete inheritedProperties.target;
-
-
-        // If `data` is being updated then `dataCid` and `dataSize` must not be present.
-        if (request.data !== undefined) {
-          delete inheritedProperties.dataCid;
-          delete inheritedProperties.dataSize;
-        }
-
-        // Ensure update gets a new messageTimestamp so it's always "newer" than the original.
-        // Mirrors @abaxxtech/id RecordsWrite.createFrom behavior.
-        delete inheritedProperties.messageTimestamp;
-
-        // 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 (request.message?.published === false && inheritedProperties.datePublished !== undefined) {
-          delete inheritedProperties.datePublished;
-          delete inheritedProperties.published;
-        }
-
-        // If the request changes the `author` or message `descriptor` then the deterministic `recordId` will change.
-        // As a result, we will discard the `recordId` if either of these changes occur.
-        // NOTE: `isEmptyObject(undefined)` returns false, so we must guard against undefined/null
-        // to avoid discarding `recordId` when no message overrides are provided (update case).
-        const hasMessageOverrides = request.message != null && !isEmptyObject(request.message);
-        const hasAuthorChange = request.author && request.author !== inheritedAuthor;
-        if (hasMessageOverrides || hasAuthorChange) {
-          delete inheritedProperties.recordId;
-        }
-
-        return this.records.write({
-          data    : request.data,
-          target  : request.target,
-          message : {
-            ...inheritedProperties,
-            ...request.message,
-          },
-        });
-      },
-
-      /**
-       * Delete a record
-       */
-      delete: async (request: RecordsDeleteRequest): Promise<ResponseStatus> => {
-        const agentRequest = {
-          author         : this.connectedDid,
-          messageOptions : request.message,
-          messageType    : DwnInterfaceName.Records + DwnMethodName.Delete,
-          target         : request.from || this.connectedDid
-        };
-
-        let agentResponse: DwnResponse;
-
-        if (request.from) {
-          agentResponse = await this.agent.sendDwnRequest(agentRequest);
-        } else {
-          agentResponse = await this.agent.processDwnRequest(agentRequest);
-        }
-
-        const { reply: { status } } = agentResponse;
-        return { status };
-      },
-
-      /**
-       * Query a single or multiple records based on the given filter
-       */
-      query: async (request: RecordsQueryRequest): Promise<RecordsQueryResponse> => {
-        const agentRequest = {
-          author         : this.connectedDid,
-          messageOptions : request.message,
-          messageType    : DwnInterfaceName.Records + DwnMethodName.Query,
-          target         : request.from || this.connectedDid
-        };
-
-        let agentResponse: DwnResponse;
-
-        if (request.from) {
-          agentResponse = await this.agent.sendDwnRequest(agentRequest);
-        } else {
-          agentResponse = await this.agent.processDwnRequest(agentRequest);
-        }
-
-        const { reply: { entries, status, cursor } } = agentResponse;
-
-        const records = entries.map((entry: RecordsQueryReplyEntry) => {
-          const recordOptions = {
-            /**
-             * Extract the `author` DID from the record entry since records may be signed by the
-             * tenant owner or any other entity.
-             */
-            author : RecordsWrite.getAuthor(entry),
-            /**
-             * Set the `target` DID to currently connected DID so that subsequent calls to
-             * {@link Record} instance methods, such as `record.update()` are executed on the
-             * local DWN even if the record was returned by a query of a remote DWN.
-             */
-            target : this.connectedDid,
-            ...entry as RecordsWriteMessage
-          };
-          const record = new Record(this.agent, recordOptions);
-          return record;
-        });
-
-        return { records, status, cursor };
-      },
-
-      /**
-       * Read a single record based on the given filter
-       */
-      read: async (request: RecordsReadRequest): Promise<RecordsReadResponse> => {
-        const agentRequest = {
-          author         : this.connectedDid,
-          messageOptions : request.message,
-          messageType    : DwnInterfaceName.Records + DwnMethodName.Read,
-          target         : request.from || this.connectedDid
-        };
-
-        let agentResponse: DwnResponse;
-
-        if (request.from) {
-          agentResponse = await this.agent.sendDwnRequest(agentRequest);
-        } else {
-          agentResponse = await this.agent.processDwnRequest(agentRequest);
-        }
-
-        const { reply: { record: responseRecord, status } } = agentResponse;
-
-        let record: Record;
-        if (200 <= status.code && status.code <= 299) {
-          const recordOptions = {
-            author : RecordsWrite.getAuthor(responseRecord),
-            target : this.connectedDid,
-            ...responseRecord,
-          };
-
-          record = new Record(this.agent, recordOptions);
-        }
-
-        return { record, status };
-      },
-
-      /**
-       * 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'
-       * parameter of 10KB. This is done to maintain consistency with other DWN methods,
-       * like RecordsQuery, that include relatively small data payloads when returning
-       * RecordsWrite message properties. Regardless of data size, methods such as
-       * `record.data.stream()` will return the data when called even if it requires fetching
-       * from the DWN datastore.
-       */
-      write: async (request: RecordsWriteRequest): Promise<RecordsWriteResponse> => {
-        const messageOptions: Partial<RecordsWriteOptions> = {
-          ...request.message
-        };
-
-        const { dataBlob, dataFormat } = dataToBlob(request.data, messageOptions.dataFormat);
-        messageOptions.dataFormat = dataFormat;
-
-        const target = request.target || this.connectedDid;
-        const isRemote = target !== this.connectedDid;
-
-        let agentResponse: DwnResponse;
-
-        if (isRemote) {
-          agentResponse = await this.agent.sendDwnRequest({
-            author      : this.connectedDid,
-            dataStream  : dataBlob,
-            messageOptions,
-            messageType : DwnInterfaceName.Records + DwnMethodName.Write,
-            target      : target
-          });
-        } else {
-          agentResponse = await this.agent.processDwnRequest({
-            author      : this.connectedDid,
-            dataStream  : dataBlob,
-            messageOptions,
-            messageType : DwnInterfaceName.Records + DwnMethodName.Write,
-            store       : request.store,
-            target      : this.connectedDid
-          });
-        }
-
-        const { message, reply: { status } } = agentResponse;
-        const responseMessage = message as RecordsWriteMessage;
-
-        let record: Record;
-        if (200 <= status.code && status.code <= 299) {
-          const recordOptions = {
-            author      : this.connectedDid,
-            encodedData : dataBlob,
-            target      : target,
-            ...responseMessage,
-          };
-
-          record = new Record(this.agent, recordOptions);
-        }
-
-        return { record, status };
-      },
-    };
-  }
-
-  /**
-   * API to retrieve the service nodes via did:web:dwn.x.id.
-   */
-  async getServiceNodes(): Promise<any> {
-    return await getServiceDwnEndpoints();
-  }
-
-  /**
-   * Helper method to resolve encryption keys from a recipient's DID.
-   * This can be used to get encryption keys before creating an encrypted RecordsWrite.
-   *
-   * @param recipientDid - The DID of the recipient
-   * @param options - Optional configuration
-   * @param options.useRelayEndpoint - If true, uses the relay's /api/did/:did/encryption-keys endpoint (default: false)
-   * @param options.relayUrl - The relay URL to use (default: tries to detect from service endpoints)
-   * @returns Array of encryption keys with keyId, publicKeyJwk, and keyType
-   */
-  async resolveRecipientEncryptionKeys(
-    recipientDid: string,
-    options?: { useRelayEndpoint?: boolean; relayUrl?: string }
-  ): Promise<Array<{ keyId: string; publicKeyJwk: any; keyType: string }>> {
-    const { useRelayEndpoint = false, relayUrl } = options || {};
-
-    // Option 1: Use relay endpoint if specified
-    if (useRelayEndpoint) {
-      try {
-        const url = relayUrl || (await getServiceDwnEndpoints())[0] || 'http://localhost:8085';
-        const response = await fetch(`${url}/api/did/${recipientDid}/encryption-keys`);
-        const result = await response.json();
-
-        if (result.ok && result.encryptionKeys) {
-          return result.encryptionKeys;
-        }
-      } catch (error) {
-        console.warn('Failed to resolve encryption keys via relay endpoint:', error);
-      }
-    }
-
-    // Option 2: Use SDK's built-in DID resolver
-    try {
-      // Check if agent has didResolver (IDManagedAgent)
-      const managedAgent = this.agent as any;
-      if (!managedAgent.didResolver) {
-        throw new Error('DID resolver not available. Use useRelayEndpoint: true or ensure agent is properly initialized.');
-      }
-
-      const { didDocument } = await managedAgent.didResolver.resolve(recipientDid);
-
-      if (!didDocument) {
-        throw new Error(`DID document not found for ${recipientDid}`);
-      }
-
-      const encryptionKeys: Array<{ keyId: string; publicKeyJwk: any; keyType: string }> = [];
-
-      // Look for verification methods with publicKeyJwk
-      if (didDocument.verificationMethod) {
-        for (const vm of didDocument.verificationMethod) {
-          if (vm.publicKeyJwk && vm.id) {
-            const keyId = vm.id.includes('#') ? vm.id.split('#')[1] : vm.id;
-            if (keyId) {
-              encryptionKeys.push({
-                keyId,
-                publicKeyJwk : vm.publicKeyJwk,
-                keyType      : vm.type || 'Unknown',
-              });
-            }
-          }
-        }
-      }
-
-      // Also check keyAgreement section
-      if (didDocument.keyAgreement) {
-        for (const ka of didDocument.keyAgreement) {
-          if (typeof ka === 'string') {
-            const keyId = ka.includes('#') ? ka.split('#')[1] : ka;
-            const vm = didDocument.verificationMethod?.find(
-              (v) => v.id === ka || v.id.endsWith(`#${keyId}`)
-            );
-            if (vm?.publicKeyJwk && keyId) {
-              encryptionKeys.push({
-                keyId,
-                publicKeyJwk : vm.publicKeyJwk,
-                keyType      : vm.type || 'Unknown',
-              });
-            }
-          } else if (ka.publicKeyJwk) {
-            const keyId = ka.id?.includes('#')
-              ? ka.id.split('#')[1]
-              : ka.id || 'unknown';
-            if (keyId) {
-              encryptionKeys.push({
-                keyId,
-                publicKeyJwk : ka.publicKeyJwk,
-                keyType      : ka.type || 'Unknown',
-              });
-            }
-          }
-        }
-      }
-
-      return encryptionKeys;
-    } catch (error: any) {
-      throw new Error(`Failed to resolve encryption keys for ${recipientDid}: ${error.message}`);
-    }
-  }
-}