Add documentation

MetaMask · Apr 16, 2024 · 3ff26c2 · 3ff26c2
1 parent 3476930
commit 3ff26c2
Show file tree

Hide file tree

Showing 2 changed files with 105 additions and 15 deletions.
diff --git a/packages/snaps-sdk/src/provider-wrapper.test.ts b/packages/snaps-sdk/src/provider-wrapper.test.ts
@@ -96,6 +96,7 @@ describe('getBip44Entropy', () => {
     const node = {
       chainCode:
         '0x50ccfa58a885b48b5eed09486b3948e8454f34856fb81da5d7b8519d7997abd1',
+      // eslint-disable-next-line @typescript-eslint/naming-convention
       coin_type: 1,
       depth: 2,
       index: 2147483649,
@@ -205,7 +206,7 @@ describe('getLocale', () => {
     (snap.request as jest.MockedFn<typeof snap.request>).mockResolvedValue(
       'en',
     );
-    expect(await getLocale()).toStrictEqual('en');
+    expect(await getLocale()).toBe('en');
     expect(snap.request).toHaveBeenCalledWith({
       method: 'snap_getLocale',
     });
@@ -217,7 +218,7 @@ describe('setState', () => {
     (snap.request as jest.MockedFn<typeof snap.request>).mockResolvedValue(
       null,
     );
-    expect(await setState({ foo: 'bar' })).toStrictEqual(null);
+    expect(await setState({ foo: 'bar' })).toBeNull();
     expect(snap.request).toHaveBeenCalledWith({
       method: 'snap_manageState',
       params: {
@@ -234,7 +235,7 @@ describe('setState', () => {
     (snap.request as jest.MockedFn<typeof snap.request>).mockResolvedValue(
       null,
     );
-    expect(await setState({ foo: 'bar' }, false)).toStrictEqual(null);
+    expect(await setState({ foo: 'bar' }, false)).toBeNull();
     expect(snap.request).toHaveBeenCalledWith({
       method: 'snap_manageState',
       params: {
@@ -285,7 +286,7 @@ describe('clearState', () => {
     (snap.request as jest.MockedFn<typeof snap.request>).mockResolvedValue(
       null,
     );
-    expect(await clearState()).toStrictEqual(null);
+    expect(await clearState()).toBeNull();
     expect(snap.request).toHaveBeenCalledWith({
       method: 'snap_manageState',
       params: {
@@ -299,7 +300,7 @@ describe('clearState', () => {
     (snap.request as jest.MockedFn<typeof snap.request>).mockResolvedValue(
       null,
     );
-    expect(await clearState(false)).toStrictEqual(null);
+    expect(await clearState(false)).toBeNull();
     expect(snap.request).toHaveBeenCalledWith({
       method: 'snap_manageState',
       params: {
@@ -315,9 +316,7 @@ describe('notify', () => {
     (snap.request as jest.MockedFn<typeof snap.request>).mockResolvedValue(
       null,
     );
-    expect(await notify(NotificationType.InApp, 'Hello world!')).toStrictEqual(
-      null,
-    );
+    expect(await notify(NotificationType.InApp, 'Hello world!')).toBeNull();
     expect(snap.request).toHaveBeenCalledWith({
       method: 'snap_notify',
       params: {
@@ -333,9 +332,7 @@ describe('createInterface', () => {
     (snap.request as jest.MockedFn<typeof snap.request>).mockResolvedValue(
       'foo',
     );
-    expect(await createInterface(panel([text('Hello world!')]))).toStrictEqual(
-      'foo',
-    );
+    expect(await createInterface(panel([text('Hello world!')]))).toBe('foo');
     expect(snap.request).toHaveBeenCalledWith({
       method: 'snap_createInterface',
       params: {
@@ -360,7 +357,7 @@ describe('updateInterface', () => {
     );
     expect(
       await updateInterface('foo', panel([text('Hello world!')])),
-    ).toStrictEqual(null);
+    ).toBeNull();
     expect(snap.request).toHaveBeenCalledWith({
       method: 'snap_updateInterface',
       params: {

diff --git a/packages/snaps-sdk/src/provider-wrapper.ts b/packages/snaps-sdk/src/provider-wrapper.ts
@@ -1,5 +1,4 @@
-import {
-  AuxiliaryFileEncoding,
+import type {
   ClearStateOperation,
   CreateInterfaceParams,
   GetBip32EntropyParams,
@@ -8,12 +7,19 @@ import {
   GetEntropyParams,
   GetFileParams,
   GetStateOperation,
-  ManageStateOperation,
   NotifyParams,
   UpdateInterfaceParams,
   UpdateStateOperation,
 } from './types';
+import { AuxiliaryFileEncoding, ManageStateOperation } from './types';
 
+/**
+ * Retrieve BIP-32 entropy for the specified curve and path.
+ *
+ * @param curve - The curve to use for BIP-32 key derivation.
+ * @param path - The BIP-32 derivation path.
+ * @returns A promise that resolves to a BIP-32 node.
+ */
 export async function getBip32Entropy(
   curve: GetBip32EntropyParams['curve'],
   path: GetBip32EntropyParams['path'],
@@ -24,6 +30,14 @@ export async function getBip32Entropy(
   });
 }
 
+/**
+ * Retrieve BIP-32 public key for the specified curve and path.
+ *
+ * @param curve - The curve to use for BIP-32 key derivation.
+ * @param path - The BIP-32 derivation path.
+ * @param compressed - Whether the public key should be compressed (default: false).
+ * @returns A promise that resolves to the BIP-32 public key in hexadecimal.
+ */
 export async function getBip32PublicKey(
   curve: GetBip32PublicKeyParams['curve'],
   path: GetBip32PublicKeyParams['path'],
@@ -35,6 +49,12 @@ export async function getBip32PublicKey(
   });
 }
 
+/**
+ * Retrieve BIP-44 entropy for the specified coin type.
+ *
+ * @param coinType - The coin type used for BIP-44 key derivation.
+ * @returns A promise that resolves to a BIP-44 node.
+ */
 export async function getBip44Entropy(
   coinType: GetBip44EntropyParams['coinType'],
 ) {
@@ -44,12 +64,25 @@ export async function getBip44Entropy(
   });
 }
 
+/**
+ * Retrieve status of the client.
+ *
+ * @returns A promise that resolves to an object containing
+ * useful information about the client.
+ */
 export async function getClientStatus() {
   return snap.request({
     method: 'snap_getClientStatus',
   });
 }
 
+/**
+ * Retrieve entropy for the specified version and salt.
+ *
+ * @param version - The version of the entropy (default: 1).
+ * @param salt - The salt to use for entropy generation.
+ * @returns A promise that resolves to the entropy.
+ */
 export async function getEntropy(
   version: GetEntropyParams['version'] = 1,
   salt?: GetEntropyParams['salt'],
@@ -60,6 +93,13 @@ export async function getEntropy(
   });
 }
 
+/**
+ * Retrieve content of a file at the specified path.
+ *
+ * @param path - The path of the file.
+ * @param encoding - The encoding to use for the file content (default: AuxiliaryFileEncoding.Base64).
+ * @returns A promise that resolves to the file content.
+ */
 export async function getFile(
   path: GetFileParams['path'],
   encoding: GetFileParams['encoding'] = AuxiliaryFileEncoding.Base64,
@@ -70,10 +110,25 @@ export async function getFile(
   });
 }
 
+/**
+ * Retrieve currently selected user locale.
+ *
+ * @returns A promise that resolves to the locale.
+ */
 export async function getLocale() {
   return snap.request({ method: 'snap_getLocale' });
 }
 
+/**
+ * Set the state to a JSON blob, overwriting the existing state.
+ *
+ * The state is located in two buckets, encrypted and unencrypted.
+ * A boolean flag can be used to toggle between the two buckets.
+ *
+ * @param newState - A JSON blob to set as the state.
+ * @param encrypted - Whether the state should be encrypted (default: true).
+ * @returns A promise that resolves when the state is set.
+ */
 export async function setState(
   newState: UpdateStateOperation['newState'],
   encrypted: UpdateStateOperation['encrypted'] = true,
@@ -88,6 +143,15 @@ export async function setState(
   });
 }
 
+/**
+ * Retrieve the current state JSON blob.
+ *
+ * The state is located in two buckets, encrypted and unencrypted.
+ * A boolean flag can be used to toggle between the two buckets.
+ *
+ * @param encrypted - Whether to get the encrypted or the unencrypted state (default: true).
+ * @returns A promise that resolves to the current state.
+ */
 export async function getState(
   encrypted: GetStateOperation['encrypted'] = true,
 ) {
@@ -97,6 +161,15 @@ export async function getState(
   });
 }
 
+/**
+ * Clear the current state blob, setting it to null.
+ *
+ * The state is located in two buckets, encrypted and unencrypted.
+ * A boolean flag can be used to toggle between the two buckets.
+ *
+ * @param encrypted - Whether the state should be encrypted (default: true).
+ * @returns A promise that resolves when the state is cleared.
+ */
 export async function clearState(
   encrypted: ClearStateOperation['encrypted'] = true,
 ) {
@@ -106,17 +179,37 @@ export async function clearState(
   });
 }
 
+/**
+ * Send a notification with the specified type and message.
+ *
+ * @param type - The type of the notification.
+ * @param message - The message of the notification.
+ * @returns A promise that resolves when the notification is sent.
+ */
 export async function notify(
   type: NotifyParams['type'],
   message: NotifyParams['message'],
 ) {
   return snap.request({ method: 'snap_notify', params: { type, message } });
 }
 
+/**
+ * Create a new interface with the specified UI.
+ *
+ * @param ui - The UI of the interface.
+ * @returns A promise that resolves to the interface ID.
+ */
 export async function createInterface(ui: CreateInterfaceParams['ui']) {
   return snap.request({ method: 'snap_createInterface', params: { ui } });
 }
 
+/**
+ * Update the interface with the specified ID and UI.
+ *
+ * @param id - The ID of the interface to update.
+ * @param ui - The updated UI of the interface.
+ * @returns A promise that resolves when the interface is updated.
+ */
 export async function updateInterface(
   id: UpdateInterfaceParams['id'],
   ui: UpdateInterfaceParams['ui'],