@walletwright/core 0.2.0

package/dist/types-CWxz_dJe.d.mts

@@ -0,0 +1,196 @@
+import { BrowserContext, Locator, Page } from "@playwright/test";
+//#region src/types.d.ts
+/** Blockchain ecosystem a wallet operates in. A wallet may span several (e.g. Phantom = EVM + SVM). */
+type Ecosystem = "evm" | "svm" | "sui" | "dot" | "btc";
+/**
+ * Supported wallet extensions. Only wallets with a verified end-to-end (connect + sign) flow are
+ * listed. The roadmap (top 3 per ecosystem) is tracked in `AGENTS.md`; each lands here once driven.
+ */
+type WalletKind = "metamask" | "phantom" | "rabby" | "slush" | "solflare";
+/** A wallet to import and the credentials to unlock it. */
+type WalletSetup = {
+  /** Cache directory for downloaded extensions and onboarded profiles. Defaults to `.walletwright`. */
+  cacheDir?: string;
+  password: string;
+  /** 12/24-word seed phrase. Avoid the famous public test seed for Phantom, it blocks connections. */
+  seedPhrase: string;
+  /** Pin a specific extension version (defaults to a known-good version per wallet). */
+  version?: string;
+  wallet: WalletKind;
+};
+/**
+ * Everything an action needs to drive the wallet's own UI (as opposed to an approval popup). Passed
+ * as one object so a new dependency doesn't churn every wallet's action signatures.
+ */
+type WalletActionContext = {
+  context: BrowserContext;
+  extensionId: string;
+  /** The wallet's own extension page, kept open after unlock. */
+  home: Page;
+  password: string;
+};
+/**
+ * The wallet-side counterpart of one dapp-facing capability: the same arguments, with the action
+ * context threaded in front.
+ */
+type WalletAction<Method> = Method extends ((...args: infer Args) => Promise<void>) ? (ctx: WalletActionContext, ...args: Args) => Promise<void> : never;
+/**
+ * The wallet-side half of a dapp-facing capability group, derived from that group's `*Api` type on
+ * `Wallet` so a capability's name and arguments are written exactly once.
+ */
+type WalletActionsFor<Api> = { [Name in keyof Api]?: WalletAction<Api[Name]>; };
+/** Create, import, rename, and switch accounts from the wallet's own UI. */
+type AccountActions = WalletActionsFor<AccountsApi>;
+/** A custom EVM network, as the wallet's add-network form expects it. */
+type NetworkConfig = {
+  chainId: number;
+  name: string;
+  rpcUrl: string;
+  symbol: string;
+};
+/** Add a custom network and switch the active one, from the wallet's own UI. */
+type NetworkActions = WalletActionsFor<NetworkApi>;
+/** Lock and unlock the wallet itself, from its own UI. */
+type SettingsActions = WalletActionsFor<SettingsApi>;
+/**
+ * Optional, per-wallet capabilities beyond the universal connect/sign flow. A wallet declares only
+ * what has actually been driven against the real extension, so the registry never claims support it
+ * doesn't have: `network` is meaningless for Slush (Sui), and Phantom's settings UI has no analogue
+ * for much of MetaMask's. Anything undeclared throws a clear error at call time.
+ */
+type WalletActions = {
+  accounts?: AccountActions;
+  network?: NetworkActions;
+  settings?: SettingsActions;
+};
+/**
+ * Everything wallet-specific that the generic engine needs. One implementation per wallet lives in
+ * `src/wallets/*`.
+ */
+type WalletDefinition = {
+  /** Optional capabilities beyond connect/sign. Omit a group the wallet can't (or doesn't) drive. */
+  actions?: WalletActions;
+  /**
+   * Controls that only exist while a request is on screen, used to tell a real approval from the
+   * wallet's idle UI: MetaMask's approval window can render its home screen, buttons and all. A
+   * wallet that doesn't declare this falls back to "any button is visible", which is enough for a
+   * window that only ever opens for a request.
+   */
+  approvalControls?: (popup: Page) => Locator;
+  /**
+   * Click the approve/confirm button in an approval popup (connect or sign). `password` is provided
+   * because some wallets (e.g. Slush) re-prompt for it to authorize a signature.
+   */
+  approve: (popup: Page, password: string) => Promise<void>;
+  /** Ecosystems this wallet can drive (e.g. `["evm", "svm"]` for Phantom). */
+  ecosystems: ReadonlyArray<Ecosystem>;
+  /** Name as it appears in `chrome://extensions` (used to resolve the loaded extension id). */
+  extensionName: string;
+  /**
+   * Optional fix applied to the persisted profile *after* the build context closes (browser not
+   * holding the DB), e.g. forcing `completedOnboarding=true` in MetaMask's leveldb.
+   */
+  finalizeCache?: (profileDir: string, extensionId: string) => Promise<void>;
+  /**
+   * Whether this wallet's approval window surfaces as a page when the browser runs headless, so the
+   * engine can find and drive it. Declared only once verified against the real extension: MetaMask's
+   * window is created but never exposed, and `launchWallet` refuses headless without this rather
+   * than hanging at the first approval.
+   */
+  headlessApprovals?: boolean;
+  /** Run the import-from-seed onboarding flow. */
+  importWallet: (page: Page, seedPhrase: string, password: string) => Promise<void>;
+  /**
+   * URL token that identifies this wallet's approval popup. Defaults to `notification.html`
+   * (MetaMask/Phantom). Single-page wallets differ, Slush routes approvals through `index.html` and
+   * marks them with `isPopup=1`.
+   */
+  notificationMatch?: string;
+  /** Extension-relative path of the first-run onboarding entry (e.g. `home.html`). */
+  onboardingPage: string;
+  /**
+   * Applied to every context this wallet runs in, before anything navigates: `buildCache`'s and
+   * `launchWallet`'s alike. For wallets that need the browser itself adjusted (routing, permissions)
+   * rather than a page driven.
+   */
+  prepareContext?: (context: BrowserContext) => Promise<void>;
+  /** Download + extract the unpacked extension into `cacheDir`; returns its absolute path. */
+  prepareExtension: (cacheDir: string, version?: string) => Promise<string>;
+  /**
+   * Open the wallet's home/unlock page and return it once it has settled into a known state (its
+   * password screen, or an already-unlocked wallet for the wallets that can reopen that way). Throws
+   * rather than returning a page that never rendered. The returned page stays open as `Wallet.home`.
+   */
+  reachUnlockScreen: (context: BrowserContext, extensionId: string) => Promise<Page>;
+  /**
+   * Click the cancel/reject button in an approval popup, the counterpart of `approve`. Optional:
+   * a wallet declares it only once it has been driven against the real extension.
+   */
+  reject?: (popup: Page) => Promise<void>;
+  /** Unlock the wallet on its (already-open) home page. */
+  unlock: (page: Page, password: string) => Promise<void>;
+};
+/** Lock and unlock the wallet from its own UI. Throws if the wallet doesn't declare support. */
+type SettingsApi = {
+  lock: () => Promise<void>;
+  unlock: () => Promise<void>;
+};
+/** Add and switch networks from the wallet's own UI. Throws if the wallet doesn't declare support. */
+type NetworkApi = {
+  add: (config: NetworkConfig) => Promise<void>;
+  /**
+   * No wallet implements this today, so calling it throws. MetaMask 13.x scopes the active chain
+   * per dapp and has no wallet-side network selector, so switching is dapp-initiated: the dapp calls
+   * `wallet_addEthereumChain` (idempotent, adds when missing and switches when present) and
+   * `wallet.approve()` drives the popup. See the network recipe in Examples.
+   */
+  switch: (chainId: number) => Promise<void>;
+};
+/** Manage accounts from the wallet's own UI. Throws if the wallet doesn't declare support. */
+type AccountsApi = {
+  /** Derive the next HD account from the seed. */
+  add: () => Promise<void>;
+  importPrivateKey: (privateKey: string) => Promise<void>;
+  rename: (options: {
+    index: number;
+    name: string;
+  }) => Promise<void>;
+  /** Make the account at `index` (order shown in the wallet's account list) the active one. */
+  switch: (index: number) => Promise<void>;
+};
+/** Drives an unlocked wallet against a dapp under test. */
+type Wallet = {
+  accounts: AccountsApi;
+  /** Approve whatever approval popup is currently pending (connect, sign, tx…). */
+  approve: (options?: {
+    optional?: boolean;
+  }) => Promise<void>;
+  /** Approve a pending signature request popup. */
+  confirmSignature: () => Promise<void>;
+  /** Approve a pending transaction request popup. */
+  confirmTransaction: () => Promise<void>;
+  /** Approve a pending connection request popup. Resolves quietly if the wallet auto-approved. */
+  connectToDapp: () => Promise<void>;
+  /** The loaded extension id. */
+  readonly extensionId: string;
+  /**
+   * The wallet's own extension page, kept open after unlock. Named `home` rather than `page` because
+   * `page` already means the dapp under test in every spec.
+   */
+  readonly home: Page;
+  network: NetworkApi;
+  /** Reject whatever approval popup is currently pending (connect, sign, tx…). */
+  reject: (options?: {
+    optional?: boolean;
+  }) => Promise<void>;
+  /** Reject a pending connection request popup. */
+  rejectConnection: () => Promise<void>;
+  /** Reject a pending signature request popup. */
+  rejectSignature: () => Promise<void>;
+  /** Reject a pending transaction request popup. */
+  rejectTransaction: () => Promise<void>;
+  settings: SettingsApi;
+};
+//#endregion
+export { WalletSetup as a, WalletKind as i, Wallet as n, WalletDefinition as r, Ecosystem as t };
+//# sourceMappingURL=types-CWxz_dJe.d.mts.map

package/package.json

@@ -0,0 +1,94 @@
+{
+  "name": "@walletwright/core",
+  "version": "0.2.0",
+  "description": "Playwright wallet automation for MetaMask, Phantom, Rabby, Solflare, and Slush across EVM, Solana, and Sui. Connect and sign in real browser extensions.",
+  "keywords": [
+    "e2e",
+    "ethereum",
+    "metamask",
+    "phantom",
+    "playwright",
+    "rabby",
+    "slush",
+    "solana",
+    "solflare",
+    "sui",
+    "testing",
+    "wallet",
+    "web3"
+  ],
+  "license": "MIT",
+  "author": "Pedro Filho <pedro@filho.me>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pedroapfilho/walletwright.git",
+    "directory": "packages/walletwright"
+  },
+  "bin": {
+    "walletwright": "dist/cli.mjs"
+  },
+  "files": [
+    "dist",
+    "CHANGELOG.md"
+  ],
+  "type": "module",
+  "types": "dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    },
+    "./chain": {
+      "types": "./dist/chain.d.mts",
+      "default": "./dist/chain.mjs"
+    },
+    "./mock": {
+      "types": "./dist/mock.d.mts",
+      "default": "./dist/mock.mjs"
+    },
+    "./mock-standard": {
+      "types": "./dist/mock-standard.d.mts",
+      "default": "./dist/mock-standard.mjs"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "adm-zip": "^0.6.0",
+    "classic-level": "^1.4.1"
+  },
+  "devDependencies": {
+    "@playwright/test": "1.62.1",
+    "@types/adm-zip": "^0.5.7",
+    "@types/node": "^25.9.1",
+    "prool": "^0.2.10",
+    "typescript": "^6.0.3",
+    "viem": "^2.21.0",
+    "vitest": "^4.1.8",
+    "@repo/config-vitest": "0.0.0",
+    "@repo/typescript-config": "0.0.0"
+  },
+  "peerDependencies": {
+    "@playwright/test": ">=1.48 <2",
+    "prool": ">=0.2 <1",
+    "viem": ">=2 <3"
+  },
+  "peerDependenciesMeta": {
+    "prool": {
+      "optional": true
+    },
+    "viem": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "tsdown",
+    "clean": "rm -rf dist",
+    "dev": "tsdown --watch",
+    "lint": "oxlint src",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}