@drmhse/authos-react 0.1.2 → 0.1.4

package/dist/index.d.mts

@@ -3,14 +3,56 @@ import * as _drmhse_sso_sdk from '@drmhse/sso-sdk';
 import { SsoClientOptions, SsoClient, UserProfile, Organization } from '@drmhse/sso-sdk';
 export { AuthErrorCodes, Organization, SsoApiError, SsoClient, SsoClientOptions, UserProfile } from '@drmhse/sso-sdk';
 
+/**
+ * Extended configuration options for the AuthOS React provider.
+ *
+ * Supports two modes:
+ * - **Platform-level**: Just `baseURL` for platform owners/admins (email/password only)
+ * - **Multi-tenant**: With `org` and `service` for tenant apps (enables OAuth)
+ */
+interface AuthOSConfig extends SsoClientOptions {
+    /**
+     * Organization slug for OAuth flows.
+     * Only required when using OAuth login buttons.
+     * Omit for platform-level access.
+     * @example 'acme-corp'
+     */
+    org?: string;
+    /**
+     * Service slug for OAuth flows.
+     * Only required when using OAuth login buttons.
+     * Omit for platform-level access.
+     * @example 'main-app'
+     */
+    service?: string;
+    /**
+     * Redirect URI after OAuth authentication.
+     * Defaults to current window location origin + '/callback'.
+     * @example 'https://app.example.com/callback'
+     */
+    redirectUri?: string;
+    /**
+     * URL to redirect to after successful sign-in.
+     * If not set, user stays on current page.
+     * @example '/dashboard'
+     */
+    afterSignInUrl?: string;
+    /**
+     * URL to redirect to after successful sign-up.
+     * If not set, user stays on current page.
+     * @example '/onboarding'
+     */
+    afterSignUpUrl?: string;
+}
 /**
  * Configuration options for the AuthOS React provider
  */
 interface AuthOSProviderProps {
     /**
-     * SDK configuration options
+     * SDK and OAuth configuration options.
+     * At minimum, requires `baseURL`. For OAuth flows, also set `org` and `service`.
      */
-    config: SsoClientOptions;
+    config: AuthOSConfig;
     /**
      * React children
      */
@@ -32,6 +74,8 @@ interface AuthOSProviderProps {
 interface AuthOSContextState {
     /** The underlying SDK client instance */
     client: SsoClient;
+    /** The provider configuration */
+    config: AuthOSConfig;
     /** Current authenticated user, or null if not authenticated */
     user: UserProfile | null;
     /** Whether the user is authenticated */
@@ -61,6 +105,19 @@ interface SignInProps {
     showSignUp?: boolean;
     /** Custom class name for the form container */
     className?: string;
+    /**
+     * OAuth providers to display as buttons.
+     * Set to false to hide all OAuth buttons, or provide an array of providers.
+     * @default false (no OAuth buttons shown by default)
+     * @example ['github', 'google', 'microsoft']
+     */
+    providers?: ('github' | 'google' | 'microsoft')[] | false;
+    /**
+     * Show a divider between OAuth and email/password forms.
+     * Only visible when providers are enabled.
+     * @default true
+     */
+    showDivider?: boolean;
 }
 /**
  * Props for the SignUp component
@@ -112,23 +169,71 @@ interface ProtectProps {
     /** React children to render when access is granted */
     children: React.ReactNode;
 }
+/**
+ * Supported OAuth providers
+ */
+type SupportedOAuthProvider = 'github' | 'google' | 'microsoft';
+/**
+ * Props for the OAuthButton component
+ */
+interface OAuthButtonProps {
+    /** OAuth provider to authenticate with */
+    provider: SupportedOAuthProvider;
+    /** Button content. Defaults to "Continue with {Provider}" */
+    children?: React.ReactNode;
+    /** Custom class name for the button */
+    className?: string;
+    /** Callback when OAuth redirect is initiated */
+    onRedirect?: () => void;
+    /** Whether the button is disabled */
+    disabled?: boolean;
+}
+/**
+ * Props for the SignedIn component.
+ * Renders children only when the user is authenticated.
+ */
+interface SignedInProps {
+    /** Content to render when user is signed in */
+    children: React.ReactNode;
+}
+/**
+ * Props for the SignedOut component.
+ * Renders children only when the user is not authenticated.
+ */
+interface SignedOutProps {
+    /** Content to render when user is signed out */
+    children: React.ReactNode;
+}
 
 /**
  * Provider component that wraps your app and provides AuthOS context.
  *
- * @example
+ * @example Basic usage
  * ```tsx
- * import { AuthOSProvider } from '@drmhse/authos-react';
+ * import { AuthOSProvider, SignIn, SignedOut } from '@drmhse/authos-react';
  *
  * function App() {
  *   return (
- *     <AuthOSProvider config={{ baseURL: 'https://auth.example.com' }}>
- *       <YourApp />
+ *     <AuthOSProvider config={{ baseURL: 'https://sso.example.com' }}>
+ *       <SignedOut>
+ *         <SignIn />
+ *       </SignedOut>
  *     </AuthOSProvider>
  *   );
  * }
  * ```
  *
+ * @example With OAuth (requires org and service)
+ * ```tsx
+ * <AuthOSProvider config={{
+ *   baseURL: 'https://sso.example.com',
+ *   org: 'my-org',
+ *   service: 'my-app',
+ * }}>
+ *   <SignIn providers={['github', 'google']} />
+ * </AuthOSProvider>
+ * ```
+ *
  * @example With SSR token (Next.js App Router)
  * ```tsx
  * import { cookies } from 'next/headers';
@@ -140,7 +245,7 @@ interface ProtectProps {
  *
  *   return (
  *     <AuthOSProvider
- *       config={{ baseURL: 'https://auth.example.com' }}
+ *       config={{ baseURL: 'https://sso.example.com' }}
  *       initialSessionToken={token}
  *     >
  *       {children}
@@ -203,15 +308,15 @@ declare function useUser(): UserProfile | null;
 interface UseOrganizationReturn {
     /** The current active organization */
     organization: Organization | null;
-    /** Switch to a different organization by slug */
+    /** Switch to a different organization by slug - issues new org-scoped tokens */
     switchOrganization: (slug: string) => Promise<void>;
 }
 /**
  * Hook to access the current organization context and switch between organizations.
  *
- * Note: Organization switching sets the local context. For full token-scoped
- * organization switching, users should re-authenticate through the OAuth flow
- * with the organization parameter.
+ * When switching organizations, this hook calls the backend to issue new JWT tokens
+ * with the organization context, enabling seamless organization switching without
+ * requiring re-authentication.
  *
  * @returns The current organization and a function to switch organizations
  *
@@ -291,9 +396,10 @@ declare function useAnyPermission(permissions: string[]): boolean;
 declare function useAllPermissions(permissions: string[]): boolean;
 
 /**
- * Headless SignIn component that handles email/password authentication with MFA support.
+ * SignIn component that handles email/password authentication with MFA support.
+ * Optionally displays OAuth provider buttons when `providers` prop is set.
  *
- * @example
+ * @example Basic email/password only
  * ```tsx
  * import { SignIn } from '@drmhse/authos-react';
  *
@@ -306,8 +412,16 @@ declare function useAllPermissions(permissions: string[]): boolean;
  *   );
  * }
  * ```
+ *
+ * @example With OAuth providers (requires org/service in provider config)
+ * ```tsx
+ * <SignIn
+ *   providers={['github', 'google', 'microsoft']}
+ *   onSuccess={(user) => router.push('/dashboard')}
+ * />
+ * ```
  */
-declare function SignIn({ onSuccess, onError, showForgotPassword, showSignUp, className, }: SignInProps): react_jsx_runtime.JSX.Element;
+declare function SignIn({ onSuccess, onError, showForgotPassword, showSignUp, className, providers, showDivider, }: SignInProps): react_jsx_runtime.JSX.Element;
 
 /**
  * Headless SignUp component that handles user registration.
@@ -395,4 +509,138 @@ declare function UserButton({ className, showEmail, onLogout }: UserButtonProps)
  */
 declare function Protect({ permission, role, fallback, children }: ProtectProps): react_jsx_runtime.JSX.Element;
 
-export { type AuthOSContextState, AuthOSProvider, type AuthOSProviderProps, OrganizationSwitcher, type OrganizationSwitcherProps, Protect, type ProtectProps, SignIn, type SignInProps, SignUp, type SignUpProps, UserButton, type UserButtonProps, useAllPermissions, useAnyPermission, useAuthOS, useAuthOSContext, useOrganization, usePermission, useUser };
+/**
+ * OAuth login button for a specific provider.
+ * Redirects the user to the OAuth provider's login page.
+ *
+ * Requires `org` and `service` to be configured in the AuthOSProvider.
+ *
+ * @example
+ * ```tsx
+ * import { OAuthButton } from '@drmhse/authos-react';
+ *
+ * function LoginPage() {
+ *   return (
+ *     <div>
+ *       <OAuthButton provider="github" />
+ *       <OAuthButton provider="google">Sign in with Google</OAuthButton>
+ *       <OAuthButton provider="microsoft" className="btn-microsoft" />
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function OAuthButton({ provider, children, className, onRedirect, disabled, }: OAuthButtonProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Renders children only when the user is authenticated.
+ * Use with SignedOut to create conditional UI based on auth state.
+ *
+ * @example
+ * ```tsx
+ * import { SignedIn, SignedOut, UserButton, SignIn } from '@drmhse/authos-react';
+ *
+ * function Header() {
+ *   return (
+ *     <header>
+ *       <SignedIn>
+ *         <UserButton />
+ *       </SignedIn>
+ *       <SignedOut>
+ *         <SignIn />
+ *       </SignedOut>
+ *     </header>
+ *   );
+ * }
+ * ```
+ */
+declare function SignedIn({ children }: SignedInProps): react_jsx_runtime.JSX.Element | null;
+
+/**
+ * Renders children only when the user is NOT authenticated.
+ * Use with SignedIn to create conditional UI based on auth state.
+ *
+ * @example
+ * ```tsx
+ * import { SignedIn, SignedOut, UserButton, SignIn } from '@drmhse/authos-react';
+ *
+ * function Header() {
+ *   return (
+ *     <header>
+ *       <SignedIn>
+ *         <UserButton />
+ *       </SignedIn>
+ *       <SignedOut>
+ *         <SignIn />
+ *       </SignedOut>
+ *     </header>
+ *   );
+ * }
+ * ```
+ */
+declare function SignedOut({ children }: SignedOutProps): react_jsx_runtime.JSX.Element | null;
+
+interface MagicLinkSignInProps {
+    /** Callback when magic link is successfully sent */
+    onSuccess?: () => void;
+    /** Callback when sending fails */
+    onError?: (error: Error) => void;
+    /** Custom class name */
+    className?: string;
+    /** Show sign in with password link */
+    showPasswordSignIn?: boolean;
+}
+/**
+ * Passwordless sign-in via magic link (email).
+ *
+ * Sends a one-time login link to the user's email address.
+ *
+ * @example
+ * ```tsx
+ * import { MagicLinkSignIn } from '@drmhse/authos-react';
+ *
+ * function LoginPage() {
+ *   return (
+ *     <MagicLinkSignIn
+ *       onSuccess={() => alert('Check your email!')}
+ *       onError={(err) => console.error(err)}
+ *     />
+ *   );
+ * }
+ * ```
+ */
+declare function MagicLinkSignIn({ onSuccess, onError, className, showPasswordSignIn, }: MagicLinkSignInProps): react_jsx_runtime.JSX.Element;
+
+interface PasskeySignInProps {
+    /** Callback when passkey sign-in is successful */
+    onSuccess?: () => void;
+    /** Callback when sign-in fails */
+    onError?: (error: Error) => void;
+    /** Custom class name */
+    className?: string;
+    /** Show sign in with password link */
+    showPasswordSignIn?: boolean;
+}
+/**
+ * Passkey (WebAuthn) sign-in component.
+ *
+ * Uses the Web Authentication API for passwordless authentication
+ * via biometrics, security keys, or platform authenticators.
+ *
+ * @example
+ * ```tsx
+ * import { PasskeySignIn } from '@drmhse/authos-react';
+ *
+ * function LoginPage() {
+ *   return (
+ *     <PasskeySignIn
+ *       onSuccess={() => router.push('/dashboard')}
+ *       onError={(err) => console.error(err)}
+ *     />
+ *   );
+ * }
+ * ```
+ */
+declare function PasskeySignIn({ onSuccess, onError, className, showPasswordSignIn, }: PasskeySignInProps): react_jsx_runtime.JSX.Element;
+
+export { type AuthOSConfig, type AuthOSContextState, AuthOSProvider, type AuthOSProviderProps, MagicLinkSignIn, type MagicLinkSignInProps, OAuthButton, type OAuthButtonProps, OrganizationSwitcher, type OrganizationSwitcherProps, PasskeySignIn, type PasskeySignInProps, Protect, type ProtectProps, SignIn, type SignInProps, SignUp, type SignUpProps, SignedIn, type SignedInProps, SignedOut, type SignedOutProps, type SupportedOAuthProvider, UserButton, type UserButtonProps, useAllPermissions, useAnyPermission, useAuthOS, useAuthOSContext, useOrganization, usePermission, useUser };