@ram_28/kf-ai-sdk 1.0.1 → 1.0.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ram_28/kf-ai-sdk",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "Type-safe, AI-driven SDK for building modern web applications with role-based access control",
   "author": "Ramprasad",
   "license": "MIT",

package/sdk/auth/AuthProvider.tsx

@@ -0,0 +1,277 @@
+// ============================================================
+// AUTH PROVIDER COMPONENT
+// ============================================================
+// React Context Provider for authentication state
+
+import React, {
+  createContext,
+  useContext,
+  useCallback,
+  useEffect,
+  useMemo,
+  useState,
+  useRef,
+} from "react";
+import { useQuery, useQueryClient } from "@tanstack/react-query";
+
+import type {
+  AuthContextValue,
+  AuthProviderProps,
+  AuthStatus,
+  UserDetails,
+  SessionResponse,
+  AuthProviderName,
+  LoginOptions,
+  LogoutOptions,
+} from "./types";
+
+import {
+  fetchSession,
+  initiateLogin,
+  performLogout,
+  AuthenticationError,
+} from "./authClient";
+import { getAuthConfig, configureAuth } from "./authConfig";
+
+// ============================================================
+// CONTEXT
+// ============================================================
+
+const AuthContext = createContext<AuthContextValue | null>(null);
+
+const SESSION_QUERY_KEY = ["auth", "session"] as const;
+
+// ============================================================
+// PROVIDER COMPONENT
+// ============================================================
+
+export function AuthProvider({
+  children,
+  config: configOverride,
+  onAuthChange,
+  onError,
+  loadingComponent,
+  unauthenticatedComponent,
+  skipInitialCheck = false,
+}: AuthProviderProps): React.ReactElement {
+  const configApplied = useRef(false);
+
+  if (configOverride && !configApplied.current) {
+    configureAuth(configOverride);
+    configApplied.current = true;
+  }
+
+  const queryClient = useQueryClient();
+  const authConfig = getAuthConfig();
+
+  // ============================================================
+  // SESSION QUERY
+  // ============================================================
+
+  const {
+    data: sessionData,
+    isLoading,
+    error: queryError,
+    refetch,
+    isFetching,
+  } = useQuery<SessionResponse, Error>({
+    queryKey: SESSION_QUERY_KEY,
+    queryFn: fetchSession,
+    enabled: !skipInitialCheck,
+    retry: (failureCount, error) => {
+      if (error instanceof AuthenticationError) {
+        if (error.statusCode === 401 || error.statusCode === 403) {
+          return false;
+        }
+      }
+      return failureCount < authConfig.retry.count;
+    },
+    retryDelay: authConfig.retry.delay,
+    staleTime: authConfig.staleTime,
+    gcTime: authConfig.staleTime * 2,
+    refetchOnWindowFocus: authConfig.refetchOnWindowFocus ?? true,
+    refetchOnReconnect: authConfig.refetchOnReconnect ?? true,
+    refetchInterval: authConfig.sessionCheckInterval || false,
+  });
+
+  // ============================================================
+  // DERIVED STATE
+  // ============================================================
+
+  const [error, setError] = useState<Error | null>(null);
+
+  const status: AuthStatus = useMemo(() => {
+    if (isLoading || isFetching) return "loading";
+    if (sessionData?.userDetails) return "authenticated";
+    return "unauthenticated";
+  }, [isLoading, isFetching, sessionData]);
+
+  const user: UserDetails | null = sessionData?.userDetails || null;
+  const staticBaseUrl: string | null = sessionData?.staticBaseUrl || null;
+  const buildId: string | null = sessionData?.buildId || null;
+  const isAuthenticated = status === "authenticated";
+
+  // ============================================================
+  // REFS FOR CALLBACKS
+  // ============================================================
+
+  const onAuthChangeRef = useRef(onAuthChange);
+  onAuthChangeRef.current = onAuthChange;
+
+  const onErrorRef = useRef(onError);
+  onErrorRef.current = onError;
+
+  // ============================================================
+  // EFFECTS
+  // ============================================================
+
+  useEffect(() => {
+    if (!isLoading) {
+      onAuthChangeRef.current?.(status, user);
+    }
+  }, [status, user, isLoading]);
+
+  useEffect(() => {
+    if (queryError) {
+      setError(queryError);
+      onErrorRef.current?.(queryError);
+    }
+  }, [queryError]);
+
+  useEffect(() => {
+    if (
+      status === "unauthenticated" &&
+      authConfig.autoRedirect &&
+      !isLoading
+    ) {
+      initiateLogin();
+    }
+  }, [status, isLoading, authConfig.autoRedirect]);
+
+  // ============================================================
+  // AUTH OPERATIONS
+  // ============================================================
+
+  const login = useCallback(
+    (provider?: AuthProviderName, options?: LoginOptions) => {
+      initiateLogin(provider, options);
+    },
+    []
+  );
+
+  const logout = useCallback(
+    async (options?: LogoutOptions) => {
+      queryClient.removeQueries({ queryKey: SESSION_QUERY_KEY });
+      await performLogout(options);
+    },
+    [queryClient]
+  );
+
+  const refreshSession = useCallback(async (): Promise<SessionResponse | null> => {
+    // Prevent concurrent refreshes - return existing data if already fetching
+    if (isFetching) {
+      return sessionData || null;
+    }
+
+    try {
+      const result = await refetch();
+      return result.data || null;
+    } catch (err) {
+      setError(err as Error);
+      return null;
+    }
+  }, [refetch, isFetching, sessionData]);
+
+  const hasRole = useCallback(
+    (role: string): boolean => {
+      return user?.Role === role;
+    },
+    [user]
+  );
+
+  const hasAnyRole = useCallback(
+    (roles: string[]): boolean => {
+      return roles.includes(user?.Role || "");
+    },
+    [user]
+  );
+
+  const clearError = useCallback(() => {
+    setError(null);
+  }, []);
+
+  const _forceCheck = useCallback(() => {
+    refetch();
+  }, [refetch]);
+
+  // ============================================================
+  // CONTEXT VALUE
+  // ============================================================
+
+  const contextValue: AuthContextValue = useMemo(
+    () => ({
+      user,
+      staticBaseUrl,
+      buildId,
+      status,
+      isAuthenticated,
+      isLoading,
+      login,
+      logout,
+      refreshSession,
+      hasRole,
+      hasAnyRole,
+      error,
+      clearError,
+      _forceCheck,
+    }),
+    [
+      user,
+      staticBaseUrl,
+      buildId,
+      status,
+      isAuthenticated,
+      isLoading,
+      login,
+      logout,
+      refreshSession,
+      hasRole,
+      hasAnyRole,
+      error,
+      clearError,
+      _forceCheck,
+    ]
+  );
+
+  // ============================================================
+  // RENDER
+  // ============================================================
+
+  if (status === "loading" && loadingComponent) {
+    return <>{loadingComponent}</>;
+  }
+
+  if (
+    status === "unauthenticated" &&
+    !authConfig.autoRedirect &&
+    unauthenticatedComponent
+  ) {
+    return <>{unauthenticatedComponent}</>;
+  }
+
+  return (
+    <AuthContext.Provider value={contextValue}>{children}</AuthContext.Provider>
+  );
+}
+
+// ============================================================
+// CONTEXT HOOK (internal)
+// ============================================================
+
+export function useAuthContext(): AuthContextValue {
+  const context = useContext(AuthContext);
+  if (!context) {
+    throw new Error("useAuth must be used within an AuthProvider");
+  }
+  return context;
+}

package/sdk/auth/authClient.ts

@@ -0,0 +1,175 @@
+// ============================================================
+// AUTH API CLIENT
+// ============================================================
+// Low-level functions for authentication API calls
+
+import type {
+  SessionResponse,
+  AuthProviderName,
+  LoginOptions,
+  LogoutOptions,
+} from "./types";
+import {
+  getAuthBaseUrl,
+  getAuthConfig,
+  getProviderConfig,
+} from "./authConfig";
+import { getDefaultHeaders } from "../api/client";
+
+/**
+ * Custom error class for authentication errors
+ */
+export class AuthenticationError extends Error {
+  public readonly statusCode: number;
+
+  constructor(message: string, statusCode: number) {
+    super(message);
+    this.name = "AuthenticationError";
+    this.statusCode = statusCode;
+  }
+}
+
+/**
+ * Fetch current session from the server
+ * Calls the session endpoint (default: /api/id)
+ *
+ * @throws AuthenticationError if session check fails or user is not authenticated
+ */
+export async function fetchSession(): Promise<SessionResponse> {
+  const config = getAuthConfig();
+  const baseUrl = getAuthBaseUrl();
+  const headers = getDefaultHeaders();
+
+  const response = await fetch(`${baseUrl}${config.sessionEndpoint}`, {
+    method: "GET",
+    headers,
+    credentials: "include",
+  });
+
+  if (!response.ok) {
+    if (response.status === 401 || response.status === 403) {
+      throw new AuthenticationError("Not authenticated", response.status);
+    }
+    throw new AuthenticationError(
+      `Session check failed: ${response.statusText}`,
+      response.status
+    );
+  }
+
+  const data: SessionResponse = await response.json();
+  return data;
+}
+
+/**
+ * Initiates OAuth login flow by redirecting to the auth provider.
+ *
+ * @remarks
+ * This function redirects the browser and never resolves.
+ * Any code after calling this function will not execute.
+ *
+ * @param provider - OAuth provider to use (defaults to config.defaultProvider)
+ * @param options - Login options including callback URL and custom params
+ * @returns Promise that never resolves (browser redirects away)
+ *
+ * @example
+ * ```typescript
+ * // Correct usage - no code after login()
+ * function handleLoginClick() {
+ *   login('google');
+ *   // Don't put code here - it won't run
+ * }
+ * ```
+ */
+export function initiateLogin(
+  provider?: AuthProviderName,
+  options?: LoginOptions
+): Promise<never> {
+  return new Promise(() => {
+    const config = getAuthConfig();
+    const baseUrl = getAuthBaseUrl();
+
+    // Validate base URL
+    if (!baseUrl) {
+      throw new Error(
+        'Auth base URL is not configured. Call setApiBaseUrl("https://...") or configureAuth({ baseUrl: "https://..." }) first.'
+      );
+    }
+
+    const selectedProvider = provider || config.defaultProvider;
+    const providerConfig = getProviderConfig(selectedProvider);
+
+    // Validate provider config
+    if (!providerConfig) {
+      const availableProviders = Object.keys(config.providers || {}).join(", ") || "none";
+      throw new Error(
+        `Auth provider "${selectedProvider}" is not configured. Available providers: ${availableProviders}`
+      );
+    }
+
+    // Validate login path
+    if (!providerConfig.loginPath) {
+      throw new Error(
+        `Login path not configured for provider "${selectedProvider}". ` +
+        `Configure it with: configureAuth({ providers: { ${selectedProvider}: { loginPath: '/api/auth/...' } } })`
+      );
+    }
+
+    // Validate URL construction
+    let loginUrl: URL;
+    try {
+      loginUrl = new URL(`${baseUrl}${providerConfig.loginPath}`);
+    } catch {
+      throw new Error(
+        `Failed to construct login URL. Base URL: "${baseUrl}", Login path: "${providerConfig.loginPath}". ` +
+        `Ensure baseUrl is a valid URL (e.g., "https://example.com").`
+      );
+    }
+
+    if (options?.callbackUrl || config.callbackUrl) {
+      loginUrl.searchParams.set(
+        "callbackUrl",
+        options?.callbackUrl || config.callbackUrl || window.location.href
+      );
+    }
+
+    if (options?.params) {
+      Object.entries(options.params).forEach(([key, value]) => {
+        loginUrl.searchParams.set(key, value);
+      });
+    }
+
+    window.location.href = loginUrl.toString();
+    // Promise never resolves - browser navigates away
+  });
+}
+
+/**
+ * Logout the current user
+ * Optionally calls the logout endpoint before clearing client state
+ */
+export async function performLogout(options?: LogoutOptions): Promise<void> {
+  const config = getAuthConfig();
+  const baseUrl = getAuthBaseUrl();
+  const headers = getDefaultHeaders();
+
+  const providerConfig = getProviderConfig(config.defaultProvider);
+  const logoutPath = providerConfig?.logoutPath;
+
+  if (logoutPath && options?.callLogoutEndpoint !== false) {
+    try {
+      await fetch(`${baseUrl}${logoutPath}`, {
+        method: "POST",
+        headers,
+        credentials: "include",
+      });
+    } catch (error) {
+      console.warn("Logout endpoint call failed:", error);
+    }
+  }
+
+  if (options?.redirectUrl) {
+    window.location.href = options.redirectUrl;
+  } else if (config.loginRedirectUrl) {
+    window.location.href = config.loginRedirectUrl;
+  }
+}

package/sdk/auth/authConfig.ts

@@ -0,0 +1,105 @@
+// ============================================================
+// AUTH CONFIGURATION
+// ============================================================
+// Global auth configuration following the setApiBaseUrl pattern
+
+import type { AuthConfig, AuthProviderName, AuthEndpointConfig } from "./types";
+import { getApiBaseUrl } from "../api/client";
+
+/**
+ * Default auth configuration
+ */
+const defaultAuthConfig: AuthConfig = {
+  sessionEndpoint: "/api/id",
+  providers: {
+    google: {
+      loginPath: "/api/auth/google/login",
+      logoutPath: "/api/auth/logout",
+    },
+  },
+  defaultProvider: "google",
+  autoRedirect: true,
+  sessionCheckInterval: 0,
+  retry: {
+    count: 3,
+    delay: 1000,
+  },
+  staleTime: 5 * 60 * 1000,
+  refetchOnWindowFocus: true,
+  refetchOnReconnect: true,
+};
+
+/**
+ * Current auth configuration (mutable)
+ */
+let authConfig: AuthConfig = { ...defaultAuthConfig };
+
+/**
+ * Configure authentication settings globally
+ * @example
+ * ```ts
+ * configureAuth({
+ *   defaultProvider: "google",
+ *   autoRedirect: true,
+ *   providers: {
+ *     google: { loginPath: "/api/auth/google/login" },
+ *     microsoft: { loginPath: "/api/auth/microsoft/login" },
+ *   },
+ * });
+ * ```
+ */
+export function configureAuth(config: Partial<AuthConfig>): void {
+  authConfig = {
+    ...authConfig,
+    ...config,
+    providers: {
+      ...authConfig.providers,
+      ...config.providers,
+    },
+    retry: {
+      ...authConfig.retry,
+      ...config.retry,
+    },
+  };
+}
+
+/**
+ * Add or update an auth provider configuration
+ */
+export function setAuthProvider(
+  provider: AuthProviderName,
+  config: AuthEndpointConfig
+): void {
+  authConfig.providers[provider] = config;
+}
+
+/**
+ * Get current auth configuration
+ */
+export function getAuthConfig(): Readonly<AuthConfig> {
+  return { ...authConfig };
+}
+
+/**
+ * Get the base URL for auth endpoints
+ * Falls back to API base URL if not explicitly set
+ */
+export function getAuthBaseUrl(): string {
+  return authConfig.baseUrl || getApiBaseUrl();
+}
+
+/**
+ * Get endpoint configuration for a specific provider
+ */
+export function getProviderConfig(
+  provider: AuthProviderName
+): AuthEndpointConfig | undefined {
+  return authConfig.providers[provider];
+}
+
+/**
+ * Reset auth configuration to defaults
+ */
+export function resetAuthConfig(): void {
+  authConfig = { ...defaultAuthConfig };
+}

package/sdk/auth/index.ts

@@ -0,0 +1,40 @@
+// ============================================================
+// AUTH MODULE EXPORTS
+// ============================================================
+
+// Provider component
+export { AuthProvider } from "./AuthProvider";
+
+// Main hook
+export { useAuth } from "./useAuth";
+
+// Configuration functions
+export {
+  configureAuth,
+  setAuthProvider,
+  getAuthConfig,
+  getAuthBaseUrl,
+  resetAuthConfig,
+} from "./authConfig";
+
+// API client functions (for advanced use cases)
+export {
+  fetchSession,
+  initiateLogin,
+  performLogout,
+  AuthenticationError,
+} from "./authClient";
+
+// Type exports
+export type {
+  UserDetails,
+  SessionResponse,
+  AuthStatus,
+  AuthConfig,
+  AuthProviderName,
+  AuthEndpointConfig,
+  AuthProviderProps,
+  UseAuthReturn,
+  LoginOptions,
+  LogoutOptions,
+} from "./types";