@0xsequence/dapp-client 0.0.0-20250910142613

package/src/types/index.ts

@@ -0,0 +1,218 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { Attestation, Payload } from '@0xsequence/wallet-primitives'
+import { Signers } from '@0xsequence/wallet-core'
+import { Address, Hex } from 'ox'
+import type { TypedData } from 'ox/TypedData'
+
+// --- Public Interfaces and Constants ---
+
+export const RequestActionType = {
+  CREATE_NEW_SESSION: 'createNewSession',
+  ADD_EXPLICIT_SESSION: 'addExplicitSession',
+  MODIFY_EXPLICIT_SESSION: 'modifyExplicitSession',
+  SIGN_MESSAGE: 'signMessage',
+  SIGN_TYPED_DATA: 'signTypedData',
+  SEND_WALLET_TRANSACTION: 'sendWalletTransaction',
+} as const
+
+export type LoginMethod = 'google' | 'apple' | 'email' | 'passkey' | 'mnemonic'
+
+export interface GuardConfig {
+  url: string
+  address: Address.Address
+}
+
+// --- Payloads for Transport ---
+
+export interface CreateNewSessionPayload {
+  sessionAddress: Address.Address
+  origin: string
+  permissions?: Signers.Session.ExplicitParams
+  includeImplicitSession?: boolean
+  preferredLoginMethod?: LoginMethod
+  email?: string
+}
+
+export interface AddExplicitSessionPayload {
+  sessionAddress: Address.Address
+  permissions: Signers.Session.ExplicitParams
+  preferredLoginMethod?: LoginMethod
+  email?: string
+}
+
+export interface ModifySessionPayload {
+  walletAddress: Address.Address
+  sessionAddress: Address.Address
+  permissions: Signers.Session.ExplicitParams
+}
+
+export interface SignMessagePayload {
+  address: Address.Address
+  message: string
+  chainId: number
+}
+
+export interface SignTypedDataPayload {
+  address: Address.Address
+  typedData: TypedData
+  chainId: number
+}
+
+export type TransactionRequest = {
+  to: Address.Address
+  value?: bigint
+  data?: Hex.Hex
+  gasLimit?: bigint
+}
+
+export interface SendWalletTransactionPayload {
+  address: Address.Address
+  transactionRequest: TransactionRequest
+  chainId: number
+}
+
+export interface ConnectSuccessResponsePayload {
+  walletAddress: string
+  attestation?: Attestation.Attestation
+  signature?: Hex.Hex
+  userEmail?: string
+  loginMethod?: LoginMethod
+  guard?: GuardConfig
+}
+
+export interface ModifySessionSuccessResponsePayload {
+  walletAddress: string
+  sessionAddress: string
+}
+
+export interface SignatureSuccessResponse {
+  signature: Hex.Hex
+  walletAddress: string
+}
+
+export interface SendWalletTransactionSuccessResponse {
+  transactionHash: Hex.Hex
+  walletAddress: string
+}
+
+export type WalletActionResponse = SignatureSuccessResponse | SendWalletTransactionSuccessResponse
+
+export interface ExplicitSessionResponsePayload {
+  walletAddress: string
+  sessionAddress: string
+}
+
+// --- Dapp-facing Types ---
+
+export type RandomPrivateKeyFn = () => Hex.Hex | Promise<Hex.Hex>
+
+type RequiredKeys = 'to' | 'data' | 'value'
+
+export type Transaction =
+  // Required properties from Payload.Call
+  Pick<Payload.Call, RequiredKeys> &
+    // All other properties from Payload.Call, but optional
+    Partial<Omit<Payload.Call, RequiredKeys>>
+
+export type Session = {
+  address: Address.Address
+  isImplicit: boolean
+  permissions?: Signers.Session.ExplicitParams
+  chainId?: number
+}
+
+// --- Event Types ---
+
+export type ChainSessionManagerEvent = 'sessionsUpdated' | 'explicitSessionResponse'
+
+export type ExplicitSessionEventListener = (data: {
+  action: (typeof RequestActionType)['ADD_EXPLICIT_SESSION' | 'MODIFY_EXPLICIT_SESSION']
+  response?: ExplicitSessionResponsePayload
+  error?: any
+}) => void
+
+// A generic listener for events from the DappClient
+export type DappClientEventListener = (data?: any) => void
+
+export type DappClientWalletActionEventListener = (data: {
+  action: (typeof RequestActionType)['SIGN_MESSAGE' | 'SIGN_TYPED_DATA' | 'SEND_WALLET_TRANSACTION']
+  response?: WalletActionResponse
+  error?: any
+  chainId: number
+}) => void
+
+export type DappClientExplicitSessionEventListener = (data: {
+  action: (typeof RequestActionType)['ADD_EXPLICIT_SESSION' | 'MODIFY_EXPLICIT_SESSION']
+  response?: ExplicitSessionResponsePayload
+  error?: any
+  chainId: number
+}) => void
+
+// --- DappTransport Types ---
+
+export interface SequenceSessionStorage {
+  getItem(key: string): string | null | Promise<string | null>
+  setItem(key: string, value: string): void | Promise<void>
+  removeItem(key: string): void | Promise<void>
+}
+
+export enum MessageType {
+  WALLET_OPENED = 'WALLET_OPENED',
+  INIT = 'INIT',
+  REQUEST = 'REQUEST',
+  RESPONSE = 'RESPONSE',
+}
+
+export enum TransportMode {
+  POPUP = 'popup',
+  REDIRECT = 'redirect',
+}
+
+export interface PopupModeOptions {
+  requestTimeoutMs?: number
+  handshakeTimeoutMs?: number
+}
+
+export interface TransportMessage<T = any> {
+  id: string
+  type: MessageType
+  sessionId?: string
+  action?: string
+  payload?: T
+  error?: any
+}
+
+export interface BaseRequest {
+  type: string
+}
+
+export interface MessageSignatureRequest extends BaseRequest {
+  type: 'message_signature'
+  message: string
+  address: Address.Address
+  chainId: number
+}
+
+export interface TypedDataSignatureRequest extends BaseRequest {
+  type: 'typed_data_signature'
+  typedData: unknown
+  address: Address.Address
+  chainId: number
+}
+
+export const WalletSize = {
+  width: 380,
+  height: 600,
+}
+
+export interface PendingRequest {
+  resolve: (payload: any) => void
+  reject: (error: any) => void
+  timer: number
+  action: string
+}
+
+export interface SendRequestOptions {
+  timeout?: number
+  path?: string
+}

package/src/utils/constants.ts

@@ -0,0 +1,5 @@
+export const CACHE_DB_NAME = 'sequence-cache'
+export const NODES_URL = 'https://nodes.sequence.app/{network}'
+export const RELAYER_URL = 'https://dev-{network}-relayer.sequence.app'
+export const KEYMACHINE_URL = 'https://v3-keymachine.sequence-dev.app'
+export const VALUE_FORWARDER_ADDRESS = '0xABAAd93EeE2a569cF0632f39B10A9f5D734777ca'

package/src/utils/errors.ts

@@ -0,0 +1,62 @@
+export class InitializationError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'InitializationError'
+  }
+}
+
+export class SigningError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'SigningError'
+  }
+}
+
+export class TransactionError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'TransactionError'
+  }
+}
+
+export class ModifyExplicitSessionError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'ModifyExplicitSessionError'
+  }
+}
+
+export class ConnectionError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'ConnectionError'
+  }
+}
+
+export class AddExplicitSessionError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'AddExplicitSessionError'
+  }
+}
+
+export class FeeOptionError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'FeeOptionError'
+  }
+}
+
+export class WalletRedirectError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'WalletRedirectError'
+  }
+}
+
+export class SessionConfigError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'SessionConfigError'
+  }
+}

package/src/utils/index.ts

@@ -0,0 +1,158 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { Network } from '@0xsequence/wallet-primitives'
+import { Bytes, Hex } from 'ox'
+import { NODES_URL, RELAYER_URL } from './constants.js'
+
+type JsonReplacer = (key: string, value: any) => any
+type JsonReviver = (key: string, value: any) => any
+
+/**
+ * Creates a single JSON replacer by chaining multiple replacers.
+ * The first replacer to transform a value wins.
+ */
+function chainReplacers(replacers: JsonReplacer[]): JsonReplacer {
+  return function (key: string, value: any): any {
+    for (const replacer of replacers) {
+      const replacedValue = replacer(key, value)
+      if (replacedValue !== value) {
+        return replacedValue
+      }
+    }
+    return value
+  }
+}
+
+/**
+ * Creates a single JSON reviver by chaining multiple revivers.
+ * The output of one reviver becomes the input for the next.
+ */
+function chainRevivers(revivers: JsonReviver[]): JsonReviver {
+  return function (key: string, value: any): any {
+    let currentValue = value
+    for (const reviver of revivers) {
+      currentValue = reviver(key, currentValue)
+    }
+    return currentValue
+  }
+}
+
+/**
+ * A JSON replacer that serializes BigInt values into a structured object.
+ */
+const bigIntReplacer: JsonReplacer = (_key, value) => {
+  if (typeof value === 'bigint') {
+    return {
+      _isBigInt: true,
+      data: value.toString(),
+    }
+  }
+  return value
+}
+
+/**
+ * A JSON replacer that serializes Uint8Array values into a structured object.
+ */
+const uint8ArrayReplacer: JsonReplacer = (_key, value) => {
+  if (value instanceof Uint8Array) {
+    return {
+      _isUint8Array: true,
+      data: Hex.from(value),
+    }
+  }
+  return value
+}
+
+/**
+ * A JSON reviver that deserializes a structured object back into a BigInt.
+ */
+const bigIntReviver: JsonReviver = (key, value) => {
+  if (value !== null && typeof value === 'object' && value._isBigInt === true && typeof value.data === 'string') {
+    try {
+      return BigInt(value.data)
+    } catch (e) {
+      console.error(`Failed to revive BigInt for key "${key}":`, e)
+      return value // Return original object if revival fails
+    }
+  }
+  return value
+}
+
+/**
+ * A JSON reviver that deserializes a structured object back into a Uint8Array.
+ */
+const uint8ArrayReviver: JsonReviver = (key, value) => {
+  if (value !== null && typeof value === 'object' && value._isUint8Array === true && typeof value.data === 'string') {
+    try {
+      return Bytes.from(value.data)
+    } catch (e) {
+      console.error(`Failed to revive Uint8Array for key "${key}":`, e)
+      return value // Return original object if revival fails
+    }
+  }
+  return value
+}
+
+export const jsonReplacers = chainReplacers([bigIntReplacer, uint8ArrayReplacer])
+
+export const jsonRevivers = chainRevivers([bigIntReviver, uint8ArrayReviver])
+
+/**
+ * Apply a template to a string.
+ *
+ * Example:
+ * applyTemplate('https://v3-{network}-relayer.sequence.app', { network: 'arbitrum' })
+ * returns 'https://v3-arbitrum-relayer.sequence.app'
+ *
+ * @param template - The template to apply.
+ * @param values - The values to apply to the template.
+ * @returns The template with the values applied.
+ */
+function applyTemplate(template: string, values: Record<string, string>) {
+  return template.replace(/{(.*?)}/g, (_, key) => {
+    const value = values[key]
+    if (value === undefined) {
+      throw new Error(`Missing template value for ${template}: ${key}`)
+    }
+    return value
+  })
+}
+
+export const getNetwork = (chainId: Network.ChainId | bigint | number) => {
+  const network = Network.getNetworkFromChainId(chainId)
+
+  if (!network) {
+    throw new Error(`Network with chainId ${chainId} not found`)
+  }
+
+  return network
+}
+
+export const getRpcUrl = (chainId: Network.ChainId | bigint | number, nodesUrl: string, projectAccessKey: string) => {
+  const network = getNetwork(chainId)
+
+  let url = applyTemplate(nodesUrl, { network: network.name })
+
+  if (nodesUrl.includes('sequence')) {
+    url = `${url}/${projectAccessKey}`
+  }
+
+  return url
+}
+
+export const getRelayerUrl = (chainId: Network.ChainId | bigint | number, relayerUrl: string) => {
+  const network = getNetwork(chainId)
+
+  const url = applyTemplate(relayerUrl, { network: network.name })
+
+  return url
+}
+
+export const getExplorerUrl = (chainId: Network.ChainId | bigint | number, txHash: string) => {
+  const network = getNetwork(chainId)
+  const explorerUrl = network.blockExplorer?.url
+  if (!explorerUrl) {
+    throw new Error(`Explorer URL not found for chainId ${chainId}`)
+  }
+
+  return `${explorerUrl}/tx/${txHash}`
+}

package/src/utils/storage.ts

@@ -0,0 +1,272 @@
+import { Attestation } from '@0xsequence/wallet-primitives'
+import { Address, Hex } from 'ox'
+import { jsonReplacers, jsonRevivers } from './index.js'
+import {
+  AddExplicitSessionPayload,
+  CreateNewSessionPayload,
+  ModifySessionPayload,
+  LoginMethod,
+  SignMessagePayload,
+  SignTypedDataPayload,
+  GuardConfig,
+  SendWalletTransactionPayload,
+} from '../types/index.js'
+
+export interface ExplicitSessionData {
+  pk: Hex.Hex
+  walletAddress: Address.Address
+  chainId: number
+  loginMethod?: LoginMethod
+  userEmail?: string
+  guard?: GuardConfig
+}
+
+export interface ImplicitSessionData {
+  pk: Hex.Hex
+  walletAddress: Address.Address
+  attestation: Attestation.Attestation
+  identitySignature: Hex.Hex
+  chainId: number
+  loginMethod?: LoginMethod
+  userEmail?: string
+  guard?: GuardConfig
+}
+
+export type PendingPayload =
+  | CreateNewSessionPayload
+  | AddExplicitSessionPayload
+  | ModifySessionPayload
+  | SignMessagePayload
+  | SignTypedDataPayload
+  | SendWalletTransactionPayload
+
+export interface PendingRequestContext {
+  chainId: number
+  action: string
+  payload: PendingPayload
+}
+
+export interface SequenceStorage {
+  setPendingRedirectRequest(isPending: boolean): Promise<void>
+  isRedirectRequestPending(): Promise<boolean>
+
+  saveTempSessionPk(pk: Hex.Hex): Promise<void>
+  getAndClearTempSessionPk(): Promise<Hex.Hex | null>
+
+  savePendingRequest(context: PendingRequestContext): Promise<void>
+  getAndClearPendingRequest(): Promise<PendingRequestContext | null>
+  peekPendingRequest(): Promise<PendingRequestContext | null>
+
+  saveExplicitSession(sessionData: ExplicitSessionData): Promise<void>
+  getExplicitSessions(): Promise<ExplicitSessionData[]>
+  clearExplicitSessions(): Promise<void>
+
+  saveImplicitSession(sessionData: ImplicitSessionData): Promise<void>
+  getImplicitSession(): Promise<ImplicitSessionData | null>
+  clearImplicitSession(): Promise<void>
+
+  clearAllData(): Promise<void>
+}
+
+const DB_NAME = 'SequenceDappStorage'
+const DB_VERSION = 1
+const STORE_NAME = 'userKeys'
+const IMPLICIT_SESSIONS_IDB_KEY = 'SequenceImplicitSession'
+const EXPLICIT_SESSIONS_IDB_KEY = 'SequenceExplicitSession'
+
+const PENDING_REDIRECT_REQUEST_KEY = 'SequencePendingRedirect'
+const TEMP_SESSION_PK_KEY = 'SequencePendingTempSessionPk'
+const PENDING_REQUEST_CONTEXT_KEY = 'SequencePendingRequestContext'
+
+export class WebStorage implements SequenceStorage {
+  private openDB(): Promise<IDBDatabase> {
+    return new Promise((resolve, reject) => {
+      const request = indexedDB.open(DB_NAME, DB_VERSION)
+      request.onerror = (event) => reject(`IndexedDB error: ${(event.target as IDBRequest).error}`)
+      request.onsuccess = (event) => resolve((event.target as IDBRequest).result as IDBDatabase)
+      request.onupgradeneeded = (event) => {
+        const db = (event.target as IDBRequest).result as IDBDatabase
+        if (!db.objectStoreNames.contains(STORE_NAME)) {
+          db.createObjectStore(STORE_NAME)
+        }
+      }
+    })
+  }
+
+  private async getIDBItem<T>(key: IDBValidKey): Promise<T | undefined> {
+    const db = await this.openDB()
+    return new Promise((resolve, reject) => {
+      const request = db.transaction(STORE_NAME, 'readonly').objectStore(STORE_NAME).get(key)
+      request.onerror = (event) => reject(`Failed to retrieve item: ${(event.target as IDBRequest).error}`)
+      request.onsuccess = (event) => resolve((event.target as IDBRequest).result as T | undefined)
+    })
+  }
+
+  private async setIDBItem(key: IDBValidKey, value: unknown): Promise<void> {
+    const db = await this.openDB()
+    return new Promise((resolve, reject) => {
+      const request = db.transaction(STORE_NAME, 'readwrite').objectStore(STORE_NAME).put(value, key)
+      request.onerror = (event) => reject(`Failed to save item: ${(event.target as IDBRequest).error}`)
+      request.onsuccess = () => resolve()
+    })
+  }
+
+  private async deleteIDBItem(key: IDBValidKey): Promise<void> {
+    const db = await this.openDB()
+    return new Promise((resolve, reject) => {
+      const request = db.transaction(STORE_NAME, 'readwrite').objectStore(STORE_NAME).delete(key)
+      request.onerror = (event) => reject(`Failed to delete item: ${(event.target as IDBRequest).error}`)
+      request.onsuccess = () => resolve()
+    })
+  }
+
+  async setPendingRedirectRequest(isPending: boolean): Promise<void> {
+    try {
+      if (isPending) {
+        sessionStorage.setItem(PENDING_REDIRECT_REQUEST_KEY, 'true')
+      } else {
+        sessionStorage.removeItem(PENDING_REDIRECT_REQUEST_KEY)
+      }
+    } catch (error) {
+      console.error('Failed to set pending redirect flag:', error)
+    }
+  }
+
+  async isRedirectRequestPending(): Promise<boolean> {
+    try {
+      return sessionStorage.getItem(PENDING_REDIRECT_REQUEST_KEY) === 'true'
+    } catch (error) {
+      console.error('Failed to check pending redirect flag:', error)
+      return false
+    }
+  }
+
+  async saveTempSessionPk(pk: Hex.Hex): Promise<void> {
+    try {
+      sessionStorage.setItem(TEMP_SESSION_PK_KEY, pk)
+    } catch (error) {
+      console.error('Failed to save temp session PK:', error)
+    }
+  }
+
+  async getAndClearTempSessionPk(): Promise<Hex.Hex | null> {
+    try {
+      const pk = sessionStorage.getItem(TEMP_SESSION_PK_KEY)
+      sessionStorage.removeItem(TEMP_SESSION_PK_KEY)
+      return pk as Hex.Hex | null
+    } catch (error) {
+      console.error('Failed to retrieve temp session PK:', error)
+      return null
+    }
+  }
+
+  async savePendingRequest(context: PendingRequestContext): Promise<void> {
+    try {
+      sessionStorage.setItem(PENDING_REQUEST_CONTEXT_KEY, JSON.stringify(context, jsonReplacers))
+    } catch (error) {
+      console.error('Failed to save pending request context:', error)
+    }
+  }
+
+  async getAndClearPendingRequest(): Promise<PendingRequestContext | null> {
+    try {
+      const context = sessionStorage.getItem(PENDING_REQUEST_CONTEXT_KEY)
+      if (!context) return null
+      sessionStorage.removeItem(PENDING_REQUEST_CONTEXT_KEY)
+      return JSON.parse(context, jsonRevivers)
+    } catch (error) {
+      console.error('Failed to retrieve pending request context:', error)
+      return null
+    }
+  }
+
+  async peekPendingRequest(): Promise<PendingRequestContext | null> {
+    try {
+      const context = sessionStorage.getItem(PENDING_REQUEST_CONTEXT_KEY)
+      if (!context) return null
+      return JSON.parse(context, jsonRevivers)
+    } catch (error) {
+      console.error('Failed to peek at pending request context:', error)
+      return null
+    }
+  }
+
+  async saveExplicitSession(sessionData: ExplicitSessionData): Promise<void> {
+    try {
+      const existingSessions = (await this.getExplicitSessions()).filter(
+        (s) =>
+          !(
+            Address.isEqual(s.walletAddress, sessionData.walletAddress) &&
+            s.pk === sessionData.pk &&
+            s.chainId === sessionData.chainId
+          ),
+      )
+      await this.setIDBItem(EXPLICIT_SESSIONS_IDB_KEY, [...existingSessions, sessionData])
+    } catch (error) {
+      console.error('Failed to save explicit session:', error)
+      throw error
+    }
+  }
+
+  async getExplicitSessions(): Promise<ExplicitSessionData[]> {
+    try {
+      const sessions = await this.getIDBItem<ExplicitSessionData[]>(EXPLICIT_SESSIONS_IDB_KEY)
+      return sessions && Array.isArray(sessions) ? sessions : []
+    } catch (error) {
+      console.error('Failed to retrieve explicit sessions:', error)
+      return []
+    }
+  }
+
+  async clearExplicitSessions(): Promise<void> {
+    try {
+      await this.deleteIDBItem(EXPLICIT_SESSIONS_IDB_KEY)
+    } catch (error) {
+      console.error('Failed to clear explicit sessions:', error)
+      throw error
+    }
+  }
+
+  async saveImplicitSession(sessionData: ImplicitSessionData): Promise<void> {
+    try {
+      await this.setIDBItem(IMPLICIT_SESSIONS_IDB_KEY, sessionData)
+    } catch (error) {
+      console.error('Failed to save implicit session:', error)
+      throw error
+    }
+  }
+
+  async getImplicitSession(): Promise<ImplicitSessionData | null> {
+    try {
+      return (await this.getIDBItem<ImplicitSessionData>(IMPLICIT_SESSIONS_IDB_KEY)) ?? null
+    } catch (error) {
+      console.error('Failed to retrieve implicit session:', error)
+      return null
+    }
+  }
+
+  async clearImplicitSession(): Promise<void> {
+    try {
+      await this.deleteIDBItem(IMPLICIT_SESSIONS_IDB_KEY)
+    } catch (error) {
+      console.error('Failed to clear implicit session:', error)
+      throw error
+    }
+  }
+
+  async clearAllData(): Promise<void> {
+    try {
+      // Clear all session storage items
+      sessionStorage.removeItem(PENDING_REDIRECT_REQUEST_KEY)
+      sessionStorage.removeItem(TEMP_SESSION_PK_KEY)
+      sessionStorage.removeItem(PENDING_REQUEST_CONTEXT_KEY)
+
+      // Clear all IndexedDB items
+      await this.clearExplicitSessions()
+      await this.clearImplicitSession()
+    } catch (error) {
+      console.error('Failed to clear all data:', error)
+      throw error
+    }
+  }
+}