@joeywallet/wallet-sdk 0.2.0

package/dist/vanilla.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vanilla.js","sourceRoot":"","sources":["../src/vanilla.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAClD,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAiC5D,MAAM,UAAU,iBAAiB,CAAC,UAAoC,EAAE;IACtE,MAAM,EAAE,WAAW,GAAG,IAAI,EAAE,eAAe,GAAG,IAAI,EAAE,GAAG,OAAO,CAAA;IAE9D,MAAM,OAAO,GAAG,OAAO,EAAE,CAAA;IACzB,IAAI,KAAK,GAAqB;QAC5B,IAAI,EAAE,OAAO;QACb,WAAW,EAAE,OAAO,KAAK,IAAI;QAC7B,OAAO,EAAE,OAAO,KAAK,IAAI;QACzB,YAAY,EAAE,KAAK;QACnB,QAAQ,EAAE,EAAE;QACZ,OAAO,EAAE,IAAI;QACb,OAAO,EAAE,IAAI;QACb,KAAK,EAAE,IAAI;KACZ,CAAA;IAED,MAAM,SAAS,GAAG,IAAI,GAAG,EAAqC,CAAA;IAC9D,MAAM,QAAQ,GAAsB,EAAE,CAAA;IACtC,IAAI,SAAS,GAAG,KAAK,CAAA;IAErB,MAAM,GAAG,GAAG,CAAC,KAAgC,EAAQ,EAAE;QACrD,MAAM,IAAI,GAAG,EAAE,GAAG,KAAK,EAAE,GAAG,KAAK,EAAE,CAAA;QACnC,2EAA2E;QAC3E,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,IAAI,CAAA;QACvC,KAAK,GAAG,IAAI,CAAA;QACZ,KAAK,MAAM,QAAQ,IAAI,SAAS;YAAE,QAAQ,CAAC,KAAK,CAAC,CAAA;IACnD,CAAC,CAAA;IAED,MAAM,MAAM,GAAG,CAAC,IAAU,EAAQ,EAAE;QAClC,QAAQ,CAAC,IAAI,CACX,IAAI,CAAC,EAAE,CAAC,iBAAiB,EAAE,CAAC,QAAQ,EAAE,EAAE,CACtC,GAAG,CAAC,EAAE,QAAQ,EAAE,QAAQ,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC,CAC9D,CACF,CAAA;QACD,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,gBAAgB,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,GAAG,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,CAAA;QACvE,QAAQ,CAAC,IAAI,CACX,IAAI,CAAC,EAAE,CAAC,SAAS,EAAE,CAAC,MAAM,EAAE,EAAE,CAC5B,GAAG,CAAC,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC,CACrE,CACF,CAAA;QACD,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,YAAY,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,CAAA;IACnE,CAAC,CAAA;IAED,MAAM,OAAO,GAAG,KAAK,EAAE,IAAU,EAAiB,EAAE;QAClD,MAAM,CAAC,QAAQ,EAAE,OAAO,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;YAC5C,IAAI,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAc,CAAC;YAC9C,IAAI,CAAC,UAAU,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC;SACpC,CAAC,CAAA;QACF,IAAI,CAAC,SAAS;YAAE,GAAG,CAAC,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC,CAAA;IAC5C,CAAC,CAAA;IAED,MAAM,KAAK,GAAG,KAAK,EAAE,IAAU,EAAiB,EAAE;QAChD,IAAI,SAAS;YAAE,OAAM;QACrB,GAAG,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAA;QAC/C,MAAM,CAAC,IAAI,CAAC,CAAA;QACZ,IAAI,WAAW,EAAE,CAAC;YAChB,IAAI,CAAC;gBACH,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAA;gBACnD,IAAI,SAAS;oBAAE,OAAM;gBACrB,IAAI,MAAM,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;oBAC/B,GAAG,CAAC,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC,CAAA;oBACpE,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,UAAU,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAA;oBACzD,IAAI,CAAC,SAAS;wBAAE,GAAG,CAAC,EAAE,OAAO,EAAE,CAAC,CAAA;oBAChC,OAAM;gBACR,CAAC;YACH,CAAC;YAAC,MAAM,CAAC;gBACP,iDAAiD;YACnD,CAAC;QACH,CAAC;QACD,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;IACrB,CAAC,CAAA;IAED,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;QACrB,KAAK,KAAK,CAAC,OAAO,CAAC,CAAA;IACrB,CAAC;SAAM,CAAC;QACN,KAAK,WAAW,CAAC,EAAE,SAAS,EAAE,eAAe,EAAE,CAAC;aAC7C,IAAI,CAAC,KAAK,CAAC;aACX,KAAK,CAAC,GAAG,EAAE;YACV,IAAI,CAAC,SAAS;gBAAE,GAAG,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAA;QACxC,CAAC,CAAC,CAAA;IACN,CAAC;IAED,OAAO;QACL,QAAQ,EAAE,GAAG,EAAE,CAAC,KAAK;QAErB,SAAS,CAAC,QAAQ;YAChB,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAA;YACvB,QAAQ,CAAC,KAAK,CAAC,CAAA;YACf,OAAO,GAAG,EAAE,CAAC,SAAS,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAA;QACzC,CAAC;QAED,KAAK,CAAC,OAAO,CAAC,MAAM;YAClB,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,IAAI,OAAO,EAAE,CAAA;YACpC,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;gBAClB,MAAM,KAAK,GAAG,IAAI,YAAY,CAC5B,gBAAgB,CAAC,YAAY,EAC7B,qFAAqF,CACtF,CAAA;gBACD,GAAG,CAAC,EAAE,KAAK,EAAE,CAAC,CAAA;gBACd,MAAM,KAAK,CAAA;YACb,CAAC;YACD,GAAG,CAAC,EAAE,YAAY,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAA;YACxC,IAAI,CAAC;gBACH,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAA;gBACzC,MAAM,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,CAAA;gBAClE,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,UAAU,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,CAAA;gBAClE,GAAG,CAAC,EAAE,QAAQ,EAAE,OAAO,EAAE,YAAY,EAAE,KAAK,EAAE,CAAC,CAAA;gBAC/C,OAAO,QAAQ,CAAC,CAAC,CAAC,IAAI,IAAI,CAAA;YAC5B,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,MAAM,KAAK,GAAG,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;gBACtC,GAAG,CAAC,EAAE,YAAY,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAA;gBACnC,MAAM,KAAK,CAAA;YACb,CAAC;QACH,CAAC;QAED,KAAK,CAAC,UAAU;YACd,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAA;YACvB,IAAI,IAAI,KAAK,IAAI;gBAAE,OAAM;YACzB,MAAM,IAAI,CAAC,UAAU,EAAE,CAAA;YACvB,GAAG,CAAC,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC,CAAA;QACvB,CAAC;QAED,OAAO;YACL,SAAS,GAAG,IAAI,CAAA;YAChB,KAAK,MAAM,GAAG,IAAI,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;gBAAE,GAAG,EAAE,CAAA;YAC3C,SAAS,CAAC,KAAK,EAAE,CAAA;QACnB,CAAC;KACF,CAAA;AACH,CAAC;AAcD;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAC/B,MAAyB,EACzB,OAAoB,EACpB,UAAoC,EAAE;IAEtC,MAAM,EACJ,YAAY,GAAG,cAAc,EAC7B,cAAc,GAAG,CAAC,OAAO,EAAE,EAAE,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,EAC3E,iBAAiB,GAAG,cAAc,EAClC,UAAU,EACV,OAAO,GACR,GAAG,OAAO,CAAA;IAEX,MAAM,MAAM,GAAG,CAAC,KAAuB,EAAQ,EAAE;QAC/C,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC;YACnB,MAAM,CAAC,QAAQ,GAAG,IAAI,CAAA;YACtB,MAAM,CAAC,WAAW,GAAG,YAAY,CAAA;YACjC,OAAM;QACR,CAAC;QACD,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC;YACvB,MAAM,CAAC,QAAQ,GAAG,UAAU,KAAK,SAAS,CAAA;YAC1C,MAAM,CAAC,WAAW,GAAG,iBAAiB,CAAA;YACtC,OAAM;QACR,CAAC;QACD,MAAM,CAAC,QAAQ,GAAG,KAAK,CAAC,YAAY,CAAA;QACpC,MAAM,CAAC,WAAW,GAAG,KAAK,CAAC,OAAO,KAAK,IAAI,CAAC,CAAC,CAAC,cAAc,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,YAAY,CAAA;IAC5F,CAAC,CAAA;IAED,MAAM,OAAO,GAAG,GAAS,EAAE;QACzB,MAAM,KAAK,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAA;QAChC,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC;YACvB,IAAI,UAAU,KAAK,SAAS;gBAAE,MAAM,CAAC,IAAI,CAAC,UAAU,EAAE,QAAQ,EAAE,qBAAqB,CAAC,CAAA;YACtF,OAAM;QACR,CAAC;QACD,uEAAuE;QACvE,4CAA4C;QAC5C,KAAK,OAAO,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;YAC9C,OAAO,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAA;QACrC,CAAC,CAAC,CAAA;IACJ,CAAC,CAAA;IAED,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAA;IACzC,MAAM,WAAW,GAAG,OAAO,CAAC,SAAS,CAAC,MAAM,CAAC,CAAA;IAE7C,OAAO,GAAG,EAAE;QACV,MAAM,CAAC,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAA;QAC5C,WAAW,EAAE,CAAA;IACf,CAAC,CAAA;AACH,CAAC"}

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@joeywallet/wallet-sdk",
+  "version": "0.2.0",
+  "description": "Dependency-free TypeScript SDK for the Joey Wallet browser extension (XLS-72d / Wallet Standard).",
+  "license": "MIT",
+  "homepage": "https://github.com/Joey-Wallet/joey-wallet-sdk#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Joey-Wallet/joey-wallet-sdk.git",
+    "directory": "packages/sdk"
+  },
+  "bugs": {
+    "url": "https://github.com/Joey-Wallet/joey-wallet-sdk/issues"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "import": "./dist/react.js"
+    },
+    "./vanilla": {
+      "types": "./dist/vanilla.d.ts",
+      "import": "./dist/vanilla.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "LICENSE",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/react": "19.0.2",
+    "react": "19.0.0",
+    "typescript": "5.7.2",
+    "xrpl": "4.2.5"
+  },
+  "keywords": [
+    "xrpl",
+    "wallet",
+    "joey",
+    "xls-72d",
+    "wallet-standard"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "ts:check": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json"
+  }
+}

package/src/client.ts

@@ -0,0 +1,342 @@
+/**
+ * The typed API a dapp actually calls.
+ *
+ * Every method resolves a value or rejects with a {@link JoeyRpcError}. There is
+ * deliberately no `{ type, result }` envelope: an envelope forces a branch at
+ * every call site, and a promise rejection is what a JS developer already writes
+ * `try`/`catch` around.
+ *
+ * Event payloads are normalised here rather than passed through raw. The
+ * provider forwards whatever the background sent, which is the right choice for
+ * a protocol layer and the wrong one for a dapp — a listener should not have to
+ * guess whether `accountsChanged` carried an array, an object with an
+ * `accounts` key, or a list of bare address strings.
+ */
+import { JOEY_ERROR_CODES, JoeyRpcError } from './errors.js'
+import {
+  JOEY_RPC_METHODS,
+  invoke,
+  subscribe,
+  type JoeyInjectedProvider,
+  type JoeyProviderEventName,
+  type JoeyRequestArguments,
+  type JoeyRpcMethod,
+} from './provider.js'
+import {
+  isJoeyChain,
+  networkIdForChain,
+  type AnyTransaction,
+  type ConnectParams,
+  type ConnectResult,
+  type JoeyAccount,
+  type JoeyChain,
+  type JoeyEventListener,
+  type JoeyEventName,
+  type JoeyNetwork,
+  type SignAndSubmitTransactionResult,
+  type SignInParams,
+  type SignInResult,
+  type SignTransactionBulkParams,
+  type SignTransactionForParams,
+  type SignTransactionParams,
+  type SignTransactionResult,
+  type TransactionLike,
+} from './types.js'
+
+export interface Joey {
+  /** The raw injected object, for anything this SDK version does not model. */
+  readonly provider: JoeyInjectedProvider
+  /** Version of the injected surface, when the provider reports one. */
+  readonly version: string | undefined
+  /** Reverse-DNS identity, `xyz.joeywallet`. */
+  readonly rdns: string | undefined
+  /** Granted addresses, read synchronously. `[]` until the user connects. */
+  readonly accounts: readonly string[]
+  /** The chain the wallet is on, or `null` before the first connect. */
+  readonly chain: JoeyChain | null
+
+  /** Synchronous. True once the user has granted this origin an account. */
+  isConnected(): boolean
+
+  connect(params?: ConnectParams): Promise<ConnectResult>
+  disconnect(): Promise<void>
+  /** Granted addresses. `[]` for an origin with no grant — never an error. */
+  getAccounts(): Promise<string[]>
+  getNetwork(): Promise<JoeyNetwork>
+
+  signTransaction<TTx extends TransactionLike = AnyTransaction>(
+    params: SignTransactionParams<TTx>,
+  ): Promise<SignTransactionResult>
+
+  signAndSubmitTransaction<TTx extends TransactionLike = AnyTransaction>(
+    params: SignTransactionParams<TTx>,
+  ): Promise<SignAndSubmitTransactionResult>
+
+  /** Add one signature to a multisigned transaction. */
+  signTransactionFor<TTx extends TransactionLike = AnyTransaction>(
+    params: SignTransactionForParams<TTx>,
+  ): Promise<SignTransactionResult>
+
+  /**
+   * One approval, up to `MAX_BULK_TRANSACTIONS` transactions, signed in order.
+   *
+   * Resolves with one entry per transaction, in the order you sent them.
+   * `engine_result` is present only when you asked for `submit: true` — with
+   * `submit: false` nothing is broadcast, so there is no engine result to give.
+   *
+   * A batch that fails part way *rejects*, and the error's `data` is a
+   * {@link SignTransactionBulkFailure} carrying every signed blob and which
+   * index stopped it. Read that rather than re-prompting the user.
+   */
+  signTransactionBulk<TTx extends TransactionLike = AnyTransaction>(
+    params: SignTransactionBulkParams<TTx>,
+  ): Promise<SignAndSubmitTransactionResult[]>
+
+  signIn(params?: SignInParams): Promise<SignInResult>
+
+  /** Escape hatch for a method the wallet added after this SDK was published. */
+  request<TResult = unknown>(args: JoeyRequestArguments): Promise<TResult>
+
+  on<K extends JoeyEventName>(event: K, listener: JoeyEventListener<K>): () => void
+  off<K extends JoeyEventName>(event: K, listener: JoeyEventListener<K>): void
+}
+
+/* --------------------------------------------------------------- normalising */
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+/**
+ * Read an account list out of whatever the wallet sent.
+ *
+ * Accepts a bare array, `{ accounts: [...] }`, and entries that are either
+ * address strings or objects — the shapes the provider and the background
+ * between them can produce.
+ */
+export function readAccounts(value: unknown): JoeyAccount[] {
+  const source = Array.isArray(value) ? value : isRecord(value) ? value.accounts : undefined
+  if (!Array.isArray(source)) return []
+
+  const out: JoeyAccount[] = []
+  for (const entry of source) {
+    if (typeof entry === 'string') {
+      out.push({ address: entry })
+      continue
+    }
+    if (!isRecord(entry) || typeof entry.address !== 'string') continue
+    const account: JoeyAccount = { address: entry.address }
+    if (typeof entry.publicKey === 'string') account.publicKey = entry.publicKey
+    if (typeof entry.label === 'string') account.label = entry.label
+    out.push(account)
+  }
+  return out
+}
+
+export function readChain(value: unknown): JoeyChain | null {
+  if (isJoeyChain(value)) return value
+  if (!isRecord(value)) return null
+  return isJoeyChain(value.chain) ? value.chain : null
+}
+
+export function readNetwork(value: unknown): JoeyNetwork | null {
+  const chain = readChain(value)
+  if (chain === null) return null
+  const record = isRecord(value) ? value : {}
+  return {
+    chain,
+    networkId:
+      typeof record.networkId === 'number' ? record.networkId : (networkIdForChain(chain) ?? 0),
+    name: typeof record.name === 'string' ? record.name : chain,
+  }
+}
+
+/* -------------------------------------------------------------------- client */
+
+/** Wrap a raw injected provider in the typed API. */
+export function createJoeyClient(provider: JoeyInjectedProvider): Joey {
+  /**
+   * Unsubscribe functions, keyed by the exact listener the caller handed us.
+   *
+   * Needed because the SDK subscribes a *wrapper* that normalises the payload,
+   * so the provider never sees the caller's own function.
+   *
+   * The value is a stack, not a single function, because a listener may be
+   * registered more than once and each registration is a separate subscription
+   * on the provider. Storing one function per listener silently dropped the
+   * earlier registration's unsubscriber: `off()` then removed the newest, the
+   * oldest kept firing, and nothing the dapp could call would ever remove it.
+   * A React effect that re-subscribes on a dependency change and unsubscribes
+   * on cleanup does exactly this, in that order, on every render — so the leak
+   * compounds. Each `off()` removes one registration, newest first, which is
+   * what `addEventListener`-shaped APIs do.
+   */
+  const unsubscribers = new Map<JoeyEventName, Map<unknown, Array<() => void>>>()
+
+  const call = async <TResult>(method: JoeyRpcMethod, params?: unknown): Promise<TResult> => {
+    try {
+      return await invoke<TResult>(provider, method, params)
+    } catch (cause) {
+      throw JoeyRpcError.from(cause)
+    }
+  }
+
+  /** Drop one specific registration, wherever it sits in the stack. */
+  const release = (
+    event: JoeyEventName,
+    listener: unknown,
+    unsubscribe: () => void,
+  ): void => {
+    const forEvent = unsubscribers.get(event)
+    const stack = forEvent?.get(listener)
+    if (stack === undefined) return
+    const at = stack.lastIndexOf(unsubscribe)
+    if (at === -1) return
+    stack.splice(at, 1)
+    if (stack.length === 0) forEvent?.delete(listener)
+    unsubscribe()
+  }
+
+  const normalise: {
+    [K in JoeyEventName]: (payload: unknown) => Parameters<JoeyEventListener<K>>[0]
+  } = {
+    connect: (payload) => ({ accounts: readAccounts(payload), chain: readChain(payload) }),
+    disconnect: (payload) =>
+      isRecord(payload) && typeof payload.reason === 'string' ? { reason: payload.reason } : {},
+    accountsChanged: (payload) => readAccounts(payload),
+    networkChanged: (payload) => readNetwork(payload),
+  }
+
+  const client: Joey = {
+    provider,
+    version: typeof provider.version === 'string' ? provider.version : undefined,
+    rdns: typeof provider.rdns === 'string' ? provider.rdns : undefined,
+
+    get accounts() {
+      return provider.accounts ?? []
+    },
+
+    get chain() {
+      return provider.chain ?? null
+    },
+
+    isConnected() {
+      if (typeof provider.isConnected === 'function') return provider.isConnected()
+      return (provider.accounts ?? []).length > 0
+    },
+
+    async connect(params) {
+      const result = await call<unknown>(JOEY_RPC_METHODS.connect, params ?? {})
+      const record = isRecord(result) ? result : {}
+      const chain = readChain(record)
+      return {
+        accounts: readAccounts(record),
+        chain,
+        networkId:
+          typeof record.networkId === 'number'
+            ? record.networkId
+            : chain === null
+              ? null
+              : networkIdForChain(chain),
+      }
+    },
+
+    async disconnect() {
+      await call<unknown>(JOEY_RPC_METHODS.disconnect, {})
+    },
+
+    async getAccounts() {
+      const result = await call<unknown>(JOEY_RPC_METHODS.getAccounts, {})
+      // The provider answers with bare addresses; the background may answer with
+      // account objects. Both collapse to addresses here.
+      return readAccounts(result).map((account) => account.address)
+    },
+
+    async getNetwork() {
+      const result = await call<unknown>(JOEY_RPC_METHODS.getNetwork, {})
+      const network = readNetwork(result)
+      if (network === null) {
+        throw new JoeyRpcError(
+          JOEY_ERROR_CODES.UNRECOGNIZED_CHAIN,
+          'The wallet reported a chain this SDK does not recognise.',
+        )
+      }
+      return network
+    },
+
+    signTransaction(params) {
+      return call<SignTransactionResult>(JOEY_RPC_METHODS.signTransaction, params)
+    },
+
+    signAndSubmitTransaction(params) {
+      return call<SignAndSubmitTransactionResult>(
+        JOEY_RPC_METHODS.signAndSubmitTransaction,
+        params,
+      )
+    },
+
+    signTransactionFor(params) {
+      return call<SignTransactionResult>(JOEY_RPC_METHODS.signTransactionFor, params)
+    },
+
+    signTransactionBulk(params) {
+      return call<SignAndSubmitTransactionResult[]>(
+        JOEY_RPC_METHODS.signTransactionBulk,
+        params,
+      )
+    },
+
+    signIn(params) {
+      return call<SignInResult>(JOEY_RPC_METHODS.signIn, params ?? {})
+    },
+
+    async request(args) {
+      try {
+        return await provider.request(args)
+      } catch (cause) {
+        throw JoeyRpcError.from(cause)
+      }
+    },
+
+    on(event, listener) {
+      const wrapped = (payload: unknown): void => {
+        ;(listener as (value: unknown) => void)(normalise[event](payload))
+      }
+      const unsubscribe = subscribe(
+        provider,
+        event as JoeyProviderEventName,
+        wrapped as (payload: never) => void,
+      )
+
+      let forEvent = unsubscribers.get(event)
+      if (forEvent === undefined) {
+        forEvent = new Map()
+        unsubscribers.set(event, forEvent)
+      }
+      const stack = forEvent.get(listener)
+      if (stack === undefined) forEvent.set(listener, [unsubscribe])
+      else stack.push(unsubscribe)
+
+      // The returned function removes *this* registration, once. Calling it
+      // twice must not take a sibling registration down with it.
+      let released = false
+      return () => {
+        if (released) return
+        released = true
+        release(event, listener, unsubscribe)
+      }
+    },
+
+    off(event, listener) {
+      const stack = unsubscribers.get(event)?.get(listener)
+      const unsubscribe = stack?.pop()
+      if (unsubscribe === undefined) return
+      unsubscribe()
+      if (stack !== undefined && stack.length === 0) {
+        unsubscribers.get(event)?.delete(listener)
+      }
+    },
+  }
+
+  return Object.freeze(client)
+}