@getpara/core-sdk 2.12.0 → 2.13.0

package/dist/types/state/types/auth.d.ts

@@ -0,0 +1,113 @@
+import type { ServerAuthState } from '@getpara/user-management-client';
+import type { AuthState, WithCustomTheme, WithUseShortUrls } from '../../types/index.js';
+import type { createAuthStateMachine } from '../machines/authStateMachine.js';
+import type { CoreActor, ServerAuthStateResult } from './core.js';
+import type { LoginExternalWalletParams } from '../../services/types/AuthServiceTypes.js';
+import type { PerformVerifyNewAccountParams, VerifyFarcasterParams, VerifyTelegramParams } from '../../services/types/VerificationFlowServiceTypes.js';
+import type { WaitForWalletCreationParams } from '../../services/types/SignupFlowServiceTypes.js';
+import type { BaseVerifyExternalWalletParams, ConnectExternalWalletParams, InitOAuthPollingParams, PerformConnectExternalWalletResponse, PerformSignUpOrLogInParams, ExternalSignMessageParams, SwitchExternalWalletParams, VerifyExternalWalletParams, WaitForTelegramEventParams, WaitForFarcasterEventParams, PollingCallbacks } from '../../services/types';
+/**
+ * Represents the current phase of the authentication flow.
+ *
+ * @example
+ * ```typescript
+ * // Check current auth phase
+ * if (authPhase === 'unauthenticated') {
+ *   // Show login form
+ * } else if (authPhase === 'authenticated') {
+ *   // The user's session is active
+ * }
+ * ```
+ */
+export type AuthPhase = 'uninitialized' | 'checking_state' | 'clearing_state' | 'unauthenticated' | 'authenticating_email_phone' | 'authenticating_oauth' | 'connecting_external_wallet' | 'switching_external_wallet' | 'authenticating_external_wallet' | 'authenticating_telegram' | 'authenticating_telegram_legacy' | 'authenticating_farcaster' | 'authenticating_farcaster_legacy' | 'waiting_for_farcaster' | 'processing_authentication' | 'awaiting_wallet_signature' | 'awaiting_wallet_verification' | 'awaiting_account_verification' | 'awaiting_session_start' | 'verifying_new_account' | 'verifying_external_wallet' | 'waiting_for_session' | 'authenticated' | 'guest_mode' | 'error' | 'signing_external_wallet_verification';
+export type AuthEvents = {
+    type: 'AUTHENTICATE_EMAIL_PHONE';
+    data: PerformSignUpOrLogInParams & {
+        isLegacy: boolean;
+    };
+} | {
+    type: 'AUTHENTICATE_OAUTH';
+    data: InitOAuthPollingParams & PollingCallbacks & {
+        isLegacy: boolean;
+    };
+} | {
+    type: 'AUTHENTICATE_EXTERNAL_WALLET';
+    data: LoginExternalWalletParams;
+} | {
+    type: 'CONNECT_EXTERNAL_WALLET';
+    data: ConnectExternalWalletParams;
+} | {
+    type: 'SWITCH_EXTERNAL_WALLET';
+    data: SwitchExternalWalletParams;
+} | {
+    type: 'AUTHENTICATE_TELEGRAM';
+    data: WaitForTelegramEventParams;
+} | {
+    type: 'AUTHENTICATE_TELEGRAM_LEGACY';
+    data: VerifyTelegramParams;
+} | {
+    type: 'AUTHENTICATE_FARCASTER';
+    data: WaitForFarcasterEventParams;
+} | {
+    type: 'AUTHENTICATE_FARCASTER_LEGACY';
+    data: VerifyFarcasterParams;
+} | {
+    type: 'VERIFY_NEW_ACCOUNT';
+    data: PerformVerifyNewAccountParams;
+} | {
+    type: 'VERIFY_EXTERNAL_WALLET';
+    data?: VerifyExternalWalletParams;
+} | {
+    type: 'SIGN_EXTERNAL_WALLET_VERIFICATION';
+    data: ExternalSignMessageParams;
+} | {
+    type: 'WAIT_FOR_SESSION';
+    data: PollingCallbacks & {
+        autoCreateWallets?: boolean;
+        skipSessionRefresh?: boolean;
+    };
+} | {
+    type: 'WAIT_FOR_WALLET_CREATION';
+    data?: WaitForWalletCreationParams;
+} | {
+    type: 'RESET';
+} | {
+    type: 'COMPLETE';
+} | {
+    type: 'CANCEL';
+} | {
+    type: 'INITIALIZE_GUEST_MODE';
+} | {
+    type: 'SESSION_IMPORTED';
+} | {
+    type: 'ERROR';
+    error: string;
+};
+export type AuthMachine = ReturnType<typeof createAuthStateMachine>;
+export interface AuthContext {
+    coreRef: CoreActor | null;
+    authStateResult: AuthState | null;
+    serverAuthStateResult: ServerAuthStateResult;
+    isNewUser: boolean;
+    error: Error | null;
+    pollingCallbacks: PollingCallbacks | null;
+    shouldAutoCreateWallets: boolean;
+    skipSessionRefreshOnSetup: boolean;
+    externalWalletInfo?: PerformConnectExternalWalletResponse;
+    externalWalletSignVerification?: BaseVerifyExternalWalletParams;
+    isLegacy: boolean;
+    retryAttempts?: {
+        externalWalletVerification?: number;
+        newAccountVerification?: number;
+    };
+}
+export interface AuthInput {
+    coreRef: CoreActor;
+}
+export type AuthenticationOutput = {
+    authState: ServerAuthState;
+    opts: WithCustomTheme & WithUseShortUrls & {
+        sessionLookupId?: string;
+        isFromExternalWallet?: boolean;
+    };
+};

package/dist/types/state/types/core.d.ts

@@ -0,0 +1,114 @@
+import type { BiometricLocationHint, CurrentWalletIds, ServerAuthState } from '@getpara/user-management-client';
+import type { AuthState, Wallet, WithCustomTheme, WithUseShortUrls } from '../../types/index.js';
+import { AuthMachine, AuthPhase } from './auth.js';
+import { WalletMachine, WalletPhase } from './wallet.js';
+import { BaseVerifyExternalWalletParams } from '../../services/types/VerificationFlowServiceTypes.js';
+import { ActorRef, ActorRefFrom, Snapshot } from 'xstate';
+/**
+ * Represents the current phase of the core flow.
+ *
+ * @example
+ * ```typescript
+ * // Check current core phase
+ * if (corePhase === 'initializing') {
+ *   // Show loading indicator
+ * } else if (corePhase === 'auth_flow') {
+ *   // The user is in the authentication flow (refer to the authPhase for more details)
+ * } else if (corePhase === 'wallet_flow') {
+ *   // The user is in the wallet flow (refer to the walletPhase for more details)
+ * } else if (corePhase === 'authenticated') {
+ *   // The user is fully logged in
+ * }
+ * ```
+ */
+export type CorePhase = 'setting_up' | 'waiting_for_external_wallet_providers' | 'logging_out' | 'auth_flow' | 'wallet_flow' | 'authenticated' | 'guest_mode' | 'error';
+export type CoreEvents = {
+    type: 'LOGOUT';
+} | {
+    type: 'RETRY_WALLET_FLOW';
+};
+type ChildEvents = {
+    type: 'AUTHENTICATED' | 'GUEST_MODE';
+};
+export type CoreActor = ActorRef<Snapshot<unknown>, ChildEvents>;
+export type CoreContext = {
+    isReady: boolean;
+    authMachineRef: ActorRefFrom<AuthMachine> | null;
+    walletMachineRef: ActorRefFrom<WalletMachine> | null;
+    error: Error | null;
+    setupRetryCount: number;
+    lastErrorSource: 'auth' | 'wallet' | null;
+};
+export interface CoreState {
+    phase: CorePhase;
+    isLoading: boolean;
+    error: Error | null;
+    isReady: boolean;
+    isNewUser: boolean;
+    authStatePhase: AuthPhase;
+    walletStatePhase: WalletPhase;
+    authStateInfo: AuthStateInfo;
+    authStateResult: AuthState | null;
+    newWalletsResult: {
+        walletIds: CurrentWalletIds;
+        recoverySecret: string | undefined;
+    } | null;
+    needsWallet: boolean;
+    externalWalletSignVerification?: BaseVerifyExternalWalletParams;
+    guestWallets: Wallet[] | null;
+}
+/**
+ * Contains all authentication state data needed by UI consumers.
+ * This is extracted from the internal authStateResult and provides
+ * a flat, consistent interface for rendering auth UIs.
+ */
+export type AuthStateInfo = {
+    /** User ID if available */
+    userId: string | null;
+    /** Whether the current device supports passkeys/WebAuthn */
+    isPasskeySupported: boolean;
+    /** Passkey hints for known device detection */
+    passkeyHints: BiometricLocationHint[] | null;
+    /** Whether the user has a passkey configured */
+    hasPasskey: boolean;
+    /** Whether the user has a password configured */
+    hasPassword: boolean;
+    /** Whether the user has a PIN configured */
+    hasPin: boolean;
+    /** Portal URL for passkey login/signup */
+    passkeyUrl: string | null;
+    /** Portal URL for authorizing from a known device with passkey */
+    passkeyKnownDeviceUrl: string | null;
+    /** Portal URL for password login/signup */
+    passwordUrl: string | null;
+    /** Portal URL for PIN login/signup */
+    pinUrl: string | null;
+    /** Verification URL for email/phone verification in SLO */
+    verificationUrl: string | null;
+    /** External wallet verification data when signature is needed */
+    externalWalletVerification: {
+        signatureVerificationMessage: string;
+        walletAddress: string;
+        walletType: string;
+    } | null;
+    /** Recovery secret after wallet creation */
+    recoverySecret: string | null;
+    /** Whether this is a new user (signup flow) */
+    isNewUser: boolean;
+};
+export type StateSnapshot = {
+    corePhase: CorePhase;
+    authPhase: AuthPhase;
+    walletPhase: WalletPhase;
+    authStateInfo: AuthStateInfo;
+    error: Error | null;
+    isReady: boolean;
+};
+export type ServerAuthStateResult = {
+    authState: ServerAuthState | null;
+    opts: WithCustomTheme & WithUseShortUrls & {
+        sessionLookupId?: string;
+        isFromExternalWallet?: boolean;
+    };
+} | null;
+export {};

package/dist/types/state/types/wallet.d.ts

@@ -0,0 +1,76 @@
+import type { CurrentWalletIds } from '@getpara/user-management-client';
+import type { createWalletStateMachine } from '../machines/walletStateMachine.js';
+import type { AuthState, Wallet } from '../../types/index.js';
+import type { PollingCallbacks } from '../../services/types/PollingServiceTypes.js';
+export type WalletMachine = ReturnType<typeof createWalletStateMachine>;
+/**
+ * Represents the current phase of the wallet flow.
+ *
+ * @example
+ * ```typescript
+ * // Check current wallet phase
+ * if (walletPhase === 'needs_wallets') {
+ *   // Call waitForWalletCreation to create wallets
+ * } else if (walletPhase === 'wallets_ready' || walletPhase === 'no_wallets_needed') {
+ *   // The user's wallets are ready (if applicable) and they are fully logged in
+ * }
+ * ```
+ */
+export type WalletPhase = 'uninitialized' | 'checking_wallet_state' | 'needs_wallets' | 'claiming_wallets' | 'creating_wallets' | 'connecting_para_connectors' | 'waiting_for_wallets' | 'setting_up_after_login' | 'no_wallets_needed' | 'wallets_ready' | 'guest_mode' | 'creating_guest_wallets' | 'error';
+export type WalletEvents = {
+    type: 'WAIT_FOR_WALLET_CREATION';
+    data?: {
+        pollingCallbacks?: PollingCallbacks;
+    };
+} | {
+    type: 'SET_NEEDS_WALLET';
+    data: {
+        needsWallet: boolean;
+    };
+} | {
+    type: 'SET_TEMPORARY_SHARES';
+    data: {
+        temporaryShares: any[];
+    };
+} | {
+    type: 'COMPLETE';
+} | {
+    type: 'CLAIM_WALLETS';
+} | {
+    type: 'ERROR';
+    error: string;
+};
+export interface WalletContext {
+    needsWallet: boolean;
+    newWalletsResult: {
+        walletIds: CurrentWalletIds;
+        recoverySecret: string | undefined;
+    } | null;
+    temporaryShares: any[] | null;
+    pollingCallbacks: PollingCallbacks | null;
+    error: Error | null;
+    authData: {
+        shouldAutoCreateWallets: boolean;
+        isNewUser: boolean;
+        authStateResult: AuthState | null;
+        skipSessionRefreshOnSetup: boolean;
+        isGuestMode?: boolean;
+    } | null;
+    guestWallets: Wallet[] | null;
+    retryAttempts: {
+        claiming?: number;
+        creating?: number;
+        connecting?: number;
+    };
+}
+export interface WalletMachineInput {
+    shouldAutoCreateWallets?: boolean;
+    isNewUser?: boolean;
+    authStateResult?: AuthState | null;
+    skipSessionRefreshOnSetup?: boolean;
+    isGuestMode?: boolean;
+    previousWalletsResult?: {
+        walletIds: CurrentWalletIds;
+        recoverySecret: string | undefined;
+    } | null;
+}

package/dist/types/types/authState.d.ts

@@ -0,0 +1,66 @@
+import type { AuthExtras, PrimaryAuthInfo, ServerAuthStateDone, ServerAuthStateLogin, ServerAuthStateSignup, ServerAuthStateVerify, TAuthMethod } from '@getpara/user-management-client';
+import type { WithCustomTheme, WithIsPasskeySupported, WithUseShortUrls } from './util';
+export type CoreAuthInfo = PrimaryAuthInfo & AuthExtras;
+export type AuthStateBaseParams = WithCustomTheme & WithUseShortUrls;
+export type AuthStateVerify = ServerAuthStateVerify & {
+    loginUrl?: string;
+};
+export type AuthStateLogin = Omit<ServerAuthStateLogin, 'loginAuthMethods'> & WithIsPasskeySupported & {
+    /**
+     * A Para Portal URL for logging in via a WebAuth passkey. For best compatibility, you should open this URL in a new window or tab.
+     */
+    passkeyUrl?: string;
+    /**
+     * A Para Portal URL for authorizing a new device using a WebAuth passkey located elsewhere, to be visited using that other device.
+     */
+    passkeyKnownDeviceUrl?: string;
+    /**
+     * A Para Portal URL for logging in via a password.
+     */
+    passwordUrl?: string;
+    /**
+     * A Para Portal URL for logging in via a PIN.
+     */
+    pinUrl?: string;
+    /**
+     * Supported login auth methods for this session.
+     */
+    loginAuthMethods?: TAuthMethod[];
+};
+export type AuthStateSignup = Omit<ServerAuthStateSignup, 'signupAuthMethods'> & WithIsPasskeySupported & {
+    /**
+     * A Para Portal URL for creating a new WebAuth passkey.
+     */
+    passkeyUrl?: string;
+    /**
+     * A Para Portal URL for creating a new user password.
+     */
+    passwordUrl?: string;
+    /**
+     * A Para Portal URL for creating a new user PIN.
+     */
+    pinUrl?: string;
+    /**
+     * The Para system ID for the newly generated passkey.
+     */
+    passkeyId?: string;
+    /**
+     * The Para system ID for the newly generated password.
+     */
+    passwordId?: string;
+    /**
+     * The Para system ID for the newly generated PIN.
+     */
+    pinId?: string;
+    /**
+     * Supported signup auth methods for this session.
+     */
+    signupAuthMethods?: TAuthMethod[];
+};
+export type AuthStateDone = Omit<ServerAuthStateDone, 'authMethods'> & {
+    authMethods: TAuthMethod[];
+};
+export type AuthStateVerifyOrLogin = AuthStateVerify | AuthStateLogin;
+export type AuthStateSignupOrLoginOrDone = AuthStateSignup | AuthStateLogin | AuthStateDone;
+export type OAuthResponse = AuthStateSignupOrLoginOrDone;
+export type AuthState = AuthStateVerify | AuthStateLogin | AuthStateSignup | AuthStateDone;

package/dist/types/types/config.d.ts

@@ -151,4 +151,9 @@ export interface ConstructorOpts {
     }) => Promise<{
         userShare?: string;
     }>;
+    /**
+     * If `true`, enables verbose logging for debugging purposes. This will output additional internal SDK operations to the console.
+     * @default false
+     */
+    enableDebugLogs?: boolean;
 }