@stytch/nextjs 21.4.3 → 21.5.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @stytch/nextjs
 
+## 21.5.0
+
+### Minor Changes
+
+- 1e9ab0e: Add a new `assumeHydrated` prop to the `StytchProvider` and `StytchB2BProvider` components. This prop allows the provider to assume whether or not the app might be hydrated in a browser environment after initially being rendered in a server environment. When `true`, the provider eagerly reads from the browser's local cache to retrieve cached session and related data. When `false`, the provider defers this initialization until after the first render, to avoid hydration errors. This prop defaults to `false` in `@stytch/nextjs`, which preserves the behavior from previous versions.
+
+  We recommend setting `assumeHydrated={false}` if your app hydrates server-rendered content on the client. Otherwise, it is safe to set `assumeHydrated={true}`. If you're unsure or notice hydration errors in your app, set `assumeHydrated={false}`.
+
+  Unless you set `assumeHydrated={true}`, you should continue to check the initialized state of the provider by checking the `isInitialized` value (returned from hooks like `useStytchUser`, `useStytchSession`, `useStytchMember`, `useStytchMemberSession`, `useStytchOrganization`, and `useStytchIsAuthorized`) or `*IsInitialized` prop (injected by HOCs like `withStytchUser`, `withStytchSession`, `withStytchMember`, `withStytchMemberSession`, and `withStytchOrganization`) before relying on any other values.
+
+## 21.4.4
+
+### Patch Changes
+
+- 54275c2: Make some minor improvements to JSDoc comments
+- 54275c2: Add missing default generic type parameters
+
 ## 21.4.3
 
 ### Patch Changes

package/dist/StytchB2BContext-54aa990c.d.ts

@@ -0,0 +1,272 @@
+/// <reference types="react" />
+import React from 'react';
+import { ReactNode } from "react";
+import { PermissionsMap } from '@stytch/core/public';
+import { Member, MemberSession, Organization, StytchB2BUIClient } from '@stytch/vanilla-js/b2b';
+import { StytchB2BHeadlessClient, StytchProjectConfigurationInput } from '@stytch/vanilla-js/b2b/headless';
+/**
+ * The Stytch Client object passed in to <StytchB2BProvider /> in your application root.
+ * Either a StytchB2BUIClient or StytchB2BHeadlessClient.
+ */
+type StytchB2BClient<TProjectConfiguration extends StytchProjectConfigurationInput> = StytchB2BHeadlessClient<TProjectConfiguration> | StytchB2BUIClient<TProjectConfiguration>;
+type SWRMemberUninitialized = {
+    /**
+     * Either the active {@link Member} object, or null if the member is not logged in.
+     */
+    member: null;
+    /**
+     * If true, indicates that the value returned is from the application cache and a state refresh is in progress.
+     */
+    fromCache: false;
+    /**
+     * If true, indicates that the SDK has completed initialization.
+     */
+    isInitialized: false;
+};
+type SWRMemberInitialized = {
+    /**
+     * Either the active {@link Member} object, or null if the member is not logged in.
+     */
+    member: Member | null;
+    /**
+     * If true, indicates that the value returned is from the application cache and a state refresh is in progress.
+     */
+    fromCache: boolean;
+    /**
+     * If true, indicates that the SDK has completed initialization.
+     */
+    isInitialized: true;
+};
+type SWRMember<TAlwaysInitialized extends boolean = boolean> = TAlwaysInitialized extends true ? SWRMemberInitialized : SWRMemberInitialized | SWRMemberUninitialized;
+type SWRMemberSessionUninitialized = {
+    /**
+     * Either the active {@link MemberSession} object, or null if the member is not logged in.
+     */
+    session: null;
+    /**
+     * If true, indicates that the value returned is from the application cache and a state refresh is in progress.
+     */
+    fromCache: false;
+    /**
+     * If true, indicates that the SDK has completed initialization.
+     */
+    isInitialized: false;
+};
+type SWRMemberSessionInitialized = {
+    /**
+     * Either the active {@link MemberSession} object, or null if the member is not logged in.
+     */
+    session: MemberSession | null;
+    /**
+     * If true, indicates that the value returned is from the application cache and a state refresh is in progress.
+     */
+    fromCache: boolean;
+    /**
+     * If true, indicates that the SDK has completed initialization.
+     */
+    isInitialized: true;
+};
+type SWRMemberSession<TAlwaysInitialized extends boolean = boolean> = TAlwaysInitialized extends true ? SWRMemberSessionInitialized : SWRMemberSessionInitialized | SWRMemberSessionUninitialized;
+type SWROrganizationUninitialized = {
+    /**
+     * Either the active {@link Organization} object, or null if the member is not logged in.
+     */
+    organization: null;
+    /**
+     * If true, indicates that the value returned is from the application cache and a state refresh is in progress.
+     */
+    fromCache: false;
+    /**
+     * If true, indicates that the SDK has completed initialization.
+     */
+    isInitialized: false;
+};
+type SWROrganizationInitialized = {
+    /**
+     * Either the active {@link Organization} object, or null if the member is not logged in.
+     */
+    organization: Organization | null;
+    /**
+     * If true, indicates that the value returned is from the application cache and a state refresh is in progress.
+     */
+    fromCache: boolean;
+    /**
+     * If true, indicates that the SDK has completed initialization.
+     */
+    isInitialized: true;
+};
+type SWROrganization<TAlwaysInitialized extends boolean = boolean> = TAlwaysInitialized extends true ? SWROrganizationInitialized : SWROrganizationInitialized | SWROrganizationUninitialized;
+declare const useIsMounted__INTERNAL: () => boolean;
+declare const isUIClient: <TProjectConfiguration extends Partial<import("@stytch/core/public").StytchProjectConfiguration>>(client: StytchB2BClient<TProjectConfiguration>) => client is StytchB2BUIClient<TProjectConfiguration>;
+/**
+ * Returns the active Member.
+ * The Stytch SDKs are used for client-side authentication and session management.
+ * Check the isInitialized property to determine if the SDK has completed initialization.
+ * Check the fromCache property to determine if the member data is from persistent storage.
+ * @example
+ * const {member, isInitialized, fromCache} = useStytchMember();
+ * if (!isInitialized) {
+ *     return <p>Loading...</p>;
+ * }
+ * return (<h1>Welcome, {member.name}</h1>);
+ */
+declare const useStytchMember: <TAssumeHydrated extends boolean = false>() => SWRMember<TAssumeHydrated>;
+/**
+ * Returns the active member's Stytch member session.
+ * The Stytch SDKs are used for client-side authentication and session management.
+ * Check the isInitialized property to determine if the SDK has completed initialization.
+ * Check the fromCache property to determine if the session data is from persistent storage.
+ * @example
+ * const {session, isInitialized, fromCache} = useStytchMemberSession();
+ * useEffect(() => {
+ *   if (!isInitialized) {
+ *     return;
+ *   }
+ *   if (!session) {
+ *     router.replace('/login')
+ *   }
+ * }, [session, isInitialized]);
+ */
+declare const useStytchMemberSession: <TAssumeHydrated extends boolean = false>() => SWRMemberSession<TAssumeHydrated>;
+/**
+ * Returns the active Stytch organization.
+ * The Stytch SDKs are used for client-side authentication and session management.
+ * Check the isInitialized property to determine if the SDK has completed initialization.
+ * Check the fromCache property to determine if the organization data is from persistent storage.
+ * @example
+ * const {organization, isInitialized, fromCache} = useStytchOrganization();
+ * if (!isInitialized) {
+ *     return <p>Loading...</p>;
+ * }
+ * return (<p>Welcome to {organization.organization_name}</p>);
+ */
+declare const useStytchOrganization: <TAssumeHydrated extends boolean = false>() => SWROrganization<TAssumeHydrated>;
+type SWRIsAuthorizedUninitialized = {
+    /**
+     * Whether the logged-in member is allowed to perform the specified action on the specified resource.
+     */
+    isAuthorized: false;
+    /**
+     * If true, indicates that the value returned is from the application cache and a state refresh is in progress.
+     */
+    fromCache: false;
+    /**
+     * If true, indicates that the SDK has completed initialization.
+     */
+    isInitialized: false;
+};
+type SWRIsAuthorizedInitialized = {
+    /**
+     * Whether the logged-in member is allowed to perform the specified action on the specified resource.
+     */
+    isAuthorized: boolean;
+    /**
+     * If true, indicates that the value returned is from the application cache and a state refresh is in progress.
+     */
+    fromCache: boolean;
+    /**
+     * If true, indicates that the SDK has completed initialization.
+     */
+    isInitialized: boolean;
+};
+type SWRIsAuthorized<TAlwaysInitialized extends boolean> = TAlwaysInitialized extends true ? SWRIsAuthorizedInitialized : SWRIsAuthorizedInitialized | SWRIsAuthorizedUninitialized;
+/**
+ * Determines whether the logged-in member is allowed to perform the specified action on the specified resource.
+ * Returns `true` if the member can perform the action, `false` otherwise.
+ *
+ * If the member is not logged in, this method will always return false.
+ * If the resource or action provided are not valid for the configured RBAC policy, this method will return false.
+ *
+ * Remember - authorization checks for sensitive actions should always occur on the backend as well.
+ * @example
+ * const { isAuthorized } = useStytchIsAuthorized<Permissions>('documents', 'edit');
+ * return <button disabled={!isAuthorized}>Edit</button>
+ */
+declare const useStytchIsAuthorized: <TAssumeHydrated extends boolean = false>(resourceId: string, action: string) => SWRIsAuthorized<TAssumeHydrated>;
+/**
+ * Returns the Stytch B2B client stored in the Stytch context.
+ *
+ * @example
+ * const stytch = useStytchB2BClient();
+ * useEffect(() => {
+ *   stytch.magicLinks.authenticate('...')
+ * }, [stytch]);
+ */
+declare const useStytchB2BClient: <TProjectConfiguration extends Partial<import("@stytch/core/public").StytchProjectConfiguration> = Stytch.DefaultProjectConfiguration>() => StytchB2BHeadlessClient<TProjectConfiguration>;
+declare const withStytchB2BClient: <T extends object, TProjectConfiguration extends Partial<import("@stytch/core/public").StytchProjectConfiguration>>(Component: React.ComponentType<T & {
+    stytch: StytchB2BHeadlessClient<TProjectConfiguration>;
+}>) => React.ComponentType<T>;
+declare const withStytchMember: <T extends object, TAssumeHydrated extends boolean = false>(Component: React.ComponentType<T & {
+    stytchMember: Member | null;
+    stytchMemberIsInitialized: boolean;
+    stytchMemberIsFromCache: boolean;
+}>) => React.ComponentType<T>;
+declare const withStytchMemberSession: <T extends object, TAssumeHydrated extends boolean = false>(Component: React.ComponentType<T & {
+    stytchMemberSession: MemberSession | null;
+    stytchMemberSessionIsInitialized: boolean;
+    stytchMemberSessionIsFromCache: boolean;
+}>) => React.ComponentType<T>;
+declare const withStytchOrganization: <T extends object, TAssumeHydrated extends boolean = false>(Component: React.ComponentType<T & {
+    stytchOrganization: Organization | null;
+    stytchOrganizationIsInitialized: boolean;
+    stytchOrganizationIsFromCache: boolean;
+}>) => React.ComponentType<T>;
+/**
+ * Wrap your component with this HOC in order to receive the permissions for the logged-in member.
+ * Evaluates all permissions granted to the logged-in member.
+ * Returns a Record<RoleId, Record<Action, boolean>> response indicating the member's permissions.
+ * Each boolean will be `true` if the member can perform the action, `false` otherwise.
+ *
+ * If the member is not logged in, all values will be false.
+ *
+ * Remember - authorization checks for sensitive actions should always occur on the backend as well.
+ * @example
+ * type Permissions = {
+ *   document: 'create' | 'read' | 'write
+ *   image: 'create' | 'read'
+ * }
+ *
+ * const MyComponent = (props) => {
+ *   const canEditDocuments = props.stytchPermissions.document.edit;
+ *   const canReadImages = props.stytchPermissions.image.read;
+ * }
+ * return withStytchPermissions<Permissions>(MyComponent)
+ */
+declare const withStytchPermissions: <Permissions_1 extends Record<string, string>, T extends object>(Component: React.ComponentType<T & {
+    stytchPermissions: PermissionsMap<Permissions_1>;
+}>) => React.ComponentType<T>;
+interface StytchB2BProviderProps<TProjectConfiguration extends StytchProjectConfigurationInput = Stytch.DefaultProjectConfiguration> {
+    /**
+     * A Stytch client instance, created using either {@link createStytchHeadlessClient} or {@link createStytchUIClient}
+     */
+    stytch: StytchB2BClient<TProjectConfiguration>;
+    /**
+     * When true, the provider will assume that the component will only be
+     * rendered in a browser environment, either in a single-page application or
+     * after completing hydration of a server-rendered application. This allows
+     * cached values to be retrieved from the browser on the first render, meaning
+     * that the `isInitialized` value returned from Stytch hooks will be `true`
+     * starting from the first render.
+     *
+     * When `false`, the provider will defer initialization until after the first
+     * render, and `isInitialized` will initially be `false`.
+     *
+     * This value defaults to `false` in `@stytch/nextjs`.
+     */
+    assumeHydrated?: boolean;
+    children?: ReactNode;
+}
+/**
+ * The Stytch Context Provider.
+ * Wrap your application with this component in order to use Stytch everywhere in your app.
+ * @example
+ * const stytch = createStytchB2BHeadlessClient('public-token-<find yours in the stytch dashboard>')
+ *
+ * return (
+ *   <StytchB2BProvider stytch={stytch}>
+ *     <App />
+ *   </StytchB2BProvider>
+ * )
+ */
+declare const StytchB2BProvider: <TProjectConfiguration extends Partial<import("@stytch/core/public").StytchProjectConfiguration> = Stytch.DefaultProjectConfiguration>({ stytch, children, assumeHydrated, }: StytchB2BProviderProps<TProjectConfiguration>) => JSX.Element;
+export { useIsMounted__INTERNAL, isUIClient, useStytchMember, useStytchMemberSession, useStytchOrganization, useStytchIsAuthorized, useStytchB2BClient, withStytchB2BClient, withStytchMember, withStytchMemberSession, withStytchOrganization, withStytchPermissions, StytchB2BProviderProps, StytchB2BProvider };

package/dist/{StytchB2BContext-a2d58b5b.js → StytchB2BContext-54aa990c.js}

@@ -1,6 +1,6 @@
-import React, { createContext, useContext, useEffect, useMemo } from 'react';
-import { i as invariant, u as useAsyncState, m as mergeWithStableProps } from './useIsomorphicLayoutEffect-2962f7c7.js';
-import { i as isStytchSSRProxy, n as noProviderError } from './StytchSSRProxy-4e34fb34.js';
+import React, { createContext, useContext, useEffect, useMemo, useCallback, useRef } from 'react';
+import { i as invariant, u as useAsyncState, m as mergeWithStableProps } from './useIsomorphicLayoutEffect-1babb81e.js';
+import { i as isStytchSSRProxy, n as noProviderError } from './StytchSSRProxy-34c789b5.js';
 
 const initialMember = {
     member: null,
@@ -17,20 +17,19 @@ const initialOrganization = {
     fromCache: false,
     isInitialized: false,
 };
-const StytchContext = createContext({ isMounted: false });
+const StytchB2BContext = createContext({ isMounted: false });
 const StytchMemberContext = createContext(initialMember);
 const StytchMemberSessionContext = createContext(initialMemberSession);
 const StytchOrganizationContext = createContext(initialOrganization);
-const useIsMounted__INTERNAL = () => useContext(StytchContext).isMounted;
+const useIsMounted__INTERNAL = () => useContext(StytchB2BContext).isMounted;
 const isUIClient = (client) => {
     return client.mount !== undefined;
 };
 /**
- * Returns the active member.
+ * Returns the active Member.
  * The Stytch SDKs are used for client-side authentication and session management.
  * Check the isInitialized property to determine if the SDK has completed initialization.
- * Check the fromCache property to determine if the session data is from persistent storage.
- * See Next's {@link https://nextjs.org/docs/authentication#authenticating-statically-generated-pages documentation} for more.
+ * Check the fromCache property to determine if the member data is from persistent storage.
  * @example
  * const {member, isInitialized, fromCache} = useStytchMember();
  * if (!isInitialized) {
@@ -43,11 +42,10 @@ const useStytchMember = () => {
     return useContext(StytchMemberContext);
 };
 /**
- * Returns the member's active Stytch member session.
+ * Returns the active member's Stytch member session.
  * The Stytch SDKs are used for client-side authentication and session management.
  * Check the isInitialized property to determine if the SDK has completed initialization.
  * Check the fromCache property to determine if the session data is from persistent storage.
- * See Next's {@link https://nextjs.org/docs/authentication#authenticating-statically-generated-pages documentation} for more.
  * @example
  * const {session, isInitialized, fromCache} = useStytchMemberSession();
  * useEffect(() => {
@@ -67,8 +65,7 @@ const useStytchMemberSession = () => {
  * Returns the active Stytch organization.
  * The Stytch SDKs are used for client-side authentication and session management.
  * Check the isInitialized property to determine if the SDK has completed initialization.
- * Check the fromCache property to determine if the session data is from persistent storage.
- * See Next's {@link https://nextjs.org/docs/authentication#authenticating-statically-generated-pages documentation} for more.
+ * Check the fromCache property to determine if the organization data is from persistent storage.
  * @example
  * const {organization, isInitialized, fromCache} = useStytchOrganization();
  * if (!isInitialized) {
@@ -89,7 +86,7 @@ const useStytchOrganization = () => {
  *
  * Remember - authorization checks for sensitive actions should always occur on the backend as well.
  * @example
- * const isAuthorized = useStytchIsAuthorized<Permissions>('documents', 'edit');
+ * const { isAuthorized } = useStytchIsAuthorized<Permissions>('documents', 'edit');
  * return <button disabled={!isAuthorized}>Edit</button>
  */
 const useStytchIsAuthorized = (resourceId, action) => {
@@ -122,16 +119,16 @@ const useStytchIsAuthorized = (resourceId, action) => {
     return isAuthorized;
 };
 /**
- * Returns the Stytch client stored in the Stytch context.
+ * Returns the Stytch B2B client stored in the Stytch context.
  *
  * @example
- * const stytch = useStytch();
+ * const stytch = useStytchB2BClient();
  * useEffect(() => {
  *   stytch.magicLinks.authenticate('...')
  * }, [stytch]);
  */
 const useStytchB2BClient = () => {
-    const ctx = useContext(StytchContext);
+    const ctx = useContext(StytchB2BContext);
     invariant(ctx.isMounted, noProviderError('useStytchB2BClient', 'StytchB2BProvider'));
     return ctx.client;
 };
@@ -212,7 +209,7 @@ const withStytchPermissions = (Component) => {
 };
 /**
  * The Stytch Context Provider.
- * Wrap your application with this component in `_app.js` in order to use Stytch everywhere in your app.
+ * Wrap your application with this component in order to use Stytch everywhere in your app.
  * @example
  * const stytch = createStytchB2BHeadlessClient('public-token-<find yours in the stytch dashboard>')
  *
@@ -222,34 +219,41 @@ const withStytchPermissions = (Component) => {
  *   </StytchB2BProvider>
  * )
  */
-const StytchB2BProvider = ({ stytch, children, }) => {
+const StytchB2BProvider = ({ stytch, children, assumeHydrated = false, }) => {
+    invariant(!useIsMounted__INTERNAL(), 'You cannot render a <StytchB2BProvider> inside another <StytchB2BProvider>.');
+    invariant(!assumeHydrated || typeof window !== 'undefined', 'The `assumeHydrated` prop must be set to `false` when using StytchB2BProvider in a server environment.');
     const ctx = useMemo(() => ({ client: stytch, isMounted: true }), [stytch]);
-    const [{ member, session, organization }, setClientState] = useAsyncState({
-        member: initialMember,
-        session: initialMemberSession,
-        organization: initialOrganization,
-    });
+    const getHydratedState = useCallback(() => {
+        return {
+            member: Object.assign(Object.assign({}, stytch.self.getInfo()), { isInitialized: true }),
+            session: Object.assign(Object.assign({}, stytch.session.getInfo()), { isInitialized: true }),
+            organization: Object.assign(Object.assign({}, stytch.organization.getInfo()), { isInitialized: true }),
+        };
+    }, [stytch]);
+    const getInitialState = () => {
+        return {
+            member: initialMember,
+            session: initialMemberSession,
+            organization: initialOrganization,
+        };
+    };
+    const [{ member, session, organization }, setClientState] = useAsyncState(() => assumeHydrated ? getHydratedState() : getInitialState());
+    // Store the initial value of `assumeHydrated` in a ref, because it is
+    // logically only relevant for the first render
+    const assumeHydratedRef = useRef(assumeHydrated);
     useEffect(() => {
         if (isStytchSSRProxy(stytch)) {
             return;
         }
-        setClientState({
-            member: Object.assign(Object.assign({}, stytch.self.getInfo()), { isInitialized: true }),
-            session: Object.assign(Object.assign({}, stytch.session.getInfo()), { isInitialized: true }),
-            organization: Object.assign(Object.assign({}, stytch.organization.getInfo()), { isInitialized: true }),
-        });
-        return stytch.onStateChange(() => {
-            setClientState((oldState) => {
-                const newState = {
-                    member: Object.assign(Object.assign({}, stytch.self.getInfo()), { isInitialized: true }),
-                    session: Object.assign(Object.assign({}, stytch.session.getInfo()), { isInitialized: true }),
-                    organization: Object.assign(Object.assign({}, stytch.organization.getInfo()), { isInitialized: true }),
-                };
-                return mergeWithStableProps(oldState, newState);
-            });
-        });
-    }, [setClientState, stytch]);
-    return (React.createElement(StytchContext.Provider, { value: ctx },
+        const updateState = () => {
+            setClientState((oldState) => mergeWithStableProps(oldState, getHydratedState()));
+        };
+        if (!assumeHydratedRef.current) {
+            updateState();
+        }
+        return stytch.onStateChange(updateState);
+    }, [getHydratedState, setClientState, stytch]);
+    return (React.createElement(StytchB2BContext.Provider, { value: ctx },
         React.createElement(StytchOrganizationContext.Provider, { value: organization },
             React.createElement(StytchMemberContext.Provider, { value: member },
                 React.createElement(StytchMemberSessionContext.Provider, { value: session }, children)))));