@metamask/snaps-simulation/dist/types.mjs.map

A simulation framework for MetaMask Snaps, enabling headless testing of Snaps in a controlled environment

{"version":3,"file":"types.mjs","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"","sourcesContent":["import type {\n  NotificationType,\n  EnumToUnion,\n  TrackableError,\n  TraceRequest,\n} from '@metamask/snaps-sdk';\nimport type { JSXElement } from '@metamask/snaps-sdk/jsx';\nimport type { InferMatching } from '@metamask/snaps-utils';\nimport type { Infer } from '@metamask/superstruct';\nimport type {\n  CaipChainId,\n  Json,\n  JsonRpcId,\n  JsonRpcParams,\n} from '@metamask/utils';\n\nimport type {\n  NameLookupOptionsStruct,\n  SignatureOptionsStruct,\n  SnapOptionsStruct,\n  SnapResponseStruct,\n  TransactionOptionsStruct,\n} from './structs';\n\nexport type RequestOptions = {\n  /**\n   * The JSON-RPC request ID.\n   */\n  id?: JsonRpcId;\n\n  /**\n   * The JSON-RPC method.\n   */\n  method: string;\n\n  /**\n   * The JSON-RPC params.\n   */\n  params?: JsonRpcParams;\n\n  /**\n   * The origin to send the request from.\n   */\n  origin?: string;\n};\n\n/**\n * The `runCronjob` options. This is the same as {@link RequestOptions}, except\n * that it does not have an `origin` property.\n */\nexport type CronjobOptions = Omit<RequestOptions, 'origin'>;\n\n/**\n * The options to use for transaction requests.\n *\n * @property chainId - The CAIP-2 chain ID to send the transaction on. Defaults\n * to `eip155:1`.\n * @property origin - The origin to send the transaction from. Defaults to\n * `metamask.io`.\n * @property from - The address to send the transaction from. Defaults to a\n * randomly generated address.\n * @property to - The address to send the transaction to. Defaults to a randomly\n * generated address.\n * @property value - The value to send with the transaction. Defaults to `0`.\n * @property data - The data to send with the transaction. Defaults to `0x`.\n * @property gasLimit - The gas limit to use for the transaction. Defaults to\n * `21_000`.\n * @property maxFeePerGas - The maximum fee per gas to use for the transaction.\n * Defaults to `1`.\n * @property maxPriorityFeePerGas - The maximum priority fee per gas to use for\n * the transaction. Defaults to `1`.\n * @property nonce - The nonce to use for the transaction. Defaults to `0`.\n */\nexport type TransactionOptions = Infer<typeof TransactionOptionsStruct>;\n\n/**\n * The options to use for keyring requests.\n */\nexport type KeyringOptions = RequestOptions;\n\n/**\n * The options to use for name lookup requests.\n *\n * @property chainId - Chain ID.\n * @property domain - Domain name to lookup and resolve.\n * @property address - Address to lookup and resolve.\n */\nexport type NameLookupOptions = Infer<typeof NameLookupOptionsStruct>;\n\n/**\n * The options to use for signature requests.\n *\n * @property origin - The origin to send the signature request from. Defaults to\n * `metamask.io`.\n * @property from - The address to send the signature from. Defaults to a\n * randomly generated address.\n * @property data - The data to sign. Defaults to `0x`.\n * @property signatureMethod - The signature method.\n */\nexport type SignatureOptions = Infer<typeof SignatureOptionsStruct>;\n\n/**\n * The options to use for requests to the snap.\n *\n * @property timeout - The timeout in milliseconds to use. Defaults to `1000`.\n */\nexport type SnapOptions = Infer<typeof SnapOptionsStruct>;\n\n/**\n * Options for uploading a file.\n *\n * @property fileName - The name of the file. By default, this is inferred from\n * the file path if it's a path, and defaults to an empty string if it's a\n * `Uint8Array`.\n * @property contentType - The content type of the file. By default, this is\n * inferred from the file name if it's a path, and defaults to\n * `application/octet-stream` if it's a `Uint8Array` or the content type cannot\n * be inferred from the file name.\n */\nexport type FileOptions = {\n  fileName?: string;\n  contentType?: string;\n};\n\nexport type SnapInterfaceActions = {\n  /**\n   * Click on an interface element.\n   *\n   * @param name - The element name to click.\n   */\n  clickElement(name: string): Promise<void>;\n\n  /**\n   * Type a value in a interface field.\n   *\n   * @param name - The element name to type in.\n   * @param value - The value to type.\n   */\n  typeInField(name: string, value: string): Promise<void>;\n\n  /**\n   * Select an option with a value in a dropdown.\n   *\n   * @param name - The element name to type in.\n   * @param value - The value to type.\n   */\n  selectInDropdown(name: string, value: string): Promise<void>;\n\n  /**\n   * Choose an option with a value from radio group.\n   *\n   * @param name - The element name to type in.\n   * @param value - The value to type.\n   */\n  selectFromRadioGroup(name: string, value: string): Promise<void>;\n\n  /**\n   * Choose an option with a value from a Selector, AccountSelector or AssetSelector component.\n   *\n   * @param name - The element name to type in.\n   * @param value - The value to select.\n   */\n  selectFromSelector(name: string, value: string): Promise<void>;\n\n  /**\n   * Upload a file.\n   *\n   * @param name - The element name to upload the file to.\n   * @param file - The file to upload. This can be a path to a file or a\n   * `Uint8Array` containing the file contents. If this is a path, the file is\n   * resolved relative to the current working directory.\n   * @param options - The file options.\n   * @param options.fileName - The name of the file. By default, this is\n   * inferred from the file path if it's a path, and defaults to an empty string\n   * if it's a `Uint8Array`.\n   * @param options.contentType - The content type of the file. By default, this\n   * is inferred from the file name if it's a path, and defaults to\n   * `application/octet-stream` if it's a `Uint8Array` or the content type\n   * cannot be inferred from the file name.\n   */\n  uploadFile(\n    name: string,\n    file: string | Uint8Array,\n    options?: FileOptions,\n  ): Promise<void>;\n\n  /**\n   * Wait for the interface to be updated.\n   */\n  waitForUpdate: () => Promise<SnapHandlerInterface>;\n};\n\n/**\n * A `snap_dialog` alert interface.\n */\nexport type SnapAlertInterface = {\n  /**\n   * The type of the interface. This is always `alert`.\n   */\n  type: 'alert';\n\n  /**\n   * The content to show in the alert.\n   */\n  content: JSXElement;\n\n  /**\n   * The ID of the interface.\n   */\n  id: string;\n\n  /**\n   * Close the alert.\n   */\n  ok(): Promise<void>;\n};\n\n/**\n * A `snap_dialog` confirmation interface.\n */\nexport type SnapConfirmationInterface = {\n  /**\n   * The type of the interface. This is always `confirmation`.\n   */\n  type: 'confirmation';\n\n  /**\n   * The content to show in the confirmation.\n   */\n  content: JSXElement;\n\n  /**\n   * The ID of the interface.\n   */\n  id: string;\n\n  /**\n   * Close the confirmation.\n   */\n  ok(): Promise<void>;\n\n  /**\n   * Cancel the confirmation.\n   */\n  cancel(): Promise<void>;\n};\n\n/**\n * A `snap_dialog` prompt interface.\n */\nexport type SnapPromptInterface = {\n  /**\n   * The type of the interface. This is always `prompt`.\n   */\n  type: 'prompt';\n\n  /**\n   * The content to show in the prompt.\n   */\n  content: JSXElement;\n\n  /**\n   * The ID of the interface.\n   */\n  id: string;\n\n  /**\n   * Close the prompt.\n   *\n   * @param value - The value to close the prompt with.\n   */\n  ok(value?: string): Promise<void>;\n\n  /**\n   * Cancel the prompt.\n   */\n  cancel(): Promise<void>;\n};\n\n/**\n * A `snap_dialog` default interface that has a Footer with two buttons defined.\n * The approval of this confirmation is handled by the snap.\n */\nexport type DefaultSnapInterfaceWithFooter = {\n  /**\n   * The content to show in the interface.\n   */\n  content: JSXElement;\n\n  /**\n   * The ID of the interface.\n   */\n  id: string;\n};\n\n/**\n * A `snap_dialog` default interface that has a Footer with one button defined.\n * A cancel button is automatically applied to the interface in this case.\n */\nexport type DefaultSnapInterfaceWithPartialFooter =\n  DefaultSnapInterfaceWithFooter & {\n    /**\n     * Cancel the dialog.\n     */\n    cancel(): Promise<void>;\n  };\n\n/**\n * A `snap_dialog` default interface that has no Footer defined.\n * A cancel and ok button is automatically applied to the interface in this case.\n */\nexport type DefaultSnapInterfaceWithoutFooter =\n  DefaultSnapInterfaceWithPartialFooter & {\n    /**\n     * Close the dialog.\n     *\n     */\n    ok(): Promise<void>;\n  };\n\nexport type DefaultSnapInterface = (\n  | DefaultSnapInterfaceWithFooter\n  | DefaultSnapInterfaceWithPartialFooter\n  | DefaultSnapInterfaceWithoutFooter\n) & {\n  type?: never;\n};\n\nexport type SnapInterface = (\n  | SnapAlertInterface\n  | SnapConfirmationInterface\n  | SnapPromptInterface\n  | DefaultSnapInterface\n) &\n  SnapInterfaceActions;\n\nexport type SnapRequestObject = {\n  /**\n   * Get a user interface object from a snap. This will throw an error if the\n   * snap does not show a user interface within the timeout.\n   *\n   * @param options - The options to use.\n   * @param options.timeout - The timeout in milliseconds to use. Defaults to\n   * `1000`.\n   * @returns The user interface object.\n   */\n  getInterface(options?: SnapOptions): Promise<SnapInterface>;\n};\n\n/**\n * A pending request object. This is a promise with extra\n * {@link SnapRequestObject} fields.\n */\nexport type SnapRequest = Promise<SnapResponse> & SnapRequestObject;\n\n/**\n * The options to use for mocking a JSON-RPC request.\n */\nexport type JsonRpcMockOptions = {\n  /**\n   * The JSON-RPC request method.\n   */\n  method: string;\n\n  /**\n   * The JSON-RPC response, which will be returned when a request with the\n   * specified method is sent.\n   */\n  result: Json;\n};\n\n/**\n * This is the main entry point to interact with the snap. It is returned by\n * {@link installSnap}, and has methods to send requests to the snap.\n *\n * @example\n * import { installSnap } from '@metamask/snaps-jest';\n *\n * const snap = await installSnap();\n * const response = await snap.request({ method: 'hello' });\n *\n * expect(response).toRespondWith('Hello, world!');\n */\nexport type Snap = {\n  /**\n   * Send a JSON-RPC request to the snap.\n   *\n   * @param request - The request. This is similar to a JSON-RPC request, but\n   * has an extra `origin` field.\n   * @returns The response promise, with extra {@link SnapRequestObject} fields.\n   */\n  request(request: RequestOptions): SnapRequest;\n\n  /**\n   * Send a transaction to the snap.\n   *\n   * @param transaction - The transaction. This is similar to an Ethereum\n   * transaction object, but has an extra `origin` field. Any missing fields\n   * will be filled in with default values.\n   * @returns The response.\n   */\n  onTransaction(\n    transaction?: Partial<TransactionOptions>,\n  ): Promise<SnapResponseWithInterface>;\n\n  /**\n   * Send a transaction to the snap.\n   *\n   * @param transaction - The transaction. This is similar to an Ethereum\n   * transaction object, but has an extra `origin` field. Any missing fields\n   * will be filled in with default values.\n   * @returns The response.\n   * @deprecated Use {@link onTransaction} instead.\n   */\n  sendTransaction(\n    transaction?: Partial<TransactionOptions>,\n  ): Promise<SnapResponseWithInterface>;\n\n  /**\n   * Send a signature request to the snap.\n   *\n   * @param signature - The signature request object. Contains the params from\n   * the various signature methods, but has an extra `origin` and `signatureMethod` field.\n   * Any missing fields will be filled in with default values.\n   * @returns The response.\n   */\n  onSignature(\n    signature?: Partial<SignatureOptions>,\n  ): Promise<SnapResponseWithInterface>;\n\n  /**\n   * Run a cronjob in the snap. This is similar to {@link request}, but the\n   * request will be sent to the `onCronjob` method of the snap.\n   *\n   * @param cronjob - The cronjob request. This is similar to a JSON-RPC\n   * request, and is normally specified in the snap manifest, under the\n   * `endowment:cronjob` permission.\n   * @returns The response promise, with extra {@link SnapRequestObject} fields.\n   */\n  onCronjob(cronjob?: Partial<CronjobOptions>): SnapRequest;\n\n  /**\n   * Run a cronjob in the snap. This is similar to {@link request}, but the\n   * request will be sent to the `onCronjob` method of the snap.\n   *\n   * @param cronjob - The cronjob request. This is similar to a JSON-RPC\n   * request, and is normally specified in the snap manifest, under the\n   * `endowment:cronjob` permission.\n   * @returns The response promise, with extra {@link SnapRequestObject} fields.\n   * @deprecated Use {@link onCronjob} instead.\n   */\n  runCronjob(cronjob: CronjobOptions): SnapRequest;\n\n  /**\n   * Run a background event in the snap. This is similar to {@link request}, but the\n   * request will be sent to the `onCronjob` method of the snap.\n   *\n   * @param backgroundEvent - The cronjob request. This is similar to a JSON-RPC\n   * request, and is normally specified as the `request` param in the `snap_scheduleBackgroundEvent` method.\n   * @returns The response promise, with extra {@link SnapRequestObject} fields.\n   */\n  onBackgroundEvent(backgroundEvent: CronjobOptions): SnapRequest;\n\n  /**\n   * Get the response from the snap's `onHomePage` method.\n   *\n   * @returns The response.\n   */\n  onHomePage(): Promise<SnapResponseWithInterface>;\n\n  /**\n   * Get the response from the snap's `onSettingsPage` method.\n   *\n   * @returns The response.\n   */\n  onSettingsPage(): Promise<SnapResponseWithInterface>;\n\n  /**\n   * Send a keyring to the Snap.\n   *\n   * @param keyringRequest - Keyring request options.\n   * @returns The response.\n   */\n  onKeyringRequest(keyringRequest: KeyringOptions): SnapRequest;\n\n  /**\n   * Get the response from the Snap's `onInstall` handler.\n   *\n   * @returns The response.\n   */\n  onInstall(request?: Pick<RequestOptions, 'origin'>): SnapRequest;\n\n  /**\n   * Get the response from the Snap's `onUpdate` handler.\n   *\n   * @returns The response.\n   */\n  onUpdate(request?: Pick<RequestOptions, 'origin'>): SnapRequest;\n\n  /**\n   * Get the response from the Snap's `onStart` handler.\n   *\n   * @returns The response.\n   */\n  onStart(request?: Pick<RequestOptions, 'origin'>): SnapRequest;\n\n  /**\n   * Get the response from the Snap's `onNameLookup` handler.\n   *\n   * @returns The response.\n   */\n  onNameLookup(\n    nameLookupRequest: NameLookupOptions,\n  ): Promise<SnapResponseWithoutInterface>;\n\n  /**\n   * Send a JSON-RPC protocol request to the Snap.\n   *\n   * @param scope - A CAIP-2 scope.\n   * @param request - The request. This is similar to a JSON-RPC request, but\n   * has an extra `origin` field.\n   * @returns The response promise, with extra {@link SnapRequestObject} fields.\n   */\n  onProtocolRequest(\n    scope: CaipChainId,\n    request: RequestOptions,\n  ): Promise<SnapResponseWithoutInterface>;\n\n  /**\n   * Send a JSON-RPC client request to the Snap.\n   *\n   * @param request - The JSON-RPC request.\n   * @returns The response promise, with extra {@link SnapRequestObject} fields.\n   */\n  onClientRequest(request: Omit<RequestOptions, 'origin'>): SnapRequest;\n\n  /**\n   * Mock a JSON-RPC request. This will cause the snap to respond with the\n   * specified response when a request with the specified method is sent.\n   *\n   * @param mock - The mock options.\n   * @param mock.method - The JSON-RPC request method.\n   * @param mock.result - The JSON-RPC response, which will be returned when a\n   * request with the specified method is sent.\n   * @example\n   * import { installSnap } from '@metamask/snaps-jest';\n   *\n   * // In the test\n   * const snap = await installSnap();\n   * snap.mockJsonRpc({ method: 'eth_accounts', result: ['0x1234'] });\n   *\n   * // In the Snap\n   * const response =\n   *   await ethereum.request({ method: 'eth_accounts' }); // ['0x1234']\n   */\n  mockJsonRpc(mock: JsonRpcMockOptions): {\n    /**\n     * Remove the mock.\n     */\n    unmock(): void;\n  };\n\n  /**\n   * Close the page running the snap. This is mainly useful for cleaning up\n   * the test environment, and calling it is not strictly necessary.\n   *\n   * @returns A promise that resolves when the page is closed.\n   * @deprecated Snaps are now automatically closed when the test ends. This\n   * method will be removed in a future release.\n   */\n  close(): Promise<void>;\n};\n\nexport type SnapHandlerInterface = {\n  content: JSXElement;\n} & SnapInterfaceActions;\n\nexport type TrackedSnapResponseData = {\n  errors: TrackableError[];\n  events: {\n    event: string;\n    properties?: Record<string, Json>;\n    sensitiveProperties?: Record<string, Json>;\n  }[];\n  traces: TraceRequest[];\n};\n\nexport type SnapResponseWithInterface = {\n  id: string;\n  response: { result: Json } | { error: Json };\n\n  notifications: {\n    id: string;\n    message: string;\n    type: EnumToUnion<NotificationType>;\n    title?: string | undefined;\n    content?: string | undefined;\n    footerLink?: { text: string; href: string } | undefined;\n  }[];\n\n  tracked: TrackedSnapResponseData;\n\n  getInterface(): SnapHandlerInterface;\n};\n\nexport type SnapResponseWithoutInterface = Omit<\n  SnapResponseWithInterface,\n  'getInterface'\n>;\n\nexport type SnapResponseType =\n  | SnapResponseWithoutInterface\n  | SnapResponseWithInterface;\n\nexport type SnapResponse = InferMatching<\n  typeof SnapResponseStruct,\n  SnapResponseType\n>;\n"]}