@k3-universe/react-kit 0.0.29 → 0.0.31

package/src/kit/builder/auth/components/RequireAuth.tsx

@@ -0,0 +1,78 @@
+import type { RequireAuthProps } from '../types';
+import { useAuthContext } from '../providers/AuthProvider';
+
+/**
+ * Component that requires authentication
+ * Optionally checks for specific roles and permissions
+ *
+ * @example
+ * ```tsx
+ * // Basic authentication check
+ * <RequireAuth fallback={<Login />}>
+ *   <Dashboard />
+ * </RequireAuth>
+ *
+ * // With role check
+ * <RequireAuth
+ *   roles="admin"
+ *   fallback={<Forbidden />}
+ *   loadingFallback={<Spinner />}
+ * >
+ *   <AdminPanel />
+ * </RequireAuth>
+ *
+ * // With permission check
+ * <RequireAuth
+ *   permissions={['post:edit', 'post:delete']}
+ *   fallback={<Forbidden />}
+ * >
+ *   <PostEditor />
+ * </RequireAuth>
+ *
+ * // Complex rule
+ * <RequireAuth
+ *   roles={['admin', 'moderator']}
+ *   permissions={{
+ *     operator: 'OR',
+ *     permissions: ['post:edit', 'post:delete']
+ *   }}
+ *   requireAll={false}
+ *   fallback={<Forbidden />}
+ * >
+ *   <ContentManager />
+ * </RequireAuth>
+ * ```
+ */
+export function RequireAuth<
+  TRole extends string = string,
+  TPermission extends string = string,
+>({
+  children,
+  fallback = null,
+  loadingFallback = null,
+  roles,
+  permissions,
+  requireAll = true,
+}: RequireAuthProps<TRole, TPermission>) {
+  const { status, can } = useAuthContext();
+
+  if (status === 'loading' || status === 'idle') {
+    return loadingFallback;
+  }
+
+  if (status !== 'authenticated') {
+    return fallback;
+  }
+
+  if (!roles && !permissions) {
+    return children;
+  }
+
+  const allowed = can({ roles, permissions, requireAll });
+
+  if (!allowed) {
+    return fallback;
+  }
+
+  return children;
+}

package/src/kit/builder/auth/components/ShowWhenAuthenticated.tsx

@@ -0,0 +1,10 @@
+import type { ReactNode } from 'react';
+import { useAuthContext } from '../providers/AuthProvider';
+
+/**
+ * Component that shows children only when authenticated.
+ */
+export function ShowWhenAuthenticated({ children }: { children: ReactNode }) {
+  const { status } = useAuthContext();
+  return status === 'authenticated' ? children : null;
+}

package/src/kit/builder/auth/components/ShowWhenError.tsx

@@ -0,0 +1,10 @@
+import type { ReactNode } from 'react';
+import { useAuthContext } from '../providers/AuthProvider';
+
+/**
+ * Component that shows children only when there's an error.
+ */
+export function ShowWhenError({ children }: { children: ReactNode }) {
+  const { status } = useAuthContext();
+  return status === 'error' ? children : null;
+}

package/src/kit/builder/auth/components/ShowWhenLoading.tsx

@@ -0,0 +1,10 @@
+import type { ReactNode } from 'react';
+import { useAuthContext } from '../providers/AuthProvider';
+
+/**
+ * Component that shows children only while loading.
+ */
+export function ShowWhenLoading({ children }: { children: ReactNode }) {
+  const { status } = useAuthContext();
+  return status === 'loading' ? children : null;
+}

package/src/kit/builder/auth/components/ShowWhenUnauthenticated.tsx

@@ -0,0 +1,10 @@
+import type { ReactNode } from 'react';
+import { useAuthContext } from '../providers/AuthProvider';
+
+/**
+ * Component that shows children only when NOT authenticated.
+ */
+export function ShowWhenUnauthenticated({ children }: { children: ReactNode }) {
+  const { status } = useAuthContext();
+  return status === 'unauthenticated' ? children : null;
+}

package/src/kit/builder/auth/components/withPermission.tsx

@@ -0,0 +1,23 @@
+import type { ComponentType } from 'react';
+import type { WithPermissionOptions } from '../types';
+import { useCan } from '../hooks';
+
+/**
+ * Higher-order component that wraps a component with permission checks.
+ */
+export function withPermission<
+  TRole extends string = string,
+  TPermission extends string = string,
+  TProps extends Record<string, unknown> = Record<string, unknown>,
+>(
+  Component: ComponentType<TProps>,
+  options: WithPermissionOptions<TRole, TPermission>,
+): ComponentType<TProps> {
+  const WithPermissionWrapper = (props: TProps) => {
+    const allowed = useCan(options);
+    if (!allowed) return null;
+    return <Component {...props} />;
+  };
+  WithPermissionWrapper.displayName = `WithPermission(${Component.displayName ?? Component.name ?? 'Component'})`;
+  return WithPermissionWrapper as ComponentType<TProps>;
+}

package/src/kit/builder/auth/hooks/action-hooks.ts

@@ -0,0 +1,34 @@
+import type { AuthSession } from '../types';
+import { useAuthContext } from '../providers/AuthProvider';
+
+/**
+ * Hook to get the login function.
+ */
+export function useLogin<TCredentials = unknown>() {
+  const { login } = useAuthContext();
+  return login as ((credentials: TCredentials) => Promise<unknown>) | undefined;
+}
+
+/**
+ * Hook to get the logout function.
+ */
+export function useLogout() {
+  const { logout } = useAuthContext();
+  return logout;
+}
+
+/**
+ * Hook to get the refresh function.
+ */
+export function useRefresh() {
+  const { refresh } = useAuthContext();
+  return refresh;
+}
+
+/**
+ * Hook to get the setSession function.
+ */
+export function useSetSession<TSession extends AuthSession>() {
+  const { setSession } = useAuthContext();
+  return setSession as (session: TSession | null) => Promise<unknown>;
+}

package/src/kit/builder/auth/hooks/core-hooks.ts

@@ -0,0 +1,65 @@
+import type { AuthSession } from '../types';
+import { useAuthContext } from '../providers/AuthProvider';
+
+/**
+ * Hook to access the entire auth context
+ */
+export function useAuth() {
+  return useAuthContext();
+}
+
+/**
+ * Hook to get the current auth status
+ */
+export function useAuthStatus() {
+  const { status } = useAuthContext();
+  return status;
+}
+
+/**
+ * Hook to check if user is authenticated
+ */
+export function useIsAuthenticated() {
+  const { status } = useAuthContext();
+  return status === 'authenticated';
+}
+
+/**
+ * Hook to get the current session
+ */
+export function useAuthSession<TSession extends AuthSession>() {
+  const { session } = useAuthContext();
+  return session as TSession | null;
+}
+
+/**
+ * Hook to get the current user
+ */
+export function useAuthUser<TUser>() {
+  const { user } = useAuthContext();
+  return user as TUser | null;
+}
+
+/**
+ * Hook to get user roles
+ */
+export function useAuthRoles<TRole extends string = string>() {
+  const { roles } = useAuthContext();
+  return roles as TRole[];
+}
+
+/**
+ * Hook to get user permissions
+ */
+export function useAuthPermissions<TPermission extends string = string>() {
+  const { permissions } = useAuthContext();
+  return permissions as TPermission[];
+}
+
+/**
+ * Hook to get authentication error
+ */
+export function useAuthError() {
+  const { error } = useAuthContext();
+  return error;
+}

package/src/kit/builder/auth/hooks/index.ts

@@ -0,0 +1,4 @@
+export * from './core-hooks';
+export * from './permission-hooks';
+export * from './token-hooks';
+export * from './action-hooks';

package/src/kit/builder/auth/hooks/permission-hooks.ts

@@ -0,0 +1,43 @@
+import type {
+  PermissionPolicy,
+  PermissionRule,
+  WithPermissionOptions,
+} from '../types';
+import { useAuthContext } from '../providers/AuthProvider';
+
+/**
+ * Hook to check if user has specific permission(s).
+ */
+export function usePermission<TPermission extends string = string>(
+  permission: TPermission | TPermission[] | PermissionPolicy<TPermission>,
+  options?: { requireAll?: boolean },
+) {
+  const { hasPermission } = useAuthContext();
+  return hasPermission(permission, options);
+}
+
+/**
+ * Hook to check if user has specific role(s).
+ */
+export function useRole<TRole extends string = string>(
+  roles: TRole | TRole[],
+  options?: { requireAll?: boolean },
+) {
+  const { hasRole } = useAuthContext();
+  return hasRole(roles, options);
+}
+
+/**
+ * Hook to check complex permission rules.
+ */
+export function useCan<
+  TRole extends string = string,
+  TPermission extends string = string,
+>(
+  rule:
+    | WithPermissionOptions<TRole, TPermission>
+    | PermissionRule<TRole, TPermission>,
+) {
+  const { can } = useAuthContext();
+  return can(rule as PermissionRule<TRole, TPermission>);
+}

package/src/kit/builder/auth/hooks/token-hooks.ts

@@ -0,0 +1,25 @@
+import { useAuthContext } from '../providers/AuthProvider';
+
+/**
+ * Hook to get the current auth token.
+ */
+export function useAuthToken() {
+  const { getToken } = useAuthContext();
+  return getToken();
+}
+
+/**
+ * Hook to check if token is expired.
+ */
+export function useIsTokenExpired() {
+  const { isTokenExpired } = useAuthContext();
+  return isTokenExpired();
+}
+
+/**
+ * Hook to get time until token expiry in milliseconds.
+ */
+export function useTimeUntilExpiry() {
+  const { getTimeUntilExpiry } = useAuthContext();
+  return getTimeUntilExpiry();
+}

package/src/kit/builder/auth/index.ts

@@ -2,8 +2,8 @@
 // Core
 // ============================================================================
 
-export { createAuthAdapter } from './adapter';
-export { AuthProvider, useAuthContext } from './AuthProvider';
+export { createAuthAdapter } from "./utils/auth-adapter";
+export { AuthProvider, useAuthContext } from "./providers/AuthProvider";
 
 // ============================================================================
 // Storage
@@ -14,20 +14,20 @@ export {
   createMemoryStorage,
   createBrowserStorage,
   createCookieStorage,
-} from './storage';
+} from "./utils/storage";
 
 // ============================================================================
 // Utilities
 // ============================================================================
 
-export { createTokenManager } from './token-manager';
+export { createTokenManager } from "./utils/token-manager";
 export {
   expandPermissions,
   expandRoles,
   checkPermissions,
   checkRoles,
   evaluatePermissionRule,
-} from './permission-checker';
+} from "./utils/permission-checker";
 
 // ============================================================================
 // Client Adapters
@@ -39,12 +39,12 @@ export {
   createAxiosAuthInterceptor,
   createAuthFetch,
   createApolloAuthLink,
-} from './client-adapters';
+} from "./utils/client-adapters";
 
 export type {
   GraphQLClientAdapterOptions,
   RESTClientAdapterOptions,
-} from './client-adapters';
+} from "./utils/client-adapters";
 
 // ============================================================================
 // Hooks
@@ -69,21 +69,19 @@ export {
   useLogout,
   useRefresh,
   useSetSession,
-} from './hooks';
+} from "./hooks";
 
 // ============================================================================
 // Components
 // ============================================================================
 
-export {
-  RequireAuth,
-  Can,
-  withPermission,
-  ShowWhenAuthenticated,
-  ShowWhenUnauthenticated,
-  ShowWhenLoading,
-  ShowWhenError,
-} from './components';
+export { RequireAuth } from "./components/RequireAuth";
+export { Can } from "./components/Can";
+export { withPermission } from "./components/withPermission";
+export { ShowWhenAuthenticated } from "./components/ShowWhenAuthenticated";
+export { ShowWhenUnauthenticated } from "./components/ShowWhenUnauthenticated";
+export { ShowWhenLoading } from "./components/ShowWhenLoading";
+export { ShowWhenError } from "./components/ShowWhenError";
 
 // ============================================================================
 // Types
@@ -131,4 +129,4 @@ export type {
   InferRole,
   InferPermission,
   InferCredentials,
-} from './types';
+} from "./types";

package/src/kit/builder/auth/{AuthProvider.tsx → providers/AuthProvider.tsx}

@@ -6,7 +6,7 @@ import {
   useSyncExternalStore,
 } from 'react';
 import type { ReactNode } from 'react';
-import type { AuthAdapter, AuthContextValue, AuthSession } from './types';
+import type { AuthAdapter, AuthContextValue, AuthSession } from '../types';
 
 type AnyAuthContextValue = AuthContextValue<
   unknown,

package/src/kit/builder/auth/types/adapter-config.ts

@@ -0,0 +1,44 @@
+import type { AuthSession, RefreshStrategy } from './core';
+import type { PermissionHierarchy, RoleHierarchy } from './permissions';
+import type { AuthAdapterState } from './state';
+import type { AuthMiddleware } from './middleware';
+import type { TokenManager } from './token-manager';
+import type { AuthStorage } from './storage';
+
+export type AuthAdapterConfig<
+  TUser = unknown,
+  TRole extends string = string,
+  TPermission extends string = string,
+  TSession extends AuthSession<TUser, TRole, TPermission> = AuthSession<
+    TUser,
+    TRole,
+    TPermission
+  >,
+  TCredentials = unknown,
+> = {
+  storage?: AuthStorage<TSession>;
+  loadSession?: () => Promise<TSession | null>;
+  login?: (credentials: TCredentials) => Promise<TSession>;
+  logout?: (session: TSession | null) => Promise<void> | void;
+  refresh?: (session: TSession) => Promise<TSession>;
+  resolveUser?: (session: TSession | null) => TUser | null;
+  resolveRoles?: (session: TSession | null) => TRole[];
+  resolvePermissions?: (session: TSession | null) => TPermission[];
+  shouldRefresh?: (session: TSession) => boolean;
+  onStateChange?: (
+    state: AuthAdapterState<TSession, TUser, TRole, TPermission>,
+  ) => void;
+
+  refreshStrategy?: RefreshStrategy;
+  refreshThreshold?: number;
+  autoRefresh?: boolean;
+  permissionHierarchy?: PermissionHierarchy<TPermission>;
+  roleHierarchy?: RoleHierarchy<TRole>;
+  middleware?: AuthMiddleware<TSession, TUser, TRole, TPermission>[];
+  tokenManager?: TokenManager;
+  retryConfig?: {
+    maxRetries?: number;
+    retryDelay?: number;
+    retryOn?: (error: unknown) => boolean;
+  };
+};

package/src/kit/builder/auth/types/adapter.ts

@@ -0,0 +1,132 @@
+import type { AuthSession } from './core';
+import type { PermissionPolicy, PermissionRule } from './permissions';
+import type { AuthAdapterState, AuthAdapterSubscriber } from './state';
+
+export type AuthAdapter<
+  TUser = unknown,
+  TRole extends string = string,
+  TPermission extends string = string,
+  TSession extends AuthSession<TUser, TRole, TPermission> = AuthSession<
+    TUser,
+    TRole,
+    TPermission
+  >,
+  TCredentials = unknown,
+> = {
+  getState: () => AuthAdapterState<TSession, TUser, TRole, TPermission>;
+  subscribe: (
+    listener: AuthAdapterSubscriber<TSession, TUser, TRole, TPermission>,
+  ) => () => void;
+  sync: () => Promise<AuthAdapterState<TSession, TUser, TRole, TPermission>>;
+  login?: (
+    credentials: TCredentials,
+  ) => Promise<AuthAdapterState<TSession, TUser, TRole, TPermission>>;
+  logout: () => Promise<void>;
+  refresh: () => Promise<AuthAdapterState<TSession, TUser, TRole, TPermission>>;
+  setSession: (
+    session: TSession | null,
+  ) => Promise<AuthAdapterState<TSession, TUser, TRole, TPermission>>;
+  hasRole: (
+    target: TRole | TRole[],
+    options?: { requireAll?: boolean },
+  ) => boolean;
+  hasPermission: (
+    target: TPermission | TPermission[] | PermissionPolicy<TPermission>,
+    options?: { requireAll?: boolean },
+  ) => boolean;
+  can: (rule: PermissionRule<TRole, TPermission>) => boolean;
+  getToken: () => string | null;
+  isTokenExpired: () => boolean;
+  getTimeUntilExpiry: () => number;
+  scheduleAutoRefresh?: () => () => void;
+};
+
+export type AuthContextValue<
+  TUser = unknown,
+  TRole extends string = string,
+  TPermission extends string = string,
+  TSession extends AuthSession<TUser, TRole, TPermission> = AuthSession<
+    TUser,
+    TRole,
+    TPermission
+  >,
+  TCredentials = unknown,
+> = {
+  state: AuthAdapterState<TSession, TUser, TRole, TPermission>;
+  status: AuthAdapterState<TSession, TUser, TRole, TPermission>['status'];
+  session: TSession | null;
+  user: TUser | null;
+  roles: TRole[];
+  permissions: TPermission[];
+  error?: unknown;
+  login?: (
+    credentials: TCredentials,
+  ) => Promise<AuthAdapterState<TSession, TUser, TRole, TPermission>>;
+  logout: () => Promise<void>;
+  refresh: () => Promise<AuthAdapterState<TSession, TUser, TRole, TPermission>>;
+  setSession: (
+    session: TSession | null,
+  ) => Promise<AuthAdapterState<TSession, TUser, TRole, TPermission>>;
+  hasRole: (
+    target: TRole | TRole[],
+    options?: { requireAll?: boolean },
+  ) => boolean;
+  hasPermission: (
+    target: TPermission | TPermission[] | PermissionPolicy<TPermission>,
+    options?: { requireAll?: boolean },
+  ) => boolean;
+  can: (rule: PermissionRule<TRole, TPermission>) => boolean;
+  getToken: () => string | null;
+  isTokenExpired: () => boolean;
+  getTimeUntilExpiry: () => number;
+};
+
+export type RequireAuthProps<
+  TRole extends string = string,
+  TPermission extends string = string,
+> = {
+  children: React.ReactNode;
+  fallback?: React.ReactNode;
+  loadingFallback?: React.ReactNode;
+  roles?: TRole | TRole[];
+  permissions?: TPermission | TPermission[] | PermissionPolicy<TPermission>;
+  requireAll?: boolean;
+};
+
+export type CanProps<
+  TRole extends string = string,
+  TPermission extends string = string,
+> = {
+  children: React.ReactNode;
+  fallback?: React.ReactNode;
+  roles?: TRole | TRole[];
+  permissions?: TPermission | TPermission[] | PermissionPolicy<TPermission>;
+  requireAll?: boolean;
+};
+
+export type WithPermissionOptions<
+  TRole extends string = string,
+  TPermission extends string = string,
+> = {
+  roles?: TRole | TRole[];
+  permissions?: TPermission | TPermission[] | PermissionPolicy<TPermission>;
+  requireAll?: boolean;
+};
+
+export type GraphQLAuthClient<TSession = unknown, TCredentials = unknown> = {
+  login: (credentials: TCredentials) => Promise<TSession>;
+  logout?: () => Promise<void>;
+  refresh?: (refreshToken: string) => Promise<TSession>;
+  getCurrentUser?: () => Promise<TSession>;
+};
+
+export type RESTAuthClient<TSession = unknown, TCredentials = unknown> = {
+  login: (credentials: TCredentials) => Promise<TSession>;
+  logout?: () => Promise<void>;
+  refresh?: (refreshToken: string) => Promise<TSession>;
+  getCurrentUser?: () => Promise<TSession>;
+};
+
+export type ClientAdapter<TSession = unknown, TCredentials = unknown> =
+  | GraphQLAuthClient<TSession, TCredentials>
+  | RESTAuthClient<TSession, TCredentials>;

package/src/kit/builder/auth/types/core.ts

@@ -0,0 +1,27 @@
+export type AuthStatus =
+  | 'idle'
+  | 'loading'
+  | 'authenticated'
+  | 'unauthenticated'
+  | 'error';
+
+export type TokenType = 'bearer' | 'jwt' | 'custom';
+
+export type RefreshStrategy = 'auto' | 'manual' | 'sliding';
+
+export type AuthSession<
+  TUser = unknown,
+  TRole = string,
+  TPermission = string,
+> = {
+  user?: TUser | null;
+  accessToken?: string | null;
+  refreshToken?: string | null;
+  tokenType?: TokenType;
+  roles?: TRole[] | null;
+  permissions?: TPermission[] | null;
+  expiresAt?: number | null;
+  refreshExpiresAt?: number | null;
+  issuedAt?: number | null;
+  meta?: Record<string, unknown> | null;
+};

package/src/kit/builder/auth/types/index.ts

@@ -0,0 +1,9 @@
+export * from './core';
+export * from './permissions';
+export * from './state';
+export * from './storage';
+export * from './middleware';
+export * from './token-manager';
+export * from './adapter-config';
+export * from './adapter';
+export * from './utils';

package/src/kit/builder/auth/types/middleware.ts

@@ -0,0 +1,20 @@
+import type { AuthAdapterState } from './state';
+
+export type AuthMiddleware<
+  TSession = unknown,
+  TUser = unknown,
+  TRole extends string = string,
+  TPermission extends string = string,
+> = {
+  onBeforeLogin?: (credentials: unknown) => Promise<void> | void;
+  onAfterLogin?: (
+    state: AuthAdapterState<TSession, TUser, TRole, TPermission>,
+  ) => Promise<void> | void;
+  onBeforeLogout?: () => Promise<void> | void;
+  onAfterLogout?: () => Promise<void> | void;
+  onRefresh?: (
+    state: AuthAdapterState<TSession, TUser, TRole, TPermission>,
+  ) => Promise<void> | void;
+  onError?: (error: unknown) => Promise<void> | void;
+  onSessionExpired?: () => Promise<void> | void;
+};

package/src/kit/builder/auth/types/permissions.ts

@@ -0,0 +1,23 @@
+export type PermissionOperator = 'AND' | 'OR';
+
+export type PermissionPolicy<TPermission extends string = string> = {
+  operator?: PermissionOperator;
+  permissions: TPermission[];
+};
+
+export type PermissionRule<
+  TRole extends string = string,
+  TPermission extends string = string,
+> = {
+  roles?: TRole | TRole[];
+  permissions?: TPermission | TPermission[] | PermissionPolicy<TPermission>;
+  requireAll?: boolean;
+};
+
+export type PermissionHierarchy<TPermission extends string = string> = {
+  [key in TPermission]?: TPermission[];
+};
+
+export type RoleHierarchy<TRole extends string = string> = {
+  [key in TRole]?: TRole[];
+};