@drmhse/authos-react 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,372 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+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';
+
+/**
+ * Configuration options for the AuthOS React provider
+ */
+interface AuthOSProviderProps {
+    /**
+     * SDK configuration options
+     */
+    config: SsoClientOptions;
+    /**
+     * React children
+     */
+    children: React.ReactNode;
+    /**
+     * Optional: Provide an existing SsoClient instance instead of creating a new one
+     */
+    client?: SsoClient;
+}
+/**
+ * Authentication context state
+ */
+interface AuthOSContextState {
+    /** The underlying SDK client instance */
+    client: SsoClient;
+    /** Current authenticated user, or null if not authenticated */
+    user: UserProfile | null;
+    /** Whether the user is authenticated */
+    isAuthenticated: boolean;
+    /** Whether the initial auth check is still loading */
+    isLoading: boolean;
+    /** Current active organization context */
+    organization: Organization | null;
+    /** Set the current user (internal use) */
+    setUser: (user: UserProfile | null) => void;
+    /** Set the current organization (internal use) */
+    setOrganization: (org: Organization | null) => void;
+    /** Refresh the current user data from the server */
+    refreshUser: () => Promise<void>;
+}
+/**
+ * Props for the SignIn component
+ */
+interface SignInProps {
+    /** Callback when sign-in is successful */
+    onSuccess?: (user: UserProfile) => void;
+    /** Callback when sign-in fails */
+    onError?: (error: Error) => void;
+    /** Whether to show the "forgot password" link */
+    showForgotPassword?: boolean;
+    /** Whether to show the "sign up" link */
+    showSignUp?: boolean;
+    /** Custom class name for the form container */
+    className?: string;
+}
+/**
+ * Props for the SignUp component
+ */
+interface SignUpProps {
+    /** Callback when sign-up is successful */
+    onSuccess?: () => void;
+    /** Callback when sign-up fails */
+    onError?: (error: Error) => void;
+    /** Organization slug for registration context */
+    orgSlug?: string;
+    /** Whether to show the "sign in" link */
+    showSignIn?: boolean;
+    /** Custom class name for the form container */
+    className?: string;
+}
+/**
+ * Props for the OrganizationSwitcher component
+ */
+interface OrganizationSwitcherProps {
+    /** Callback when organization is switched */
+    onSwitch?: (org: Organization) => void;
+    /** Custom class name for the switcher container */
+    className?: string;
+    /** Render prop for custom organization item rendering */
+    renderItem?: (org: Organization, isActive: boolean) => React.ReactNode;
+}
+/**
+ * Props for the UserButton component
+ */
+interface UserButtonProps {
+    /** Custom class name for the button container */
+    className?: string;
+    /** Whether to show the user's email */
+    showEmail?: boolean;
+    /** Callback after successful logout */
+    onLogout?: () => void;
+}
+/**
+ * Props for the Protect component
+ */
+interface ProtectProps {
+    /** Required permission to access children */
+    permission?: string;
+    /** Required role to access children */
+    role?: 'owner' | 'admin' | 'member';
+    /** Fallback content when access is denied */
+    fallback?: React.ReactNode;
+    /** React children to render when access is granted */
+    children: React.ReactNode;
+}
+
+/**
+ * Provider component that wraps your app and provides AuthOS context.
+ *
+ * @example
+ * ```tsx
+ * import { AuthOSProvider } from '@drmhse/authos-react';
+ *
+ * function App() {
+ *   return (
+ *     <AuthOSProvider config={{ baseURL: 'https://auth.example.com' }}>
+ *       <YourApp />
+ *     </AuthOSProvider>
+ *   );
+ * }
+ * ```
+ */
+declare function AuthOSProvider({ config, children, client: externalClient }: AuthOSProviderProps): react_jsx_runtime.JSX.Element;
+/**
+ * Hook to access the AuthOS context.
+ * Must be used within an AuthOSProvider.
+ *
+ * @throws Error if used outside of AuthOSProvider
+ */
+declare function useAuthOSContext(): AuthOSContextState;
+
+/**
+ * Hook to access the AuthOS client and loading status.
+ *
+ * @returns The SDK client instance and loading state
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { client, isLoading } = useAuthOS();
+ *
+ *   if (isLoading) return <div>Loading...</div>;
+ *
+ *   const handleLogin = async () => {
+ *     await client.auth.login({ email, password });
+ *   };
+ * }
+ * ```
+ */
+declare function useAuthOS(): {
+    client: _drmhse_sso_sdk.SsoClient;
+    isLoading: boolean;
+    isAuthenticated: boolean;
+};
+
+/**
+ * Hook to access the current authenticated user.
+ *
+ * @returns The current user profile or null if not authenticated
+ *
+ * @example
+ * ```tsx
+ * function ProfilePage() {
+ *   const user = useUser();
+ *
+ *   if (!user) return <div>Please sign in</div>;
+ *
+ *   return <div>Welcome, {user.email}!</div>;
+ * }
+ * ```
+ */
+declare function useUser(): UserProfile | null;
+
+interface UseOrganizationReturn {
+    /** The current active organization */
+    organization: Organization | null;
+    /** Switch to a different organization by slug */
+    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.
+ *
+ * @returns The current organization and a function to switch organizations
+ *
+ * @example
+ * ```tsx
+ * function OrgSelector() {
+ *   const { organization, switchOrganization } = useOrganization();
+ *
+ *   return (
+ *     <div>
+ *       <p>Current org: {organization?.name}</p>
+ *       <button onClick={() => switchOrganization('other-org')}>
+ *         Switch to Other Org
+ *       </button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useOrganization(): UseOrganizationReturn;
+
+/**
+ * Hook to check if the current user has a specific permission.
+ *
+ * @param permission - The permission string to check for
+ * @returns True if the user has the permission, false otherwise
+ *
+ * @example
+ * ```tsx
+ * function AdminPanel() {
+ *   const canManageUsers = usePermission('users:manage');
+ *
+ *   if (!canManageUsers) {
+ *     return <div>Access denied</div>;
+ *   }
+ *
+ *   return <div>Admin Panel Content</div>;
+ * }
+ * ```
+ */
+declare function usePermission(permission: string): boolean;
+/**
+ * Hook to check if the current user has any of the specified permissions.
+ *
+ * @param permissions - Array of permission strings to check
+ * @returns True if the user has at least one of the permissions
+ *
+ * @example
+ * ```tsx
+ * function EditButton() {
+ *   const canEdit = useAnyPermission(['posts:edit', 'posts:manage']);
+ *
+ *   if (!canEdit) return null;
+ *
+ *   return <button>Edit</button>;
+ * }
+ * ```
+ */
+declare function useAnyPermission(permissions: string[]): boolean;
+/**
+ * Hook to check if the current user has all of the specified permissions.
+ *
+ * @param permissions - Array of permission strings that are all required
+ * @returns True only if the user has all of the permissions
+ *
+ * @example
+ * ```tsx
+ * function AdvancedSettings() {
+ *   const hasAccess = useAllPermissions(['settings:view', 'settings:edit']);
+ *
+ *   if (!hasAccess) return <div>Insufficient permissions</div>;
+ *
+ *   return <SettingsForm />;
+ * }
+ * ```
+ */
+declare function useAllPermissions(permissions: string[]): boolean;
+
+/**
+ * Headless SignIn component that handles email/password authentication with MFA support.
+ *
+ * @example
+ * ```tsx
+ * import { SignIn } from '@drmhse/authos-react';
+ *
+ * function LoginPage() {
+ *   return (
+ *     <SignIn
+ *       onSuccess={(user) => console.log('Logged in:', user)}
+ *       onError={(error) => console.error('Login failed:', error)}
+ *     />
+ *   );
+ * }
+ * ```
+ */
+declare function SignIn({ onSuccess, onError, showForgotPassword, showSignUp, className, }: SignInProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Headless SignUp component that handles user registration.
+ *
+ * @example
+ * ```tsx
+ * import { SignUp } from '@drmhse/authos-react';
+ *
+ * function RegisterPage() {
+ *   return (
+ *     <SignUp
+ *       onSuccess={() => console.log('Registration successful!')}
+ *       onError={(error) => console.error('Registration failed:', error)}
+ *     />
+ *   );
+ * }
+ * ```
+ */
+declare function SignUp({ onSuccess, onError, orgSlug, showSignIn, className }: SignUpProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Component for switching between organizations.
+ *
+ * @example
+ * ```tsx
+ * import { OrganizationSwitcher } from '@drmhse/authos-react';
+ *
+ * function Header() {
+ *   return (
+ *     <OrganizationSwitcher
+ *       onSwitch={(org) => console.log('Switched to:', org.name)}
+ *     />
+ *   );
+ * }
+ * ```
+ */
+declare function OrganizationSwitcher({ onSwitch, className, renderItem }: OrganizationSwitcherProps): react_jsx_runtime.JSX.Element | null;
+
+/**
+ * Component for displaying user info and handling logout.
+ *
+ * @example
+ * ```tsx
+ * import { UserButton } from '@drmhse/authos-react';
+ *
+ * function Header() {
+ *   return (
+ *     <UserButton
+ *       showEmail
+ *       onLogout={() => window.location.href = '/'}
+ *     />
+ *   );
+ * }
+ * ```
+ */
+declare function UserButton({ className, showEmail, onLogout }: UserButtonProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Component that conditionally renders children based on permission or role.
+ *
+ * @example
+ * ```tsx
+ * import { Protect } from '@drmhse/authos-react';
+ *
+ * function AdminPage() {
+ *   return (
+ *     <Protect
+ *       permission="admin:access"
+ *       fallback={<div>Access denied</div>}
+ *     >
+ *       <AdminDashboard />
+ *     </Protect>
+ *   );
+ * }
+ *
+ * // Or using role
+ * function OwnerSettings() {
+ *   return (
+ *     <Protect role="owner">
+ *       <DangerZone />
+ *     </Protect>
+ *   );
+ * }
+ * ```
+ */
+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 };