@stytch/react 0.0.3-0 → 0.3.0

package/README.md

@@ -9,7 +9,7 @@ With `npm`
 
 ## Documentation
 
-For full documentation please refer to Stytch's javascript SDK documentation on https://stytch.com/docs/sdks.
+For full documentation please refer to Stytch's javascript SDK documentation at https://stytch.com/docs/sdks.
 
 ## Example Usage
 
@@ -54,7 +54,11 @@ const App = () => {
 
   return (
     <div id="login">
-      <Stytch config={stytchProps.loginOrSignupView} styles={stytchProps.style} callbacks={stytchProps.callbacks} />
+      <StytchLogin
+        config={stytchProps.loginOrSignupView}
+        styles={stytchProps.style}
+        callbacks={stytchProps.callbacks}
+      />
     </div>
   );
 };
@@ -63,3 +67,90 @@ const App = () => {
 ## Typescript Support
 
 There are built in typescript definitions in the npm package.
+
+## Migrating from @stytch/stytch-react
+
+If you are migrating from [@stytch/stytch-react](https://www.npmjs.com/package/@stytch/stytch-react), follow the steps below:
+
+### Step 1: Install the new libraries
+
+- The core SDK is now bundled in its own module - [@stytch/vanilla-js](https://www.npmjs.com/package/@stytch/vanilla-js)
+- We now have a library specifically for React bindings - [@stytch/react](https://www.npmjs.com/package/@stytch/react)
+
+```shell
+# NPM
+npm install @stytch/vanilla-js @stytch/react
+# Yarn
+yarn add @stytch/vanilla-js @stytch/react
+```
+
+### Step 2: Remove the old SDK
+
+- Remove the `@styth/stytch-react` package
+- If you are explicitly loading the `stytch.js` script in the document header, remove it. It isn't needed anymore.
+
+```shell
+# NPM
+npm rm @stytch/stytch-react
+# Yarn
+yarn remove @stytch/stytch-react
+```
+
+### Step 3: Initialize the client in your Application Root
+
+- Determine if you need the Headless or UI client. If you plan to use the `<StytchLogin />` component in your application then you should use the the UI client. Otherwise use the Headless client to minimize application bundle size.
+- To create the Stytch Headless client, use `StytchHeadlessClient` from `@stytch/vanilla-js/headless`
+- To create the Stytch UI client, use `StytchUIClient` from `@stytch/vanilla-js`
+- Pass it into `<StytchProvider />` component from `@stytch/react`
+
+```jsx
+import React from 'react';
+import { StytchProvider } from '@stytch/react';
+import { StytchHeadlessClient } from '@stytch/vanilla-js/headless';
+// Or alternately
+// import { StytchUIClient } from '@stytch/vanilla-js';
+
+const stytch = new StytchHeadlessClient(process.env.REACT_APP_STYTCH_PUBLIC_TOKEN);
+
+function WrappedApp() {
+  return (
+    <StytchProvider stytch={stytch}>
+      <App />
+    </StytchProvider>
+  );
+}
+
+export default WrappedApp;
+```
+
+### Step 4: Update calls to `useStytchUser` , `useStytchSession`, and `useStytchLazy`
+
+- `useStytchUser` and `useStytchSession` hooks now return envelope objects - `{ user, isCached }` and `{ session, isCached }` respectively.
+  - On first render the SDK will read user/session out of persistent storage, and serve them with `isCached: true` - at this point you’re reading the stale-while-revalidating value
+  - The SDK will make network requests to pull the most up-to-date user and session objects, and serve them with `isCached: false`
+- `useStytchLazy` is no longer required - you may always call `useStytch` now
+
+```jsx
+import React, { useEffect } from 'react';
+import { useStytchUser } from '@stytch/react';
+
+export default function Profile() {
+  const router = useRouter();
+  const { user, isCached } = useStytchUser();
+
+  return (
+    <Layout>
+      <h1>Your {isCached ? 'Cached' : null} Profile</h1>
+      <pre>{JSON.stringify(user, null, 2)}</pre>
+    </Layout>
+  );
+}
+```
+
+### Step 5: UI Naming Changes
+
+We've made a number of small changes to our naming conventions to make the API cleaner and easier to understand.
+
+- The `<Stytch />` login component is now called `<StytchLogin />`
+- The `OAuthProvidersTypes` enum is now called `OAuthProviders`
+- The `SDKProductTypes` enum is now called `Products`

package/dist/index.d.ts

@@ -1,35 +1,208 @@
 /// <reference types="react" />
-import { Callbacks, Config, StyleConfig, User, Session, StytchUIClient } from "@stytch/vanilla-js";
+// We need to import the StytchUIClient type to give the TSDoc parser a hint as to where it is from
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+import { Callbacks, StytchLoginConfig, StyleConfig, User, Session, StytchUIClient } from "@stytch/vanilla-js";
 import React from "react";
 import { ReactNode } from "react";
 import { StytchHeadlessClient } from "@stytch/vanilla-js/headless";
+interface StytchProps {
+    /**
+     * A {@link StytchLoginConfig} object. Add products and product-specific config to this object to change the login methods shown.
+     *
+     * @example
+     * {
+     *   products: ['crypto', 'otps']
+     * }
+     *
+     * @example
+     * {
+     *   products: ['emailMagicLinks'>]
+     *   emailMagicLinksOptions: {
+     *     loginRedirectURL: 'https://example.com/authenticate',
+     *     signupRedirectURL: 'https://example.com/authenticate',
+     *   }
+     * }
+     *
+     * @example
+     * {
+     *   products: ['oauth'>]
+     *   oauthOptions: {
+     *   providers: [
+     *       { type: 'google', one_tap: true, position: 'embedded' },
+     *       { type: 'microsoft' },
+     *       { type: 'apple' },
+     *       { type: 'facebook' },
+     *     ],
+     *   }
+     * }
+     */
+    config: StytchLoginConfig;
+    /**
+     * An optional {@link StyleConfig} to customize the look and feel of the screen.
+     *
+     * @example
+     * {
+     *    fontFamily: 'Arial, Helvetica, sans-serif',
+     *    width: '360px',
+     *    primaryColor: '#19303D',
+     * }
+     */
+    styles?: StyleConfig;
+    /**
+     * An optional {@link Callbacks} object.
+     *
+     * @example
+     * {
+     *   onError: ({message}) => {
+     *      console.error('Stytch login screen error', message)
+     *   }
+     * }
+     *
+     * @example
+     * {
+     *   onEvent: ({type, data}) => {
+     *     if(type === StytchEventType.CryptoWalletAuthenticate) {
+     *       console.log('Logged in with crypto wallet', data);
+     *     }
+     *   }
+     * }
+     */
+    callbacks?: Callbacks;
+}
 /**
- * Stytch JS React Component
+ * The Stytch Login Screen component.
+ * This component can only be used with a {@link StytchUIClient} client constructor
+ * passed into the {@link StytchProvider}
  *
- * [Documentation](https://stytch.com/docs/javascript-sdk)
+ * See the {@link https://stytch.com/docs/sdks/javascript-sdk online reference}
+ * and {@link https://storybook.stytch.com interactive examples} for more.
+ *
+ * @example
+ * <StytchLogin
+ *   config={{
+ *     products: ['emailMagicLinks', 'oauth'],
+ *     emailMagicLinksOptions: {
+ *       loginRedirectURL: 'https://example.com/authenticate',
+ *       signupRedirectURL: 'https://example.com/authenticate',
+ *     },
+ *     oauthOptions: {
+ *      providers: [{ type: OAuthProviders.Google }, { type: OAuthProviders.Microsoft }],
+ *    },
+ *   }}
+ *   styles={{
+ *     fontFamily: '"Helvetica New", Helvetica, sans-serif',
+ *     primaryColor: '#0577CA',
+ *     width: '321px',
+ *   }}
+ *   callbacks={{
+ *     onEvent: (event) => console.log(event)
+ *   }}
+ * />
+ * @param props {@link StytchProps}
+ */
+declare const StytchLogin: ({ config, styles, callbacks }: StytchProps) => JSX.Element;
+interface StytchResetPasswordProps extends StytchProps {
+    passwordResetToken: string;
+}
+/**
+ * The Stytch Reset Password component.
+ * This component can only be used with a {@link StytchUIClient} client constructor
+ * passed into the {@link StytchProvider}
+ *
+ * See the {@link https://stytch.com/docs/sdks/javascript-sdk online reference}
+ * and {@link https://storybook.stytch.com interactive examples} for more.
+ *
+ * @example
+ * TODO
+ */
+declare const StytchPasswordReset: ({ config, styles, callbacks, passwordResetToken }: StytchResetPasswordProps) => JSX.Element;
+/**
+ * The Stytch Client object passed in to <StytchProvider /> in your application root.
+ * Either a StytchUIClient or StytchHeadlessClient.
  */
-declare const Stytch: ({ config, styles, callbacks }: {
-    config: Config;
-    styles: StyleConfig;
-    callbacks?: Callbacks | undefined;
-}) => JSX.Element | null;
 type StytchClient = StytchUIClient | StytchHeadlessClient;
-declare const useStytchUser: () => User | null;
-declare const useStytchSession: () => Session | null;
+type SWRUser = {
+    /**
+     * Either the active {@link User} object, or null if the user is not logged in.
+     */
+    user: User | null;
+    /**
+     * If true, indicates that the value returned is from the application cache and a state refresh is in progress.
+     */
+    fromCache: boolean;
+};
+type SWRSession = {
+    /**
+     * Either the active {@link Session} object, or null if the user is not logged in.
+     */
+    session: Session | null;
+    /**
+     * If true, indicates that the value returned is from the application cache and a state refresh is in progress.
+     */
+    fromCache: boolean;
+};
+/**
+ * Returns the active User.
+ * Check the fromCache property to determine if the user data is from persistent storage.
+ * @example
+ * const {user} = useStytchUser();
+ * return (<h1>Welcome, {user.name.first_name}</h1>);
+ * @returns A {@link SWRUser}
+ */
+declare const useStytchUser: () => SWRUser;
+/**
+ * Returns the active user's Stytch session.
+ * @example
+ * const {session} = useStytchSession();
+ * useEffect(() => {
+ *   if (!session) {
+ *     router.replace('/login')
+ *   }
+ * }, [session]);
+ * @returns A {@link SWRSession}
+ */
+declare const useStytchSession: () => SWRSession;
+/**
+ * Returns the Stytch client stored in the Stytch context.
+ *
+ * @example
+ * const stytch = useStytch();
+ * useEffect(() => {
+ *   stytch.magicLinks.authenticate('...')
+ * }, [stytch]);
+ */
 declare const useStytch: () => StytchClient;
 declare const withStytch: <T extends object>(Component: React.ComponentType<T & {
     stytch: StytchClient;
 }>) => React.ComponentType<T>;
 declare const withStytchUser: <T extends object>(Component: React.ComponentType<T & {
     stytchUser: User | null;
+    stytchUserIsFromCache: boolean;
 }>) => React.ComponentType<T>;
 declare const withStytchSession: <T extends object>(Component: React.ComponentType<T & {
     stytchSession: Session | null;
+    stytchSessionIsFromCache: boolean;
 }>) => React.ComponentType<T>;
 type StytchProviderProps = {
+    /**
+     * A Stytch client instance, either a {@link StytchUIClient} or {@link StytchHeadlessClient}
+     */
     stytch: StytchClient;
     children?: ReactNode;
 };
+/**
+ * The Stytch Context Provider.
+ * Wrap your application with this component in the root file in order to use Stytch everywhere in your app.
+ * @example
+ * const stytch = new StytchHeadlessClient('public-token-<find yours in the stytch dashboard>')
+ *
+ * ReactDOM.render(
+ *   <StytchProvider stytch={stytch}>
+ *     <App />
+ *   </StytchProvider>,
+ *   document.getElementById('root'),
+ * )
+ */
 declare const StytchProvider: ({ stytch, children }: StytchProviderProps) => JSX.Element;
-export { Stytch, StytchProvider, useStytch, useStytchSession, useStytchUser, withStytch, withStytchSession, withStytchUser };
+export { StytchLogin, StytchPasswordReset, StytchProvider, useStytch, useStytchSession, useStytchUser, withStytch, withStytchSession, withStytchUser };
 export type { StytchProviderProps };

package/dist/index.esm.d.ts

@@ -1,35 +1,208 @@
 /// <reference types="react" />
-import { Callbacks, Config, StyleConfig, User, Session, StytchUIClient } from "@stytch/vanilla-js";
+// We need to import the StytchUIClient type to give the TSDoc parser a hint as to where it is from
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+import { Callbacks, StytchLoginConfig, StyleConfig, User, Session, StytchUIClient } from "@stytch/vanilla-js";
 import React from "react";
 import { ReactNode } from "react";
 import { StytchHeadlessClient } from "@stytch/vanilla-js/headless";
+interface StytchProps {
+    /**
+     * A {@link StytchLoginConfig} object. Add products and product-specific config to this object to change the login methods shown.
+     *
+     * @example
+     * {
+     *   products: ['crypto', 'otps']
+     * }
+     *
+     * @example
+     * {
+     *   products: ['emailMagicLinks'>]
+     *   emailMagicLinksOptions: {
+     *     loginRedirectURL: 'https://example.com/authenticate',
+     *     signupRedirectURL: 'https://example.com/authenticate',
+     *   }
+     * }
+     *
+     * @example
+     * {
+     *   products: ['oauth'>]
+     *   oauthOptions: {
+     *   providers: [
+     *       { type: 'google', one_tap: true, position: 'embedded' },
+     *       { type: 'microsoft' },
+     *       { type: 'apple' },
+     *       { type: 'facebook' },
+     *     ],
+     *   }
+     * }
+     */
+    config: StytchLoginConfig;
+    /**
+     * An optional {@link StyleConfig} to customize the look and feel of the screen.
+     *
+     * @example
+     * {
+     *    fontFamily: 'Arial, Helvetica, sans-serif',
+     *    width: '360px',
+     *    primaryColor: '#19303D',
+     * }
+     */
+    styles?: StyleConfig;
+    /**
+     * An optional {@link Callbacks} object.
+     *
+     * @example
+     * {
+     *   onError: ({message}) => {
+     *      console.error('Stytch login screen error', message)
+     *   }
+     * }
+     *
+     * @example
+     * {
+     *   onEvent: ({type, data}) => {
+     *     if(type === StytchEventType.CryptoWalletAuthenticate) {
+     *       console.log('Logged in with crypto wallet', data);
+     *     }
+     *   }
+     * }
+     */
+    callbacks?: Callbacks;
+}
 /**
- * Stytch JS React Component
+ * The Stytch Login Screen component.
+ * This component can only be used with a {@link StytchUIClient} client constructor
+ * passed into the {@link StytchProvider}
  *
- * [Documentation](https://stytch.com/docs/javascript-sdk)
+ * See the {@link https://stytch.com/docs/sdks/javascript-sdk online reference}
+ * and {@link https://storybook.stytch.com interactive examples} for more.
+ *
+ * @example
+ * <StytchLogin
+ *   config={{
+ *     products: ['emailMagicLinks', 'oauth'],
+ *     emailMagicLinksOptions: {
+ *       loginRedirectURL: 'https://example.com/authenticate',
+ *       signupRedirectURL: 'https://example.com/authenticate',
+ *     },
+ *     oauthOptions: {
+ *      providers: [{ type: OAuthProviders.Google }, { type: OAuthProviders.Microsoft }],
+ *    },
+ *   }}
+ *   styles={{
+ *     fontFamily: '"Helvetica New", Helvetica, sans-serif',
+ *     primaryColor: '#0577CA',
+ *     width: '321px',
+ *   }}
+ *   callbacks={{
+ *     onEvent: (event) => console.log(event)
+ *   }}
+ * />
+ * @param props {@link StytchProps}
+ */
+declare const StytchLogin: ({ config, styles, callbacks }: StytchProps) => JSX.Element;
+interface StytchResetPasswordProps extends StytchProps {
+    passwordResetToken: string;
+}
+/**
+ * The Stytch Reset Password component.
+ * This component can only be used with a {@link StytchUIClient} client constructor
+ * passed into the {@link StytchProvider}
+ *
+ * See the {@link https://stytch.com/docs/sdks/javascript-sdk online reference}
+ * and {@link https://storybook.stytch.com interactive examples} for more.
+ *
+ * @example
+ * TODO
+ */
+declare const StytchPasswordReset: ({ config, styles, callbacks, passwordResetToken }: StytchResetPasswordProps) => JSX.Element;
+/**
+ * The Stytch Client object passed in to <StytchProvider /> in your application root.
+ * Either a StytchUIClient or StytchHeadlessClient.
  */
-declare const Stytch: ({ config, styles, callbacks }: {
-    config: Config;
-    styles: StyleConfig;
-    callbacks?: Callbacks | undefined;
-}) => JSX.Element | null;
 type StytchClient = StytchUIClient | StytchHeadlessClient;
-declare const useStytchUser: () => User | null;
-declare const useStytchSession: () => Session | null;
+type SWRUser = {
+    /**
+     * Either the active {@link User} object, or null if the user is not logged in.
+     */
+    user: User | null;
+    /**
+     * If true, indicates that the value returned is from the application cache and a state refresh is in progress.
+     */
+    fromCache: boolean;
+};
+type SWRSession = {
+    /**
+     * Either the active {@link Session} object, or null if the user is not logged in.
+     */
+    session: Session | null;
+    /**
+     * If true, indicates that the value returned is from the application cache and a state refresh is in progress.
+     */
+    fromCache: boolean;
+};
+/**
+ * Returns the active User.
+ * Check the fromCache property to determine if the user data is from persistent storage.
+ * @example
+ * const {user} = useStytchUser();
+ * return (<h1>Welcome, {user.name.first_name}</h1>);
+ * @returns A {@link SWRUser}
+ */
+declare const useStytchUser: () => SWRUser;
+/**
+ * Returns the active user's Stytch session.
+ * @example
+ * const {session} = useStytchSession();
+ * useEffect(() => {
+ *   if (!session) {
+ *     router.replace('/login')
+ *   }
+ * }, [session]);
+ * @returns A {@link SWRSession}
+ */
+declare const useStytchSession: () => SWRSession;
+/**
+ * Returns the Stytch client stored in the Stytch context.
+ *
+ * @example
+ * const stytch = useStytch();
+ * useEffect(() => {
+ *   stytch.magicLinks.authenticate('...')
+ * }, [stytch]);
+ */
 declare const useStytch: () => StytchClient;
 declare const withStytch: <T extends object>(Component: React.ComponentType<T & {
     stytch: StytchClient;
 }>) => React.ComponentType<T>;
 declare const withStytchUser: <T extends object>(Component: React.ComponentType<T & {
     stytchUser: User | null;
+    stytchUserIsFromCache: boolean;
 }>) => React.ComponentType<T>;
 declare const withStytchSession: <T extends object>(Component: React.ComponentType<T & {
     stytchSession: Session | null;
+    stytchSessionIsFromCache: boolean;
 }>) => React.ComponentType<T>;
 type StytchProviderProps = {
+    /**
+     * A Stytch client instance, either a {@link StytchUIClient} or {@link StytchHeadlessClient}
+     */
     stytch: StytchClient;
     children?: ReactNode;
 };
+/**
+ * The Stytch Context Provider.
+ * Wrap your application with this component in the root file in order to use Stytch everywhere in your app.
+ * @example
+ * const stytch = new StytchHeadlessClient('public-token-<find yours in the stytch dashboard>')
+ *
+ * ReactDOM.render(
+ *   <StytchProvider stytch={stytch}>
+ *     <App />
+ *   </StytchProvider>,
+ *   document.getElementById('root'),
+ * )
+ */
 declare const StytchProvider: ({ stytch, children }: StytchProviderProps) => JSX.Element;
-export { Stytch, StytchProvider, useStytch, useStytchSession, useStytchUser, withStytch, withStytchSession, withStytchUser };
+export { StytchLogin, StytchPasswordReset, StytchProvider, useStytch, useStytchSession, useStytchUser, withStytch, withStytchSession, withStytchUser };
 export type { StytchProviderProps };

package/dist/index.esm.js

@@ -1,5 +1,4 @@
-import * as React from 'react';
-import React__default, { useRef, useState, useEffect, useCallback, createContext, useContext, useMemo } from 'react';
+import React, { useRef, useState, useEffect, useCallback, createContext, useContext, useMemo, useLayoutEffect } from 'react';
 
 const noProviderError = (item) => `${item} can only be used inside <StytchProvider>.`;
 const providerMustBeUniqueError = 'You cannot render a <StytchProvider> inside another <StytchProvider>.';
@@ -34,21 +33,57 @@ const useAsyncState = (initialState) => {
     return [state, setStateAction];
 };
 
+const initialUser = {
+    user: null,
+    fromCache: false,
+};
+const initialSession = {
+    session: null,
+    fromCache: false,
+};
 const StytchContext = createContext({ isMounted: false });
-const StytchUserContext = createContext(null);
-const StytchSessionContext = createContext(null);
+const StytchUserContext = createContext(initialUser);
+const StytchSessionContext = createContext(initialSession);
 const useIsMounted__INTERNAL = () => useContext(StytchContext).isMounted;
 const isUIClient = (client) => {
-    return client.mount !== undefined;
+    return client.mountLogin !== undefined;
 };
+/**
+ * Returns the active User.
+ * Check the fromCache property to determine if the user data is from persistent storage.
+ * @example
+ * const {user} = useStytchUser();
+ * return (<h1>Welcome, {user.name.first_name}</h1>);
+ * @returns A {@link SWRUser}
+ */
 const useStytchUser = () => {
     invariant(useIsMounted__INTERNAL(), noProviderError('useStytchUser'));
     return useContext(StytchUserContext);
 };
+/**
+ * Returns the active user's Stytch session.
+ * @example
+ * const {session} = useStytchSession();
+ * useEffect(() => {
+ *   if (!session) {
+ *     router.replace('/login')
+ *   }
+ * }, [session]);
+ * @returns A {@link SWRSession}
+ */
 const useStytchSession = () => {
     invariant(useIsMounted__INTERNAL(), noProviderError('useStytchSession'));
     return useContext(StytchSessionContext);
 };
+/**
+ * Returns the Stytch client stored in the Stytch context.
+ *
+ * @example
+ * const stytch = useStytch();
+ * useEffect(() => {
+ *   stytch.magicLinks.authenticate('...')
+ * }, [stytch]);
+ */
 const useStytch = () => {
     const ctx = useContext(StytchContext);
     invariant(ctx.isMounted, noProviderError('useStytch'));
@@ -57,7 +92,7 @@ const useStytch = () => {
 const withStytch = (Component) => {
     const WithStytch = (props) => {
         invariant(useIsMounted__INTERNAL(), noProviderError('withStytch'));
-        return React__default.createElement(Component, { ...props, stytch: useStytch() });
+        return React.createElement(Component, Object.assign({}, props, { stytch: useStytch() }));
     };
     WithStytch.displayName = `withStytch(${Component.displayName || Component.name || 'Component'})`;
     return WithStytch;
@@ -65,7 +100,8 @@ const withStytch = (Component) => {
 const withStytchUser = (Component) => {
     const WithStytchUser = (props) => {
         invariant(useIsMounted__INTERNAL(), noProviderError('withStytchUser'));
-        return React__default.createElement(Component, { ...props, stytchUser: useStytchUser() });
+        const { user, fromCache } = useStytchUser();
+        return React.createElement(Component, Object.assign({}, props, { stytchUser: user, stytchUserIsFromCache: fromCache }));
     };
     WithStytchUser.displayName = `withStytchUser(${Component.displayName || Component.name || 'Component'})`;
     return WithStytchUser;
@@ -73,65 +109,150 @@ const withStytchUser = (Component) => {
 const withStytchSession = (Component) => {
     const WithStytchSession = (props) => {
         invariant(useIsMounted__INTERNAL(), noProviderError('withStytchSession'));
-        return React__default.createElement(Component, { ...props, stytchSession: useStytchSession() });
+        const { session, fromCache } = useStytchSession();
+        return React.createElement(Component, Object.assign({}, props, { stytchSession: session, stytchSessionIsFromCache: fromCache }));
     };
     WithStytchSession.displayName = `withStytchSession(${Component.displayName || Component.name || 'Component'})`;
     return WithStytchSession;
 };
+/**
+ * The Stytch Context Provider.
+ * Wrap your application with this component in the root file in order to use Stytch everywhere in your app.
+ * @example
+ * const stytch = new StytchHeadlessClient('public-token-<find yours in the stytch dashboard>')
+ *
+ * ReactDOM.render(
+ *   <StytchProvider stytch={stytch}>
+ *     <App />
+ *   </StytchProvider>,
+ *   document.getElementById('root'),
+ * )
+ */
 const StytchProvider = ({ stytch, children }) => {
     invariant(!useIsMounted__INTERNAL(), providerMustBeUniqueError);
     invariant(typeof window !== 'undefined', noSSRError);
     const ctx = useMemo(() => ({ client: stytch, isMounted: true }), [stytch]);
-    const [user, setUser] = useAsyncState(stytch.user.getSync());
-    const [session, setSession] = useAsyncState(stytch.session.getSync());
+    const [user, setUser] = useAsyncState({
+        user: stytch.user.getSync(),
+        fromCache: true,
+    });
+    const [session, setSession] = useAsyncState({
+        session: stytch.session.getSync(),
+        fromCache: true,
+    });
     useEffect(() => {
-        const unsubscribeUser = stytch.user.onChange((user) => setUser(user));
-        const unsubscribeSession = stytch.session.onChange((session) => setSession(session));
+        const unsubscribeUser = stytch.user.onChange((user) => setUser({
+            user,
+            fromCache: false,
+        }));
+        const unsubscribeSession = stytch.session.onChange((session) => setSession({
+            session,
+            fromCache: false,
+        }));
         return () => {
             unsubscribeUser();
             unsubscribeSession();
         };
     }, [stytch, setUser, setSession]);
-    return (React__default.createElement(StytchContext.Provider, { value: ctx },
-        React__default.createElement(StytchUserContext.Provider, { value: session && user },
-            React__default.createElement(StytchSessionContext.Provider, { value: user && session }, children))));
+    const finalSess = !!session.session === !!user.user ? session : initialSession;
+    const finalUser = !!session.session === !!user.user ? user : initialUser;
+    return (React.createElement(StytchContext.Provider, { value: ctx },
+        React.createElement(StytchUserContext.Provider, { value: finalUser },
+            React.createElement(StytchSessionContext.Provider, { value: finalSess }, children))));
 };
 
 /**
- * Returns a unique element ID.
- * Intended to only be used client-side - this will cause HTML mismatch issues in SSR!
- * cf: https://github.com/vercel/next.js/issues/7322#issuecomment-968858477
- */
-const useUniqueElementId = () => {
-    return React.useMemo(() => {
-        const randId = Math.floor(Math.random() * 1e6);
-        return `stytch-magic-link-${randId}`;
-    }, []);
-};
-/**
- * Stytch JS React Component
+ * The Stytch Login Screen component.
+ * This component can only be used with a {@link StytchUIClient} client constructor
+ * passed into the {@link StytchProvider}
  *
- * [Documentation](https://stytch.com/docs/javascript-sdk)
+ * See the {@link https://stytch.com/docs/sdks/javascript-sdk online reference}
+ * and {@link https://storybook.stytch.com interactive examples} for more.
+ *
+ * @example
+ * <StytchLogin
+ *   config={{
+ *     products: ['emailMagicLinks', 'oauth'],
+ *     emailMagicLinksOptions: {
+ *       loginRedirectURL: 'https://example.com/authenticate',
+ *       signupRedirectURL: 'https://example.com/authenticate',
+ *     },
+ *     oauthOptions: {
+ *      providers: [{ type: OAuthProviders.Google }, { type: OAuthProviders.Microsoft }],
+ *    },
+ *   }}
+ *   styles={{
+ *     fontFamily: '"Helvetica New", Helvetica, sans-serif',
+ *     primaryColor: '#0577CA',
+ *     width: '321px',
+ *   }}
+ *   callbacks={{
+ *     onEvent: (event) => console.log(event)
+ *   }}
+ * />
+ * @param props {@link StytchProps}
  */
-const Stytch = ({ config, styles, callbacks, }) => {
-    invariant(useIsMounted__INTERNAL(), noProviderError('<Stytch />'));
+const StytchLogin = ({ config, styles, callbacks }) => {
+    invariant(useIsMounted__INTERNAL(), noProviderError('<StytchLogin />'));
     const stytchClient = useStytch();
-    const elementId = useUniqueElementId();
-    React.useEffect(() => {
-        if (!elementId) {
-            return;
-        }
+    const containerEl = useRef(null);
+    useLayoutEffect(() => {
         if (!isUIClient(stytchClient)) {
             throw Error(noHeadlessClientError);
         }
-        stytchClient.mount({
+        if (!containerEl.current) {
+            return;
+        }
+        if (!containerEl.current.id) {
+            const randId = Math.floor(Math.random() * 1e6);
+            containerEl.current.id = `stytch-magic-link-${randId}`;
+        }
+        stytchClient.mountLogin({
             config,
             callbacks,
-            elementId: `#${elementId}`,
+            elementId: `#${containerEl.current.id}`,
             styles,
         });
-    }, [elementId, stytchClient]);
-    return elementId ? React.createElement("div", { id: elementId }) : null;
+    }, [stytchClient, config, styles, callbacks]);
+    return React.createElement("div", { ref: containerEl });
+};
+/**
+ * The Stytch Reset Password component.
+ * This component can only be used with a {@link StytchUIClient} client constructor
+ * passed into the {@link StytchProvider}
+ *
+ * See the {@link https://stytch.com/docs/sdks/javascript-sdk online reference}
+ * and {@link https://storybook.stytch.com interactive examples} for more.
+ *
+ * @example
+ * TODO
+ */
+const StytchPasswordReset = ({ config, styles, callbacks, passwordResetToken }) => {
+    invariant(useIsMounted__INTERNAL(), noProviderError('<StytchResetPassword />'));
+    const stytchClient = useStytch();
+    const containerEl = useRef(null);
+    useLayoutEffect(() => {
+        if (!isUIClient(stytchClient)) {
+            throw Error(noHeadlessClientError);
+        }
+        if (!containerEl.current) {
+            return;
+        }
+        if (!containerEl.current.id) {
+            const randId = Math.floor(Math.random() * 1e6);
+            containerEl.current.id = `stytch-reset-password-${randId}`;
+        }
+        if (passwordResetToken) {
+            stytchClient.mountResetPassword({
+                config,
+                callbacks,
+                elementId: `#${containerEl.current.id}`,
+                styles,
+                passwordResetToken,
+            });
+        }
+    }, [stytchClient, config, styles, callbacks, passwordResetToken]);
+    return React.createElement("div", { ref: containerEl });
 };
 
-export { Stytch, StytchProvider, useStytch, useStytchSession, useStytchUser, withStytch, withStytchSession, withStytchUser };
+export { StytchLogin, StytchPasswordReset, StytchProvider, useStytch, useStytchSession, useStytchUser, withStytch, withStytchSession, withStytchUser };

package/dist/index.js

@@ -6,26 +6,7 @@ var React = require('react');
 
 function _interopDefaultLegacy (e) { return e && typeof e === 'object' && 'default' in e ? e : { 'default': e }; }
 
-function _interopNamespace(e) {
-  if (e && e.__esModule) return e;
-  var n = Object.create(null);
-  if (e) {
-    Object.keys(e).forEach(function (k) {
-      if (k !== 'default') {
-        var d = Object.getOwnPropertyDescriptor(e, k);
-        Object.defineProperty(n, k, d.get ? d : {
-          enumerable: true,
-          get: function () { return e[k]; }
-        });
-      }
-    });
-  }
-  n["default"] = e;
-  return Object.freeze(n);
-}
-
 var React__default = /*#__PURE__*/_interopDefaultLegacy(React);
-var React__namespace = /*#__PURE__*/_interopNamespace(React);
 
 const noProviderError = (item) => `${item} can only be used inside <StytchProvider>.`;
 const providerMustBeUniqueError = 'You cannot render a <StytchProvider> inside another <StytchProvider>.';
@@ -60,21 +41,57 @@ const useAsyncState = (initialState) => {
     return [state, setStateAction];
 };
 
+const initialUser = {
+    user: null,
+    fromCache: false,
+};
+const initialSession = {
+    session: null,
+    fromCache: false,
+};
 const StytchContext = React.createContext({ isMounted: false });
-const StytchUserContext = React.createContext(null);
-const StytchSessionContext = React.createContext(null);
+const StytchUserContext = React.createContext(initialUser);
+const StytchSessionContext = React.createContext(initialSession);
 const useIsMounted__INTERNAL = () => React.useContext(StytchContext).isMounted;
 const isUIClient = (client) => {
-    return client.mount !== undefined;
+    return client.mountLogin !== undefined;
 };
+/**
+ * Returns the active User.
+ * Check the fromCache property to determine if the user data is from persistent storage.
+ * @example
+ * const {user} = useStytchUser();
+ * return (<h1>Welcome, {user.name.first_name}</h1>);
+ * @returns A {@link SWRUser}
+ */
 const useStytchUser = () => {
     invariant(useIsMounted__INTERNAL(), noProviderError('useStytchUser'));
     return React.useContext(StytchUserContext);
 };
+/**
+ * Returns the active user's Stytch session.
+ * @example
+ * const {session} = useStytchSession();
+ * useEffect(() => {
+ *   if (!session) {
+ *     router.replace('/login')
+ *   }
+ * }, [session]);
+ * @returns A {@link SWRSession}
+ */
 const useStytchSession = () => {
     invariant(useIsMounted__INTERNAL(), noProviderError('useStytchSession'));
     return React.useContext(StytchSessionContext);
 };
+/**
+ * Returns the Stytch client stored in the Stytch context.
+ *
+ * @example
+ * const stytch = useStytch();
+ * useEffect(() => {
+ *   stytch.magicLinks.authenticate('...')
+ * }, [stytch]);
+ */
 const useStytch = () => {
     const ctx = React.useContext(StytchContext);
     invariant(ctx.isMounted, noProviderError('useStytch'));
@@ -83,7 +100,7 @@ const useStytch = () => {
 const withStytch = (Component) => {
     const WithStytch = (props) => {
         invariant(useIsMounted__INTERNAL(), noProviderError('withStytch'));
-        return React__default["default"].createElement(Component, { ...props, stytch: useStytch() });
+        return React__default["default"].createElement(Component, Object.assign({}, props, { stytch: useStytch() }));
     };
     WithStytch.displayName = `withStytch(${Component.displayName || Component.name || 'Component'})`;
     return WithStytch;
@@ -91,7 +108,8 @@ const withStytch = (Component) => {
 const withStytchUser = (Component) => {
     const WithStytchUser = (props) => {
         invariant(useIsMounted__INTERNAL(), noProviderError('withStytchUser'));
-        return React__default["default"].createElement(Component, { ...props, stytchUser: useStytchUser() });
+        const { user, fromCache } = useStytchUser();
+        return React__default["default"].createElement(Component, Object.assign({}, props, { stytchUser: user, stytchUserIsFromCache: fromCache }));
     };
     WithStytchUser.displayName = `withStytchUser(${Component.displayName || Component.name || 'Component'})`;
     return WithStytchUser;
@@ -99,68 +117,154 @@ const withStytchUser = (Component) => {
 const withStytchSession = (Component) => {
     const WithStytchSession = (props) => {
         invariant(useIsMounted__INTERNAL(), noProviderError('withStytchSession'));
-        return React__default["default"].createElement(Component, { ...props, stytchSession: useStytchSession() });
+        const { session, fromCache } = useStytchSession();
+        return React__default["default"].createElement(Component, Object.assign({}, props, { stytchSession: session, stytchSessionIsFromCache: fromCache }));
     };
     WithStytchSession.displayName = `withStytchSession(${Component.displayName || Component.name || 'Component'})`;
     return WithStytchSession;
 };
+/**
+ * The Stytch Context Provider.
+ * Wrap your application with this component in the root file in order to use Stytch everywhere in your app.
+ * @example
+ * const stytch = new StytchHeadlessClient('public-token-<find yours in the stytch dashboard>')
+ *
+ * ReactDOM.render(
+ *   <StytchProvider stytch={stytch}>
+ *     <App />
+ *   </StytchProvider>,
+ *   document.getElementById('root'),
+ * )
+ */
 const StytchProvider = ({ stytch, children }) => {
     invariant(!useIsMounted__INTERNAL(), providerMustBeUniqueError);
     invariant(typeof window !== 'undefined', noSSRError);
     const ctx = React.useMemo(() => ({ client: stytch, isMounted: true }), [stytch]);
-    const [user, setUser] = useAsyncState(stytch.user.getSync());
-    const [session, setSession] = useAsyncState(stytch.session.getSync());
+    const [user, setUser] = useAsyncState({
+        user: stytch.user.getSync(),
+        fromCache: true,
+    });
+    const [session, setSession] = useAsyncState({
+        session: stytch.session.getSync(),
+        fromCache: true,
+    });
     React.useEffect(() => {
-        const unsubscribeUser = stytch.user.onChange((user) => setUser(user));
-        const unsubscribeSession = stytch.session.onChange((session) => setSession(session));
+        const unsubscribeUser = stytch.user.onChange((user) => setUser({
+            user,
+            fromCache: false,
+        }));
+        const unsubscribeSession = stytch.session.onChange((session) => setSession({
+            session,
+            fromCache: false,
+        }));
         return () => {
             unsubscribeUser();
             unsubscribeSession();
         };
     }, [stytch, setUser, setSession]);
+    const finalSess = !!session.session === !!user.user ? session : initialSession;
+    const finalUser = !!session.session === !!user.user ? user : initialUser;
     return (React__default["default"].createElement(StytchContext.Provider, { value: ctx },
-        React__default["default"].createElement(StytchUserContext.Provider, { value: session && user },
-            React__default["default"].createElement(StytchSessionContext.Provider, { value: user && session }, children))));
+        React__default["default"].createElement(StytchUserContext.Provider, { value: finalUser },
+            React__default["default"].createElement(StytchSessionContext.Provider, { value: finalSess }, children))));
 };
 
 /**
- * Returns a unique element ID.
- * Intended to only be used client-side - this will cause HTML mismatch issues in SSR!
- * cf: https://github.com/vercel/next.js/issues/7322#issuecomment-968858477
- */
-const useUniqueElementId = () => {
-    return React__namespace.useMemo(() => {
-        const randId = Math.floor(Math.random() * 1e6);
-        return `stytch-magic-link-${randId}`;
-    }, []);
-};
-/**
- * Stytch JS React Component
+ * The Stytch Login Screen component.
+ * This component can only be used with a {@link StytchUIClient} client constructor
+ * passed into the {@link StytchProvider}
+ *
+ * See the {@link https://stytch.com/docs/sdks/javascript-sdk online reference}
+ * and {@link https://storybook.stytch.com interactive examples} for more.
  *
- * [Documentation](https://stytch.com/docs/javascript-sdk)
+ * @example
+ * <StytchLogin
+ *   config={{
+ *     products: ['emailMagicLinks', 'oauth'],
+ *     emailMagicLinksOptions: {
+ *       loginRedirectURL: 'https://example.com/authenticate',
+ *       signupRedirectURL: 'https://example.com/authenticate',
+ *     },
+ *     oauthOptions: {
+ *      providers: [{ type: OAuthProviders.Google }, { type: OAuthProviders.Microsoft }],
+ *    },
+ *   }}
+ *   styles={{
+ *     fontFamily: '"Helvetica New", Helvetica, sans-serif',
+ *     primaryColor: '#0577CA',
+ *     width: '321px',
+ *   }}
+ *   callbacks={{
+ *     onEvent: (event) => console.log(event)
+ *   }}
+ * />
+ * @param props {@link StytchProps}
  */
-const Stytch = ({ config, styles, callbacks, }) => {
-    invariant(useIsMounted__INTERNAL(), noProviderError('<Stytch />'));
+const StytchLogin = ({ config, styles, callbacks }) => {
+    invariant(useIsMounted__INTERNAL(), noProviderError('<StytchLogin />'));
     const stytchClient = useStytch();
-    const elementId = useUniqueElementId();
-    React__namespace.useEffect(() => {
-        if (!elementId) {
-            return;
-        }
+    const containerEl = React.useRef(null);
+    React.useLayoutEffect(() => {
         if (!isUIClient(stytchClient)) {
             throw Error(noHeadlessClientError);
         }
-        stytchClient.mount({
+        if (!containerEl.current) {
+            return;
+        }
+        if (!containerEl.current.id) {
+            const randId = Math.floor(Math.random() * 1e6);
+            containerEl.current.id = `stytch-magic-link-${randId}`;
+        }
+        stytchClient.mountLogin({
             config,
             callbacks,
-            elementId: `#${elementId}`,
+            elementId: `#${containerEl.current.id}`,
             styles,
         });
-    }, [elementId, stytchClient]);
-    return elementId ? React__namespace.createElement("div", { id: elementId }) : null;
+    }, [stytchClient, config, styles, callbacks]);
+    return React__default["default"].createElement("div", { ref: containerEl });
+};
+/**
+ * The Stytch Reset Password component.
+ * This component can only be used with a {@link StytchUIClient} client constructor
+ * passed into the {@link StytchProvider}
+ *
+ * See the {@link https://stytch.com/docs/sdks/javascript-sdk online reference}
+ * and {@link https://storybook.stytch.com interactive examples} for more.
+ *
+ * @example
+ * TODO
+ */
+const StytchPasswordReset = ({ config, styles, callbacks, passwordResetToken }) => {
+    invariant(useIsMounted__INTERNAL(), noProviderError('<StytchResetPassword />'));
+    const stytchClient = useStytch();
+    const containerEl = React.useRef(null);
+    React.useLayoutEffect(() => {
+        if (!isUIClient(stytchClient)) {
+            throw Error(noHeadlessClientError);
+        }
+        if (!containerEl.current) {
+            return;
+        }
+        if (!containerEl.current.id) {
+            const randId = Math.floor(Math.random() * 1e6);
+            containerEl.current.id = `stytch-reset-password-${randId}`;
+        }
+        if (passwordResetToken) {
+            stytchClient.mountResetPassword({
+                config,
+                callbacks,
+                elementId: `#${containerEl.current.id}`,
+                styles,
+                passwordResetToken,
+            });
+        }
+    }, [stytchClient, config, styles, callbacks, passwordResetToken]);
+    return React__default["default"].createElement("div", { ref: containerEl });
 };
 
-exports.Stytch = Stytch;
+exports.StytchLogin = StytchLogin;
+exports.StytchPasswordReset = StytchPasswordReset;
 exports.StytchProvider = StytchProvider;
 exports.useStytch = useStytch;
 exports.useStytchSession = useStytchSession;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stytch/react",
-  "version": "0.0.3-0",
+  "version": "0.3.0",
   "description": "Stytch's official React Library",
   "main": "./dist/index.js",
   "module": "./dist/index.esm.js",
@@ -12,22 +12,33 @@
     "build": "npm run clean && npm run compile",
     "clean": "rm -rf ./dist",
     "compile": "rollup -c",
-    "dev": "tsc -p tsconfig.build.json --watch",
+    "dev": "rollup -c -w",
     "test": "jest"
   },
   "license": "MIT",
+  "homepage": "https://stytch.com/docs/sdks/javascript-sdk",
   "author": "Stytch",
+  "keywords": [
+    "stytch",
+    "react",
+    "nextjs",
+    "typescript",
+    "auth",
+    "authentication",
+    "session",
+    "jwt",
+    "user"
+  ],
   "devDependencies": {
     "@babel/runtime": "^7.18.6",
-    "@stytch/vanilla-js": "0.0.2-0",
+    "@stytch/vanilla-js": "0.3.0",
     "eslint-config-custom": "0.0.0",
     "rollup": "^2.56.3",
-    "typescript": "^4.5.3"
+    "typescript": "4.7.4"
   },
   "peerDependencies": {
-    "@stytch/vanilla-js": "^0.0.2-0",
+    "@stytch/vanilla-js": "^0.3.0",
     "react": ">= 17.0.2",
     "react-dom": ">= 17.0.2"
-  },
-  "stableVersion": "0.0.2"
-}
+  }
+}