@veramo/utils - npm Package Compare versions

Comparing version 3.1.5-next.127 to 3.1.6-next.129

build/credential-utils.d.ts

 import { CredentialPayload, IMessage, PresentationPayload, VerifiableCredential, VerifiablePresentation, W3CVerifiableCredential, W3CVerifiablePresentation } from '@veramo/core';
+/**
+ * Every Verifiable Credential `@context` property must contain this.
+ *
+ * @public
+ */
 export declare const MANDATORY_CREDENTIAL_CONTEXT = "https://www.w3.org/2018/credentials/v1";
@@ -6,24 +11,23 @@ /**
  * set as the first item in the result array.
- * @param inputEntryOrArray
- * @param startWithEntry
+ * @param inputEntryOrArray - The input that needs to be transformed to an array.
+ * @param startWithEntry - If this is provided, this element will be the first in the resulting array.
  *
- * @beta This API may change without prior notice.
+ * @beta This API may change without a BREAKING CHANGE notice.
  */
 export declare function processEntryToArray(inputEntryOrArray?: string | string[] | null, startWithEntry?: string): string[];
 /**
- * Parses a {@link W3CVerifiableCredential} and converts it to a {@link VerifiableCredential} so it is easier to use
- * programmatically.
+ * Parses a {@link @veramo/core#W3CVerifiableCredential | W3CVerifiableCredential} and converts it to a
+ * {@link @veramo/core#VerifiableCredential | VerifiableCredential} so it is easier to use programmatically.
  *
- * @param input
-
- * @beta This API may change without prior notice.
+ * @param input - the raw credential to be transformed
+ * @beta This API may change without a BREAKING CHANGE notice.
  */
 export declare function decodeCredentialToObject(input: W3CVerifiableCredential): VerifiableCredential;
 /**
- * Parses a {@link W3CVerifiableCredential} and converts it to a {@link VerifiablePresentation} so it is easier to use
- * programmatically.
+ * Parses a {@link @veramo/core#W3CVerifiablePresentation | W3CVerifiablePresentation} and converts it to a
+ * {@link @veramo/core#VerifiablePresentation | VerifiablePresentation} so it is easier to use programmatically.
  *
- * @param input
-
- * @beta This API may change without prior notice.
+ * @param input - the raw presentation to be transformed.
+ *
+ * @beta This API may change without a BREAKING CHANGE notice.
  */
@@ -35,5 +39,5 @@ export declare function decodePresentationToObject(input: W3CVerifiablePresentation): VerifiablePresentation;
  *
- * @param input
+ * @param input - the Credential or Presentation whose hash is neeeded
  *
- * @beta This API may change without prior notice.
+ * @beta This API may change without a BREAKING CHANGE notice.
  */
@@ -45,7 +49,7 @@ export declare function computeEntryHash(input: W3CVerifiableCredential | W3CVerifiablePresentation | IMessage): string;
  *
- * @param input
+ * @param input - the credential or presentation whose issuer/holder needs to be extracted.
  *
- * @beta This API may change without prior notice.
+ * @beta This API may change without a BREAKING CHANGE notice.
  */
 export declare function extractIssuer(input?: W3CVerifiableCredential | W3CVerifiablePresentation | CredentialPayload | PresentationPayload | null): string;
 //# sourceMappingURL=credential-utils.d.ts.map

build/credential-utils.js

@@ -8,2 +8,7 @@ "use strict";
 const did_jwt_vc_1 = require("did-jwt-vc");
+/**
+ * Every Verifiable Credential `@context` property must contain this.
+ *
+ * @public
+ */
 exports.MANDATORY_CREDENTIAL_CONTEXT = 'https://www.w3.org/2018/credentials/v1';
@@ -13,6 +18,6 @@ /**
  * set as the first item in the result array.
- * @param inputEntryOrArray
- * @param startWithEntry
+ * @param inputEntryOrArray - The input that needs to be transformed to an array.
+ * @param startWithEntry - If this is provided, this element will be the first in the resulting array.
  *
- * @beta This API may change without prior notice.
+ * @beta This API may change without a BREAKING CHANGE notice.
  */
@@ -28,8 +33,7 @@ function processEntryToArray(inputEntryOrArray, startWithEntry) {
 /**
- * Parses a {@link W3CVerifiableCredential} and converts it to a {@link VerifiableCredential} so it is easier to use
- * programmatically.
+ * Parses a {@link @veramo/core#W3CVerifiableCredential | W3CVerifiableCredential} and converts it to a
+ * {@link @veramo/core#VerifiableCredential | VerifiableCredential} so it is easier to use programmatically.
  *
- * @param input
-
- * @beta This API may change without prior notice.
+ * @param input - the raw credential to be transformed
+ * @beta This API may change without a BREAKING CHANGE notice.
  */
@@ -41,8 +45,8 @@ function decodeCredentialToObject(input) {
 /**
- * Parses a {@link W3CVerifiableCredential} and converts it to a {@link VerifiablePresentation} so it is easier to use
- * programmatically.
+ * Parses a {@link @veramo/core#W3CVerifiablePresentation | W3CVerifiablePresentation} and converts it to a
+ * {@link @veramo/core#VerifiablePresentation | VerifiablePresentation} so it is easier to use programmatically.
  *
- * @param input
-
- * @beta This API may change without prior notice.
+ * @param input - the raw presentation to be transformed.
+ *
+ * @beta This API may change without a BREAKING CHANGE notice.
  */
@@ -65,5 +69,5 @@ function decodePresentationToObject(input) {
  *
- * @param input
+ * @param input - the Credential or Presentation whose hash is neeeded
  *
- * @beta This API may change without prior notice.
+ * @beta This API may change without a BREAKING CHANGE notice.
  */
@@ -95,5 +99,5 @@ function computeEntryHash(input) {
  *
- * @param input
+ * @param input - the credential or presentation whose issuer/holder needs to be extracted.
  *
- * @beta This API may change without prior notice.
+ * @beta This API may change without a BREAKING CHANGE notice.
  */
@@ -100,0 +104,0 @@ function extractIssuer(input) {

build/did-utils.d.ts

 import { DIDDocumentSection, IAgentContext, IIdentifier, IKey, IResolver } from '@veramo/core';
 import { DIDDocument } from 'did-resolver';
 import { _ExtendedIKey, _ExtendedVerificationMethod, _NormalizedVerificationMethod } from './types/utility-types';
+/**
+ * Converts any Ed25519 keys of an {@link @veramo/core#IIdentifier | IIdentifier} to X25519 to be usable for encryption.
+ *
+ * @param identifier - the identifier with keys
+ *
+ * @returns the array of converted keys filtered to contain only those usable for encryption.
+ *
+ * @beta This API may change without a BREAKING CHANGE notice.
+ */
 export declare function convertIdentifierEncryptionKeys(identifier: IIdentifier): IKey[];
+/**
+ * Converts any Secp256k1 public keys of an {@link @veramo/core#IIdentifier | IIdentifier} to their compressed form.
+ *
+ * @param identifier - the identifier with keys
+ *
+ * @returns the array of keys where the Secp256k1 entries are compressed.
+ *
+ * @beta This API may change without a BREAKING CHANGE notice.
+ */
 export declare function compressIdentifierSecp256k1Keys(identifier: IIdentifier): IKey[];
+/**
+ * Extracts an ethereum address from a {@link did-resolver#VerificationMethod | verification method} supporting legacy
+ * representations.
+ *
+ * @param verificationMethod - the VerificationMethod object (from a DID document)
+ *
+ * @returns an ethereum address `string` or `undefined` if none could be extracted
+ *
+ * @beta This API may change without a BREAKING CHANGE notice.
+ */
 export declare function getEthereumAddress(verificationMethod: _NormalizedVerificationMethod): string | undefined;
+/**
+ * Extracts the chain ID from a {@link did-resolver#VerificationMethod | verification method} supporting legacy
+ * representations as well.
+ *
+ * @param verificationMethod - the VerificationMethod object (from a DID document)
+ *
+ * @returns a chain ID `number` or `undefined` if none could be extracted.
+ *
+ * @beta This API may change without a BREAKING CHANGE notice.
+ */
 export declare function getChainIdForDidEthr(verificationMethod: _NormalizedVerificationMethod): number;
+/**
+ * Maps the keys of a locally managed {@link @veramo/core#IIdentifier | IIdentifier} to the corresponding
+ * {@link did-resolver#VerificationMethod | VerificationMethod} entries from the DID document.
+ *
+ * @param identifier - the identifier to be mapped
+ * @param section - the section of the DID document to be mapped (see
+ *   {@link https://www.w3.org/TR/did-core/#verification-relationships | verification relationships}), but can also be
+ *   `verificationMethod` to map all the keys.
+ * @param context - the veramo agent context, which must contain a {@link @veramo/core#IResolver | IResolver}
+ *   implementation that can resolve the DID document of the identifier.
+ *
+ * @returns an array of mapped keys. The corresponding verification method is added to the `meta.verificationMethod`
+ *   property of the key.
+ *
+ * @beta This API may change without a BREAKING CHANGE notice.
+ */
 export declare function mapIdentifierKeysToDoc(identifier: IIdentifier, section: DIDDocumentSection | undefined, context: IAgentContext<IResolver>): Promise<_ExtendedIKey[]>;
+/**
+ * Resolve a DID document or throw an error if the resolution fails.
+ *
+ * @param didUrl - the DID to be resolved
+ * @param context - the veramo agent context, which must contain a {@link @veramo/core#IResolver | IResolver}
+ *   implementation that can resolve the DID document of the `didUrl`.
+ *
+ * @returns a {@link did-resolver#DIDDocument | DIDDocument} if resolution is successful
+ * @throws if the resolution fails
+ *
+ * @beta This API may change without a BREAKING CHANGE notice.
+ */
 export declare function resolveDidOrThrow(didUrl: string, context: IAgentContext<IResolver>): Promise<DIDDocument>;
@@ -16,3 +82,5 @@ /**
  *
- * @returns Promise<NormalizedVerificationMethod[]>
+ * @returns a Promise that resolves to the list of dereferenced keys.
+ *
+ * @beta This API may change without a BREAKING CHANGE notice.
  */
@@ -23,7 +91,9 @@ export declare function dereferenceDidKeys(didDocument: DIDDocument, section: DIDDocumentSection | undefined, context: IAgentContext<IResolver>): Promise<_NormalizedVerificationMethod[]>;
  *
- * @param pk the VerificationMethod to be converted
- * @param convert when this flag is set to true, Ed25519 keys are converted to their X25519 pairs
- * @returns
+ * @param pk - the VerificationMethod to be converted
+ * @param convert - when this flag is set to true, Ed25519 keys are converted to their X25519 pairs
+ * @returns the hex encoding of the public key
+ *
+ * @beta This API may change without a BREAKING CHANGE notice.
  */
 export declare function extractPublicKeyHex(pk: _ExtendedVerificationMethod, convert?: boolean): string;
 //# sourceMappingURL=did-utils.d.ts.map

build/did-utils.js

@@ -57,2 +57,11 @@ "use strict";
 const debug = (0, debug_1.default)('veramo:utils');
+/**
+ * Converts any Ed25519 keys of an {@link @veramo/core#IIdentifier | IIdentifier} to X25519 to be usable for encryption.
+ *
+ * @param identifier - the identifier with keys
+ *
+ * @returns the array of converted keys filtered to contain only those usable for encryption.
+ *
+ * @beta This API may change without a BREAKING CHANGE notice.
+ */
 function convertIdentifierEncryptionKeys(identifier) {
@@ -79,2 +88,11 @@ return identifier.keys
 exports.convertIdentifierEncryptionKeys = convertIdentifierEncryptionKeys;
+/**
+ * Converts any Secp256k1 public keys of an {@link @veramo/core#IIdentifier | IIdentifier} to their compressed form.
+ *
+ * @param identifier - the identifier with keys
+ *
+ * @returns the array of keys where the Secp256k1 entries are compressed.
+ *
+ * @beta This API may change without a BREAKING CHANGE notice.
+ */
 function compressIdentifierSecp256k1Keys(identifier) {
@@ -94,2 +112,14 @@ return identifier.keys
 exports.compressIdentifierSecp256k1Keys = compressIdentifierSecp256k1Keys;
+/**
+ * Compares the `blockchainAccountId` of a `EcdsaSecp256k1RecoveryMethod2020` verification method with the address
+ * computed from a locally managed key.
+ *
+ * @returns true if the local key address corresponds to the `blockchainAccountId`
+ *
+ * @param localKey - The locally managed key
+ * @param verificationMethod - a {@link did-resolver#VerificationMethod | VerificationMethod} with a
+ *   `blockchainAccountId`
+ *
+ * @beta This API may change without a BREAKING CHANGE notice.
+ */
 function compareBlockchainAccountId(localKey, verificationMethod) {
@@ -103,2 +133,12 @@ if (verificationMethod.type !== 'EcdsaSecp256k1RecoveryMethod2020' || localKey.type !== 'Secp256k1') {
 }
+/**
+ * Extracts an ethereum address from a {@link did-resolver#VerificationMethod | verification method} supporting legacy
+ * representations.
+ *
+ * @param verificationMethod - the VerificationMethod object (from a DID document)
+ *
+ * @returns an ethereum address `string` or `undefined` if none could be extracted
+ *
+ * @beta This API may change without a BREAKING CHANGE notice.
+ */
 function getEthereumAddress(verificationMethod) {
@@ -118,2 +158,12 @@ var _a, _b, _c, _d, _e;
 exports.getEthereumAddress = getEthereumAddress;
+/**
+ * Extracts the chain ID from a {@link did-resolver#VerificationMethod | verification method} supporting legacy
+ * representations as well.
+ *
+ * @param verificationMethod - the VerificationMethod object (from a DID document)
+ *
+ * @returns a chain ID `number` or `undefined` if none could be extracted.
+ *
+ * @beta This API may change without a BREAKING CHANGE notice.
+ */
 function getChainIdForDidEthr(verificationMethod) {
@@ -130,2 +180,18 @@ var _a, _b;
 exports.getChainIdForDidEthr = getChainIdForDidEthr;
+/**
+ * Maps the keys of a locally managed {@link @veramo/core#IIdentifier | IIdentifier} to the corresponding
+ * {@link did-resolver#VerificationMethod | VerificationMethod} entries from the DID document.
+ *
+ * @param identifier - the identifier to be mapped
+ * @param section - the section of the DID document to be mapped (see
+ *   {@link https://www.w3.org/TR/did-core/#verification-relationships | verification relationships}), but can also be
+ *   `verificationMethod` to map all the keys.
+ * @param context - the veramo agent context, which must contain a {@link @veramo/core#IResolver | IResolver}
+ *   implementation that can resolve the DID document of the identifier.
+ *
+ * @returns an array of mapped keys. The corresponding verification method is added to the `meta.verificationMethod`
+ *   property of the key.
+ *
+ * @beta This API may change without a BREAKING CHANGE notice.
+ */
 function mapIdentifierKeysToDoc(identifier, section = 'keyAgreement', context) {
@@ -161,2 +227,14 @@ return __awaiter(this, void 0, void 0, function* () {
 exports.mapIdentifierKeysToDoc = mapIdentifierKeysToDoc;
+/**
+ * Resolve a DID document or throw an error if the resolution fails.
+ *
+ * @param didUrl - the DID to be resolved
+ * @param context - the veramo agent context, which must contain a {@link @veramo/core#IResolver | IResolver}
+ *   implementation that can resolve the DID document of the `didUrl`.
+ *
+ * @returns a {@link did-resolver#DIDDocument | DIDDocument} if resolution is successful
+ * @throws if the resolution fails
+ *
+ * @beta This API may change without a BREAKING CHANGE notice.
+ */
 function resolveDidOrThrow(didUrl, context) {
@@ -183,3 +261,5 @@ var _a, _b;
  *
- * @returns Promise<NormalizedVerificationMethod[]>
+ * @returns a Promise that resolves to the list of dereferenced keys.
+ *
+ * @beta This API may change without a BREAKING CHANGE notice.
  */
@@ -225,5 +305,7 @@ function dereferenceDidKeys(didDocument, section = 'keyAgreement', context) {
  *
- * @param pk the VerificationMethod to be converted
- * @param convert when this flag is set to true, Ed25519 keys are converted to their X25519 pairs
- * @returns
+ * @param pk - the VerificationMethod to be converted
+ * @param convert - when this flag is set to true, Ed25519 keys are converted to their X25519 pairs
+ * @returns the hex encoding of the public key
+ *
+ * @beta This API may change without a BREAKING CHANGE notice.
  */
@@ -230,0 +312,0 @@ function extractPublicKeyHex(pk, convert = false) {

build/encodings.d.ts

@@ -0,7 +1,53 @@
+/**
+ * Converts a Uint8Array to a base64url string
+ * @param b - the array to be converted
+ *
+ * @public
+ */
 export declare function bytesToBase64url(b: Uint8Array): string;
+/**
+ * Converts a base64url string to the Uint8Array it represents.
+ *
+ * @param s - the string to be converted
+ *
+ * @throws if the string is not formatted correctly.
+ *
+ * @public
+ */
 export declare function base64ToBytes(s: string): Uint8Array;
+/**
+ * Encodes a Uint8Array to a base64 string representation with padding.
+ * @param b - the byte array to convert
+ *
+ * @public
+ */
 export declare function bytesToBase64(b: Uint8Array): string;
+/**
+ * Encodes the bytes of an input string to base64url
+ * @param s - the original string
+ *
+ * @beta This API may change without a BREAKING CHANGE notice.
+ */
 export declare function encodeBase64url(s: string): string;
+/**
+ * Decodes a base64url string to a utf8 string represented by the same bytes.
+ * @param s - the base64url string to be decoded
+ *
+ * @beta This API may change without a BREAKING CHANGE notice.
+ */
 export declare function decodeBase64url(s: string): string;
+/**
+ * Stringifies a JSON object and encodes the bytes of the resulting string to a base64url representation.
+ * @param payload - the object to be encoded
+ *
+ * @beta This API may change without a BREAKING CHANGE notice.
+ */
 export declare function encodeJoseBlob(payload: {}): string;
+/**
+ * Decodes a base64url string representing stringified JSON to a JSON object.
+ *
+ * @param blob - The base64url encoded stringified JSON to be decoded
+ *
+ * @beta This API may change without a BREAKING CHANGE notice.
+ */
 export declare function decodeJoseBlob(blob: string): any;
@@ -15,5 +61,19 @@ /**
  * @throws `illegal_argument` error if the parameter is not a string
+ *
+ * @beta This API may change without a BREAKING CHANGE notice.
  */
 export declare function hexToBytes(hexString: string): Uint8Array;
+/**
+ * Converts a Uint8Array input to a hex string
+ *
+ * @param byteArray - The array to be converted
+ * @param prefix - If this is set to true, the resulting hex string will be prefixed with 0x
+ *
+ * @returns the hex encoding of the input byte array
+ *
+ * @throws `illegal_argument` error if the input is not a Uint8Array
+ *
+ * @beta This API may change without a BREAKING CHANGE notice.
+ */
 export declare function bytesToHex(byteArray: Uint8Array, prefix?: boolean): string;
 //# sourceMappingURL=encodings.d.ts.map

build/encodings.js

@@ -28,2 +28,8 @@ "use strict";
 const u8a = __importStar(require("uint8arrays"));
+/**
+ * Converts a Uint8Array to a base64url string
+ * @param b - the array to be converted
+ *
+ * @public
+ */
 function bytesToBase64url(b) {
@@ -33,2 +39,11 @@ return u8a.toString(b, 'base64url');
 exports.bytesToBase64url = bytesToBase64url;
+/**
+ * Converts a base64url string to the Uint8Array it represents.
+ *
+ * @param s - the string to be converted
+ *
+ * @throws if the string is not formatted correctly.
+ *
+ * @public
+ */
 function base64ToBytes(s) {
@@ -39,2 +54,8 @@ const inputBase64Url = s.replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, '');
 exports.base64ToBytes = base64ToBytes;
+/**
+ * Encodes a Uint8Array to a base64 string representation with padding.
+ * @param b - the byte array to convert
+ *
+ * @public
+ */
 function bytesToBase64(b) {
@@ -44,2 +65,8 @@ return u8a.toString(b, 'base64pad');
 exports.bytesToBase64 = bytesToBase64;
+/**
+ * Encodes the bytes of an input string to base64url
+ * @param s - the original string
+ *
+ * @beta This API may change without a BREAKING CHANGE notice.
+ */
 function encodeBase64url(s) {
@@ -49,2 +76,8 @@ return bytesToBase64url(u8a.fromString(s));
 exports.encodeBase64url = encodeBase64url;
+/**
+ * Decodes a base64url string to a utf8 string represented by the same bytes.
+ * @param s - the base64url string to be decoded
+ *
+ * @beta This API may change without a BREAKING CHANGE notice.
+ */
 function decodeBase64url(s) {
@@ -54,2 +87,8 @@ return u8a.toString(base64ToBytes(s));
 exports.decodeBase64url = decodeBase64url;
+/**
+ * Stringifies a JSON object and encodes the bytes of the resulting string to a base64url representation.
+ * @param payload - the object to be encoded
+ *
+ * @beta This API may change without a BREAKING CHANGE notice.
+ */
 function encodeJoseBlob(payload) {
@@ -59,2 +98,9 @@ return u8a.toString(u8a.fromString(JSON.stringify(payload), 'utf-8'), 'base64url');
 exports.encodeJoseBlob = encodeJoseBlob;
+/**
+ * Decodes a base64url string representing stringified JSON to a JSON object.
+ *
+ * @param blob - The base64url encoded stringified JSON to be decoded
+ *
+ * @beta This API may change without a BREAKING CHANGE notice.
+ */
 function decodeJoseBlob(blob) {
@@ -71,2 +117,4 @@ return JSON.parse(u8a.toString(u8a.fromString(blob, 'base64url'), 'utf-8'));
  * @throws `illegal_argument` error if the parameter is not a string
+ *
+ * @beta This API may change without a BREAKING CHANGE notice.
  */
@@ -86,2 +134,14 @@ function hexToBytes(hexString) {
 exports.hexToBytes = hexToBytes;
+/**
+ * Converts a Uint8Array input to a hex string
+ *
+ * @param byteArray - The array to be converted
+ * @param prefix - If this is set to true, the resulting hex string will be prefixed with 0x
+ *
+ * @returns the hex encoding of the input byte array
+ *
+ * @throws `illegal_argument` error if the input is not a Uint8Array
+ *
+ * @beta This API may change without a BREAKING CHANGE notice.
+ */
 function bytesToHex(byteArray, prefix = false) {
@@ -88,0 +148,0 @@ if (!(byteArray instanceof Uint8Array)) {

build/type-utils.d.ts

 /**
- * Checks if a variable is defined and not null
- * @param arg
+ * Checks if a variable is defined and not null.
+ * After this check, typescript sees the variable as defined.
  *
+ * @param arg - The input to be verified
+ *
+ * @returns true if the input variable is defined.
+ *
  * @beta This API may change without a BREAKING CHANGE notice.
@@ -9,5 +13,7 @@ */
 /**
- * Transforms an item or an array of items into an array of items
- * @param arg
+ * Ensures that a given input is an array. If the input is a single item, it is converted to an array with a single
+ * entry.
  *
+ * @param arg - a variable that needs to be converted to array
+ *
  * @beta This API may change without a BREAKING CHANGE notice.
@@ -18,3 +24,3 @@ */
  * Checks if an object is iterable (can be used for `for..of`)
- * @param obj
+ * @param obj - the variable to be checked
  *
@@ -21,0 +27,0 @@ * @beta This API may change without a BREAKING CHANGE notice.

build/type-utils.js

@@ -5,5 +5,9 @@ "use strict";
 /**
- * Checks if a variable is defined and not null
- * @param arg
+ * Checks if a variable is defined and not null.
+ * After this check, typescript sees the variable as defined.
  *
+ * @param arg - The input to be verified
+ *
+ * @returns true if the input variable is defined.
+ *
  * @beta This API may change without a BREAKING CHANGE notice.
@@ -16,5 +20,7 @@ */
 /**
- * Transforms an item or an array of items into an array of items
- * @param arg
+ * Ensures that a given input is an array. If the input is a single item, it is converted to an array with a single
+ * entry.
  *
+ * @param arg - a variable that needs to be converted to array
+ *
  * @beta This API may change without a BREAKING CHANGE notice.
@@ -28,3 +34,3 @@ */
  * Checks if an object is iterable (can be used for `for..of`)
- * @param obj
+ * @param obj - the variable to be checked
  *
@@ -31,0 +37,0 @@ * @beta This API may change without a BREAKING CHANGE notice.

build/types/utility-types.d.ts

@@ -30,3 +30,5 @@ import { IKey, KeyMetadata } from '@veramo/core';
 /**
- * Accept a Type or a Promise of that Type
+ * Accept a Type or a Promise of that Type.
+ *
+ * @internal
  */
@@ -37,4 +39,6 @@ export declare type OrPromise<T> = T | Promise<T>;
  * Both Map and Record are accepted.
+ *
+ * @beta This API may change without a BREAKING CHANGE notice.
  */
 export declare type RecordLike<T> = Map<string, T> | Record<string, T>;
 //# sourceMappingURL=utility-types.d.ts.map

package.json

 {
   "name": "@veramo/utils",
   "description": "Helper methods for Veramo plugins",
-  "version": "3.1.5-next.127+0c77d03e",
+  "version": "3.1.6-next.129+79c38723",
   "main": "build/index.js",
   "types": "build/index.d.ts",
   "scripts": {
-    "build": "tsc"
+    "build": "tsc",
+    "extract-api": "yarn veramo dev extract-api"
   },
@@ -13,3 +14,3 @@ "dependencies": {
     "@stablelib/ed25519": "^1.0.2",
-    "@veramo/core": "^3.1.5-next.127+0c77d03e",
+    "@veramo/core": "^3.1.6-next.129+79c38723",
     "blakejs": "^1.1.1",
@@ -42,3 +43,3 @@ "cross-fetch": "^3.1.4",
   "keywords": [],
-  "gitHead": "0c77d03ec5ec9e2091de3f74f67ab86a22cde197"
+  "gitHead": "79c387230219c92c1951d19b8ddf716308a46c5b"
 }

src/credential-utils.ts

@@ -16,2 +16,7 @@ import { asArray, isDefined } from './type-utils'
 
+/**
+ * Every Verifiable Credential `@context` property must contain this.
+ *
+ * @public
+ */
 export const MANDATORY_CREDENTIAL_CONTEXT = 'https://www.w3.org/2018/credentials/v1'
@@ -22,6 +27,6 @@
  * set as the first item in the result array.
- * @param inputEntryOrArray
- * @param startWithEntry
+ * @param inputEntryOrArray - The input that needs to be transformed to an array.
+ * @param startWithEntry - If this is provided, this element will be the first in the resulting array.
  *
- * @beta This API may change without prior notice.
+ * @beta This API may change without a BREAKING CHANGE notice.
  */
@@ -40,8 +45,7 @@ export function processEntryToArray(
 /**
- * Parses a {@link W3CVerifiableCredential} and converts it to a {@link VerifiableCredential} so it is easier to use
- * programmatically.
+ * Parses a {@link @veramo/core#W3CVerifiableCredential | W3CVerifiableCredential} and converts it to a
+ * {@link @veramo/core#VerifiableCredential | VerifiableCredential} so it is easier to use programmatically.
  *
- * @param input
-
- * @beta This API may change without prior notice.
+ * @param input - the raw credential to be transformed
+ * @beta This API may change without a BREAKING CHANGE notice.
  */
@@ -53,8 +57,8 @@ export function decodeCredentialToObject(input: W3CVerifiableCredential): VerifiableCredential {
 /**
- * Parses a {@link W3CVerifiableCredential} and converts it to a {@link VerifiablePresentation} so it is easier to use
- * programmatically.
+ * Parses a {@link @veramo/core#W3CVerifiablePresentation | W3CVerifiablePresentation} and converts it to a
+ * {@link @veramo/core#VerifiablePresentation | VerifiablePresentation} so it is easier to use programmatically.
  *
- * @param input
-
- * @beta This API may change without prior notice.
+ * @param input - the raw presentation to be transformed.
+ *
+ * @beta This API may change without a BREAKING CHANGE notice.
  */
@@ -78,5 +82,5 @@ export function decodePresentationToObject(input: W3CVerifiablePresentation): VerifiablePresentation {
  *
- * @param input
+ * @param input - the Credential or Presentation whose hash is neeeded
  *
- * @beta This API may change without prior notice.
+ * @beta This API may change without a BREAKING CHANGE notice.
  */
@@ -106,5 +110,5 @@ export function computeEntryHash(
  *
- * @param input
+ * @param input - the credential or presentation whose issuer/holder needs to be extracted.
  *
- * @beta This API may change without prior notice.
+ * @beta This API may change without a BREAKING CHANGE notice.
  */
@@ -111,0 +115,0 @@ export function extractIssuer(

src/did-utils.ts

@@ -14,4 +14,14 @@ import { convertPublicKeyToX25519, convertSecretKeyToX25519 } from '@stablelib/ed25519'
 import Debug from 'debug'
+
 const debug = Debug('veramo:utils')
 
+/**
+ * Converts any Ed25519 keys of an {@link @veramo/core#IIdentifier | IIdentifier} to X25519 to be usable for encryption.
+ *
+ * @param identifier - the identifier with keys
+ *
+ * @returns the array of converted keys filtered to contain only those usable for encryption.
+ *
+ * @beta This API may change without a BREAKING CHANGE notice.
+ */
 export function convertIdentifierEncryptionKeys(identifier: IIdentifier): IKey[] {
@@ -37,2 +47,11 @@ return identifier.keys
 
+/**
+ * Converts any Secp256k1 public keys of an {@link @veramo/core#IIdentifier | IIdentifier} to their compressed form.
+ *
+ * @param identifier - the identifier with keys
+ *
+ * @returns the array of keys where the Secp256k1 entries are compressed.
+ *
+ * @beta This API may change without a BREAKING CHANGE notice.
+ */
 export function compressIdentifierSecp256k1Keys(identifier: IIdentifier): IKey[] {
@@ -52,3 +71,18 @@ return identifier.keys
 
-function compareBlockchainAccountId(localKey: IKey, verificationMethod: _NormalizedVerificationMethod): boolean {
+/**
+ * Compares the `blockchainAccountId` of a `EcdsaSecp256k1RecoveryMethod2020` verification method with the address
+ * computed from a locally managed key.
+ *
+ * @returns true if the local key address corresponds to the `blockchainAccountId`
+ *
+ * @param localKey - The locally managed key
+ * @param verificationMethod - a {@link did-resolver#VerificationMethod | VerificationMethod} with a
+ *   `blockchainAccountId`
+ *
+ * @beta This API may change without a BREAKING CHANGE notice.
+ */
+function compareBlockchainAccountId(
+  localKey: IKey,
+  verificationMethod: _NormalizedVerificationMethod,
+): boolean {
   if (verificationMethod.type !== 'EcdsaSecp256k1RecoveryMethod2020' || localKey.type !== 'Secp256k1') {
@@ -62,2 +96,12 @@ return false
 
+/**
+ * Extracts an ethereum address from a {@link did-resolver#VerificationMethod | verification method} supporting legacy
+ * representations.
+ *
+ * @param verificationMethod - the VerificationMethod object (from a DID document)
+ *
+ * @returns an ethereum address `string` or `undefined` if none could be extracted
+ *
+ * @beta This API may change without a BREAKING CHANGE notice.
+ */
 export function getEthereumAddress(verificationMethod: _NormalizedVerificationMethod): string | undefined {
@@ -75,2 +119,12 @@ let vmEthAddr = verificationMethod.ethereumAddress?.toLowerCase()
 
+/**
+ * Extracts the chain ID from a {@link did-resolver#VerificationMethod | verification method} supporting legacy
+ * representations as well.
+ *
+ * @param verificationMethod - the VerificationMethod object (from a DID document)
+ *
+ * @returns a chain ID `number` or `undefined` if none could be extracted.
+ *
+ * @beta This API may change without a BREAKING CHANGE notice.
+ */
 export function getChainIdForDidEthr(verificationMethod: _NormalizedVerificationMethod): number {
@@ -85,2 +139,18 @@ if (verificationMethod.blockchainAccountId?.includes('@eip155')) {
 
+/**
+ * Maps the keys of a locally managed {@link @veramo/core#IIdentifier | IIdentifier} to the corresponding
+ * {@link did-resolver#VerificationMethod | VerificationMethod} entries from the DID document.
+ *
+ * @param identifier - the identifier to be mapped
+ * @param section - the section of the DID document to be mapped (see
+ *   {@link https://www.w3.org/TR/did-core/#verification-relationships | verification relationships}), but can also be
+ *   `verificationMethod` to map all the keys.
+ * @param context - the veramo agent context, which must contain a {@link @veramo/core#IResolver | IResolver}
+ *   implementation that can resolve the DID document of the identifier.
+ *
+ * @returns an array of mapped keys. The corresponding verification method is added to the `meta.verificationMethod`
+ *   property of the key.
+ *
+ * @beta This API may change without a BREAKING CHANGE notice.
+ */
 export async function mapIdentifierKeysToDoc(
@@ -126,2 +196,14 @@ identifier: IIdentifier,
 
+/**
+ * Resolve a DID document or throw an error if the resolution fails.
+ *
+ * @param didUrl - the DID to be resolved
+ * @param context - the veramo agent context, which must contain a {@link @veramo/core#IResolver | IResolver}
+ *   implementation that can resolve the DID document of the `didUrl`.
+ *
+ * @returns a {@link did-resolver#DIDDocument | DIDDocument} if resolution is successful
+ * @throws if the resolution fails
+ *
+ * @beta This API may change without a BREAKING CHANGE notice.
+ */
 export async function resolveDidOrThrow(
@@ -148,3 +230,5 @@ didUrl: string,
  *
- * @returns Promise<NormalizedVerificationMethod[]>
+ * @returns a Promise that resolves to the list of dereferenced keys.
+ *
+ * @beta This API may change without a BREAKING CHANGE notice.
  */
@@ -194,5 +278,7 @@ export async function dereferenceDidKeys(
  *
- * @param pk the VerificationMethod to be converted
- * @param convert when this flag is set to true, Ed25519 keys are converted to their X25519 pairs
- * @returns
+ * @param pk - the VerificationMethod to be converted
+ * @param convert - when this flag is set to true, Ed25519 keys are converted to their X25519 pairs
+ * @returns the hex encoding of the public key
+ *
+ * @beta This API may change without a BREAKING CHANGE notice.
  */
@@ -199,0 +285,0 @@ export function extractPublicKeyHex(pk: _ExtendedVerificationMethod, convert: boolean = false): string {

src/encodings.ts

 import * as u8a from 'uint8arrays'
 
+/**
+ * Converts a Uint8Array to a base64url string
+ * @param b - the array to be converted
+ *
+ * @public
+ */
 export function bytesToBase64url(b: Uint8Array): string {
@@ -7,2 +13,11 @@ return u8a.toString(b, 'base64url')
 
+/**
+ * Converts a base64url string to the Uint8Array it represents.
+ *
+ * @param s - the string to be converted
+ *
+ * @throws if the string is not formatted correctly.
+ *
+ * @public
+ */
 export function base64ToBytes(s: string): Uint8Array {
@@ -13,2 +28,8 @@ const inputBase64Url = s.replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, '')
 
+/**
+ * Encodes a Uint8Array to a base64 string representation with padding.
+ * @param b - the byte array to convert
+ *
+ * @public
+ */
 export function bytesToBase64(b: Uint8Array): string {
@@ -18,2 +39,8 @@ return u8a.toString(b, 'base64pad')
 
+/**
+ * Encodes the bytes of an input string to base64url
+ * @param s - the original string
+ *
+ * @beta This API may change without a BREAKING CHANGE notice.
+ */
 export function encodeBase64url(s: string): string {
@@ -23,2 +50,8 @@ return bytesToBase64url(u8a.fromString(s))
 
+/**
+ * Decodes a base64url string to a utf8 string represented by the same bytes.
+ * @param s - the base64url string to be decoded
+ *
+ * @beta This API may change without a BREAKING CHANGE notice.
+ */
 export function decodeBase64url(s: string): string {
@@ -28,2 +61,8 @@ return u8a.toString(base64ToBytes(s))
 
+/**
+ * Stringifies a JSON object and encodes the bytes of the resulting string to a base64url representation.
+ * @param payload - the object to be encoded
+ *
+ * @beta This API may change without a BREAKING CHANGE notice.
+ */
 export function encodeJoseBlob(payload: {}) {
@@ -33,2 +72,9 @@ return u8a.toString(u8a.fromString(JSON.stringify(payload), 'utf-8'), 'base64url')
 
+/**
+ * Decodes a base64url string representing stringified JSON to a JSON object.
+ *
+ * @param blob - The base64url encoded stringified JSON to be decoded
+ *
+ * @beta This API may change without a BREAKING CHANGE notice.
+ */
 export function decodeJoseBlob(blob: string) {
@@ -45,2 +91,4 @@ return JSON.parse(u8a.toString(u8a.fromString(blob, 'base64url'), 'utf-8'))
  * @throws `illegal_argument` error if the parameter is not a string
+ *
+ * @beta This API may change without a BREAKING CHANGE notice.
  */
@@ -60,2 +108,14 @@ export function hexToBytes(hexString: string): Uint8Array {
 
+/**
+ * Converts a Uint8Array input to a hex string
+ *
+ * @param byteArray - The array to be converted
+ * @param prefix - If this is set to true, the resulting hex string will be prefixed with 0x
+ *
+ * @returns the hex encoding of the input byte array
+ *
+ * @throws `illegal_argument` error if the input is not a Uint8Array
+ *
+ * @beta This API may change without a BREAKING CHANGE notice.
+ */
 export function bytesToHex(byteArray: Uint8Array, prefix: boolean = false): string {
@@ -67,2 +127,2 @@ if (!(byteArray instanceof Uint8Array)) {
   return prefix ? `0x${result}` : result
-}
+}

src/type-utils.ts

 /**
- * Checks if a variable is defined and not null
- * @param arg
+ * Checks if a variable is defined and not null.
+ * After this check, typescript sees the variable as defined.
  *
+ * @param arg - The input to be verified
+ *
+ * @returns true if the input variable is defined.
+ *
  * @beta This API may change without a BREAKING CHANGE notice.
@@ -12,5 +16,7 @@ */
 /**
- * Transforms an item or an array of items into an array of items
- * @param arg
+ * Ensures that a given input is an array. If the input is a single item, it is converted to an array with a single
+ * entry.
  *
+ * @param arg - a variable that needs to be converted to array
+ *
  * @beta This API may change without a BREAKING CHANGE notice.
@@ -24,3 +30,3 @@ */
  * Checks if an object is iterable (can be used for `for..of`)
- * @param obj
+ * @param obj - the variable to be checked
  *
@@ -27,0 +33,0 @@ * @beta This API may change without a BREAKING CHANGE notice.

src/types/utility-types.ts

@@ -35,3 +35,5 @@ import { IKey, KeyMetadata } from '@veramo/core'
 /**
- * Accept a Type or a Promise of that Type
+ * Accept a Type or a Promise of that Type.
+ *
+ * @internal
  */
@@ -43,3 +45,5 @@ export type OrPromise<T> = T | Promise<T>
  * Both Map and Record are accepted.
+ *
+ * @beta This API may change without a BREAKING CHANGE notice.
  */
 export type RecordLike<T> = Map<string, T> | Record<string, T>

New alerts

Manifest confusion

Supply chain risk

This package has inconsistent metadata. This could be malicious or caused by an error when publishing the package.

Found 1 instance in 1 package

Fixed alerts

Manifest confusion

Supply chain risk

This package has inconsistent metadata. This could be malicious or caused by an error when publishing the package.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

113045

increased by20.24%

Number of package files

38

increased by2.7%

Lines of code

1970

increased by31.6%

Dependency changes

• + Added@multiformats/base-x@4.0.1(transitive)

• + Added@noble/ciphers@0.4.1(transitive)

• + Added@noble/curves@1.8.1(transitive)

• + Added@noble/hashes@1.7.1(transitive)

• + Added@scure/base@1.2.4(transitive)

• + Added@veramo/core@3.1.6-next.172(transitive)

• + Addeddid-jwt@7.4.7(transitive)

• + Addeddid-jwt-vc@3.2.15(transitive)

• + Addedmultibase@4.0.6(transitive)

• - Removed@veramo/core@3.1.5-next.127(transitive)

• Updated@veramo/core@^3.1.6-next.129+79c38723