@privy-io/react-auth 1.3.1-beta.3 → 1.4.0-beta.2

package/dist/index.d.ts

@@ -1,242 +1,155 @@
-import { AxiosResponse, AxiosRequestConfig } from 'axios';
 import React from 'react';
 import { Web3Provider } from '@ethersproject/providers';
 import { AbstractProvider } from 'web3-core';
 
 declare const SUPPORTED_WALLET_TYPES: readonly ["metamask", "coinbase_wallet", "wallet_connect"];
 declare type WalletType = typeof SUPPORTED_WALLET_TYPES[number];
+/** @ignore */
 interface LinkMetadata {
-    /** Link type, most commonly useful when filtering through linkedAccounts */
+    /** Account type, most commonly useful when filtering through linkedAccounts */
     type: 'wallet' | 'email' | 'google_oauth' | 'twitter_oauth' | 'discord_oauth';
-    /** Datetime when this email or wallet was associated to the user account. */
+    /** Datetime when this account was linked to the user. */
     verifiedAt: Date;
 }
+/**
+ * Object representation of a user's wallet.
+ */
 interface Wallet {
-    /** Address of the wallet */
+    /** The wallet address. */
     address: string;
-    /** Chain type of the wallet address */
+    /** Chain type of the wallet address. */
     chainType: 'ethereum' | 'solana';
-    /** Not yet implemented.
+    /**
+     * @experimental
+     * DO NOT USE: This feature is under active development.
      *
      * The chain ID of the active connected wallet, if used to verify in the current session.
      * Only present for the active wallet.
      *
      * e.g. testnet, mainnet, goerli */
     chainId?: string;
-    /** Not yet implemented.
+    /**
+     * @experimental
+     * DO NOT USE: This feature is under active development.
+     *
      * The wallet type of the active connected wallet, if used to verify in the current session.
      * Only present for the active wallet.
      */
     walletType?: WalletType;
 }
+/** Object representation of a user's email. */
 interface Email {
-    /** Email address */
+    /** The email address. */
     address: string;
 }
+/** Object representation of a user's Google account. */
 interface Google {
+    /** The `sub` claim from the Google-issued JWT for this account. */
     subject: string;
+    /** The email associated with the Google account. */
     email: string;
+    /** The name associated with the Google account. */
     name: string | null;
 }
+/** Object representation of a user's Twitter account. */
 interface Twitter {
+    /** The `sub` claim from the Twitter-issued JWT for this account. */
     subject: string;
+    /** The username associated with the Twitter account. */
     username: string | null;
+    /** The name associated with the Twitter account. */
     name: string | null;
 }
+/** Object representation of a user's Discord account. */
 interface Discord {
+    /** The `sub` claim from the Discord-issued JWT for this account. */
     subject: string;
+    /** The username associated with the Discord account.  */
     username: string | null;
+    /** The email associated with the Discord account. */
     email: string | null;
 }
+/** Object representation of a user's email, with additional metadata for advanced use cases. */
 interface EmailWithMetadata extends LinkMetadata, Email {
+    /** Denotes that this is an email account. */
     type: 'email';
 }
+/** Object representation of a user's wallet, with additional metadata for advanced use cases. */
 interface WalletWithMetadata extends LinkMetadata, Wallet {
+    /** Denotes that this is a wallet account. */
     type: 'wallet';
 }
+/** Object representation of a user's Google Account, with additional metadata for advanced use cases. */
 interface GoogleOAuthWithMetadata extends LinkMetadata, Google {
+    /** Denotes that this is a Google account. */
     type: 'google_oauth';
 }
+/** Object representation of a user's Twitter Account, with additional metadata for advanced use cases. */
 interface TwitterOAuthWithMetadata extends LinkMetadata, Twitter {
+    /** Denotes that this is a Twitter account. */
     type: 'twitter_oauth';
 }
+/** Object representation of a user's Discord Account, with additional metadata for advanced use cases. */
 interface DiscordOAuthWithMetadata extends LinkMetadata, Discord {
+    /** Denotes that this is a Discord account. */
     type: 'discord_oauth';
 }
 interface User {
-    /** The Privy DID for the user. If you need to store or link additional information
-     * about a user, you can use this DID to reference the user identity. */
+    /** The Privy-issued DID for the user. If you need to store additional information
+     * about a user, you can use this DID to reference them. */
     id: string;
-    /** When the user was created */
+    /** The datetime of when the user was created. */
     createdAt: Date;
-    /** The email associated with this user. It cannot be associated with another account. */
+    /** The user's email address, if they have linked one. It cannot be linked to another user. */
     email?: Email;
-    /** The wallet associated with this user. It cannot be associated with another account. */
+    /** The user's wallet address, if they have linked one. It cannot be linked to another user. */
     wallet?: Wallet;
-    /** The google oauth account associated with this user */
+    /** The user's Google account, if they have linked one. It cannot be linked to another user. */
     google?: Google;
-    /** The twitter oauth account associated with this user */
+    /** The user's Twitter account, if they have linked one. It cannot be linked to another user. */
     twitter?: Twitter;
-    /** The discord oauth account associated with this user */
+    /** The user's Discord account, if they have linked one. It cannot be linked to another user. */
     discord?: Discord;
-    /** The list of accounts associated with this user. Accounts contain additional metadata
-     * about the account and its linking that may be necessary for advanced use cases. */
+    /** The list of accounts associated with this user. Each account contains additional metadata
+     * that may be helpful for advanced use cases. */
     linkedAccounts: Array<WalletWithMetadata | EmailWithMetadata | GoogleOAuthWithMetadata | TwitterOAuthWithMetadata | DiscordOAuthWithMetadata>;
 }
-interface AppSettings {
-    id?: string;
-    name?: string;
-    verificationKey?: string;
-    logoUrl?: string;
-    theme?: 'System' | 'Light' | 'Dark' | string;
-    accentColor?: string;
-    createdAt?: Date;
-    updatedAt?: Date;
-}
-
-interface DefaultsType {
-    baseURL: string;
-    timeout: number;
-}
-/**
- * A raw http handler for making requests to the Privy API. It requires a Session
- * object, which is used for fetching and including any tokens that are required
- * for requests.
- */
-declare class Http {
-    private appId;
-    private session;
-    private defaults;
-    constructor(appId: string, session: Session, defaults: DefaultsType);
-    get<T = any, R = AxiosResponse<T>, D = any>(path: string, config?: AxiosRequestConfig<D>): Promise<R>;
-    post<T = any, R = AxiosResponse<T>, D = any>(path: string, data?: D, config?: AxiosRequestConfig<D>): Promise<R>;
-    delete<T = any, R = AxiosResponse<T>, D = any>(path: string, config?: AxiosRequestConfig<D>): Promise<R>;
-    private buildConfig;
-}
-
-interface ResponseEmailAccount {
-    type: 'email';
-    address: string;
-    verified_at: number;
-}
-interface ResponseEthereumAccount {
-    type: 'wallet';
-    address: string;
-    chain_type: 'ethereum';
-    verified_at: number;
-}
-interface ResponseOAuthGoogle {
-    type: 'google_oauth';
-    subject: string;
-    email: string;
-    name: string | null;
-    verified_at: number;
-}
-interface ResponseOAuthTwitter {
-    type: 'twitter_oauth';
-    subject: string;
-    username: string | null;
-    name: string | null;
-    verified_at: number;
-}
-interface ResponseOAuthDiscord {
-    type: 'discord_oauth';
-    subject: string;
-    username: string | null;
-    email: string | null;
-    verified_at: number;
-}
-declare type LinkedAccountsType = Array<ResponseEmailAccount | ResponseEthereumAccount | ResponseOAuthGoogle | ResponseOAuthTwitter | ResponseOAuthDiscord>;
-interface GetCurrentUserResponse {
-    id: string;
-    created_at: number;
-    linked_accounts: LinkedAccountsType;
-}
 
 /**
- * Valid /session and <>/authenticate calls will respond with a token
- * as well as a valid user object for streamlining.
+ * Properties to initialize the {@link PrivyProvider}.
  */
-interface ValidSessionResponse {
-    user: GetCurrentUserResponse;
-    token: string;
-    refresh_token: string | null;
-}
-/**
- * `Session` represents the session lifecycle of the login. It manages token
- * storage, refresh, and deletion.
- */
-declare class Session {
-    private destroyOnce;
-    private refreshOnce;
-    private authenticateOnce;
-    api?: Http;
-    constructor();
-    get token(): string | null;
-    get refreshToken(): string | null;
+interface PrivyProviderProps {
+    /** Your Privy App ID, which can be retrieved from the Privy console. */
+    appId: string;
     /**
-     * Checks to see if locally we have refresh credentials. Refresh
-     * credentials consist of:
-     *
-     *     1. Access token
-     *     2. Refresh token
-     *
-     * @returns true if we have what appear to be valid credentials, false otherwise.
+     * @experimental DO NOT USE: This feature is under active development.
      */
-    hasRefreshCredentials(): boolean;
+    showSocials?: boolean;
     /**
-     * Checks if the session contains a valid token that is not
-     * expired or expiring soon.
+     * An optional callback that will execute once a `login` call successfully completes.
      *
-     * @returns true if token is valid and considered active, false otherwise.
+     * You may access the `user` object corresponding to the authenticated user within this callback.
      */
-    hasActiveToken(): boolean;
-    /**
-     * Authenticate the session.
-     * @returns Promise<User>
-     */
-    authenticate(authFlow: AuthFlow): Promise<User | null>;
-    /**
-     * Renews the auth token using the refresh token.
-     * @return Promise<User> if successful with a logged-in user, Promise<null> otherwise.
-     */
-    refresh(): Promise<User | null>;
-    /**
-     * Destroy the session.
-     */
-    destroy(): Promise<void>;
-    private _authenticate;
-    private _refresh;
-    private _destroy;
-    private destroyLocalState;
-    private storeToken;
-    private storeRefreshToken;
+    onSuccess?: (user: User) => void;
+    /** @ignore */
+    children: React.ReactNode;
 }
-
-declare type AuthMeta = {
-    [key: string]: any;
-};
 /**
- * An auth flow is an encapsulation of the business logic required for a given
- * authentication process. It requires at least one definitive `authenticate`
- * method that does the final token handshaking with the API, but may also
- * include any number of methods/API calls necessary to set up the state (e.g.
- * sending an email before being able to do a passwordless code login)
+ * Passes the Privy authentication context to your React components.
+ *
+ * This should wrap any components that will to use the Privy SDK via the {@link usePrivy} hook. As an example:
+ *
+ * ```typescript
+ * // At your application root (e.g. `_app.tsx` in NextJS):
+ * import {PrivyProvider} from '@privy-io/react-auth';
+ *
+ * <PrivyProvider appId="APP_ID_FROM_CONSOLE" onSuccess={() => console.log('Success!')}>
+ *   <Component {...pageProps} />
+ * </PrivyProvider>
+ * ```
+ *
  */
-interface AuthFlow {
-    api?: Http;
-    /**
-     * Any meta information necessary for the auth flow, that may also need to be
-     * shared out to things like frontend components for displaying state of the
-     * auth flow
-     */
-    meta: AuthMeta;
-    /**
-     * Should handle the actual authentication step. An preconditions must be
-     * addressed prior to calling
-     */
-    authenticate(): Promise<ValidSessionResponse>;
-}
+declare const PrivyProvider: (props: PrivyProviderProps) => JSX.Element;
 
 declare global {
     interface Window {
@@ -252,127 +165,22 @@ interface EIP1193Provider {
     removeListener: (eventName: string | symbol, listener: (...args: any[]) => void) => any;
 }
 
-declare class PrivyConnector {
-    private ethProvider;
-    walletType: WalletType | null;
-    constructor();
-    getEthereumProvider: () => EIP1193Provider;
-    initialize(): void;
-    destroy(): void;
-    /**
-     * Connects to the wallet.
-     *
-     * @param showPrompt if true, prompts the user for a connection when no connection can be automatically re-established.
-     * @param walletType? the wallet type to connect to. If not provided, defaults to the walletType that the connector was initialized with.
-     * @returns {string | null} EIP-55 mixed-case checksum-encoded address of connected wallet or null if user does not connect.
-     */
-    connect(options: {
-        showPrompt: boolean;
-    }): Promise<string | null>;
-    private isConnected;
-    private promptConnection;
-    /**
-     * The currently connected EIP-155 chain id. E.g., `1` for Ethereum mainnet.
-     *
-     * @returns {string} The EIP-155 chain id.
-     */
-    chainId(): Promise<string>;
-    /**
-     * The currently connected address.
-     *
-     * @returns {string | null} EIP-55 mixed-case checksum-encoded address or null if not connected.
-     */
-    address(): Promise<string | null>;
-}
-
-declare class PrivyClient {
-    private api;
-    private appId;
-    private session;
-    authFlow?: AuthFlow;
-    connector: PrivyConnector;
-    /**
-     * Creates a new Privy client.
-     * @param options Initialization options.
-     */
-    constructor(options: {
-        /**
-         * The URL of the Privy API. Defaults to `https://api.privy.io/v0`.
-         */
-        apiURL?: string;
-        /**
-         * The app id from your console
-         */
-        appId: string;
-        /**
-         * Time in milliseconds after which to timeout requests to the API and KMS. Defaults to `10000` (10 seconds).
-         */
-        timeout?: number;
-    });
-    authenticate(): Promise<User | null>;
-    logout(): Promise<void>;
-    startAuthFlow(authFlow: AuthFlow): void;
-    /** DATA METHODS */
-    /**
-     * Fetches the currently authenticed user from the API or
-     * returns null if the user is not authenticated.
-     *
-     * This will refresh the user's access token and rotate
-     * the refresh token if needed.
-     *
-     * @returns Promise<User | null>
-     */
-    getAuthenticatedUser(): Promise<User | null>;
-    /**
-     * Grab the Privy access token for the currently logged in user.
-     *
-     * If the token is expired or expiring soon, this will attempt to
-     * first refresh the access token to ensure that the token is active.
-     *
-     * @returns Promise<string | null>
-     */
-    getAccessToken(): Promise<string | null>;
-    getAppSettings(): Promise<AppSettings>;
-}
-
-interface PrivyProviderProps {
-    /** Your app id, taken from the Privy console. */
-    appId: string;
-    /**
-     * onSuccess is run when an auth (`login`) or linking (`linkEmail` or `linkWallet`)
-     * action is completed successfully.
-     */
-    showSocials?: boolean;
-    onSuccess?: (user: User) => void;
-    children: React.ReactNode;
-}
 /**
- * The Privy React context provider.
- *
- * ```typescript
- * // At your application root:
- * import {PrivyProvider} from '@privy-io/react-auth';
- *
- * <PrivyProvider appId="APP_ID_FROM_CONSOLE" onSuccess={() => console.log('Success!')}>
- *   <Component {...pageProps} />
- * </PrivyProvider>
- * ```
+ * Allows you to manage the user's current authentication state and access their linked accounts.
+ * You can access the fields and methods documented here via the {@link usePrivy} hook.
  */
-declare const PrivyProvider: (props: PrivyProviderProps) => JSX.Element;
-
 interface PrivyInterface {
     /**
-     * Check whether the PrivyProvider is ready to be used. We recommend you wait for this to
-     * be true before checking values such as authenticated and user.
+     * Check whether the `PrivyProvider` is ready to be used. You should wait for this to
+     * be true before using values such as `authenticated` and `user`.
      */
     ready: boolean;
     /**
-     * True if the user is authenticated, false if they are not. In the event that the
-     * client is offline, this will be set to true if the user has a valid token,
-     * but we are unable to fetch the user object.
+     * True if the user is authenticated, false otherwise.
+     *
+     * You should always check that `ready` is true before using this value. Otherwise,
+     * the value may outdated while the Privy client fetches fresh tokens.
      *
-     * Note: this value should be checked in conjunction with `ready` - otherwise
-     * the value may incorrectly show authentication state while proper setup is completed.
      */
     authenticated: boolean;
     /**
@@ -380,76 +188,53 @@ interface PrivyInterface {
      */
     user: User | null;
     /**
-     * Opens the Privy login modal and starts a login flow
+     * Opens the Privy login modal and prompts the user to login.
      */
     login: () => void;
     /**
-     * Opens the Privy modal and starts a flow to link an email to an already existing account.
+     * For users who are authenticated, opens the Privy modal and prompts the user to link an email.
      */
     linkEmail: () => void;
     /**
-     * Opens the Privy modal and starts a flow to link a wallet to an already existing account.
+     * For users who are authenticated, opens the Privy modal and prompts the user to link a wallet.
      */
     linkWallet: () => void;
     /**
-     * Log the current user out. This clears the user state. You can await this call to take an
-     * action once the log out is complete - for example, redirecting to a specific page.
+     * Log the current user out and clears their authentication state. `authenticated` will become false, `user` will become null, and the Privy Auth tokens will be deleted from the browser's local storage.
+     *
+     * You may await this call to take an action once logout is complete (e.g. redirecting to a specific page).
      */
     logout: () => Promise<void>;
     /**
-     * Get the Privy access token. This will automatically attempt to refresh the
-     * session if the token is expired or about to expire. You can use this to validate
-     * the user is properly authenticated on your backend with the verification key issued
-     * to your Privy app.
+     * Get the Privy access token ([JWT](https://jwt.io/)) for an authenticated user. Returns null for an unauthenticated user.
+     *
+     * You may use this token to authorize requests sent from your frontend, and can validate it in your backend against your app's Privy verification key.
+     *
+     * This will automatically attempt to refresh the session if the token is expired or about to expire.
      */
     getAccessToken: () => Promise<string | null>;
-    getEthereumProvider: () => EIP1193Provider;
-    getEthersProvider: () => Web3Provider;
-    getWeb3jsProvider: () => AbstractProvider;
-}
-declare const usePrivy: () => PrivyInterface;
-
-declare abstract class PrivyError extends Error {
     /**
-     * Privy error type.
-     */
-    abstract type: string;
-    /**
-     * Original Error object, it the error originated client-side.
+     * Get an [EIP-1193](https://eips.ethereum.org/EIPS/eip-1193)-compatible provider from the user's wallet, if the user has connected one.
+     *
+     * You may then use the Ethereum Javascript API syntax to send JSON-RPC requests to the user's wallet.
      */
-    cause?: Error;
+    getEthereumProvider: () => EIP1193Provider;
     /**
-     * @param type Privy error type.
-     * @param message Human-readable message.
-     * @param cause Source of this error.
+     *
+     * Get an [ethers.js](https://docs.ethers.io/v5/)-compatible provider from the user's wallet, if the user has connected one.
+     *
      */
-    protected constructor(message: string, cause?: unknown);
-    toString(): string;
-}
-/**
- * Issues with the Privy api.
- */
-declare class PrivyApiError extends PrivyError {
-    type: string;
+    getEthersProvider: () => Web3Provider;
     /**
-     * HTTP status code, or `null` if no response was received.
+     * Get a [web3.js](https://web3js.readthedocs.io/en/v1.8.0/)-compatible provider from the user's wallet, if the user has connected one.
      */
-    status: number | null;
-    constructor(type: string, status: number | null, message: string, cause?: unknown);
-}
-/**
- * Issues with the Privy client.
- */
-declare class PrivyClientError extends PrivyError {
-    type: string;
-    constructor(message: string, cause?: unknown);
+    getWeb3jsProvider: () => AbstractProvider;
 }
 /**
- * The Session instance threw an exception.
+ * [React Hook](https://reactjs.org/docs/hooks-intro.html) that allows you to manage the user's current authentication state and access their linked accounts.
+ *
+ * You should use this hook to access the Privy SDK from within your React components and custom hooks.
  */
-declare class PrivySessionError extends PrivyError {
-    type: string;
-    constructor(message: string, cause?: unknown);
-}
+declare const usePrivy: () => PrivyInterface;
 
-export { Discord, DiscordOAuthWithMetadata, Email, EmailWithMetadata, Google, GoogleOAuthWithMetadata, PrivyApiError, PrivyClient, PrivyClientError, PrivyError, PrivyProvider, PrivySessionError, Twitter, TwitterOAuthWithMetadata, User, Wallet, WalletWithMetadata, usePrivy };
+export { Discord, DiscordOAuthWithMetadata, Email, EmailWithMetadata, Google, GoogleOAuthWithMetadata, PrivyInterface, PrivyProvider, PrivyProviderProps, Twitter, TwitterOAuthWithMetadata, User, Wallet, WalletWithMetadata, usePrivy };