@joeywallet/wallet-sdk 0.2.0

package/src/detect.ts

@@ -0,0 +1,278 @@
+/**
+ * Finding the wallet.
+ *
+ * This file is load-bearing for adoption, not just for correctness. Every XRPL
+ * wallet aggregator gives a wallet about one second to prove it exists, and a
+ * detection path that costs a message round trip to a sleeping MV3 service
+ * worker will lose that race intermittently — which the aggregator reports to
+ * the user as "not installed", the worst possible failure. So detection reads
+ * the page globals and returns; it never talks to the extension.
+ */
+import { createJoeyClient, type Joey } from './client.js'
+import { JOEY_ERROR_CODES, JoeyRpcError, notInstalledError } from './errors.js'
+import {
+  CAIP294_ANNOUNCE_EVENT,
+  CAIP294_PROMPT_EVENT,
+  WALLET_STANDARD_APP_READY_EVENT,
+  WALLET_STANDARD_REGISTER_EVENT,
+  isJoeyInjectedProvider,
+  type JoeyInjectedProvider,
+} from './provider.js'
+
+/**
+ * One client per injected object.
+ *
+ * React re-renders and aggregator retries both call `getJoey()` repeatedly; a
+ * fresh client each time would leak the event subscriptions the previous one
+ * registered and break referential equality in hook dependency arrays.
+ */
+let cachedProvider: JoeyInjectedProvider | null = null
+let cachedClient: Joey | null = null
+
+interface JoeyGlobals {
+  joey?: unknown
+  xrpl?: { joey?: unknown } | undefined
+}
+
+function globals(): JoeyGlobals | null {
+  // `globalThis` rather than `window` so importing this module in Node (SSR,
+  // Next.js, a test runner) is inert instead of a ReferenceError.
+  if (typeof globalThis === 'undefined') return null
+  return globalThis as unknown as JoeyGlobals
+}
+
+function readProvider(): JoeyInjectedProvider | null {
+  const scope = globals()
+  if (scope === null) return null
+
+  if (isJoeyInjectedProvider(scope.joey)) return scope.joey
+  // `window.xrpl` is Crossmark's namespace; Joey merges into it without
+  // touching anything already there, so this is a legitimate second home.
+  const nested = scope.xrpl?.joey
+  if (isJoeyInjectedProvider(nested)) return nested
+  return null
+}
+
+/**
+ * The Joey client, or `null` when the provider is not on the page.
+ *
+ * Synchronous by design. It is also safe to `await` — the value is not a
+ * promise, so `await getJoey()` costs one microtask and no round trip.
+ */
+export function getJoey(): Joey | null {
+  const provider = readProvider()
+  if (provider === null) return null
+  if (provider !== cachedProvider || cachedClient === null) {
+    cachedProvider = provider
+    cachedClient = createJoeyClient(provider)
+  }
+  return cachedClient
+}
+
+/** Synchronous. Never sends a message, never awaits, never throws. */
+export function isJoeyAvailable(): boolean {
+  return readProvider() !== null
+}
+
+/** Like {@link getJoey}, but throws `JoeyRpcError` 4900 instead of returning null. */
+export function requireJoey(): Joey {
+  const joey = getJoey()
+  if (joey === null) throw notInstalledError()
+  return joey
+}
+
+export interface WaitForJoeyOptions {
+  /** Default 3000. */
+  timeoutMs?: number
+  signal?: AbortSignal
+}
+
+/**
+ * Ask any wallet already on the page to announce itself again.
+ *
+ * Necessary, not merely polite. `waitForJoey` exists for the case where the
+ * dapp's bundle ran *after* the extension installed its provider — and in that
+ * case both announcements have already been dispatched into a page with no
+ * listeners attached. Listening for a second one that will never arrive is how
+ * a detection helper times out against a wallet that is sitting right there,
+ * and the poll below was quietly carrying the whole feature.
+ *
+ * Both protocols define the app's half of the handshake and Joey implements
+ * both: CAIP-294's `wallet_prompt` makes it re-dispatch `wallet_announce`, and
+ * Wallet Standard's `wallet-standard:app-ready` carries a `register` callback
+ * that every listening wallet calls synchronously. The callback's argument is
+ * discarded — the SDK wants the injected provider global, not a Wallet Standard
+ * wallet object — but a wallet that can call it has finished installing, so it
+ * is a reliable "look again now" signal.
+ *
+ * Every step is guarded, but not the way it looks: see {@link dispatchQuietly}
+ * for why a `try`/`catch` is the wrong tool for a listener that throws. Failing
+ * to prompt costs a poll interval, never the detection.
+ */
+function promptForWallets(target: EventTarget, recheck: () => void): void {
+  dispatchQuietly(target, () => new CustomEvent(CAIP294_PROMPT_EVENT))
+
+  dispatchQuietly(
+    target,
+    () =>
+      new CustomEvent(WALLET_STANDARD_APP_READY_EVENT, {
+        detail: {
+          register: (): (() => void) => {
+            recheck()
+            return () => undefined
+          },
+        },
+      }),
+  )
+}
+
+/**
+ * Dispatch one prompt event without a page listener's failure landing on
+ * anybody else.
+ *
+ * **`dispatchEvent` does not rethrow what a listener threw.** DOM's "inner
+ * invoke" *reports* the exception to the global instead and hands the
+ * dispatcher a plain boolean, so the `try`/`catch` that used to sit around
+ * these two calls caught nothing it claimed to. The SDK survived — it always
+ * would have — while the exception went on to the page's `onerror`, its crash
+ * reporter, and (in this repo) the test runner's unhandled-error channel, which
+ * failed a green suite with two errors nothing had thrown at it.
+ *
+ * So what is contained here is the *report*, not a throw. An `error` listener
+ * is installed on the global for the synchronous duration of this one dispatch
+ * and removed in `finally`. Reporting runs inline inside `dispatchEvent` and
+ * there is no `await` and no timer between install and removal, so the only
+ * errors it can possibly see are the ones this prompt caused; `preventDefault()`
+ * marks them handled, which is what suppresses the console entry and the
+ * runner's failure. Everything else the page reports is untouched.
+ *
+ * Realms differ, and the fallback is the same either way. Where the global
+ * reports asynchronously rather than through a cancellable `error` event —
+ * a bare Node `EventTarget` defers to `uncaughtException` — the absorber is
+ * already gone and the exception surfaces as that realm defines. Nothing about
+ * detection changes: the promise is unaffected in every case, because
+ * `dispatchEvent` never had the exception to give us.
+ *
+ * The `try`/`catch` that remains is for what genuinely does throw here: a realm
+ * with no `CustomEvent` constructor, or a global that refuses the dispatch.
+ */
+function dispatchQuietly(target: EventTarget, build: () => Event): void {
+  const absorb = (event: Event): void => {
+    event.preventDefault()
+  }
+
+  let absorbing = false
+  try {
+    target.addEventListener('error', absorb, true)
+    absorbing = true
+  } catch {
+    // A global that will not take an `error` listener. Nothing to absorb.
+  }
+
+  try {
+    target.dispatchEvent(build())
+  } catch {
+    // No `CustomEvent` in this realm, or `dispatchEvent` refused it outright.
+    // The poll still covers us.
+  } finally {
+    if (absorbing) target.removeEventListener('error', absorb, true)
+  }
+}
+
+/**
+ * Resolve once the provider exists.
+ *
+ * For the case the synchronous path cannot cover: a dapp bundle that executed
+ * before the extension's `document_start` content script finished installing
+ * the global. Settles on the provider's own announcement events — and, because
+ * those may already have fired, asks for them again — with a slow poll as a
+ * backstop for a provider that installs the global without announcing at all.
+ */
+export function waitForJoey(options: WaitForJoeyOptions = {}): Promise<Joey> {
+  const { timeoutMs = 3000, signal } = options
+
+  const immediate = getJoey()
+  if (immediate !== null) return Promise.resolve(immediate)
+
+  const scope = globals()
+  if (scope === null || typeof (scope as { addEventListener?: unknown }).addEventListener !== 'function') {
+    return Promise.reject(notInstalledError())
+  }
+  const target = scope as unknown as EventTarget
+
+  return new Promise<Joey>((resolve, reject) => {
+    let settled = false
+    const cleanups: Array<() => void> = []
+
+    const finish = (run: () => void): void => {
+      if (settled) return
+      settled = true
+      for (const cleanup of cleanups) cleanup()
+      run()
+    }
+
+    const check = (): void => {
+      const joey = getJoey()
+      if (joey !== null) finish(() => resolve(joey))
+    }
+
+    for (const event of [
+      CAIP294_ANNOUNCE_EVENT,
+      WALLET_STANDARD_REGISTER_EVENT,
+      'DOMContentLoaded',
+      'load',
+    ]) {
+      target.addEventListener(event, check)
+      cleanups.push(() => target.removeEventListener(event, check))
+    }
+
+    const poll = setInterval(check, 50)
+    cleanups.push(() => clearInterval(poll))
+
+    const timer = setTimeout(() => {
+      finish(() =>
+        reject(
+          new JoeyRpcError(
+            JOEY_ERROR_CODES.DISCONNECTED,
+            `Joey Wallet did not announce itself within ${timeoutMs}ms. It is probably not installed.`,
+          ),
+        ),
+      )
+    }, timeoutMs)
+    cleanups.push(() => clearTimeout(timer))
+
+    if (signal !== undefined) {
+      const onAbort = (): void => {
+        finish(() =>
+          reject(new JoeyRpcError(JOEY_ERROR_CODES.INTERNAL, 'Wallet detection was aborted.')),
+        )
+      }
+      if (signal.aborted) {
+        onAbort()
+        return
+      }
+      signal.addEventListener('abort', onAbort, { once: true })
+      cleanups.push(() => signal.removeEventListener('abort', onAbort))
+    }
+
+    // Covers a provider installed between the synchronous check above and the
+    // listeners being attached.
+    check()
+    if (settled) return
+
+    // Now that we are listening, ask the wallets that announced before we
+    // existed to say it again.
+    promptForWallets(target, check)
+  })
+}
+
+/**
+ * Drop the cached client.
+ *
+ * Only needed by tests and by SPAs that swap the provider at runtime; normal
+ * dapps never call it.
+ */
+export function resetJoeyDetection(): void {
+  cachedProvider = null
+  cachedClient = null
+}

package/src/errors.ts

@@ -0,0 +1,133 @@
+/**
+ * The one error type every SDK method rejects with.
+ *
+ * Codes are EIP-1193 numbers verbatim rather than XRPL-specific strings,
+ * because every wallet aggregator in this ecosystem already branches on them.
+ * Two of them are Joey extensions in the same numeric space: 4300 (locked) and
+ * 4902 (unrecognised chain).
+ */
+
+export const JOEY_ERROR_CODES = {
+  /** The user declined the request in the wallet. */
+  USER_REJECTED: 4001,
+  /** The origin has not been granted access to the requested account. */
+  UNAUTHORIZED: 4100,
+  /** The provider does not implement this method. */
+  UNSUPPORTED_METHOD: 4200,
+  /** A vault exists but is locked, and the user did not unlock it. */
+  LOCKED: 4300,
+  /** No provider, or the provider is not connected to this origin. */
+  DISCONNECTED: 4900,
+  /** The provider is connected but cannot reach the requested chain. */
+  CHAIN_DISCONNECTED: 4901,
+  /**
+   * The requested chain is not one of `xrpl:0`, `xrpl:1`, `xrpl:2` — or the
+   * wallet is on a different one and will not sign for the one you asked for.
+   *
+   * Spelled with a `z`. Both spellings existed: the wallet's
+   * `ProviderErrorCode` used `UNRECOGNIZED_CHAIN` and this table used
+   * `UNRECOGNISED_CHAIN`, which is exactly the kind of thing that survives
+   * until a dapp imports the wrong one. EIP-1193 names the code
+   * "Unrecognized chain ID", so the standard's spelling wins over the rest of
+   * this repo's British prose, and the wallet no longer declares a second copy
+   * to disagree with.
+   */
+  UNRECOGNIZED_CHAIN: 4902,
+  /**
+   * Too many requests from this origin in too short a window.
+   *
+   * Reachable two ways, and a dapp that does not handle it will look broken in
+   * both: the content-script bridge caps concurrent in-flight requests, and the
+   * wallet blocks an origin the user has rejected three times in a row. Back
+   * off; do not retry in a loop.
+   */
+  LIMIT_EXCEEDED: -32005,
+  /** The message was not a well-formed request — no method, or not an object. */
+  INVALID_REQUEST: -32600,
+  /** Malformed arguments; the request never reached the approval queue. */
+  INVALID_PARAMS: -32602,
+  /** Anything the SDK could not classify. */
+  INTERNAL: -32603,
+} as const
+
+export type JoeyErrorCode = (typeof JOEY_ERROR_CODES)[keyof typeof JOEY_ERROR_CODES]
+
+export class JoeyRpcError extends Error {
+  readonly code: number
+  readonly data?: unknown
+
+  constructor(code: number, message: string, data?: unknown) {
+    super(message)
+    this.name = 'JoeyRpcError'
+    this.code = code
+    if (data !== undefined) this.data = data
+    // Restores the prototype chain when this file is transpiled to ES5 by a
+    // consumer's bundler, so `instanceof JoeyRpcError` keeps working.
+    Object.setPrototypeOf(this, JoeyRpcError.prototype)
+  }
+
+  /**
+   * Normalise anything a provider threw into a `JoeyRpcError`.
+   *
+   * Providers reject with plain objects at least as often as with Errors, and
+   * some older shims reject with a bare string.
+   */
+  static from(value: unknown, fallbackCode: number = JOEY_ERROR_CODES.INTERNAL): JoeyRpcError {
+    if (value instanceof JoeyRpcError) return value
+
+    if (typeof value === 'string') {
+      return new JoeyRpcError(codeFromMessage(value, fallbackCode), value)
+    }
+
+    if (typeof value === 'object' && value !== null) {
+      const record = value as { code?: unknown; message?: unknown; data?: unknown }
+      const message =
+        typeof record.message === 'string' && record.message.length > 0
+          ? record.message
+          : 'The wallet request failed.'
+      const code =
+        typeof record.code === 'number' ? record.code : codeFromMessage(message, fallbackCode)
+      return new JoeyRpcError(code, message, record.data)
+    }
+
+    return new JoeyRpcError(fallbackCode, 'The wallet request failed.')
+  }
+}
+
+/**
+ * True when the user declined.
+ *
+ * Also matches on the message, because a provider that predates the numeric
+ * codes (or a shim in between) may only carry the word. This is the same
+ * string match the existing XRPL adapters do, which is why every rejection the
+ * SDK constructs itself is worded to contain "rejected".
+ */
+export function isUserRejection(error: unknown): boolean {
+  if (error instanceof JoeyRpcError) {
+    if (error.code === JOEY_ERROR_CODES.USER_REJECTED) return true
+    return /reject/i.test(error.message)
+  }
+  if (typeof error === 'object' && error !== null) {
+    const record = error as { code?: unknown; message?: unknown }
+    if (record.code === JOEY_ERROR_CODES.USER_REJECTED) return true
+    return typeof record.message === 'string' && /reject/i.test(record.message)
+  }
+  return typeof error === 'string' && /reject/i.test(error)
+}
+
+export function userRejectedError(what = 'The user rejected the request.'): JoeyRpcError {
+  return new JoeyRpcError(JOEY_ERROR_CODES.USER_REJECTED, what)
+}
+
+export function notInstalledError(): JoeyRpcError {
+  return new JoeyRpcError(
+    JOEY_ERROR_CODES.DISCONNECTED,
+    'Joey Wallet is not installed, or its provider has not been injected into this page.',
+  )
+}
+
+function codeFromMessage(message: string, fallbackCode: number): number {
+  return /reject|denied|declined|cancell?ed/i.test(message)
+    ? JOEY_ERROR_CODES.USER_REJECTED
+    : fallbackCode
+}

package/src/index.ts

@@ -0,0 +1,97 @@
+/**
+ * `@joeywallet/wallet-sdk` — the core API.
+ *
+ * Zero runtime dependencies, ESM only, safe to import in Node (every function
+ * that needs a page checks for one first).
+ */
+export {
+  getJoey,
+  isJoeyAvailable,
+  requireJoey,
+  resetJoeyDetection,
+  waitForJoey,
+  type WaitForJoeyOptions,
+} from './detect.js'
+
+export {
+  createJoeyClient,
+  readAccounts,
+  readChain,
+  readNetwork,
+  type Joey,
+} from './client.js'
+
+export {
+  JOEY_ERROR_CODES,
+  JoeyRpcError,
+  isUserRejection,
+  notInstalledError,
+  userRejectedError,
+  type JoeyErrorCode,
+} from './errors.js'
+
+export {
+  APPROVAL_TIMEOUT_MS,
+  CAIP294_ANNOUNCE_EVENT,
+  CAIP294_PROMPT_EVENT,
+  JOEY_DAPP_FORBIDDEN_TRANSACTION_TYPES,
+  JOEY_RDNS,
+  JOEY_RPC_METHODS,
+  JOEY_WALLET_NAME,
+  MAX_BULK_TRANSACTIONS,
+  REQUEST_TIMEOUT_MS,
+  WALLET_STANDARD_APP_READY_EVENT,
+  WALLET_STANDARD_REGISTER_EVENT,
+  invoke,
+  isJoeyInjectedProvider,
+  subscribe,
+  type JoeyInjectedProvider,
+  type JoeyProviderEventName,
+  type JoeyRequestArguments,
+  type JoeyRpcMethod,
+} from './provider.js'
+
+export {
+  JOEY_CHAINS,
+  chainForNetworkId,
+  isJoeyChain,
+  networkIdForChain,
+  type Amount,
+  type AnyTransaction,
+  type ConnectParams,
+  type ConnectResult,
+  type IssuedCurrencyAmount,
+  type JoeyAccount,
+  type JoeyChain,
+  type JoeyEventListener,
+  type JoeyEventMap,
+  type JoeyEventName,
+  type JoeyNetwork,
+  type Memo,
+  type MPTAmount,
+  type Path,
+  type PathStep,
+  type SignAndSubmitTransactionResult,
+  type SigningContextParams,
+  type SignInMode,
+  type SignInParams,
+  type SignInResult,
+  type BulkEntryResult,
+  type BulkEntryStatus,
+  type SignTransactionBulkFailure,
+  type SignTransactionBulkParams,
+  type SignTransactionForParams,
+  type SignTransactionParams,
+  type SignTransactionResult,
+  type Signer,
+  type TransactionLike,
+} from './types.js'
+
+export {
+  initialMutationState,
+  mutationReducer,
+  toPublicState,
+  type MutationAction,
+  type MutationState,
+  type MutationStatus,
+} from './mutation.js'

package/src/mutation.ts

@@ -0,0 +1,109 @@
+/**
+ * The state machine behind the react-query-shaped hooks.
+ *
+ * Kept here, free of React, for two reasons: the reducer is the part with the
+ * interesting edge cases (a stale response landing after a newer one), and it is
+ * testable without a DOM. `@joeywallet/wallet-sdk/react` is a thin binding over it, so
+ * the SDK gains react-query's ergonomics without react-query's dependency.
+ */
+import { JoeyRpcError } from './errors.js'
+
+export type MutationStatus = 'idle' | 'pending' | 'success' | 'error'
+
+export interface MutationState<TData, TVariables> {
+  status: MutationStatus
+  data: TData | undefined
+  error: JoeyRpcError | undefined
+  /** The arguments of the most recent call, kept so a retry needs no closure. */
+  variables: TVariables | undefined
+  isIdle: boolean
+  isPending: boolean
+  isSuccess: boolean
+  isError: boolean
+}
+
+export type MutationAction<TData, TVariables> =
+  | { type: 'reset' }
+  | { type: 'start'; variables: TVariables; runId: number }
+  | { type: 'success'; data: TData; runId: number }
+  | { type: 'error'; error: JoeyRpcError; runId: number }
+
+interface InternalState<TData, TVariables> extends MutationState<TData, TVariables> {
+  /** Identifies the call whose result may still write to this state. */
+  runId: number
+}
+
+export function initialMutationState<TData, TVariables>(): InternalState<TData, TVariables> {
+  return {
+    status: 'idle',
+    data: undefined,
+    error: undefined,
+    variables: undefined,
+    isIdle: true,
+    isPending: false,
+    isSuccess: false,
+    isError: false,
+    runId: 0,
+  }
+}
+
+export function mutationReducer<TData, TVariables>(
+  state: InternalState<TData, TVariables>,
+  action: MutationAction<TData, TVariables>,
+): InternalState<TData, TVariables> {
+  switch (action.type) {
+    case 'reset':
+      return { ...initialMutationState<TData, TVariables>(), runId: state.runId }
+
+    case 'start':
+      return {
+        status: 'pending',
+        // The previous result is cleared so a stale success cannot be rendered
+        // next to a spinner for the call that superseded it.
+        data: undefined,
+        error: undefined,
+        variables: action.variables,
+        isIdle: false,
+        isPending: true,
+        isSuccess: false,
+        isError: false,
+        runId: action.runId,
+      }
+
+    case 'success':
+      // A response from a superseded call is dropped: the user clicked twice,
+      // and the answer to the first click must not overwrite the second.
+      if (action.runId !== state.runId) return state
+      return {
+        ...state,
+        status: 'success',
+        data: action.data,
+        error: undefined,
+        isIdle: false,
+        isPending: false,
+        isSuccess: true,
+        isError: false,
+      }
+
+    case 'error':
+      if (action.runId !== state.runId) return state
+      return {
+        ...state,
+        status: 'error',
+        data: undefined,
+        error: action.error,
+        isIdle: false,
+        isPending: false,
+        isSuccess: false,
+        isError: true,
+      }
+  }
+}
+
+/** The public half of {@link InternalState}, with `runId` dropped. */
+export function toPublicState<TData, TVariables>(
+  state: InternalState<TData, TVariables>,
+): MutationState<TData, TVariables> {
+  const { runId: _runId, ...rest } = state
+  return rest
+}