@zerodev/wallet-core 0.0.1-alpha.3

package/src/actions/auth/authenticateWithEmail.ts

@@ -0,0 +1,52 @@
+import type { Client } from '../../client/types.js'
+
+export type EmailCustomization = {
+  /** A template for the URL to be used in a magic link button, e.g. `https://dapp.xyz/%s`. The auth bundle will be interpolated into the `%s`. */
+  magicLinkTemplate?: string
+}
+
+export type AuthenticateWithEmailParameters = {
+  /** The email address to authenticate */
+  email: string
+  /** The project ID for the request */
+  projectId: string
+  /** Target public key for authentication */
+  targetPublicKey: string
+  /** Optional email customization settings */
+  emailCustomization?: EmailCustomization
+}
+
+export type AuthenticateWithEmailReturnType = {
+  /** The user ID */
+  userId?: string
+  /** The wallet address */
+  walletAddress?: string
+  /** The sub-organization ID */
+  subOrganizationId?: string
+  /** Whether magic link is required */
+  requiresMagicLink?: boolean
+  /** The Turnkey session if available */
+  turnkeySession?: string
+}
+
+/**
+ * @deprecated Use {@link registerWithOTP} instead
+ * See {@link registerWithOTP} for more details on how to authenticate with email.
+ */
+export async function authenticateWithEmail(
+  client: Client,
+  params: AuthenticateWithEmailParameters,
+): Promise<AuthenticateWithEmailReturnType> {
+  const { email, projectId, targetPublicKey, emailCustomization } = params
+
+  return await client.request({
+    path: `${projectId}/auth/email-magic`,
+    method: 'POST',
+    body: {
+      email,
+      emailCustomization,
+      targetPublicKey,
+      projectId,
+    },
+  })
+}

package/src/actions/auth/authenticateWithOAuth.ts

@@ -0,0 +1,58 @@
+import type { Client } from '../../client/types.js'
+
+export type AuthenticateWithOAuthParameters = {
+  /** The OAuth credential/token */
+  oidcToken: string
+  /** The OAuth provider (e.g., 'google') */
+  provider: string
+  /** The project ID for the request */
+  projectId: string
+  /** Target public key for authentication */
+  targetPublicKey: string
+}
+
+export type AuthenticateWithOAuthReturnType = {
+  /** The user ID */
+  userId?: string
+  /** The wallet address */
+  walletAddress?: string
+  /** The sub-organization ID */
+  subOrganizationId?: string
+  /** The Turnkey session */
+  turnkeySession?: string
+}
+
+/**
+ * Authenticates a user with OAuth credentials
+ *
+ * @param client - The ZeroDev Wallet client
+ * @param params - The parameters for OAuth authentication
+ * @returns The authentication result
+ *
+ * @example
+ * ```ts
+ * const result = await authenticateWithOAuth(client, {
+ *   oidcToken: 'oauth_token_here',
+ *   provider: 'google',
+ *   projectId: 'proj_456',
+ *   targetPublicKey: '0x...'
+ * });
+ * ```
+ */
+export async function authenticateWithOAuth(
+  client: Client,
+  params: AuthenticateWithOAuthParameters,
+): Promise<AuthenticateWithOAuthReturnType> {
+  const { oidcToken, provider, projectId, targetPublicKey } = params
+
+  return await client.request({
+    path: `${projectId}/auth/oauth`,
+    method: 'POST',
+    body: {
+      oidcToken,
+      provider,
+      targetPublicKey,
+      projectId,
+    },
+  })
+}

package/src/actions/auth/getWhoami.ts

@@ -0,0 +1,51 @@
+import type { Client } from '../../client/types.js'
+
+export type GetWhoamiParameters = {
+  /** The organization ID to query */
+  organizationId: string
+  /** The project ID for the request */
+  projectId: string
+}
+
+export type GetWhoamiReturnType = {
+  /** The user's ID */
+  userId: string
+  /** The organization ID */
+  organizationId: string
+  /** The organization name */
+  organizationName?: string
+  /** The username */
+  username?: string
+}
+
+/**
+ * Gets the current user information
+ *
+ * @param client - The ZeroDev Wallet client
+ * @param params - The parameters for the whoami request
+ * @returns The user information
+ *
+ * @example
+ * ```ts
+ * const userInfo = await getWhoami(client, {
+ *   organizationId: 'org_123',
+ *   projectId: 'proj_456'
+ * });
+ * console.log(userInfo.userId); // 'user_789'
+ * ```
+ */
+export async function getWhoami(
+  client: Client,
+  params: GetWhoamiParameters,
+): Promise<GetWhoamiReturnType> {
+  const { organizationId, projectId } = params
+
+  return await client.request({
+    path: `${projectId}/whoami`,
+    method: 'POST',
+    body: {
+      organizationId,
+    },
+    stamp: true,
+  })
+}

package/src/actions/auth/index.ts

@@ -0,0 +1,40 @@
+export {
+  type AuthenticateWithEmailParameters,
+  type AuthenticateWithEmailReturnType,
+  authenticateWithEmail,
+  type EmailCustomization,
+} from './authenticateWithEmail.js'
+
+export {
+  type AuthenticateWithOAuthParameters,
+  type AuthenticateWithOAuthReturnType,
+  authenticateWithOAuth,
+} from './authenticateWithOAuth.js'
+
+export {
+  type GetWhoamiParameters,
+  type GetWhoamiReturnType,
+  getWhoami,
+} from './getWhoami.js'
+export {
+  type LoginWithOTPParameters,
+  type LoginWithOTPReturnType,
+  loginWithOTP,
+} from './loginWithOTP.js'
+export {
+  type LoginWithStampParameters,
+  type LoginWithStampReturnType,
+  loginWithStamp,
+} from './loginWithStamp.js'
+
+export {
+  type OtpContact,
+  type RegisterWithOTPParameters,
+  type RegisterWithOTPReturnType,
+  registerWithOTP,
+} from './registerWithOTP.js'
+export {
+  type RegisterWithPasskeyParameters,
+  type RegisterWithPasskeyReturnType,
+  registerWithPasskey,
+} from './registerWithPasskey.js'

package/src/actions/auth/loginWithOTP.ts

@@ -0,0 +1,60 @@
+import type { Client } from '../../client/types.js'
+
+export type LoginWithOTPParameters = {
+  /** The OTP ID received from registration */
+  otpId: string
+  /** The OTP code received via email/sms */
+  otpCode: string
+  /** The sub-organization ID from registration */
+  subOrganizationId: string
+  /** The encoded public key for authentication */
+  encodedPublicKey: string
+  /** The project ID for the request */
+  projectId: string
+}
+
+export type LoginWithOTPReturnType = {
+  /** The Turnkey session token */
+  session: string
+}
+
+/**
+ * Logs in a user with OTP (One-Time Password) authentication
+ * This verifies the OTP code and returns a session token
+ *
+ * @param client - The ZeroDev Wallet client
+ * @param params - The parameters for OTP login
+ * @returns The login result with session token
+ *
+ * @example
+ * ```ts
+ * // After receiving OTP code via email
+ * const result = await loginWithOTP(client, {
+ *   otpId: 'otp_123456',
+ *   otpCode: '123456',
+ *   subOrganizationId: 'org_abc',
+ *   encodedPublicKey: '0x...',
+ *   projectId: 'proj_456'
+ * });
+ *
+ * // Use result.session for authenticated requests
+ * ```
+ */
+export async function loginWithOTP(
+  client: Client,
+  params: LoginWithOTPParameters,
+): Promise<LoginWithOTPReturnType> {
+  const { otpId, otpCode, subOrganizationId, encodedPublicKey, projectId } =
+    params
+
+  return await client.request({
+    path: `${projectId}/auth/login/otp`,
+    method: 'POST',
+    body: {
+      otpId,
+      otpCode,
+      subOrganizationId,
+      encodedPublicKey,
+    },
+  })
+}

package/src/actions/auth/loginWithStamp.ts

@@ -0,0 +1,68 @@
+import type { Client } from '../../client/types.js'
+
+export type EmailCustomization = {
+  /** A template for the URL to be used in a magic link button, e.g. `https://dapp.xyz/%s`. The auth bundle will be interpolated into the `%s`. */
+  magicLinkTemplate?: string
+}
+
+export type LoginWithStampParameters = {
+  /** The project ID for the request */
+  projectId: string
+  /** The organization ID for the request */
+  organizationId: string
+  /** The encoded public key for the request */
+  targetPublicKey: string
+}
+
+export type LoginWithStampReturnType = {
+  /** The session */
+  session: string
+}
+
+/**
+ * Logs in a user with a stamp
+ *
+ * @param client - The ZeroDev Wallet client
+ * @param params - The parameters for login with a stamp
+ * @returns The login result
+ *
+ * @example
+ * ```ts
+ * const result = await loginWithStamp(client, {
+ *   organizationId: 'org_456',
+ *   projectId: 'proj_456',
+ *   targetPublicKey: 'encodedPublicKey',
+ * });
+ * ```
+ */
+export async function loginWithStamp(
+  client: Client,
+  params: LoginWithStampParameters,
+): Promise<LoginWithStampReturnType> {
+  const { projectId, targetPublicKey, organizationId } = params
+
+  const timestampMs = Date.now()
+  const timestampMsString = timestampMs.toString()
+  const timestampIso = new Date(timestampMs).toISOString()
+
+  const stampPayload = `${JSON.stringify({
+    organizationId,
+    parameters: {
+      publicKey: targetPublicKey,
+    },
+    timestampMs: timestampMsString,
+    type: 'ACTIVITY_TYPE_STAMP_LOGIN',
+  })}\n`
+  const stamp = await client.stamper.stamp(stampPayload)
+
+  return client.request({
+    path: `${projectId}/auth/login/passkey`,
+    method: 'POST',
+    body: {
+      subOrganizationId: organizationId,
+      targetPublicKey,
+      timestamp: timestampIso,
+      stamp,
+    },
+  })
+}

package/src/actions/auth/registerWithOTP.ts

@@ -0,0 +1,71 @@
+import type { Client } from '../../client/types.js'
+import type { EmailCustomization } from './authenticateWithEmail.js'
+
+export type OtpContact = {
+  /** The OTP delivery type (currently only 'email' is supported) */
+  type: 'email' | 'sms'
+  /** The contact information (email address or phone number) */
+  contact: string
+}
+
+export type RegisterWithOTPParameters = {
+  /** The email address to register */
+  email: string
+  /** The contact information for OTP delivery */
+  contact: OtpContact
+  /** The project ID for the request */
+  projectId: string
+  /** Optional email customization settings */
+  emailCustomization?: EmailCustomization
+}
+
+export type RegisterWithOTPReturnType = {
+  /** The user ID */
+  userId: string
+  /** The wallet address */
+  walletAddress: string
+  /** The sub-organization ID */
+  subOrganizationId: string
+  /** The OTP ID needed for login */
+  otpId: string
+}
+
+/**
+ * Registers a user with OTP (One-Time Password) authentication
+ * This will send an OTP code to the specified contact method
+ *
+ * @param client - The ZeroDev Wallet client
+ * @param params - The parameters for OTP registration
+ * @returns The registration result including otpId needed for login
+ *
+ * @example
+ * ```ts
+ * const result = await registerWithOTP(client, {
+ *   email: 'user@example.com',
+ *   contact: {
+ *     type: 'email',
+ *     contact: 'user@example.com'
+ *   },
+ *   projectId: 'proj_456'
+ * });
+ *
+ * // Use result.otpId for the login step
+ * ```
+ */
+export async function registerWithOTP(
+  client: Client,
+  params: RegisterWithOTPParameters,
+): Promise<RegisterWithOTPReturnType> {
+  const { email, contact, projectId, emailCustomization } = params
+
+  return await client.request({
+    path: `${projectId}/auth/register/otp`,
+    method: 'POST',
+    body: {
+      email,
+      contact,
+      projectId,
+      emailCustomization,
+    },
+  })
+}

package/src/actions/auth/registerWithPasskey.ts

@@ -0,0 +1,72 @@
+import type { Client } from '../../client/types.js'
+
+export type EmailCustomization = {
+  /** A template for the URL to be used in a magic link button, e.g. `https://dapp.xyz/%s`. The auth bundle will be interpolated into the `%s`. */
+  magicLinkTemplate?: string
+}
+
+export type RegisterWithPasskeyParameters = {
+  /** The email address to authenticate */
+  email: string
+  /** The project ID for the request */
+  projectId: string
+  /** The challenge for the request */
+  challenge: string
+  /** The attestation for the request */
+  attestation: {
+    attestationObject: string
+    clientDataJson: string
+    credentialId: string
+  }
+  /** The encoded public key for the request */
+  encodedPublicKey: string
+}
+
+export type RegisterWithPasskeyReturnType = {
+  /** The user ID */
+  userId: string
+  /** The wallet address */
+  walletAddress: string
+  /** The sub-organization ID */
+  subOrganizationId: string
+}
+
+/**
+ * Registers a passkey with the user's wallet
+ *
+ * @param client - The ZeroDev Wallet client
+ * @param params - The parameters for passkey registration
+ * @returns The passkey registration result
+ *
+ * @example
+ * ```ts
+ * const result = await registerWithPasskey(client, {
+ *   email: 'user@example.com',
+ *   projectId: 'proj_456',
+ *   challenge: 'challenge',
+ *   attestation: {
+ *     attestationObject: 'attestationObject',
+ *     clientDataJson: 'clientDataJson',
+ *     credentialId: 'credentialId'
+ *   },
+ *   encodedPublicKey: 'encodedPublicKey'
+ * });
+ * ```
+ */
+export async function registerWithPasskey(
+  client: Client,
+  params: RegisterWithPasskeyParameters,
+): Promise<RegisterWithPasskeyReturnType> {
+  const { email, projectId, challenge, attestation, encodedPublicKey } = params
+
+  return client.request({
+    path: `${projectId}/auth/register/passkey`,
+    method: 'POST',
+    body: {
+      email,
+      attestation,
+      challenge,
+      encodedPublicKey,
+    },
+  })
+}

package/src/actions/index.ts

@@ -0,0 +1,36 @@
+// Auth actions
+export {
+  type AuthenticateWithEmailParameters,
+  type AuthenticateWithEmailReturnType,
+  type AuthenticateWithOAuthParameters,
+  type AuthenticateWithOAuthReturnType,
+  authenticateWithEmail,
+  authenticateWithOAuth,
+  type EmailCustomization,
+  type GetWhoamiParameters,
+  type GetWhoamiReturnType,
+  getWhoami,
+  type LoginWithOTPParameters,
+  type LoginWithOTPReturnType,
+  loginWithOTP,
+  type OtpContact,
+  type RegisterWithOTPParameters,
+  type RegisterWithOTPReturnType,
+  type RegisterWithPasskeyParameters,
+  type RegisterWithPasskeyReturnType,
+  registerWithOTP,
+  registerWithPasskey,
+} from './auth/index.js'
+
+// Wallet actions
+export {
+  type GetUserWalletParameters,
+  type GetUserWalletReturnType,
+  getUserWallet,
+  type SignRawPayloadParameters,
+  type SignRawPayloadReturnType,
+  type SignTransactionParameters,
+  type SignTransactionReturnType,
+  signRawPayload,
+  signTransaction,
+} from './wallet/index.js'

package/src/actions/wallet/getUserWallet.ts

@@ -0,0 +1,46 @@
+import type { Hex } from 'viem'
+import type { Client } from '../../client/types.js'
+
+export type GetUserWalletParameters = {
+  /** The organization ID */
+  organizationId: string
+  /** The project ID for the request */
+  projectId: string
+}
+
+export type GetUserWalletReturnType = {
+  /** The wallet address */
+  walletAddress: Hex
+  /** The user ID */
+  userId?: string
+}
+
+/**
+ * Gets the user's wallet information
+ *
+ * @param client - The ZeroDev Wallet client
+ * @param params - The parameters for getting wallet info
+ * @returns The wallet information
+ *
+ * @example
+ * ```ts
+ * const wallet = await getUserWallet(client, {
+ *   organizationId: 'org_123',
+ *   projectId: 'proj_456'
+ * });
+ * console.log(wallet.walletAddress); // '0x...'
+ * ```
+ */
+export async function getUserWallet(
+  client: Client,
+  params: GetUserWalletParameters,
+): Promise<GetUserWalletReturnType> {
+  const { organizationId, projectId } = params
+
+  return await client.request({
+    path: `${projectId}/user-wallet`,
+    body: {
+      organizationId,
+    },
+  })
+}

package/src/actions/wallet/index.ts

@@ -0,0 +1,17 @@
+export {
+  type GetUserWalletParameters,
+  type GetUserWalletReturnType,
+  getUserWallet,
+} from './getUserWallet.js'
+
+export {
+  type SignRawPayloadParameters,
+  type SignRawPayloadReturnType,
+  signRawPayload,
+} from './signRawPayload.js'
+
+export {
+  type SignTransactionParameters,
+  type SignTransactionReturnType,
+  signTransaction,
+} from './signTransaction.js'

package/src/actions/wallet/signRawPayload.ts

@@ -0,0 +1,71 @@
+import type { Hex } from 'viem'
+import type { Client } from '../../client/types.js'
+
+export type SignRawPayloadParameters = {
+  /** The organization ID */
+  organizationId: string
+  /** The project ID for the request */
+  projectId: string
+  /** The address to sign with */
+  address: Hex
+  /** The payload hash to sign (without 0x prefix) */
+  payload: string
+  /** The encoding type */
+  encoding?: 'PAYLOAD_ENCODING_HEXADECIMAL' | 'PAYLOAD_ENCODING_EIP712'
+  /** The hash function type */
+  hashFunction?: 'HASH_FUNCTION_NO_OP'
+}
+
+export type SignRawPayloadReturnType = Hex
+
+/**
+ * Signs a raw payload with the user's wallet
+ *
+ * @param client - The ZeroDev Wallet client
+ * @param params - The parameters for signing
+ * @returns The signature
+ *
+ * @example
+ * ```ts
+ * const result = await signRawPayload(client, {
+ *   organizationId: 'org_123',
+ *   projectId: 'proj_456',
+ *   address: '0x123...',
+ *   payload: 'abc123...',
+ * });
+ * console.log(result.signature); // '0x...'
+ * ```
+ */
+export async function signRawPayload(
+  client: Client,
+  params: SignRawPayloadParameters,
+): Promise<SignRawPayloadReturnType> {
+  const {
+    organizationId,
+    projectId,
+    address,
+    payload,
+    encoding = 'PAYLOAD_ENCODING_HEXADECIMAL',
+    hashFunction = 'HASH_FUNCTION_NO_OP',
+  } = params
+
+  const { signature } = await client.request({
+    path: `${projectId}/sign/raw-payload`,
+    body: {
+      body: {
+        type: 'ACTIVITY_TYPE_SIGN_RAW_PAYLOAD_V2',
+        timestampMs: Date.now().toString(),
+        organizationId,
+        parameters: {
+          signWith: address,
+          payload,
+          encoding,
+          hashFunction,
+        },
+      },
+      apiUrl: 'https://api.turnkey.com/public/v1/submit/sign_raw_payload',
+    },
+    stamp: true,
+  })
+  return signature as Hex
+}