@usebutr/wallet-standard-shared 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,150 @@
+import { Account, ChainBase, WalletAdapter } from "@usebutr/core";
+
+//#region src/types.d.ts
+/**
+ * Minimal type surface for the Wallet Standard protocol that every
+ * platform-specific package (`@usebutr/svm`, `@usebutr/sui`,
+ * `@usebutr/bitcoin`) shares. Declared inline so butr stays
+ * self-contained at the type level — the actual `@wallet-standard/app`
+ * package is dynamic-imported at runtime, and apps that don't enable
+ * Wallet Standard discovery never resolve it.
+ *
+ * Spec: https://github.com/wallet-standard/wallet-standard
+ *
+ * Platform-specific feature shapes (e.g. `solana:signMessage`,
+ * `sui:signPersonalMessage`, `bitcoin:signPsbt`) live in their own
+ * platform packages.
+ */
+type WalletStandardWalletAccount = {
+  address: string;
+  chains: ReadonlyArray<string>;
+  features: ReadonlyArray<string>; /** Public key bytes — Wallet Standard ships these as Uint8Array. */
+  publicKey?: Uint8Array;
+};
+type WalletStandardWallet = {
+  accounts: ReadonlyArray<WalletStandardWalletAccount>;
+  chains: ReadonlyArray<string>;
+  /** Map keyed by feature name. Values are feature-specific; narrow at
+   *  use sites. */
+  features: Readonly<Record<string, unknown>>;
+  icon: string;
+  name: string;
+  version: string;
+};
+type WalletsApp = {
+  get(): ReadonlyArray<WalletStandardWallet>;
+  on(event: "register" | "unregister", listener: (...wallets: ReadonlyArray<WalletStandardWallet>) => void): () => void;
+};
+type WalletStandardAppModule = {
+  getWallets(): WalletsApp;
+};
+type StandardConnectFeature = {
+  connect(input?: {
+    silent?: boolean;
+  }): Promise<{
+    accounts: ReadonlyArray<WalletStandardWalletAccount>;
+  }>;
+};
+type StandardDisconnectFeature = {
+  disconnect(): Promise<void>;
+};
+type StandardEventsListener = (changes: {
+  accounts?: ReadonlyArray<WalletStandardWalletAccount>;
+  chains?: ReadonlyArray<string>;
+  features?: ReadonlyArray<string>;
+}) => void;
+type StandardEventsFeature = {
+  on(event: "change", listener: StandardEventsListener): () => void;
+};
+//#endregion
+//#region src/primitives.d.ts
+/**
+ * Convert a wallet name into a stable kebab-case adapter id, optionally
+ * scoped by a platform prefix so adapters from different platforms
+ * (Phantom SVM, Phantom Sui, Phantom BTC) coexist in the pool.
+ *
+ * The prefix discipline matters: every Wallet Standard adapter shares
+ * the same `getWallets()` bus, so distinct prefixes are the only thing
+ * keeping multi-chain wallets from colliding. Pass `""` to opt out —
+ * SVM does this for backwards compatibility with stored pool entries
+ * persisted before the prefix discipline existed.
+ *
+ * @example
+ * slugify("",    "Phantom")    // "wallet-standard:phantom"  (SVM legacy)
+ * slugify("sui", "Sui Wallet") // "wallet-standard:sui-sui-wallet"
+ * slugify("btc", "Phantom")    // "wallet-standard:btc-phantom"
+ */
+declare const slugify: (platformPrefix: string, name: string) => string;
+/**
+ * Read a Wallet Standard feature off a wallet, returning `undefined`
+ * when absent. The caller narrows the unknown payload to the
+ * platform-specific feature shape at use sites.
+ */
+declare const getFeature: <T>(wallet: WalletStandardWallet, name: string) => T | undefined;
+/**
+ * Build butr's `Account` shape from a Wallet Standard account address
+ * and a resolved `ChainBase`. The composite id (`<chain>:<address>`)
+ * is what butr's reducer uses to compare accounts across refreshes,
+ * so keep this format identical across platforms.
+ */
+declare const buildAccount: (address: string, chain: ChainBase) => Account;
+/**
+ * Pick the first address out of a wallet's accounts array, returning
+ * `null` when the wallet currently exposes none.
+ */
+declare const pickFirstAddress: (accounts: ReadonlyArray<WalletStandardWalletAccount>) => string | null;
+/**
+ * Look up a wallet account by address, falling back to the first
+ * exposed account when the requested address isn't present.
+ *
+ * Used by per-call routing in `sendTx` / `signMessage`: callers pass
+ * an `account` from `ConnectedWallet.accounts` to sign with a non-
+ * active address; the wallet's `accounts[]` is the source of truth.
+ */
+declare const pickAccountByAddress: (accounts: ReadonlyArray<WalletStandardWalletAccount>, address: string) => WalletStandardWalletAccount | undefined;
+//#endregion
+//#region src/discovery.d.ts
+/**
+ * Callback supplied by per-platform discovery to build a `WalletAdapter`
+ * out of a Wallet Standard wallet announcement.
+ *
+ * Returns `null` when the wallet doesn't advertise this platform — that
+ * lets a multi-chain wallet (e.g. Phantom: SVM + EVM + Sui + Bitcoin)
+ * produce one adapter per platform without each builder needing to know
+ * about the others.
+ *
+ * The second argument is a hook the builder calls during construction
+ * to wire a synthetic `disconnected` event into its subscriber set.
+ * The discovery loop fires the registered emitter when Wallet Standard
+ * announces `unregister` for that wallet.
+ */
+type WalletStandardAdapterBuilder = (wallet: WalletStandardWallet, registerDisconnector: (emit: () => void) => void) => WalletAdapter | null;
+/**
+ * Subscribe to Wallet Standard announcements and turn matching wallets
+ * into butr `WalletAdapter`s using a per-platform `build` callback.
+ *
+ * **Shared machinery** every platform package needs:
+ *  - Dynamic import of `@wallet-standard/app` (optional peer dep —
+ *    failure to resolve quietly disables discovery so consumers who
+ *    don't install it pay nothing).
+ *  - Cancellation: the returned unsubscribe is safe to call before the
+ *    dynamic import has resolved.
+ *  - Dedupe by adapter id, so re-announcements don't double-emit.
+ *  - `unregister` integration: when an extension is removed mid-session,
+ *    fire the disconnector the builder registered so connected pool
+ *    entries on the consumer side tear down cleanly.
+ *
+ * **What's platform-specific** lives entirely in `build`:
+ *  - Which `wallet.chains` to accept.
+ *  - Which features to gate on.
+ *  - The `id` slug prefix (use `slugify(prefix, wallet.name)`).
+ *  - The capability resolver, the feature decoding, the chain coercion.
+ *
+ * Disconnectors are keyed by the wallet object itself (identity equality),
+ * not by adapter id — Wallet Standard's `register` / `unregister` emit
+ * the same wallet object, so identity is the cheapest stable key.
+ */
+declare const discoverWalletStandard: (onAdapter: (adapter: WalletAdapter) => void, build: WalletStandardAdapterBuilder) => (() => void);
+//#endregion
+export { type StandardConnectFeature, type StandardDisconnectFeature, type StandardEventsFeature, type StandardEventsListener, type WalletStandardAdapterBuilder, type WalletStandardAppModule, type WalletStandardWallet, type WalletStandardWalletAccount, type WalletsApp, buildAccount, discoverWalletStandard, getFeature, pickAccountByAddress, pickFirstAddress, slugify };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/types.ts","../src/primitives.ts","../src/discovery.ts"],"mappings":";;;;;;;;;;;;;;;;;KAeK,2BAAA;EACH,OAAA;EACA,MAAA,EAAQ,aAAA;EACR,QAAA,EAAU,aAAA,UAEY;EAAtB,SAAA,GAAY,UAAA;AAAA;AAAA,KAGT,oBAAA;EACH,QAAA,EAAU,aAAA,CAAc,2BAAA;EACxB,MAAA,EAAQ,aAAA;EADE;;EAIV,QAAA,EAAU,QAAA,CAAS,MAAA;EACnB,IAAA;EACA,IAAA;EACA,OAAA;AAAA;AAAA,KAGG,UAAA;EACH,GAAA,IAAO,aAAA,CAAc,oBAAA;EACrB,EAAA,CACE,KAAA,6BACA,QAAA,MAAc,OAAA,EAAS,aAAA,CAAc,oBAAA;AAAA;AAAA,KAIpC,uBAAA;EACH,UAAA,IAAc,UAAU;AAAA;AAAA,KAGrB,sBAAA;EACH,OAAA,CAAQ,KAAA;IAAU,MAAA;EAAA,IAAqB,OAAA;IACrC,QAAA,EAAU,aAAA,CAAc,2BAAA;EAAA;AAAA;AAAA,KAIvB,yBAAA;EACH,UAAA,IAAc,OAAO;AAAA;AAAA,KAGlB,sBAAA,IAA0B,OAAA;EAC7B,QAAA,GAAW,aAAA,CAAc,2BAAA;EACzB,MAAA,GAAS,aAAA;EACT,QAAA,GAAW,aAAA;AAAA;AAAA,KAGR,qBAAA;EACH,EAAA,CAAG,KAAA,YAAiB,QAAA,EAAU,sBAAsB;AAAA;;;;;;;;;;;;;;;;;;;cC3ChD,OAAA,GAAW,cAAA,UAAwB,IAAY;ADA7B;AAAA;;;;AAAA,cCalB,UAAA,MAAiB,MAAA,EAAQ,oBAAA,EAAsB,IAAA,aAAe,CAAC;;;;;;;cAW/D,YAAA,GAAgB,OAAA,UAAiB,KAAA,EAAO,SAAA,KAAY,OAIxD;;;;;cAMI,gBAAA,GAAoB,QAAA,EAAU,aAAa,CAAC,2BAAA;;;;;;ADvBzC;AAAA;;cCoCH,oBAAA,GACJ,QAAA,EAAU,aAAA,CAAc,2BAAA,GACxB,OAAA,aACC,2BAAA;;;;;;;;;;;;;;;;;KCpDE,4BAAA,IACH,MAAA,EAAQ,oBAAA,EACR,oBAAA,GAAuB,IAAA,0BACpB,aAAa;;;AFDM;AAAA;;;;;;;;;;;;;;;;;;;;;;cE4BlB,sBAAA,GACJ,SAAA,GAAY,OAAA,EAAS,aAAA,WACrB,KAAA,EAAO,4BAA4B"}

package/dist/index.js

@@ -0,0 +1,2 @@
+const e=(e,t)=>{let n=t.trim().toLowerCase().replaceAll(RegExp(`[^a-z0-9]+`,`gv`),`-`);return e?`wallet-standard:${e}-${n}`:`wallet-standard:${n}`},t=(e,t)=>e.features[t]||void 0,n=(e,t)=>({chain:t,id:`${t.id}:${e}`,walletAddress:e}),r=e=>{let t=e[0];return t?t.address:null},i=(e,t)=>e.find(e=>e.address===t)??e[0],a=(e,t)=>{let n=!1,r=null;return(async()=>{let i;try{i=await import(`@wallet-standard/app`)}catch{return}if(n)return;let a=new Set,o=new Map,s=n=>{let r=t(n,e=>{o.set(n,e)});!r||a.has(r.id)||(a.add(r.id),e(r))},c=i.getWallets();for(let e of c.get())s(e);let l=c.on(`register`,(...e)=>{for(let t of e)s(t)}),u=c.on(`unregister`,(...e)=>{for(let t of e){let e=o.get(t);e&&(e(),o.delete(t))}});r=()=>{l(),u()}})(),()=>{n=!0,r?.(),r=null}};export{n as buildAccount,a as discoverWalletStandard,t as getFeature,i as pickAccountByAddress,r as pickFirstAddress,e as slugify};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/primitives.ts","../src/discovery.ts"],"sourcesContent":["import type { Account, ChainBase } from \"@usebutr/core\";\n\nimport type { WalletStandardWallet, WalletStandardWalletAccount } from \"./types\";\n\n/**\n * Convert a wallet name into a stable kebab-case adapter id, optionally\n * scoped by a platform prefix so adapters from different platforms\n * (Phantom SVM, Phantom Sui, Phantom BTC) coexist in the pool.\n *\n * The prefix discipline matters: every Wallet Standard adapter shares\n * the same `getWallets()` bus, so distinct prefixes are the only thing\n * keeping multi-chain wallets from colliding. Pass `\"\"` to opt out —\n * SVM does this for backwards compatibility with stored pool entries\n * persisted before the prefix discipline existed.\n *\n * @example\n * slugify(\"\",    \"Phantom\")    // \"wallet-standard:phantom\"  (SVM legacy)\n * slugify(\"sui\", \"Sui Wallet\") // \"wallet-standard:sui-sui-wallet\"\n * slugify(\"btc\", \"Phantom\")    // \"wallet-standard:btc-phantom\"\n */\nconst slugify = (platformPrefix: string, name: string): string => {\n  const slug = name\n    .trim()\n    .toLowerCase()\n    .replaceAll(/[^a-z0-9]+/gv, \"-\");\n  return platformPrefix ? `wallet-standard:${platformPrefix}-${slug}` : `wallet-standard:${slug}`;\n};\n\n/**\n * Read a Wallet Standard feature off a wallet, returning `undefined`\n * when absent. The caller narrows the unknown payload to the\n * platform-specific feature shape at use sites.\n */\nconst getFeature = <T>(wallet: WalletStandardWallet, name: string): T | undefined => {\n  const feature = wallet.features[name];\n  return feature ? (feature as T) : undefined;\n};\n\n/**\n * Build butr's `Account` shape from a Wallet Standard account address\n * and a resolved `ChainBase`. The composite id (`<chain>:<address>`)\n * is what butr's reducer uses to compare accounts across refreshes,\n * so keep this format identical across platforms.\n */\nconst buildAccount = (address: string, chain: ChainBase): Account => ({\n  chain,\n  id: `${chain.id}:${address}`,\n  walletAddress: address,\n});\n\n/**\n * Pick the first address out of a wallet's accounts array, returning\n * `null` when the wallet currently exposes none.\n */\nconst pickFirstAddress = (accounts: ReadonlyArray<WalletStandardWalletAccount>): string | null => {\n  const first = accounts[0];\n  return first ? first.address : null;\n};\n\n/**\n * Look up a wallet account by address, falling back to the first\n * exposed account when the requested address isn't present.\n *\n * Used by per-call routing in `sendTx` / `signMessage`: callers pass\n * an `account` from `ConnectedWallet.accounts` to sign with a non-\n * active address; the wallet's `accounts[]` is the source of truth.\n */\nconst pickAccountByAddress = (\n  accounts: ReadonlyArray<WalletStandardWalletAccount>,\n  address: string,\n): WalletStandardWalletAccount | undefined =>\n  accounts.find((a) => a.address === address) ?? accounts[0];\n\nexport { buildAccount, getFeature, pickAccountByAddress, pickFirstAddress, slugify };\n","import type { WalletAdapter } from \"@usebutr/core\";\n\nimport type { WalletStandardAppModule, WalletStandardWallet } from \"./types\";\n\n/**\n * Callback supplied by per-platform discovery to build a `WalletAdapter`\n * out of a Wallet Standard wallet announcement.\n *\n * Returns `null` when the wallet doesn't advertise this platform — that\n * lets a multi-chain wallet (e.g. Phantom: SVM + EVM + Sui + Bitcoin)\n * produce one adapter per platform without each builder needing to know\n * about the others.\n *\n * The second argument is a hook the builder calls during construction\n * to wire a synthetic `disconnected` event into its subscriber set.\n * The discovery loop fires the registered emitter when Wallet Standard\n * announces `unregister` for that wallet.\n */\ntype WalletStandardAdapterBuilder = (\n  wallet: WalletStandardWallet,\n  registerDisconnector: (emit: () => void) => void,\n) => WalletAdapter | null;\n\n/**\n * Subscribe to Wallet Standard announcements and turn matching wallets\n * into butr `WalletAdapter`s using a per-platform `build` callback.\n *\n * **Shared machinery** every platform package needs:\n *  - Dynamic import of `@wallet-standard/app` (optional peer dep —\n *    failure to resolve quietly disables discovery so consumers who\n *    don't install it pay nothing).\n *  - Cancellation: the returned unsubscribe is safe to call before the\n *    dynamic import has resolved.\n *  - Dedupe by adapter id, so re-announcements don't double-emit.\n *  - `unregister` integration: when an extension is removed mid-session,\n *    fire the disconnector the builder registered so connected pool\n *    entries on the consumer side tear down cleanly.\n *\n * **What's platform-specific** lives entirely in `build`:\n *  - Which `wallet.chains` to accept.\n *  - Which features to gate on.\n *  - The `id` slug prefix (use `slugify(prefix, wallet.name)`).\n *  - The capability resolver, the feature decoding, the chain coercion.\n *\n * Disconnectors are keyed by the wallet object itself (identity equality),\n * not by adapter id — Wallet Standard's `register` / `unregister` emit\n * the same wallet object, so identity is the cheapest stable key.\n */\nconst discoverWalletStandard = (\n  onAdapter: (adapter: WalletAdapter) => void,\n  build: WalletStandardAdapterBuilder,\n): (() => void) => {\n  let cancelled = false;\n  let internalUnsub: (() => void) | null = null;\n\n  void (async () => {\n    let mod: WalletStandardAppModule;\n    try {\n      mod = (await import(\"@wallet-standard/app\")) as unknown as WalletStandardAppModule;\n    } catch {\n      return;\n    }\n    if (cancelled) {\n      return;\n    }\n\n    const seenIds = new Set<string>();\n    // wallet object → emitter that pushes synthetic `disconnected` to\n    // this wallet's adapter's subscribers. Identity-keyed so the\n    // unregister handler can find the right emitter cheaply.\n    const disconnectors = new Map<WalletStandardWallet, () => void>();\n\n    const tryAdd = (wallet: WalletStandardWallet) => {\n      const adapter = build(wallet, (emit) => {\n        disconnectors.set(wallet, emit);\n      });\n      if (!adapter || seenIds.has(adapter.id)) {\n        return;\n      }\n      seenIds.add(adapter.id);\n      onAdapter(adapter);\n    };\n\n    const app = mod.getWallets();\n    for (const wallet of app.get()) {\n      tryAdd(wallet);\n    }\n\n    const offRegister = app.on(\"register\", (...wallets) => {\n      for (const wallet of wallets) {\n        tryAdd(wallet);\n      }\n    });\n    const offUnregister = app.on(\"unregister\", (...wallets) => {\n      for (const wallet of wallets) {\n        const emit = disconnectors.get(wallet);\n        if (emit) {\n          emit();\n          disconnectors.delete(wallet);\n        }\n      }\n    });\n    internalUnsub = () => {\n      offRegister();\n      offUnregister();\n    };\n  })();\n\n  return () => {\n    cancelled = true;\n    internalUnsub?.();\n    internalUnsub = null;\n  };\n};\n\nexport type { WalletStandardAdapterBuilder };\nexport { discoverWalletStandard };\n"],"mappings":"AAoBA,MAAM,GAAW,EAAwB,IAAyB,CAChE,IAAM,EAAO,EACV,KAAK,EACL,YAAY,EACZ,WAAW,OAAA,aAAA,IAAa,EAAG,GAAG,EACjC,OAAO,EAAiB,mBAAmB,EAAe,GAAG,IAAS,mBAAmB,GAC3F,EAOM,GAAiB,EAA8B,IACnC,EAAO,SAAS,IACE,IAAA,GAS9B,GAAgB,EAAiB,KAA+B,CACpE,QACA,GAAI,GAAG,EAAM,GAAG,GAAG,IACnB,cAAe,CACjB,GAMM,EAAoB,GAAwE,CAChG,IAAM,EAAQ,EAAS,GACvB,OAAO,EAAQ,EAAM,QAAU,IACjC,EAUM,GACJ,EACA,IAEA,EAAS,KAAM,GAAM,EAAE,UAAY,CAAO,GAAK,EAAS,GCvBpD,GACJ,EACA,IACiB,CACjB,IAAI,EAAY,GACZ,EAAqC,KAuDzC,OArDM,SAAY,CAChB,IAAI,EACJ,GAAI,CACF,EAAO,MAAM,OAAO,uBACtB,MAAQ,CACN,MACF,CACA,GAAI,EACF,OAGF,IAAM,EAAU,IAAI,IAId,EAAgB,IAAI,IAEpB,EAAU,GAAiC,CAC/C,IAAM,EAAU,EAAM,EAAS,GAAS,CACtC,EAAc,IAAI,EAAQ,CAAI,CAChC,CAAC,EACG,CAAC,GAAW,EAAQ,IAAI,EAAQ,EAAE,IAGtC,EAAQ,IAAI,EAAQ,EAAE,EACtB,EAAU,CAAO,EACnB,EAEM,EAAM,EAAI,WAAW,EAC3B,IAAK,IAAM,KAAU,EAAI,IAAI,EAC3B,EAAO,CAAM,EAGf,IAAM,EAAc,EAAI,GAAG,YAAa,GAAG,IAAY,CACrD,IAAK,IAAM,KAAU,EACnB,EAAO,CAAM,CAEjB,CAAC,EACK,EAAgB,EAAI,GAAG,cAAe,GAAG,IAAY,CACzD,IAAK,IAAM,KAAU,EAAS,CAC5B,IAAM,EAAO,EAAc,IAAI,CAAM,EACjC,IACF,EAAK,EACL,EAAc,OAAO,CAAM,EAE/B,CACF,CAAC,EACD,MAAsB,CACpB,EAAY,EACZ,EAAc,CAChB,CACF,GAAG,MAEU,CACX,EAAY,GACZ,IAAgB,EAChB,EAAgB,IAClB,CACF"}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@usebutr/wallet-standard-shared",
+  "version": "0.1.0",
+  "description": "Shared Wallet Standard discovery primitives used by @usebutr/svm, @usebutr/sui, @usebutr/bitcoin.",
+  "license": "MIT",
+  "author": "Pedro Filho <pedro@filho.me>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pedroapfilho/usebutr.git",
+    "directory": "packages/wallet-standard-shared"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@usebutr/core": "0.1.0"
+  },
+  "devDependencies": {
+    "@wallet-standard/app": "^1.1.0",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.6",
+    "@repo/config-vitest": "0.0.0",
+    "@repo/typescript-config": "0.0.0"
+  },
+  "peerDependencies": {
+    "@wallet-standard/app": "^1.1.0"
+  },
+  "peerDependenciesMeta": {
+    "@wallet-standard/app": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "tsdown",
+    "clean": "rm -rf dist",
+    "dev": "tsdown --watch",
+    "lint": "oxlint src",
+    "test": "vitest run --passWithNoTests",
+    "test:coverage": "vitest run --coverage --passWithNoTests",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}