@k3-universe/react-kit 0.0.28 → 0.0.30

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

@@ -0,0 +1,132 @@
+// ============================================================================
+// Core
+// ============================================================================
+
+export { createAuthAdapter } from "./utils/auth-adapter";
+export { AuthProvider, useAuthContext } from "./providers/AuthProvider";
+
+// ============================================================================
+// Storage
+// ============================================================================
+
+export {
+  createStorage,
+  createMemoryStorage,
+  createBrowserStorage,
+  createCookieStorage,
+} from "./utils/storage";
+
+// ============================================================================
+// Utilities
+// ============================================================================
+
+export { createTokenManager } from "./utils/token-manager";
+export {
+  expandPermissions,
+  expandRoles,
+  checkPermissions,
+  checkRoles,
+  evaluatePermissionRule,
+} from "./utils/permission-checker";
+
+// ============================================================================
+// Client Adapters
+// ============================================================================
+
+export {
+  createGraphQLAuthAdapter,
+  createRESTAuthAdapter,
+  createAxiosAuthInterceptor,
+  createAuthFetch,
+  createApolloAuthLink,
+} from "./utils/client-adapters";
+
+export type {
+  GraphQLClientAdapterOptions,
+  RESTClientAdapterOptions,
+} from "./utils/client-adapters";
+
+// ============================================================================
+// Hooks
+// ============================================================================
+
+export {
+  useAuth,
+  useAuthStatus,
+  useIsAuthenticated,
+  useAuthSession,
+  useAuthUser,
+  useAuthRoles,
+  useAuthPermissions,
+  useAuthError,
+  usePermission,
+  useRole,
+  useCan,
+  useAuthToken,
+  useIsTokenExpired,
+  useTimeUntilExpiry,
+  useLogin,
+  useLogout,
+  useRefresh,
+  useSetSession,
+} from "./hooks";
+
+// ============================================================================
+// 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
+// ============================================================================
+
+export type {
+  // Core types
+  AuthStatus,
+  TokenType,
+  RefreshStrategy,
+  AuthSession,
+  // Permission types
+  PermissionOperator,
+  PermissionPolicy,
+  PermissionRule,
+  PermissionHierarchy,
+  RoleHierarchy,
+  // State types
+  AuthAdapterState,
+  AuthAdapterSubscriber,
+  // Storage types
+  AuthStorage,
+  StorageType,
+  StorageOptions,
+  // Middleware types
+  AuthMiddleware,
+  // Token manager types
+  TokenManager,
+  // Adapter types
+  AuthAdapterConfig,
+  AuthAdapter,
+  // Context types
+  AuthContextValue,
+  // Component prop types
+  RequireAuthProps,
+  CanProps,
+  WithPermissionOptions,
+  // Client adapter types
+  GraphQLAuthClient,
+  RESTAuthClient,
+  ClientAdapter,
+  // Utility types
+  InferSession,
+  InferUser,
+  InferRole,
+  InferPermission,
+  InferCredentials,
+} from "./types";

package/src/kit/builder/auth/providers/AuthProvider.tsx

@@ -0,0 +1,131 @@
+import {
+  createContext,
+  useContext,
+  useEffect,
+  useMemo,
+  useSyncExternalStore,
+} from 'react';
+import type { ReactNode } from 'react';
+import type { AuthAdapter, AuthContextValue, AuthSession } from '../types';
+
+type AnyAuthContextValue = AuthContextValue<
+  unknown,
+  string,
+  string,
+  AuthSession<unknown, string, string>,
+  unknown
+>;
+
+const AuthContext = createContext<AnyAuthContextValue | undefined>(undefined);
+
+type AuthProviderProps<
+  TUser = unknown,
+  TRole extends string = string,
+  TPermission extends string = string,
+  TSession extends AuthSession<TUser, TRole, TPermission> = AuthSession<
+    TUser,
+    TRole,
+    TPermission
+  >,
+  TCredentials = unknown,
+> = {
+  adapter: AuthAdapter<TUser, TRole, TPermission, TSession, TCredentials>;
+  children: ReactNode;
+  autoSync?: boolean;
+};
+
+/**
+ * AuthProvider component - wraps your app with authentication context
+ *
+ * @example
+ * ```tsx
+ * import { AuthProvider, createAuthAdapter } from '@k3mart/react-kit/auth2';
+ *
+ * const authAdapter = createAuthAdapter({
+ *   // ... configuration
+ * });
+ *
+ * function App() {
+ *   return (
+ *     <AuthProvider adapter={authAdapter}>
+ *       <YourApp />
+ *     </AuthProvider>
+ *   );
+ * }
+ * ```
+ */
+export function AuthProvider<
+  TUser = unknown,
+  TRole extends string = string,
+  TPermission extends string = string,
+  TSession extends AuthSession<TUser, TRole, TPermission> = AuthSession<
+    TUser,
+    TRole,
+    TPermission
+  >,
+  TCredentials = unknown,
+>({
+  adapter,
+  children,
+  autoSync = true,
+}: AuthProviderProps<TUser, TRole, TPermission, TSession, TCredentials>) {
+  const state = useSyncExternalStore(
+    adapter.subscribe,
+    adapter.getState,
+    adapter.getState,
+  );
+
+  useEffect(() => {
+    if (!autoSync) return;
+    adapter.sync().catch(() => undefined);
+  }, [adapter, autoSync]);
+
+  const value = useMemo<
+    AuthContextValue<TUser, TRole, TPermission, TSession, TCredentials>
+  >(() => {
+    const login = adapter.login
+      ? async (credentials: TCredentials) => {
+          if (!adapter.login) {
+            throw new Error('Login is not configured');
+          }
+          return await adapter.login(credentials);
+        }
+      : undefined;
+
+    return {
+      state,
+      status: state.status,
+      session: state.session,
+      user: state.user,
+      roles: state.roles,
+      permissions: state.permissions,
+      error: state.error,
+      login,
+      logout: adapter.logout,
+      refresh: adapter.refresh,
+      setSession: adapter.setSession,
+      hasRole: adapter.hasRole,
+      hasPermission: adapter.hasPermission,
+      can: adapter.can,
+      getToken: adapter.getToken,
+      isTokenExpired: adapter.isTokenExpired,
+      getTimeUntilExpiry: adapter.getTimeUntilExpiry,
+    };
+  }, [adapter, state]);
+
+  const contextValue = value as unknown as AnyAuthContextValue;
+
+  return (
+    <AuthContext.Provider value={contextValue}>{children}</AuthContext.Provider>
+  );
+}
+
+/**
+ * Hook to access auth context
+ * Must be used within AuthProvider
+ */
+export function useAuthContext(): AnyAuthContextValue {
+  const ctx = useContext(AuthContext);
+  if (!ctx) throw new Error('useAuthContext must be used within AuthProvider');
+  return ctx;
+}

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[];
+};

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

@@ -0,0 +1,16 @@
+import type { AuthStatus } from './core';
+
+export type AuthAdapterState<TSession, TUser, TRole, TPermission> = {
+  status: AuthStatus;
+  session: TSession | null;
+  user: TUser | null;
+  roles: TRole[];
+  permissions: TPermission[];
+  error?: unknown;
+  lastRefresh?: number;
+  tokenExpiresIn?: number;
+};
+
+export type AuthAdapterSubscriber<TSession, TUser, TRole, TPermission> = (
+  state: AuthAdapterState<TSession, TUser, TRole, TPermission>,
+) => void;

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

@@ -0,0 +1,21 @@
+export type AuthStorage<TSession> = {
+  get: () => Promise<TSession | null> | TSession | null;
+  set: (value: TSession | null) => Promise<void> | void;
+  clear: () => Promise<void> | void;
+};
+
+export type StorageType = 'local' | 'session' | 'cookie' | 'memory';
+
+export type StorageOptions = {
+  key?: string;
+  encrypt?: boolean;
+  encryptionKey?: string;
+  storage?: StorageType;
+  cookieOptions?: {
+    domain?: string;
+    path?: string;
+    secure?: boolean;
+    sameSite?: 'strict' | 'lax' | 'none';
+    maxAge?: number;
+  };
+};

package/src/kit/builder/auth/types/token-manager.ts

@@ -0,0 +1,9 @@
+export type TokenManager = {
+  isExpired: (expiresAt?: number | null) => boolean;
+  shouldRefresh: (expiresAt?: number | null, threshold?: number) => boolean;
+  getTimeUntilExpiry: (expiresAt?: number | null) => number;
+  scheduleRefresh?: (
+    callback: () => void,
+    expiresAt?: number | null,
+  ) => () => void;
+};

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

@@ -0,0 +1,55 @@
+// ============================================================================
+// Utility Types
+// ============================================================================
+
+import type { AuthAdapter } from "./adapter";
+
+export type InferSession<T> = T extends AuthAdapter<
+  infer _User,
+  infer _Role extends string,
+  infer _Permission extends string,
+  infer TSession,
+  infer _Credentials
+>
+  ? TSession
+  : never;
+
+export type InferUser<T> = T extends AuthAdapter<
+  infer TUser,
+  infer _Role extends string,
+  infer _Permission extends string,
+  infer _Session,
+  infer _Credentials
+>
+  ? TUser
+  : never;
+
+export type InferRole<T> = T extends AuthAdapter<
+  infer _User,
+  infer TRole extends string,
+  infer _Permission extends string,
+  infer _Session,
+  infer _Credentials
+>
+  ? TRole
+  : never;
+
+export type InferPermission<T> = T extends AuthAdapter<
+  infer _User,
+  infer _Role extends string,
+  infer TPermission extends string,
+  infer _Session,
+  infer _Credentials
+>
+  ? TPermission
+  : never;
+
+export type InferCredentials<T> = T extends AuthAdapter<
+  infer _User,
+  infer _Role extends string,
+  infer _Permission extends string,
+  infer _Session,
+  infer TCredentials
+>
+  ? TCredentials
+  : never;