accounts 0.3.0 → 0.4.1

package/src/core/Remote.ts

@@ -0,0 +1,262 @@
+import { Hex } from 'ox'
+import * as Provider from 'ox/Provider'
+import * as RpcResponse from 'ox/RpcResponse'
+import { useStore } from 'zustand'
+import type { StoreApi } from 'zustand/vanilla'
+import { createStore } from 'zustand/vanilla'
+
+import type * as Messenger from '../core/Messenger.js'
+import type * as CoreProvider from '../core/Provider.js'
+import type * as Store from '../core/Store.js'
+
+/** State managed by the remote (dialog) side. */
+export type State = {
+  /** Whether the dialog is rendered in an iframe or popup. */
+  mode: 'iframe' | 'popup' | undefined
+  /** Trusted host origin from MessageEvent. */
+  origin: string | undefined
+  /** Whether the dialog is ready to display content. */
+  ready: boolean
+  /** Queued RPC requests received from the host. */
+  requests: readonly Store.QueuedRequest[]
+}
+
+/** Remote context — bundles messenger, provider, and remote store. */
+export type Remote = {
+  /**
+   * Messenger for remote communication.
+   */
+  messenger: Messenger.Bridge
+  /**
+   * Provider instance for executing RPC methods.
+   */
+  provider: CoreProvider.Provider
+  /**
+   * Remote context store.
+   */
+  store: StoreApi<State>
+  /**
+   * Subscribes to user-facing RPC requests from the parent context.
+   *
+   * Syncs the host's active chain, updates the remote store, and invokes
+   * the callback with the first pending request (or `null` when the queue
+   * is cleared, signalling the UI should close).
+   *
+   * @param cb - Callback receiving the request payload.
+   * @returns Unsubscribe function.
+   */
+  onUserRequest: (cb: (payload: onUserRequest.Payload) => void | Promise<void>) => () => void
+  /**
+   * Subscribes to incoming RPC requests from the parent context.
+   * Updates the remote store with the received requests and syncs the
+   * host's active chain to the remote provider.
+   *
+   * @param cb - Callback receiving the full queued request list.
+   * @returns Unsubscribe function.
+   */
+  onRequests: (
+    cb: (
+      requests: readonly Store.QueuedRequest[],
+      event: MessageEvent,
+      extra: { account: { address: string } | undefined },
+    ) => void,
+  ) => () => void
+  /**
+   * Signals readiness to the host and begins accepting requests.
+   * Call this after the remote context is fully initialized.
+   */
+  ready: () => void
+  /**
+   * Reject an RPC request.
+   */
+  reject: (
+    request: Store.QueuedRequest['request'],
+    error?: Provider.ProviderRpcError | RpcResponse.BaseError | undefined,
+  ) => void
+  /** Reject all pending RPC requests. */
+  rejectAll: (error?: Provider.ProviderRpcError | RpcResponse.BaseError | undefined) => void
+  /**
+   * Respond to an RPC request.
+   *
+   * When `options.result` is provided, sends it directly.
+   * When `options.error` is provided, sends an error response.
+   * Otherwise, executes `provider.request(request)` and sends the result.
+   */
+  respond: (request: Store.QueuedRequest['request'], options?: respond.Options) => Promise<unknown>
+}
+
+export declare namespace onUserRequest {
+  type Payload = {
+    /** Active account on the host side. */
+    account: { address: string } | undefined
+    /** Origin of the host that opened this dialog. */
+    origin: string
+    /** The pending request to display, or `null` when the dialog should close. */
+    request: Store.QueuedRequest['request'] | null
+  }
+}
+
+export declare namespace respond {
+  type Options = {
+    /** Error to respond with (takes precedence over result). */
+    error?: { code: number; message: string } | undefined
+    /** Explicit result — if omitted, calls `provider.request(request)`. */
+    result?: unknown | undefined
+    /** Transform the result before sending. */
+    selector?: ((result: any) => unknown) | undefined
+  }
+}
+
+/** Creates a remote context for the dialog app. */
+export function create(options: create.Options): Remote {
+  const { messenger, provider } = options
+  const ready =
+    typeof window !== 'undefined' && !new URLSearchParams(window.location.search).get('mode')
+  const store = createStore<State>(() => ({
+    mode: undefined,
+    origin: undefined,
+    ready,
+    requests: [],
+  }))
+
+  return {
+    messenger,
+    provider,
+    store,
+
+    onUserRequest(cb) {
+      return this.onRequests(async (requests, event, { account }) => {
+        // Sync the active account with the host.
+        if (account) {
+          const state = provider.store.getState()
+          const index = state.accounts.findIndex(
+            (a) => a.address.toLowerCase() === account.address.toLowerCase(),
+          )
+          if (index >= 0 && index !== state.activeAccount)
+            provider.store.setState({ activeAccount: index })
+        }
+
+        const pending = requests.find((r) => r.status === 'pending')
+        store.setState({
+          origin: event.origin,
+          ready: false,
+        })
+        await cb({
+          account,
+          origin: event.origin,
+          request: pending?.request ?? null,
+        })
+        if (pending) store.setState({ ready: true })
+      })
+    },
+
+    onRequests(cb) {
+      return messenger.on('rpc-requests', async (payload, event) => {
+        const { account, chainId, requests } = payload
+
+        // Rehydrate persisted state so the iframe picks up accounts
+        // created in a popup (e.g. Safari WebAuthn fallback).
+        await provider.store.persist?.rehydrate()
+
+        store.setState({ requests })
+
+        if (provider.store.getState().chainId !== chainId)
+          provider.request({
+            method: 'wallet_switchEthereumChain',
+            params: [{ chainId: Hex.fromNumber(chainId) }],
+          })
+
+        cb(requests, event, { account })
+      })
+    },
+
+    ready() {
+      messenger.ready()
+
+      if (typeof window !== 'undefined') {
+        const params = new URLSearchParams(window.location.search)
+        const mode = params.get('mode') as State['mode']
+        const chainId = Number(params.get('chainId'))
+
+        if (mode) store.setState({ mode })
+
+        if (chainId && provider.store.getState().chainId !== chainId)
+          provider.request({
+            method: 'wallet_switchEthereumChain',
+            params: [{ chainId: Hex.fromNumber(chainId) }],
+          })
+      }
+    },
+
+    reject(request, error) {
+      const error_ = error ?? new Provider.UserRejectedRequestError()
+      messenger.send(
+        'rpc-response',
+        Object.assign(
+          RpcResponse.from({
+            error: { code: error_.code, message: error_.message },
+            id: request.id,
+            jsonrpc: '2.0',
+          }),
+          { _request: request },
+        ),
+      )
+    },
+
+    rejectAll(error) {
+      store.setState({ ready: false })
+      const requests = store.getState().requests
+      for (const queued of requests) this.reject(queued.request, error)
+    },
+
+    async respond(request, options = {}) {
+      const { error, selector } = options
+      const shared = { id: request.id, jsonrpc: '2.0' } as const
+
+      if (error) {
+        messenger.send(
+          'rpc-response',
+          Object.assign(RpcResponse.from({ ...shared, error, status: 'error' }), {
+            _request: request,
+          }),
+        )
+        return
+      }
+
+      try {
+        let result = options.result ?? (await provider?.request(request as never))
+        if (selector) result = selector(result)
+        messenger.send(
+          'rpc-response',
+          Object.assign(RpcResponse.from({ ...shared, result }), { _request: request }),
+        )
+        return result
+      } catch (e) {
+        const err = e as RpcResponse.BaseError
+        messenger.send(
+          'rpc-response',
+          Object.assign(RpcResponse.from({ ...shared, error: err, status: 'error' }), {
+            _request: request,
+          }),
+        )
+        throw err
+      }
+    },
+  }
+}
+
+export declare namespace create {
+  type Options = {
+    /** Bridge messenger for cross-frame communication. */
+    messenger: Messenger.Bridge
+    /** Provider to execute RPC requests against. */
+    provider: CoreProvider.Provider
+  }
+}
+
+/** React hook to select state from a remote context's store. */
+export function useState(remote: Remote): State
+export function useState<selected>(remote: Remote, selector: (state: State) => selected): selected
+export function useState(remote: Remote, selector?: (state: State) => unknown) {
+  return useStore(remote.store, selector as never)
+}

package/src/core/Schema.test-d.ts

@@ -0,0 +1,211 @@
+import type { RpcSchema } from 'ox'
+import type { Hex } from 'viem'
+import { describe, expectTypeOf, test } from 'vp/test'
+
+import type * as Schema from './Schema.js'
+import type * as Rpc from './zod/rpc.js'
+
+describe('Encoded', () => {
+  test('eth_accounts', () => {
+    expectTypeOf<Rpc.eth_accounts.Encoded>().toEqualTypeOf<{
+      method: 'eth_accounts'
+      params: undefined
+      returns: readonly Hex[]
+    }>()
+  })
+
+  test('eth_chainId', () => {
+    expectTypeOf<Rpc.eth_chainId.Encoded>().toEqualTypeOf<{
+      method: 'eth_chainId'
+      params: undefined
+      returns: Hex
+    }>()
+  })
+
+  test('eth_requestAccounts', () => {
+    expectTypeOf<Rpc.eth_requestAccounts.Encoded>().toEqualTypeOf<{
+      method: 'eth_requestAccounts'
+      params: undefined
+      returns: readonly Hex[]
+    }>()
+  })
+
+  test('eth_sendTransaction', () => {
+    expectTypeOf<Rpc.eth_sendTransaction.Encoded>().toMatchTypeOf<{
+      method: 'eth_sendTransaction'
+      params: readonly [
+        {
+          accessList?: { address: Hex; storageKeys: Hex[] }[] | undefined
+          calls?: readonly { data?: Hex | undefined; to?: Hex | undefined }[] | undefined
+          chainId?: Hex | undefined
+          feePayer?: boolean | string | undefined
+          feeToken?: Hex | undefined
+          from?: Hex | undefined
+          gas?: Hex | undefined
+          maxFeePerGas?: Hex | undefined
+          maxPriorityFeePerGas?: Hex | undefined
+          nonce?: Hex | undefined
+          nonceKey?: Hex | undefined
+          validAfter?: Hex | undefined
+          validBefore?: Hex | undefined
+          value?: Hex | undefined
+        },
+      ]
+      returns: Hex
+    }>()
+  })
+
+  test('wallet_connect: params', () => {
+    expectTypeOf<Rpc.wallet_connect.Encoded['params']>().toExtend<
+      | readonly [
+          {
+            capabilities?:
+              | {
+                  digest?: Hex | undefined
+                  authorizeAccessKey?:
+                    | {
+                        address?: Hex | undefined
+                        expiry: number
+                        keyType?: 'secp256k1' | 'p256' | 'webAuthn' | undefined
+                        limits?: readonly { token: Hex; limit: Hex }[] | undefined
+                        publicKey?: Hex | undefined
+                      }
+                    | undefined
+                  method: 'register'
+                  name?: string | undefined
+                  userId?: string | undefined
+                }
+              | {
+                  digest?: Hex | undefined
+                  credentialId?: string | undefined
+                  authorizeAccessKey?:
+                    | {
+                        address?: Hex | undefined
+                        expiry: number
+                        keyType?: 'secp256k1' | 'p256' | 'webAuthn' | undefined
+                        limits?: readonly { token: Hex; limit: Hex }[] | undefined
+                        publicKey?: Hex | undefined
+                      }
+                    | undefined
+                  method?: 'login' | undefined
+                  selectAccount?: boolean | undefined
+                }
+              | undefined
+            version?: string | undefined
+          },
+        ]
+      | undefined
+    >()
+  })
+
+  test('wallet_connect: returns', () => {
+    expectTypeOf<Rpc.wallet_connect.Encoded['returns']>().toHaveProperty('accounts')
+    expectTypeOf<
+      Rpc.wallet_connect.Encoded['returns']['accounts'][number]['address']
+    >().toEqualTypeOf<Hex>()
+  })
+
+  test('wallet_authorizeAccessKey', () => {
+    expectTypeOf<Rpc.wallet_authorizeAccessKey.Encoded>().toMatchTypeOf<{
+      method: 'wallet_authorizeAccessKey'
+      params: readonly [
+        {
+          address?: Hex | undefined
+          expiry: number
+          keyType?: 'secp256k1' | 'p256' | 'webAuthn' | undefined
+          limits?: readonly { token: Hex; limit: Hex }[] | undefined
+          publicKey?: Hex | undefined
+        },
+      ]
+    }>()
+  })
+
+  test('wallet_disconnect', () => {
+    expectTypeOf<Rpc.wallet_disconnect.Encoded>().toEqualTypeOf<{
+      method: 'wallet_disconnect'
+      params: undefined
+      returns: undefined
+    }>()
+  })
+
+  test('wallet_switchEthereumChain', () => {
+    expectTypeOf<Rpc.wallet_switchEthereumChain.Encoded>().toEqualTypeOf<{
+      method: 'wallet_switchEthereumChain'
+      params: readonly [{ chainId: Hex }]
+      returns: undefined
+    }>()
+  })
+})
+
+describe('ToOx', () => {
+  test('produces RpcSchema.Generic members', () => {
+    type OxSchema = Schema.ToOx<typeof Schema.schema>
+    expectTypeOf<OxSchema>().toMatchTypeOf<RpcSchema.Generic>()
+  })
+})
+
+describe('ToViem', () => {
+  test('produces tuple with Method/Parameters/ReturnType', () => {
+    type ViemSchema = Schema.ToViem<typeof Schema.schema>
+    expectTypeOf<ViemSchema[0]['Method']>().toEqualTypeOf<'eth_accounts'>()
+    expectTypeOf<ViemSchema[0]['Parameters']>().toEqualTypeOf<undefined>()
+    expectTypeOf<ViemSchema[0]['ReturnType']>().toEqualTypeOf<readonly Hex[]>()
+  })
+})
+
+describe('Ox', () => {
+  test('includes RpcSchema.Eth', () => {
+    expectTypeOf<RpcSchema.Eth>().toMatchTypeOf<Schema.Ox>()
+  })
+
+  test('includes provider methods', () => {
+    expectTypeOf<Schema.ToOx<typeof Schema.schema>>().toMatchTypeOf<Schema.Ox>()
+  })
+})
+
+describe('Viem', () => {
+  test('is a tuple of all provider methods', () => {
+    expectTypeOf<Schema.Viem[0]['Method']>().toEqualTypeOf<'eth_accounts'>()
+    expectTypeOf<Schema.Viem[16]['Method']>().toEqualTypeOf<'wallet_switchEthereumChain'>()
+  })
+})
+
+describe('Request', () => {
+  test('is a discriminated union of all methods', () => {
+    type Methods = Schema.Request['method']
+    expectTypeOf<Methods>().toEqualTypeOf<
+      | 'eth_accounts'
+      | 'eth_chainId'
+      | 'eth_requestAccounts'
+      | 'eth_sendTransaction'
+      | 'eth_signTransaction'
+      | 'eth_sendTransactionSync'
+      | 'eth_signTypedData_v4'
+      | 'personal_sign'
+      | 'wallet_sendCalls'
+      | 'wallet_getBalances'
+      | 'wallet_getCallsStatus'
+      | 'wallet_getCapabilities'
+      | 'wallet_connect'
+      | 'wallet_disconnect'
+      | 'wallet_authorizeAccessKey'
+      | 'wallet_revokeAccessKey'
+      | 'wallet_switchEthereumChain'
+    >()
+  })
+
+  test('wallet_switchEthereumChain has decoded params', () => {
+    type SwitchChain = Extract<Schema.Request, { method: 'wallet_switchEthereumChain' }>
+    expectTypeOf<SwitchChain['params']>().toEqualTypeOf<readonly [{ chainId: number }]>()
+  })
+
+  test('eth_accounts has no params', () => {
+    type EthAccounts = Extract<Schema.Request, { method: 'eth_accounts' }>
+    expectTypeOf<EthAccounts>().not.toHaveProperty('params')
+  })
+
+  test('wallet_connect params are optional', () => {
+    type WalletConnect = Extract<Schema.Request, { method: 'wallet_connect' }>
+    expectTypeOf<WalletConnect>().toMatchTypeOf<{ method: 'wallet_connect' }>()
+  })
+})

package/src/core/Schema.ts

@@ -0,0 +1,143 @@
+import { RpcSchema } from 'ox'
+import { rpcSchema } from 'viem'
+import * as z from 'zod/mini'
+
+import * as Rpc from './zod/rpc.js'
+
+/** All provider-handled RPC method definitions. */
+export const schema = from([
+  Rpc.eth_accounts.schema,
+  Rpc.eth_chainId.schema,
+  Rpc.eth_requestAccounts.schema,
+  Rpc.eth_sendTransaction.schema,
+  Rpc.eth_signTransaction.schema,
+  Rpc.eth_sendTransactionSync.schema,
+  Rpc.eth_signTypedData_v4.schema,
+  Rpc.personal_sign.schema,
+  Rpc.wallet_sendCalls.schema,
+  Rpc.wallet_getBalances.schema,
+  Rpc.wallet_getCallsStatus.schema,
+  Rpc.wallet_getCapabilities.schema,
+  Rpc.wallet_connect.schema,
+  Rpc.wallet_disconnect.schema,
+  Rpc.wallet_authorizeAccessKey.schema,
+  Rpc.wallet_revokeAccessKey.schema,
+  Rpc.wallet_switchEthereumChain.schema,
+])
+
+/**
+ * A single JSON-RPC method definition with Zod schemas for
+ * the method name, parameters, and return type.
+ */
+export type Item = {
+  /** Method name as a Zod literal. */
+  method: z.ZodMiniLiteral<string>
+  /** Parameters schema, or `undefined` if the method takes no params. */
+  params: z.ZodMiniType | undefined
+  /** Return type schema, or `undefined` if the method returns nothing. */
+  returns: z.ZodMiniType | undefined
+}
+
+/** An array of JSON-RPC method definitions. */
+export type Schema = readonly Item[]
+
+/** Inferred wire-format type for a schema item — raw JSON-RPC `{ method, params, returns }`. */
+export type Encoded<item extends Item> = {
+  method: z.input<item['method']>
+  params: item['params'] extends z.ZodMiniType ? z.input<item['params']> : undefined
+  returns: item['returns'] extends z.ZodMiniType ? z.input<item['returns']> : undefined
+}
+
+/** Inferred decoded type for a schema item — after codec transforms are applied. */
+export type Decoded<item extends Item> = {
+  method: z.input<item['method']>
+  params: item['params'] extends z.ZodMiniType ? z.output<item['params']> : undefined
+  returns: item['returns'] extends z.ZodMiniType ? z.output<item['returns']> : undefined
+}
+
+/**
+ * Transforms a {@link Schema} into an Ox-compatible `RpcSchema.Generic` union.
+ *
+ * Uses `z.input` (the wire/encoded form — hex strings) since Ox operates
+ * on the raw JSON-RPC wire format.
+ */
+export type ToOx<schema extends Schema> = {
+  [key in keyof schema]: RpcSchema.From<{
+    Request: schema[key]['params'] extends z.ZodMiniType
+      ? undefined extends z.input<schema[key]['params']>
+        ? { method: z.input<schema[key]['method']>; params?: z.input<schema[key]['params']> }
+        : { method: z.input<schema[key]['method']>; params: z.input<schema[key]['params']> }
+      : { method: z.input<schema[key]['method']> }
+    ReturnType: schema[key]['returns'] extends z.ZodMiniType
+      ? z.input<schema[key]['returns']>
+      : undefined
+  }>
+}[number]
+
+/**
+ * Transforms a {@link Schema} into a Viem-compatible `RpcSchema` tuple.
+ *
+ * Uses `z.input` (the wire/encoded form — hex strings) since Viem's
+ * RPC schema types operate on the raw JSON-RPC wire format.
+ */
+export type ToViem<schema extends Schema> = {
+  [key in keyof schema]: {
+    Method: z.input<schema[key]['method']>
+    Parameters: schema[key]['params'] extends z.ZodMiniType
+      ? z.input<schema[key]['params']>
+      : undefined
+    ReturnType: schema[key]['returns'] extends z.ZodMiniType
+      ? z.input<schema[key]['returns']>
+      : undefined
+  }
+}
+
+/** Ox-compatible RPC schema union for the provider. */
+export type Ox = RpcSchema.Eth | ToOx<typeof schema>
+export const ox = RpcSchema.from<Ox>()
+
+/** Viem-compatible RPC schema tuple for the provider. */
+export type Viem = ToViem<typeof schema>
+export const viem = rpcSchema<Viem>()
+
+/** Derives a `z.object({ method, params? })` from an {@link Item}. */
+type ToRequestSchema<item extends Item> = item['params'] extends z.ZodMiniType
+  ? ReturnType<typeof z.object<{ method: item['method']; params: item['params'] }>>
+  : ReturnType<typeof z.object<{ method: item['method'] }>>
+
+/** Builds a request `z.object` from a schema item at runtime. */
+function toRequestSchema<const item extends Item>(item: item): ToRequestSchema<item> {
+  if (item.params) return z.object({ method: item.method, params: item.params }) as never
+  return z.object({ method: item.method }) as never
+}
+
+/** Derives a union of wire-format request shapes from a {@link Schema}. */
+type ToRequestInput<schema extends Schema> = {
+  [key in keyof schema]: schema[key]['params'] extends z.ZodMiniType
+    ? { method: z.input<schema[key]['method']>; params: z.input<schema[key]['params']> }
+    : { method: z.input<schema[key]['method']> }
+}[number]
+
+/** Derives a union of decoded request shapes from a {@link Schema}. */
+type ToRequestOutput<schema extends Schema> = {
+  [key in keyof schema]: schema[key]['params'] extends z.ZodMiniType
+    ? { method: z.output<schema[key]['method']>; params: z.output<schema[key]['params']> }
+    : { method: z.output<schema[key]['method']> }
+}[number]
+
+/** Discriminated union of all provider-handled RPC requests. */
+export const Request: z.ZodMiniType<
+  ToRequestOutput<typeof schema>,
+  ToRequestInput<typeof schema>
+> = z.discriminatedUnion('method', schema.map(toRequestSchema) as never)
+export type Request = ToRequestOutput<typeof schema>
+
+/** Defines a JSON-RPC method schema item. */
+export function defineItem<const item extends Item>(item: item): item {
+  return item
+}
+
+/** Creates a {@link Schema}. */
+export function from<const schema extends Schema>(schema: schema): schema {
+  return schema
+}