@zerodev/wallet-core 0.0.1-alpha.10

package/src/client/decorators/client.ts

@@ -0,0 +1,171 @@
+import {
+  type LoginWithStampParameters,
+  type LoginWithStampReturnType,
+  loginWithStamp,
+} from '../../actions/auth/loginWithStamp.js'
+import {
+  type AuthenticateWithEmailParameters,
+  type AuthenticateWithEmailReturnType,
+  type AuthenticateWithOAuthParameters,
+  type AuthenticateWithOAuthReturnType,
+  authenticateWithEmail,
+  authenticateWithOAuth,
+  type GetAuthProxyConfigIdReturnType,
+  type GetUserEmailParameters,
+  type GetUserEmailReturnType,
+  type GetUserWalletParameters,
+  type GetUserWalletReturnType,
+  type GetWhoamiParameters,
+  type GetWhoamiReturnType,
+  getAuthProxyConfigId,
+  getUserEmail,
+  getUserWallet,
+  getWhoami,
+  type LoginWithOTPParameters,
+  type LoginWithOTPReturnType,
+  loginWithOTP,
+  type RegisterWithOTPParameters,
+  type RegisterWithOTPReturnType,
+  type RegisterWithPasskeyParameters,
+  type RegisterWithPasskeyReturnType,
+  registerWithOTP,
+  registerWithPasskey,
+  type SignRawPayloadParameters,
+  type SignRawPayloadReturnType,
+  signRawPayload,
+} from '../../actions/index.js'
+import {
+  type SignTransactionParameters,
+  type SignTransactionReturnType,
+  signTransaction,
+} from '../../actions/wallet/signTransaction.js'
+import type { Client } from '../types.js'
+
+/**
+ * ZeroDev Wallet client actions that can be performed with a client
+ */
+export type ZeroDevWalletActions = {
+  // Auth actions
+  /**
+   * Authenticates a user with their email address
+   */
+  authenticateWithEmail: (
+    params: AuthenticateWithEmailParameters,
+  ) => Promise<AuthenticateWithEmailReturnType>
+
+  /**
+   * Authenticates a user with OAuth credentials
+   */
+  authenticateWithOAuth: (
+    params: AuthenticateWithOAuthParameters,
+  ) => Promise<AuthenticateWithOAuthReturnType>
+
+  /**
+   * Gets the current user information
+   */
+  getWhoami: (params: GetWhoamiParameters) => Promise<GetWhoamiReturnType>
+
+  /**
+   * Gets the user's email address
+   */
+  getUserEmail: (
+    params: GetUserEmailParameters,
+  ) => Promise<GetUserEmailReturnType>
+
+  // Wallet actions
+  /**
+   * Gets the user's wallet information
+   */
+  getUserWallet: (
+    params: GetUserWalletParameters,
+  ) => Promise<GetUserWalletReturnType>
+
+  /**
+   * Signs a raw payload with the user's wallet
+   */
+  signRawPayload: (
+    params: SignRawPayloadParameters,
+  ) => Promise<SignRawPayloadReturnType>
+
+  /**
+   * Signs a transaction with the user's wallet
+   */
+  signTransaction: (
+    params: SignTransactionParameters,
+  ) => Promise<SignTransactionReturnType>
+
+  /**
+   * Registers a passkey with the user's wallet
+   */
+  registerWithPasskey: (
+    params: RegisterWithPasskeyParameters,
+  ) => Promise<RegisterWithPasskeyReturnType>
+
+  /**
+   * Logs in a user with a stamp
+   */
+  loginWithStamp: (
+    params: LoginWithStampParameters,
+  ) => Promise<LoginWithStampReturnType>
+
+  /**
+   * Registers a user with OTP (One-Time Password) authentication
+   */
+  registerWithOTP: (
+    params: RegisterWithOTPParameters,
+  ) => Promise<RegisterWithOTPReturnType>
+
+  /**
+   * Logs in a user with OTP (One-Time Password) authentication
+   */
+  loginWithOTP: (
+    params: LoginWithOTPParameters,
+  ) => Promise<LoginWithOTPReturnType>
+
+  /**
+   * Gets the auth proxy config ID from the backend
+   */
+  getAuthProxyConfigId: () => Promise<GetAuthProxyConfigIdReturnType>
+}
+
+/**
+ * Decorator function that adds ZeroDev Wallet client actions to a client
+ *
+ * @param client - The base client to extend
+ * @returns An object containing all ZeroDev Wallet client actions bound to the client
+ *
+ * @example
+ * ```ts
+ * import { createClient, zeroDevWalletTransport, zeroDevWalletActions } from '@zerodev/wallet-core';
+ *
+ * const client = createClient({
+ *   transport: zeroDevWalletTransport({ baseUrl: 'https://api.example.com' }),
+ *   stamper: myStamper,
+ * }).extend(zeroDevWalletActions);
+ *
+ * // Now you can use actions directly on the client
+ * const userInfo = await client.getWhoami({
+ *   organizationId: 'org_123',
+ *   projectId: 'proj_456'
+ * });
+ * ```
+ */
+export function zeroDevWalletActions(client: Client): ZeroDevWalletActions {
+  return {
+    // Auth actions
+    authenticateWithEmail: (params) => authenticateWithEmail(client, params),
+    authenticateWithOAuth: (params) => authenticateWithOAuth(client, params),
+    getWhoami: (params) => getWhoami(client, params),
+    getUserEmail: (params) => getUserEmail(client, params),
+
+    // Wallet actions
+    getUserWallet: (params) => getUserWallet(client, params),
+    signRawPayload: (params) => signRawPayload(client, params),
+    signTransaction: (params) => signTransaction(client, params),
+    registerWithPasskey: (params) => registerWithPasskey(client, params),
+    loginWithStamp: (params) => loginWithStamp(client, params),
+    registerWithOTP: (params) => registerWithOTP(client, params),
+    loginWithOTP: (params) => loginWithOTP(client, params),
+    getAuthProxyConfigId: () => getAuthProxyConfigId(client),
+  }
+}

package/src/client/index.ts

@@ -0,0 +1,19 @@
+export {
+  type AuthProxyClient,
+  type AuthProxyClientConfig,
+  type AuthProxyVerifyOtpRequest,
+  type AuthProxyVerifyOtpResponse,
+  createAuthProxyClient,
+} from './authProxy.js'
+export {
+  createBaseClient,
+  createClient,
+  type ZeroDevWalletClient,
+} from './createClient.js'
+export { zeroDevWalletTransport } from './transports/createTransport.js'
+export type {
+  Client,
+  ClientConfig,
+  Transport,
+  TransportConfig,
+} from './types.js'

package/src/client/transports/createTransport.ts

@@ -0,0 +1,54 @@
+import type { Transport } from '../types.js'
+import { rest } from './rest.js'
+
+export type CreateTransportOptions = {
+  /** Base URL for the API */
+  baseUrl: string
+  /** Request timeout in milliseconds */
+  timeoutMs?: number
+  /** Transport key identifier */
+  key?: string
+  /** Transport name */
+  name?: string
+}
+
+/**
+ * Creates a transport for the ZeroDev Wallet client.
+ * Requires a stamper for authenticated requests.
+ */
+export function zeroDevWalletTransport(
+  options: CreateTransportOptions,
+): Transport {
+  const {
+    baseUrl,
+    timeoutMs = 10_000,
+    key = 'zeroDevWallet',
+    name = 'ZeroDev Wallet Transport',
+  } = options
+
+  return ({ indexedDbStamper, webauthnStamper }) => {
+    // Create REST transport with stamper
+    const transport = rest(baseUrl, {
+      timeoutMs,
+      key,
+      name,
+      indexedDbStamper,
+      webauthnStamper,
+    })
+
+    return {
+      config: {
+        name,
+        key,
+        url: baseUrl,
+        timeoutMs,
+        type: 'zeroDevWallet',
+      },
+      request: transport.request,
+      value: {
+        indexedDbStamper,
+        webauthnStamper,
+      },
+    }
+  }
+}

package/src/client/transports/rest.ts

@@ -0,0 +1,138 @@
+import { canonicalizeEx } from 'json-canonicalize'
+import { RestRequestError, RestTimeoutError } from '../../errors/request.js'
+import type { IndexedDbStamper, WebauthnStamper } from '../../stampers/types.js'
+
+export type RestRequestArgs = {
+  path: string
+  method?: 'GET' | 'POST' | 'PUT' | 'DELETE'
+  body?: any
+  headers?: Record<string, string>
+  stamp?: boolean
+  stampWith?: 'indexedDb' | 'webAuthn'
+  stampPostion?: 'body' | 'headers'
+  /** Include credentials (cookies) in the request */
+  credentials?: RequestCredentials
+}
+
+export type RestRequestFn = <T = any>(args: RestRequestArgs) => Promise<T>
+
+export type RestTransport = {
+  config: { key: string; name: string; url: string; timeoutMs: number }
+  request: RestRequestFn
+  value: Record<string, unknown>
+}
+
+export type RestTransportConfig = {
+  fetchOptions?: Omit<RequestInit, 'body' | 'method' | 'signal'>
+  onRequest?: (
+    url: string,
+    init: RequestInit,
+  ) => Promise<RequestInit | undefined> | RequestInit | undefined
+  onResponse?: (res: Response) => Promise<void> | void
+  timeoutMs?: number
+  key?: string
+  name?: string
+  indexedDbStamper: IndexedDbStamper
+  webauthnStamper: WebauthnStamper
+}
+
+export function rest(url: string, cfg: RestTransportConfig): RestTransport {
+  const timeoutMs = cfg.timeoutMs ?? 10_000
+  const key = cfg.key ?? 'rest'
+  const name = cfg.name ?? 'HTTP REST'
+
+  const request: RestRequestFn = async (args) => {
+    const fullUrl = `${url}/${args.path}`
+    const controller = new AbortController()
+    const timer = setTimeout(() => controller.abort(), timeoutMs)
+
+    try {
+      let requestBody = args.body
+      let requestHeaders = {
+        'content-type': 'application/json',
+        ...(args.headers ?? {}),
+        ...(cfg.fetchOptions?.headers ?? {}),
+      }
+
+      // Handle stamping if requested
+      if (args.stamp) {
+        let stamper: IndexedDbStamper | WebauthnStamper
+        if (args.stampWith === 'indexedDb') {
+          stamper = cfg.indexedDbStamper
+        } else if (args.stampWith === 'webAuthn') {
+          stamper = cfg.webauthnStamper
+        } else {
+          stamper = cfg.indexedDbStamper
+        }
+        const { body, apiUrl } = args.body
+        const bodyString = canonicalizeEx(body ?? args.body)
+        const stamp = await stamper.stamp(bodyString)
+
+        // Restructure request body to match backend expectation
+        if (args.stampPostion === 'headers') {
+          requestHeaders = {
+            ...requestHeaders,
+            [stamp.stampHeaderName]: stamp.stampHeaderValue,
+          }
+        } else if (body) {
+          requestBody = {
+            body: bodyString,
+            stamp: {
+              stampHeaderName: stamp.stampHeaderName,
+              stampHeaderValue: stamp.stampHeaderValue,
+            },
+            apiUrl: apiUrl,
+          }
+        } else {
+          requestBody = {
+            ...args.body,
+            stamp: {
+              stampHeaderName: stamp.stampHeaderName,
+              stampHeaderValue: stamp.stampHeaderValue,
+            },
+          }
+        }
+      }
+
+      const init: RequestInit = {
+        ...cfg.fetchOptions,
+        method: args.method ?? 'POST',
+        headers: requestHeaders,
+        body: requestBody != null ? JSON.stringify(requestBody) : null,
+        signal: controller.signal,
+        ...(args.credentials && { credentials: args.credentials }),
+      }
+
+      const finalInit = (await cfg.onRequest?.(fullUrl, init)) ?? init
+      const res = await fetch(fullUrl, finalInit)
+
+      await cfg.onResponse?.(res)
+
+      let data: any
+      const ct = res.headers.get('content-type') ?? ''
+      if (ct.startsWith('application/json')) data = await res.json()
+      else {
+        const text = await res.text()
+        try {
+          data = text ? JSON.parse(text) : {}
+        } catch {
+          data = text
+        }
+      }
+
+      if (!res.ok) throw new RestRequestError(fullUrl, res.status, data)
+      return data as any
+    } catch (err: any) {
+      if (err.name === 'AbortError') throw new RestTimeoutError(fullUrl)
+      throw err
+    } finally {
+      clearTimeout(timer)
+    }
+  }
+
+  return {
+    config: { key, name, url, timeoutMs },
+    request,
+    value: {},
+  }
+}

package/src/client/types.ts

@@ -0,0 +1,64 @@
+import type { IndexedDbStamper, WebauthnStamper } from '../stampers/types.js'
+import type { RestRequestFn } from './transports/rest.js'
+
+export type TransportConfig = {
+  /** The name of the transport. */
+  name: string
+  /** The key of the transport. */
+  key: string
+  /** Base URL for the API */
+  url: string
+  /** Proxy base URL for auth requests */
+  proxyBaseUrl?: string
+  /** Request timeout in milliseconds */
+  timeoutMs: number
+  /** The type of the transport. */
+  type: string
+}
+
+export type Transport = (options: {
+  indexedDbStamper: IndexedDbStamper
+  webauthnStamper: WebauthnStamper
+}) => {
+  config: TransportConfig
+  request: RestRequestFn
+  value?: Record<string, unknown>
+}
+
+export type ClientConfig = {
+  transport: Transport
+  indexedDbStamper: IndexedDbStamper
+  webauthnStamper: WebauthnStamper
+  organizationId?: string
+  key?: string
+  name?: string
+}
+
+export type Client<extended extends Extended | undefined = undefined> = {
+  /** Transport configuration */
+  transport: TransportConfig & Record<string, unknown>
+  /** Request function from transport */
+  request: RestRequestFn
+  /** IndexedDB Stamper for authenticated requests */
+  indexedDbStamper: IndexedDbStamper
+  /** WebAuthn Stamper for authenticated requests */
+  webauthnStamper: WebauthnStamper
+  /** Organization ID */
+  organizationId?: string
+  /** A key for the client */
+  key: string
+  /** A name for the client */
+  name: string
+  /** The type of client */
+  type: string
+  /** A unique ID for the client */
+  uid: string
+  /** Extend the client with additional functionality */
+  extend: <const client extends Extended>(
+    fn: (client: Client<extended>) => client,
+  ) => Client<client & (extended extends Extended ? extended : unknown)>
+} & (extended extends Extended ? extended : unknown)
+
+type Extended = {
+  [key: string]: unknown
+}

package/src/constants.ts

@@ -0,0 +1,5 @@
+export const DEFAULT_SESSION_EXPIRATION_IN_SECONDS = '900' // default to 15 minutes
+export const DEFAULT_IFRAME_CONTAINER_ID = 'turnkey-auth-iframe-container-id'
+export const DEFAULT_IFRAME_ELEMENT_ID = 'turnkey-default-iframe-element-id'
+export const DEFAULT_ORGANIZATION_ID = '0d98e826-dd8f-44ca-a585-3afcd27d4002'
+export const KMS_SERVER_URL = 'https://kms.staging.zerodev.app'