@joeywallet/wallet-sdk 0.2.0

package/src/provider.ts

@@ -0,0 +1,229 @@
+/**
+ * The object the extension injects into the page's MAIN world, as this SDK sees
+ * it.
+ *
+ * It is mounted at both `window.joey` and `window.xrpl.joey` (the latter by a
+ * non-destructive merge, so Crossmark's `window.xrpl` keeps working). The
+ * declaration below is a structural view of
+ * `apps/extension/src/provider/provider.ts`; anything the wallet adds later is
+ * still reachable through `request()`.
+ */
+import type {
+  ConnectParams,
+  ConnectResult,
+  JoeyChain,
+  JoeyNetwork,
+  SignAndSubmitTransactionResult,
+  SignInParams,
+  SignInResult,
+  SignTransactionBulkParams,
+  SignTransactionForParams,
+  SignTransactionParams,
+  SignTransactionResult,
+} from './types.js'
+
+/**
+ * Wire method names.
+ *
+ * Short, unprefixed names: the injected provider is already a Joey-specific
+ * object, and the same table is what the content-script bridge and the
+ * background validate against. The three that also exist over WalletConnect
+ * (`signTransaction`, `signTransactionFor`, `signTransactionBulk`) carry the
+ * same parameter shapes as Joey mobile, minus the `xrpl_` namespace prefix that
+ * only WalletConnect needs.
+ */
+export const JOEY_RPC_METHODS = {
+  connect: 'connect',
+  disconnect: 'disconnect',
+  getAccounts: 'getAccounts',
+  getNetwork: 'getNetwork',
+  signTransaction: 'signTransaction',
+  signAndSubmitTransaction: 'signAndSubmitTransaction',
+  signTransactionFor: 'signTransactionFor',
+  signTransactionBulk: 'signTransactionBulk',
+  signIn: 'signIn',
+} as const
+
+export type JoeyRpcMethod = (typeof JOEY_RPC_METHODS)[keyof typeof JOEY_RPC_METHODS]
+
+export interface JoeyRequestArguments {
+  method: string
+  params?: unknown
+}
+
+/** Events the wallet pushes. Payloads are unnormalised at this layer. */
+export type JoeyProviderEventName = 'connect' | 'disconnect' | 'accountsChanged' | 'networkChanged'
+
+export interface JoeyInjectedProvider {
+  readonly isJoey?: boolean
+  /** Reverse-DNS identity, `xyz.joeywallet`. Used by CAIP-294 and aggregators. */
+  readonly rdns?: string
+  /** Version of the injected surface, not of the extension. */
+  readonly version?: string
+  /** Granted addresses for this origin. `[]` until the user connects. */
+  readonly accounts?: readonly string[]
+  readonly chain?: JoeyChain | null
+
+  isAvailable?(): boolean
+  isConnected?(): boolean
+
+  connect?(params?: ConnectParams): Promise<ConnectResult>
+  disconnect?(): Promise<void>
+  getAccounts?(): Promise<string[]>
+  getNetwork?(): Promise<JoeyNetwork>
+  signTransaction?(params: SignTransactionParams): Promise<SignTransactionResult>
+  signAndSubmitTransaction?(
+    params: SignTransactionParams,
+  ): Promise<SignAndSubmitTransactionResult>
+  signTransactionFor?(params: SignTransactionForParams): Promise<SignTransactionResult>
+  signTransactionBulk?(params: SignTransactionBulkParams): Promise<SignTransactionResult[]>
+  signIn?(params?: SignInParams): Promise<SignInResult>
+
+  /** EIP-1193-shaped escape hatch. Always present. */
+  request<TResult = unknown>(args: JoeyRequestArguments): Promise<TResult>
+
+  /** Returns an unsubscribe function. */
+  on(event: JoeyProviderEventName, listener: (payload: never) => void): (() => void) | void
+  removeListener?(event: JoeyProviderEventName, listener: (payload: never) => void): void
+  /** Not implemented by Joey, but common enough elsewhere to be worth trying. */
+  off?(event: JoeyProviderEventName, listener: (payload: never) => void): void
+}
+
+/** The name Joey registers under with the Wallet Standard. */
+export const JOEY_WALLET_NAME = 'Joey'
+export const JOEY_RDNS = 'xyz.joeywallet'
+
+/**
+ * Events that mean "the provider just finished installing itself".
+ *
+ * Both are dispatched synchronously by the provider's install step, so a page
+ * whose bundle ran before `document_start` injection completed can wait on them
+ * instead of polling. There is no Joey-specific ready event on purpose: an
+ * extra global signal is one more thing a page can probe to fingerprint the
+ * extension, and these two already exist for discovery.
+ */
+export const CAIP294_ANNOUNCE_EVENT = 'wallet_announce'
+export const WALLET_STANDARD_REGISTER_EVENT = 'wallet-standard:register-wallet'
+
+/**
+ * Events an *app* dispatches to make wallets announce themselves again.
+ *
+ * The counterparts to the two above, and the half that matters for a late
+ * bundle: a wallet that installed before your code ran has already dispatched
+ * its announcement into a page with nobody listening. Waiting for a second one
+ * that will never come is how a detection helper times out against a wallet
+ * that is sitting right there. {@link waitForJoey} dispatches both.
+ */
+export const CAIP294_PROMPT_EVENT = 'wallet_prompt'
+export const WALLET_STANDARD_APP_READY_EVENT = 'wallet-standard:app-ready'
+
+/* ------------------------------------------------------------------ limits */
+
+/**
+ * How long the wallet's own plumbing will wait before answering for it.
+ *
+ * Published because a dapp cannot otherwise size its own spinner or its own
+ * retry, and the two numbers are three orders of magnitude apart on purpose. A
+ * method that never touches the approval queue — `getAccounts`, `getNetwork`,
+ * `disconnect` — answers in milliseconds or the extension's worker is wedged,
+ * so it gets {@link REQUEST_TIMEOUT_MS}. A method that does touch the queue is
+ * waiting on a person reading a transaction, and its ceiling is
+ * {@link APPROVAL_TIMEOUT_MS}, which matches the approval's own expiry: a
+ * shorter one would fail a dapp for a signature the user did in fact give.
+ *
+ * So `signTransaction` can legitimately be pending for five minutes, and with
+ * the page's own backstop on top of it, a little over five. Do not put a
+ * thirty-second timeout around it.
+ */
+export const REQUEST_TIMEOUT_MS = 30_000
+export const APPROVAL_TIMEOUT_MS = 300_000
+
+/**
+ * The most transactions `signTransactionBulk` will accept in one call.
+ *
+ * Exported so a dapp can split its own work rather than discover the rule by
+ * rejection. The wallet enforces it; this is the same constant, imported by the
+ * wallet from here.
+ */
+export const MAX_BULK_TRANSACTIONS = 32
+
+/**
+ * Transaction types Joey refuses to sign for a website, whatever the user
+ * clicks and whichever method carries them.
+ *
+ * Published so a dapp can check before it builds a flow around one, and so the
+ * refusal is a documented rule rather than a surprise `4100`. Every entry hands
+ * over or destroys the account itself:
+ *
+ * - `SetRegularKey`, `SignerListSet` and `DelegateSet` (XLS-75) each grant
+ *   permanent authority to act as the account, by three separate mechanisms.
+ * - `AccountDelete` is irreversible.
+ * - `SetHook` installs code that runs on every future transaction.
+ * - `Batch` (XLS-56) carries other transactions inside `RawTransactions`, and
+ *   Joey's approval screen renders the outer transaction. A user cannot consent
+ *   to something they were never shown, so it is refused until the review
+ *   screen can render inner transactions individually.
+ *
+ * Two rules are not expressible as a type name and are enforced anyway:
+ * `AccountSet` is refused when it sets or clears a flag that changes who
+ * controls the account (`asfDisableMaster`, `asfRequireAuth`, `asfNoFreeze` and
+ * the rest of that family) and permitted otherwise; and the ledger's
+ * pseudo-transactions — `EnableAmendment`, `SetFee`, `UNLModify` — are refused
+ * because no account signs one.
+ *
+ * The wallet checks at every nesting level, not just the top.
+ */
+export const JOEY_DAPP_FORBIDDEN_TRANSACTION_TYPES: readonly string[] = Object.freeze([
+  'SetRegularKey',
+  'SignerListSet',
+  'DelegateSet',
+  'AccountDelete',
+  'SetHook',
+  'Batch',
+])
+
+export function isJoeyInjectedProvider(value: unknown): value is JoeyInjectedProvider {
+  if (typeof value !== 'object' || value === null) return false
+  const candidate = value as Partial<JoeyInjectedProvider>
+  return typeof candidate.request === 'function' && typeof candidate.on === 'function'
+}
+
+/**
+ * Call a provider method by name, preferring the typed method over `request()`.
+ *
+ * The typed methods are not just sugar: `connect`, `disconnect` and
+ * `getAccounts` update the provider's own `accounts` and `chain` state, which a
+ * dapp reads synchronously through `joey.accounts` / `joey.isConnected()`.
+ * Routing those through `request()` would leave that state stale. `request()`
+ * remains the fallback for a provider older or newer than this SDK.
+ */
+export async function invoke<TResult>(
+  provider: JoeyInjectedProvider,
+  method: JoeyRpcMethod,
+  params?: unknown,
+): Promise<TResult> {
+  const implementation = (provider as unknown as Record<string, unknown>)[method]
+  if (typeof implementation === 'function') {
+    return (await (implementation as (arg?: unknown) => Promise<unknown>).call(
+      provider,
+      params,
+    )) as TResult
+  }
+  return await provider.request<TResult>(
+    params === undefined ? { method } : { method, params },
+  )
+}
+
+/** Subscribe, tolerating a provider that reports removal three different ways. */
+export function subscribe(
+  provider: JoeyInjectedProvider,
+  event: JoeyProviderEventName,
+  listener: (payload: never) => void,
+): () => void {
+  const returned = provider.on(event, listener)
+  if (typeof returned === 'function') return returned
+  return () => {
+    if (typeof provider.removeListener === 'function') provider.removeListener(event, listener)
+    else if (typeof provider.off === 'function') provider.off(event, listener)
+  }
+}

package/src/react.ts

@@ -0,0 +1,375 @@
+/**
+ * `@joeywallet/wallet-sdk/react`.
+ *
+ * The hooks are shaped like react-query mutations — `{ mutate, mutateAsync,
+ * isPending, error, data, reset }` — because that is the shape web3 developers
+ * already have muscle memory for. They do not depend on react-query: a wallet
+ * SDK that drags a cache library into every dapp is a tax on integration, and
+ * none of react-query's real features (caching, invalidation, retries) apply to
+ * a call whose side effect is a human clicking Approve.
+ *
+ * `react` is an optional peer dependency. Nothing in the core entry point
+ * imports this file.
+ */
+import {
+  createContext,
+  createElement,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useReducer,
+  useRef,
+  useState,
+  type ReactNode,
+} from 'react'
+
+import type { Joey } from './client.js'
+import { getJoey, waitForJoey } from './detect.js'
+import { JOEY_ERROR_CODES, JoeyRpcError } from './errors.js'
+import {
+  initialMutationState,
+  mutationReducer,
+  toPublicState,
+  type MutationState,
+} from './mutation.js'
+import type {
+  AnyTransaction,
+  ConnectParams,
+  ConnectResult,
+  JoeyNetwork,
+  SignAndSubmitTransactionResult,
+  SignInParams,
+  SignInResult,
+  SignTransactionBulkParams,
+  SignTransactionForParams,
+  SignTransactionParams,
+  SignTransactionResult,
+  TransactionLike,
+} from './types.js'
+
+function notInstalled(): JoeyRpcError {
+  return new JoeyRpcError(
+    JOEY_ERROR_CODES.DISCONNECTED,
+    'Joey Wallet is not installed, or its provider has not been injected into this page.',
+  )
+}
+
+/* ------------------------------------------------------------------ context */
+
+export interface JoeyContextValue {
+  /** `null` until the provider is found, and forever if it never appears. */
+  joey: Joey | null
+  isAvailable: boolean
+  /** True once detection has finished, whether or not it found anything. */
+  isReady: boolean
+  /** Every address granted to this origin. */
+  accounts: string[]
+  /** The first granted address, which is what most dapps mean by "the account". */
+  account: string | null
+  network: JoeyNetwork | null
+  isConnected: boolean
+  connect(params?: ConnectParams): Promise<ConnectResult>
+  disconnect(): Promise<void>
+  /** Re-read the accounts and network from the wallet. */
+  refresh(): Promise<void>
+}
+
+const JoeyContext = createContext<JoeyContextValue | null>(null)
+
+export interface JoeyProviderProps {
+  children?: ReactNode
+  /**
+   * Attempt a silent reconnect on mount. Only returns accounts the user already
+   * granted this origin, so it never opens an approval window.
+   */
+  autoConnect?: boolean
+  /** How long to wait for a late-injected provider. Default 3000ms. */
+  detectTimeoutMs?: number
+}
+
+export function JoeyProvider(props: JoeyProviderProps): ReactNode {
+  const { children, autoConnect = false, detectTimeoutMs = 3000 } = props
+
+  // Seeded synchronously: when the provider is already on the page the first
+  // render is already correct, and no dapp has to render a "detecting" state.
+  const [joey, setJoey] = useState<Joey | null>(() => getJoey())
+  const [isReady, setIsReady] = useState<boolean>(() => getJoey() !== null)
+  const [accounts, setAccounts] = useState<string[]>([])
+  const [network, setNetwork] = useState<JoeyNetwork | null>(null)
+
+  useEffect(() => {
+    if (joey !== null) return
+    let cancelled = false
+    const controller = new AbortController()
+    waitForJoey({ timeoutMs: detectTimeoutMs, signal: controller.signal })
+      .then((found) => {
+        if (!cancelled) setJoey(found)
+      })
+      .catch(() => {
+        /* absence is a state, not an error the dapp needs to handle here */
+      })
+      .finally(() => {
+        if (!cancelled) setIsReady(true)
+      })
+    return () => {
+      cancelled = true
+      controller.abort()
+    }
+  }, [joey, detectTimeoutMs])
+
+  const refresh = useCallback(async (): Promise<void> => {
+    if (joey === null) return
+    const [nextAccounts, nextNetwork] = await Promise.all([
+      joey.getAccounts().catch(() => [] as string[]),
+      joey.getNetwork().catch(() => null),
+    ])
+    setAccounts(nextAccounts)
+    setNetwork(nextNetwork)
+  }, [joey])
+
+  useEffect(() => {
+    if (joey === null) return
+    const offs = [
+      joey.on('accountsChanged', (next) => setAccounts(next.map((a) => a.address))),
+      joey.on('networkChanged', (next) => setNetwork(next)),
+      joey.on('connect', (result) => setAccounts(result.accounts.map((a) => a.address))),
+      joey.on('disconnect', () => setAccounts([])),
+    ]
+    return () => {
+      for (const off of offs) off()
+    }
+  }, [joey])
+
+  useEffect(() => {
+    if (joey === null) return
+    let cancelled = false
+
+    const run = async (): Promise<void> => {
+      if (autoConnect) {
+        try {
+          const result = await joey.connect({ silent: true })
+          if (cancelled) return
+          if (result.accounts.length > 0) {
+            setAccounts(result.accounts.map((account) => account.address))
+            const next = await joey.getNetwork().catch(() => null)
+            if (!cancelled) setNetwork(next)
+            return
+          }
+        } catch {
+          // A silent connect is best-effort. Fall through to the plain refresh.
+        }
+      }
+      if (!cancelled) await refresh()
+    }
+
+    void run()
+    return () => {
+      cancelled = true
+    }
+  }, [joey, autoConnect, refresh])
+
+  const connect = useCallback(
+    async (params?: ConnectParams): Promise<ConnectResult> => {
+      if (joey === null) throw notInstalled()
+      const result = await joey.connect(params)
+      setAccounts(result.accounts.map((account) => account.address))
+      if (result.chain !== null) {
+        setNetwork(await joey.getNetwork().catch(() => null))
+      }
+      return result
+    },
+    [joey],
+  )
+
+  const disconnect = useCallback(async (): Promise<void> => {
+    if (joey === null) return
+    await joey.disconnect()
+    setAccounts([])
+  }, [joey])
+
+  const value = useMemo<JoeyContextValue>(
+    () => ({
+      joey,
+      isAvailable: joey !== null,
+      isReady,
+      accounts,
+      account: accounts[0] ?? null,
+      network,
+      isConnected: accounts.length > 0,
+      connect,
+      disconnect,
+      refresh,
+    }),
+    [joey, isReady, accounts, network, connect, disconnect, refresh],
+  )
+
+  return createElement(JoeyContext.Provider, { value }, children)
+}
+
+export function useJoey(): JoeyContextValue {
+  const value = useContext(JoeyContext)
+  if (value === null) {
+    throw new Error('useJoey must be used inside a <JoeyProvider>.')
+  }
+  return value
+}
+
+/* ----------------------------------------------------------------- mutations */
+
+export interface UseJoeyMutationOptions<TData, TVariables> {
+  onSuccess?(data: TData, variables: TVariables): void
+  onError?(error: JoeyRpcError, variables: TVariables): void
+  onSettled?(data: TData | undefined, error: JoeyRpcError | undefined, variables: TVariables): void
+}
+
+export interface UseJoeyMutationResult<TData, TVariables>
+  extends MutationState<TData, TVariables> {
+  /** Fire and forget. Never rejects — read `error` instead. */
+  mutate(variables: TVariables): void
+  /** Resolves the result, or rejects with `JoeyRpcError`. */
+  mutateAsync(variables: TVariables): Promise<TData>
+  reset(): void
+}
+
+/**
+ * Build a mutation hook over a Joey method.
+ *
+ * Exported so a dapp can wrap a method this SDK version does not model, using
+ * `joey.request()`, and still get the same `{ mutate, isPending, error }` shape
+ * as the built-in hooks.
+ */
+export function useJoeyMutation<TData, TVariables>(
+  run: (joey: Joey, variables: TVariables) => Promise<TData>,
+  options: UseJoeyMutationOptions<TData, TVariables> = {},
+): UseJoeyMutationResult<TData, TVariables> {
+  const { joey } = useJoey()
+  const [state, dispatch] = useReducer(
+    mutationReducer<TData, TVariables>,
+    undefined,
+    initialMutationState<TData, TVariables>,
+  )
+
+  const runIdRef = useRef(0)
+  const mountedRef = useRef(true)
+  useEffect(() => {
+    mountedRef.current = true
+    return () => {
+      mountedRef.current = false
+    }
+  }, [])
+
+  // Held in refs so a callback identity that changes between renders does not
+  // change the identity of `mutate`, which dapps put in dependency arrays.
+  const runRef = useRef(run)
+  runRef.current = run
+  const optionsRef = useRef(options)
+  optionsRef.current = options
+
+  const mutateAsync = useCallback(
+    async (variables: TVariables): Promise<TData> => {
+      const runId = ++runIdRef.current
+      dispatch({ type: 'start', variables, runId })
+
+      try {
+        if (joey === null) throw notInstalled()
+        const data = await runRef.current(joey, variables)
+        if (mountedRef.current) dispatch({ type: 'success', data, runId })
+        optionsRef.current.onSuccess?.(data, variables)
+        optionsRef.current.onSettled?.(data, undefined, variables)
+        return data
+      } catch (cause) {
+        const error = JoeyRpcError.from(cause)
+        if (mountedRef.current) dispatch({ type: 'error', error, runId })
+        optionsRef.current.onError?.(error, variables)
+        optionsRef.current.onSettled?.(undefined, error, variables)
+        throw error
+      }
+    },
+    [joey],
+  )
+
+  const mutate = useCallback(
+    (variables: TVariables): void => {
+      void mutateAsync(variables).catch(() => {
+        /* surfaced through `error`; swallowing keeps `mutate` unrejectable */
+      })
+    },
+    [mutateAsync],
+  )
+
+  const reset = useCallback((): void => {
+    dispatch({ type: 'reset' })
+  }, [])
+
+  return { ...toPublicState(state), mutate, mutateAsync, reset }
+}
+
+export function useConnect(
+  options?: UseJoeyMutationOptions<ConnectResult, ConnectParams | undefined>,
+): UseJoeyMutationResult<ConnectResult, ConnectParams | undefined> {
+  const { connect } = useJoey()
+  return useJoeyMutation<ConnectResult, ConnectParams | undefined>(
+    // Routed through the context so the provider's account/network state is
+    // updated by the same call that resolves the mutation.
+    (_joey, params) => connect(params),
+    options,
+  )
+}
+
+export function useDisconnect(
+  options?: UseJoeyMutationOptions<void, void>,
+): UseJoeyMutationResult<void, void> {
+  const { disconnect } = useJoey()
+  return useJoeyMutation<void, void>(() => disconnect(), options)
+}
+
+export function useSignTransaction<TTx extends TransactionLike = AnyTransaction>(
+  options?: UseJoeyMutationOptions<SignTransactionResult, SignTransactionParams<TTx>>,
+): UseJoeyMutationResult<SignTransactionResult, SignTransactionParams<TTx>> {
+  return useJoeyMutation<SignTransactionResult, SignTransactionParams<TTx>>(
+    (joey, params) => joey.signTransaction(params),
+    options,
+  )
+}
+
+export function useSignAndSubmit<TTx extends TransactionLike = AnyTransaction>(
+  options?: UseJoeyMutationOptions<SignAndSubmitTransactionResult, SignTransactionParams<TTx>>,
+): UseJoeyMutationResult<SignAndSubmitTransactionResult, SignTransactionParams<TTx>> {
+  return useJoeyMutation<SignAndSubmitTransactionResult, SignTransactionParams<TTx>>(
+    (joey, params) => joey.signAndSubmitTransaction(params),
+    options,
+  )
+}
+
+export function useSignTransactionFor<TTx extends TransactionLike = AnyTransaction>(
+  options?: UseJoeyMutationOptions<SignTransactionResult, SignTransactionForParams<TTx>>,
+): UseJoeyMutationResult<SignTransactionResult, SignTransactionForParams<TTx>> {
+  return useJoeyMutation<SignTransactionResult, SignTransactionForParams<TTx>>(
+    (joey, params) => joey.signTransactionFor(params),
+    options,
+  )
+}
+
+export function useSignTransactionBulk<TTx extends TransactionLike = AnyTransaction>(
+  options?: UseJoeyMutationOptions<
+    SignAndSubmitTransactionResult[],
+    SignTransactionBulkParams<TTx>
+  >,
+): UseJoeyMutationResult<SignAndSubmitTransactionResult[], SignTransactionBulkParams<TTx>> {
+  return useJoeyMutation<SignAndSubmitTransactionResult[], SignTransactionBulkParams<TTx>>(
+    (joey, params) => joey.signTransactionBulk(params),
+    options,
+  )
+}
+
+export function useSignIn(
+  options?: UseJoeyMutationOptions<SignInResult, SignInParams | undefined>,
+): UseJoeyMutationResult<SignInResult, SignInParams | undefined> {
+  return useJoeyMutation<SignInResult, SignInParams | undefined>(
+    (joey, params) => joey.signIn(params),
+    options,
+  )
+}
+
+export type { MutationState, MutationStatus } from './mutation.js'