@stackwright-pro/auth 0.2.0-alpha.14 → 0.2.0-alpha.15

package/dist/client.d.mts

@@ -0,0 +1,197 @@
+import * as React from 'react';
+import React__default, { ReactNode, ReactElement } from 'react';
+import { AuthUser, AuthSession, RBACConfig, ComponentAuthConfig } from '@stackwright-pro/types';
+
+/**
+ * Auth context value provided to component tree
+ */
+interface AuthContextValue {
+    /**
+     * Currently authenticated user (null if not authenticated)
+     */
+    user: AuthUser | null;
+    /**
+     * Current session (null if not authenticated)
+     */
+    session: AuthSession | null;
+    /**
+     * Whether user is authenticated
+     */
+    isAuthenticated: boolean;
+    /**
+     * Whether auth is still loading
+     */
+    isLoading: boolean;
+    /**
+     * Check if user has a specific role
+     */
+    hasRole: (role: string) => boolean;
+    /**
+     * Check if user has a specific permission
+     */
+    hasPermission: (permission: string) => boolean;
+    /**
+     * Check if user has any of the specified roles
+     */
+    hasAnyRole: (roles: string[]) => boolean;
+    /**
+     * Check if user has all of the specified permissions
+     */
+    hasAllPermissions: (permissions: string[]) => boolean;
+}
+/**
+ * Auth context - provides authentication state to components
+ */
+declare const AuthContext: React.Context<AuthContextValue | null>;
+/**
+ * Hook to access auth context
+ * Throws error if used outside AuthProvider
+ */
+declare function useAuth(): AuthContextValue;
+/**
+ * Hook to require authentication
+ * Returns null and logs warning if not authenticated
+ */
+declare function useRequireAuth(): AuthContextValue | null;
+
+interface AuthProviderProps {
+    /**
+     * Current authenticated user (null if not authenticated)
+     */
+    user: AuthUser | null;
+    /**
+     * Current session (null if not authenticated)
+     */
+    session: AuthSession | null;
+    /**
+     * RBAC configuration for role/permission checking
+     */
+    rbacConfig: RBACConfig;
+    /**
+     * Whether auth is still loading
+     */
+    isLoading?: boolean;
+    /**
+     * Child components
+     */
+    children: ReactNode;
+}
+/**
+ * AuthProvider - Provides authentication state to component tree
+ *
+ * @example
+ * ```tsx
+ * <AuthProvider user={user} session={session} rbacConfig={config}>
+ *   <App />
+ * </AuthProvider>
+ * ```
+ */
+declare function AuthProvider({ user, session, rbacConfig, isLoading, children, }: AuthProviderProps): ReactElement;
+
+/**
+ * Props that any component wrapped with withAuth will receive
+ */
+interface ComponentProps {
+    id?: string;
+    [key: string]: any;
+}
+/**
+ * Higher-order component that wraps a component with authentication checks
+ *
+ * @example
+ * ```tsx
+ * const ProtectedButton = withAuth(Button, {
+ *   required_roles: ['ADMIN'],
+ *   fallback: 'message',
+ *   fallback_message: 'Only admins can see this button'
+ * });
+ * ```
+ *
+ * @param Component - The component to wrap
+ * @param authConfig - Authentication requirements from YAML
+ * @returns Wrapped component with auth enforcement
+ */
+declare function withAuth<P extends ComponentProps>(Component: React__default.ComponentType<P>, authConfig?: ComponentAuthConfig): React__default.ComponentType<P>;
+/**
+ * Custom fallback component (for advanced use cases)
+ */
+declare function withAuthFallback<P extends ComponentProps>(Component: React__default.ComponentType<P>, authConfig: ComponentAuthConfig, FallbackComponent: React__default.ComponentType<any>): React__default.ComponentType<P>;
+
+/**
+ * Register the auth decorator for use by content renderers
+ *
+ * This should be called once in your app's initialization (e.g., _app.tsx)
+ * to enable auth-aware component rendering.
+ *
+ * @example
+ * ```tsx
+ * // In pages/_app.tsx
+ * import { registerAuthDecorator } from '@stackwright-pro/auth';
+ *
+ * registerAuthDecorator();
+ *
+ * function MyApp({ Component, pageProps }: AppProps) {
+ *   return (
+ *     <AuthProvider {...authProps}>
+ *       <Component {...pageProps} />
+ *     </AuthProvider>
+ *   );
+ * }
+ * ```
+ */
+declare function registerAuthDecorator(): void;
+/**
+ * Get the registered auth decorator (for use by content renderers)
+ *
+ * Returns null if auth is not registered, allowing graceful degradation.
+ * This is the function that OSS core would call to check if auth is available.
+ *
+ * @returns The withAuth decorator function, or null if not registered
+ */
+declare function getAuthDecorator(): typeof withAuth | null;
+/**
+ * Wrap a component with auth if decorator is registered and config exists
+ *
+ * This is a safe wrapper that OSS packages can use without depending on auth.
+ * If auth is not registered, returns the original component unchanged.
+ * If auth config is missing/undefined, returns the original component unchanged.
+ *
+ * @example
+ * ```tsx
+ * // In content renderer (can live in OSS core!)\n * function renderContentItem(item: ContentItem) {
+ *   const Component = getComponentFromRegistry(item.type);
+ *
+ *   // Apply auth if available
+ *   const WrappedComponent = maybeWrapWithAuth(Component, item.auth);
+ *
+ *   return <WrappedComponent {...item} />;
+ * }
+ * ```
+ *
+ * @param Component - Component to wrap
+ * @param authConfig - Auth configuration from YAML (optional)
+ * @returns Wrapped component if auth is registered, original component otherwise
+ */
+declare function maybeWrapWithAuth<P extends {
+    id?: string;
+    [key: string]: any;
+}>(Component: React__default.ComponentType<P>, authConfig?: ComponentAuthConfig): React__default.ComponentType<P>;
+/**
+ * Type guard to check if content item has auth config
+ *
+ * Useful for conditionally applying auth in renderers without
+ * needing to import auth types.
+ *
+ * @example
+ * ```tsx
+ * if (hasAuthConfig(item)) {
+ *   // TypeScript knows item.auth exists
+ *   WrappedComponent = maybeWrapWithAuth(Component, item.auth);
+ * }
+ * ```
+ */
+declare function hasAuthConfig(item: any): item is {
+    auth: ComponentAuthConfig;
+};
+
+export { AuthContext, type AuthContextValue, AuthProvider, type AuthProviderProps, type ComponentProps, getAuthDecorator, hasAuthConfig, maybeWrapWithAuth, registerAuthDecorator, useAuth, useRequireAuth, withAuth, withAuthFallback };

package/dist/client.d.ts

@@ -0,0 +1,197 @@
+import * as React from 'react';
+import React__default, { ReactNode, ReactElement } from 'react';
+import { AuthUser, AuthSession, RBACConfig, ComponentAuthConfig } from '@stackwright-pro/types';
+
+/**
+ * Auth context value provided to component tree
+ */
+interface AuthContextValue {
+    /**
+     * Currently authenticated user (null if not authenticated)
+     */
+    user: AuthUser | null;
+    /**
+     * Current session (null if not authenticated)
+     */
+    session: AuthSession | null;
+    /**
+     * Whether user is authenticated
+     */
+    isAuthenticated: boolean;
+    /**
+     * Whether auth is still loading
+     */
+    isLoading: boolean;
+    /**
+     * Check if user has a specific role
+     */
+    hasRole: (role: string) => boolean;
+    /**
+     * Check if user has a specific permission
+     */
+    hasPermission: (permission: string) => boolean;
+    /**
+     * Check if user has any of the specified roles
+     */
+    hasAnyRole: (roles: string[]) => boolean;
+    /**
+     * Check if user has all of the specified permissions
+     */
+    hasAllPermissions: (permissions: string[]) => boolean;
+}
+/**
+ * Auth context - provides authentication state to components
+ */
+declare const AuthContext: React.Context<AuthContextValue | null>;
+/**
+ * Hook to access auth context
+ * Throws error if used outside AuthProvider
+ */
+declare function useAuth(): AuthContextValue;
+/**
+ * Hook to require authentication
+ * Returns null and logs warning if not authenticated
+ */
+declare function useRequireAuth(): AuthContextValue | null;
+
+interface AuthProviderProps {
+    /**
+     * Current authenticated user (null if not authenticated)
+     */
+    user: AuthUser | null;
+    /**
+     * Current session (null if not authenticated)
+     */
+    session: AuthSession | null;
+    /**
+     * RBAC configuration for role/permission checking
+     */
+    rbacConfig: RBACConfig;
+    /**
+     * Whether auth is still loading
+     */
+    isLoading?: boolean;
+    /**
+     * Child components
+     */
+    children: ReactNode;
+}
+/**
+ * AuthProvider - Provides authentication state to component tree
+ *
+ * @example
+ * ```tsx
+ * <AuthProvider user={user} session={session} rbacConfig={config}>
+ *   <App />
+ * </AuthProvider>
+ * ```
+ */
+declare function AuthProvider({ user, session, rbacConfig, isLoading, children, }: AuthProviderProps): ReactElement;
+
+/**
+ * Props that any component wrapped with withAuth will receive
+ */
+interface ComponentProps {
+    id?: string;
+    [key: string]: any;
+}
+/**
+ * Higher-order component that wraps a component with authentication checks
+ *
+ * @example
+ * ```tsx
+ * const ProtectedButton = withAuth(Button, {
+ *   required_roles: ['ADMIN'],
+ *   fallback: 'message',
+ *   fallback_message: 'Only admins can see this button'
+ * });
+ * ```
+ *
+ * @param Component - The component to wrap
+ * @param authConfig - Authentication requirements from YAML
+ * @returns Wrapped component with auth enforcement
+ */
+declare function withAuth<P extends ComponentProps>(Component: React__default.ComponentType<P>, authConfig?: ComponentAuthConfig): React__default.ComponentType<P>;
+/**
+ * Custom fallback component (for advanced use cases)
+ */
+declare function withAuthFallback<P extends ComponentProps>(Component: React__default.ComponentType<P>, authConfig: ComponentAuthConfig, FallbackComponent: React__default.ComponentType<any>): React__default.ComponentType<P>;
+
+/**
+ * Register the auth decorator for use by content renderers
+ *
+ * This should be called once in your app's initialization (e.g., _app.tsx)
+ * to enable auth-aware component rendering.
+ *
+ * @example
+ * ```tsx
+ * // In pages/_app.tsx
+ * import { registerAuthDecorator } from '@stackwright-pro/auth';
+ *
+ * registerAuthDecorator();
+ *
+ * function MyApp({ Component, pageProps }: AppProps) {
+ *   return (
+ *     <AuthProvider {...authProps}>
+ *       <Component {...pageProps} />
+ *     </AuthProvider>
+ *   );
+ * }
+ * ```
+ */
+declare function registerAuthDecorator(): void;
+/**
+ * Get the registered auth decorator (for use by content renderers)
+ *
+ * Returns null if auth is not registered, allowing graceful degradation.
+ * This is the function that OSS core would call to check if auth is available.
+ *
+ * @returns The withAuth decorator function, or null if not registered
+ */
+declare function getAuthDecorator(): typeof withAuth | null;
+/**
+ * Wrap a component with auth if decorator is registered and config exists
+ *
+ * This is a safe wrapper that OSS packages can use without depending on auth.
+ * If auth is not registered, returns the original component unchanged.
+ * If auth config is missing/undefined, returns the original component unchanged.
+ *
+ * @example
+ * ```tsx
+ * // In content renderer (can live in OSS core!)\n * function renderContentItem(item: ContentItem) {
+ *   const Component = getComponentFromRegistry(item.type);
+ *
+ *   // Apply auth if available
+ *   const WrappedComponent = maybeWrapWithAuth(Component, item.auth);
+ *
+ *   return <WrappedComponent {...item} />;
+ * }
+ * ```
+ *
+ * @param Component - Component to wrap
+ * @param authConfig - Auth configuration from YAML (optional)
+ * @returns Wrapped component if auth is registered, original component otherwise
+ */
+declare function maybeWrapWithAuth<P extends {
+    id?: string;
+    [key: string]: any;
+}>(Component: React__default.ComponentType<P>, authConfig?: ComponentAuthConfig): React__default.ComponentType<P>;
+/**
+ * Type guard to check if content item has auth config
+ *
+ * Useful for conditionally applying auth in renderers without
+ * needing to import auth types.
+ *
+ * @example
+ * ```tsx
+ * if (hasAuthConfig(item)) {
+ *   // TypeScript knows item.auth exists
+ *   WrappedComponent = maybeWrapWithAuth(Component, item.auth);
+ * }
+ * ```
+ */
+declare function hasAuthConfig(item: any): item is {
+    auth: ComponentAuthConfig;
+};
+
+export { AuthContext, type AuthContextValue, AuthProvider, type AuthProviderProps, type ComponentProps, getAuthDecorator, hasAuthConfig, maybeWrapWithAuth, registerAuthDecorator, useAuth, useRequireAuth, withAuth, withAuthFallback };