rystem.authentication.social.client 0.5.0

package/lib/models/setup/SocialLoginSettings.d.ts

@@ -0,0 +1,66 @@
+import { SocialLoginErrorResponse, SocialParameter } from "../..";
+import { PlatformConfig } from "./PlatformConfig";
+import { IStorageService } from "../../services/IStorageService";
+import { IRoutingService } from "../../services/IRoutingService";
+export interface SocialLoginSettings {
+    apiUri: string;
+    automaticRefresh: boolean;
+    identityTransformer?: IIdentityTransformer<any>;
+    onLoginFailure: (data: SocialLoginErrorResponse) => void;
+    title: string | null;
+    /**
+     * Storage service for persisting tokens, PKCE verifiers, etc.
+     * Default: LocalStorageService (browser localStorage)
+     *
+     * @example Custom secure storage for mobile
+     * storageService: new SecureStorageService()
+     */
+    storageService: IStorageService;
+    /**
+     * Routing service for URL parameter reading and navigation
+     * Default: WindowRoutingService (uses window.location and window.history)
+     *
+     * IMPORTANT: Required for React Router, Next.js App Router, and other client-side routing frameworks
+     * to properly handle OAuth callbacks, redirects, and return URLs.
+     *
+     * @example React Router with useSearchParams, useNavigate, and useLocation hooks
+     * routingService: new ReactRouterRoutingService()
+     *
+     * @example Next.js App Router with useRouter, usePathname, and useSearchParams
+     * routingService: new NextAppRouterRoutingService()
+     */
+    routingService: IRoutingService;
+    /**
+     * Platform configuration (Web, iOS, Android)
+     *
+     * @example Web configuration (auto-detect domain)
+     * platform: {
+     *   type: PlatformType.Web,
+     *   redirectPath: "/account/login"
+     * }
+     *
+     * @example React Native iOS configuration
+     * platform: {
+     *   type: PlatformType.iOS,
+     *   redirectPath: "myapp://oauth/callback"  // Complete deep link
+     * }
+     *
+     * @default { type: 'auto', redirectPath: '/account/login', loginMode: 'popup' }
+     */
+    platform?: PlatformConfig;
+    google: SocialParameter;
+    microsoft: SocialParameter;
+    facebook: SocialParameter;
+    github: SocialParameter;
+    amazon: SocialParameter;
+    linkedin: SocialParameter;
+    x: SocialParameter;
+    instagram: SocialParameter;
+    pinterest: SocialParameter;
+    tiktok: SocialParameter;
+}
+export interface IIdentityTransformer<TIdentity> {
+    toPlain: (input: TIdentity | any) => any;
+    fromPlain: (input: any) => TIdentity;
+    retrieveUsername: (input: TIdentity) => string;
+}

package/lib/models/setup/SocialLoginSettings.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/models/setup/SocialParameter.d.ts

@@ -0,0 +1,3 @@
+export interface SocialParameter {
+    clientId: string | null;
+}

package/lib/models/setup/SocialParameter.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/services/IRoutingService.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Unified routing service for URL parameter reading and navigation
+ * Handles both OAuth callback detection and client-side routing operations
+ *
+ * This service solves compatibility issues with client-side routing frameworks
+ * (React Router, Next.js, Remix) where native browser APIs bypass the router.
+ *
+ * @example Default (Vanilla React, no routing library)
+ * ```typescript
+ * const routingService = new WindowRoutingService();
+ * setupSocialLogin(x => {
+ *     x.routingService = routingService; // Uses window.location and window.history
+ * });
+ * ```
+ *
+ * @example React Router
+ * ```typescript
+ * const routingService = new ReactRouterRoutingService();
+ * setupSocialLogin(x => {
+ *     x.routingService = routingService;
+ * });
+ *
+ * // In component:
+ * const [searchParams] = useSearchParams();
+ * const navigate = useNavigate();
+ * const location = useLocation();
+ * routingService.initialize(() => searchParams, navigate, location);
+ * ```
+ */
+export interface IRoutingService {
+    /**
+     * Get a single URL parameter value
+     * Used for reading OAuth callback parameters (code, state)
+     *
+     * @param key - Parameter name (e.g., 'code', 'state')
+     * @returns Parameter value or null if not found
+     *
+     * @example
+     * ```typescript
+     * const code = routingService.getSearchParam('code');
+     * const state = routingService.getSearchParam('state');
+     * ```
+     */
+    getSearchParam(key: string): string | null;
+    /**
+     * Get all URL parameters
+     * Used for debugging or advanced OAuth scenarios
+     *
+     * @returns URLSearchParams object with all query parameters
+     *
+     * @example
+     * ```typescript
+     * const allParams = routingService.getAllSearchParams();
+     * console.log('OAuth callback params:', allParams.toString());
+     * ```
+     */
+    getAllSearchParams(): URLSearchParams;
+    /**
+     * Get current path including search parameters
+     * Used for saving return URL before OAuth redirect
+     *
+     * @returns Current route path with query string (e.g., "/dashboard?tab=settings")
+     *
+     * @example
+     * ```typescript
+     * // Save current location before OAuth
+     * const returnUrl = routingService.getCurrentPath();
+     * storageService.set('return_url', returnUrl);
+     * ```
+     */
+    getCurrentPath(): string;
+    /**
+     * Navigate to a URL (for OAuth redirects and internal navigation)
+     *
+     * @param url - Full URL (https://...) for external OAuth, or path (/login) for internal
+     *
+     * @example OAuth redirect
+     * ```typescript
+     * routingService.navigateTo('https://login.microsoftonline.com/oauth2/authorize?...');
+     * ```
+     *
+     * @example Internal navigation (React Router)
+     * ```typescript
+     * routingService.navigateTo('/dashboard'); // Calls navigate() internally
+     * ```
+     */
+    navigateTo(url: string): void;
+    /**
+     * Replace current URL without full navigation (cleanup after OAuth callback)
+     * Updates URL bar without triggering page reload or adding to browser history
+     *
+     * @param path - Path to replace current URL with
+     *
+     * @example Clean URL after OAuth
+     * ```typescript
+     * // Before: /account/login?code=ABC123&state=microsoft
+     * routingService.navigateReplace('/account/login');
+     * // After: /account/login (query params removed)
+     * ```
+     */
+    navigateReplace(path: string): void;
+    /**
+     * Open URL in popup window (for popup mode OAuth)
+     *
+     * @param url - URL to open in popup
+     * @param name - Window name/target
+     * @param features - Window features (size, position, menubar, etc.)
+     * @returns Window reference or null if blocked by popup blocker
+     *
+     * @example
+     * ```typescript
+     * const popup = routingService.openPopup(
+     *     'https://oauth.provider.com/authorize',
+     *     'oauth_popup',
+     *     'width=450,height=730,top=100,left=100'
+     * );
+     * if (!popup) {
+     *     alert('Popup blocked! Please allow popups for this site.');
+     * }
+     * ```
+     */
+    openPopup(url: string, name: string, features: string): Window | null;
+}

package/lib/services/IRoutingService.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/services/IStorageService.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Generic storage service interface (key-value storage)
+ * Allows different infrastructure implementations (localStorage, secure storage, Redis, etc.)
+ */
+export interface IStorageService {
+    /**
+     * Get value by key
+     * @param key Storage key
+     * @returns Value or null if not found
+     */
+    get(key: string): string | null;
+    /**
+     * Set value for key
+     * @param key Storage key
+     * @param value Value to store
+     */
+    set(key: string, value: string): void;
+    /**
+     * Remove value by key
+     * @param key Storage key
+     */
+    remove(key: string): void;
+    /**
+     * Check if key exists
+     * @param key Storage key
+     * @returns True if key exists
+     */
+    has(key: string): boolean;
+    /**
+     * Clear all stored values (optional)
+     */
+    clear?(): void;
+}

package/lib/services/IStorageService.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/services/LocalStorageService.d.ts

@@ -0,0 +1,32 @@
+import { IStorageService } from "./IStorageService";
+/**
+ * Default storage implementation using browser localStorage
+ * Works for web applications (browser environment)
+ * For React Native, provide a custom IStorageService implementation
+ */
+export declare class LocalStorageService implements IStorageService {
+    /**
+     * Check if localStorage is available (browser environment)
+     */
+    private isAvailable;
+    /**
+     * Get value from localStorage
+     */
+    get(key: string): string | null;
+    /**
+     * Set value in localStorage
+     */
+    set(key: string, value: string): void;
+    /**
+     * Remove value from localStorage
+     */
+    remove(key: string): void;
+    /**
+     * Check if key exists in localStorage
+     */
+    has(key: string): boolean;
+    /**
+     * Clear all localStorage
+     */
+    clear(): void;
+}

package/lib/services/LocalStorageService.js

@@ -0,0 +1,93 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LocalStorageService = void 0;
+/**
+ * Default storage implementation using browser localStorage
+ * Works for web applications (browser environment)
+ * For React Native, provide a custom IStorageService implementation
+ */
+class LocalStorageService {
+    /**
+     * Check if localStorage is available (browser environment)
+     */
+    isAvailable() {
+        return typeof window !== 'undefined' && typeof localStorage !== 'undefined';
+    }
+    /**
+     * Get value from localStorage
+     */
+    get(key) {
+        if (!this.isAvailable()) {
+            console.warn('LocalStorageService: localStorage not available (React Native or SSR?)');
+            return null;
+        }
+        try {
+            return localStorage.getItem(key);
+        }
+        catch (error) {
+            console.error(`LocalStorageService: Error getting key "${key}"`, error);
+            return null;
+        }
+    }
+    /**
+     * Set value in localStorage
+     */
+    set(key, value) {
+        if (!this.isAvailable()) {
+            console.warn('LocalStorageService: localStorage not available (React Native or SSR?)');
+            return;
+        }
+        try {
+            localStorage.setItem(key, value);
+        }
+        catch (error) {
+            console.error(`LocalStorageService: Error setting key "${key}"`, error);
+        }
+    }
+    /**
+     * Remove value from localStorage
+     */
+    remove(key) {
+        if (!this.isAvailable()) {
+            console.warn('LocalStorageService: localStorage not available (React Native or SSR?)');
+            return;
+        }
+        try {
+            localStorage.removeItem(key);
+        }
+        catch (error) {
+            console.error(`LocalStorageService: Error removing key "${key}"`, error);
+        }
+    }
+    /**
+     * Check if key exists in localStorage
+     */
+    has(key) {
+        if (!this.isAvailable()) {
+            return false;
+        }
+        try {
+            return localStorage.getItem(key) !== null;
+        }
+        catch (error) {
+            console.error(`LocalStorageService: Error checking key "${key}"`, error);
+            return false;
+        }
+    }
+    /**
+     * Clear all localStorage
+     */
+    clear() {
+        if (!this.isAvailable()) {
+            console.warn('LocalStorageService: localStorage not available (React Native or SSR?)');
+            return;
+        }
+        try {
+            localStorage.clear();
+        }
+        catch (error) {
+            console.error('LocalStorageService: Error clearing storage', error);
+        }
+    }
+}
+exports.LocalStorageService = LocalStorageService;

package/lib/services/MockRoutingService.example.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Mock Routing Service for unit testing
+ *
+ * This is a simple in-memory implementation for testing purposes.
+ * Allows setting URL parameters and controlling navigation programmatically.
+ *
+ * @example
+ * ```typescript
+ * import { MockRoutingService } from './MockRoutingService';
+ *
+ * const mockRouting = new MockRoutingService();
+ *
+ * // Setup test data
+ * mockRouting.setSearchParam('code', 'test-auth-code-12345');
+ * mockRouting.setSearchParam('state', 'microsoft');
+ * mockRouting.setCurrentPath('/account/login?tab=oauth');
+ *
+ * setupSocialLogin(x => {
+ *     x.routingService = mockRouting;
+ *     // ... rest of test config
+ * });
+ *
+ * // In your test
+ * expect(mockRouting.getSearchParam('code')).toBe('test-auth-code-12345');
+ * expect(mockRouting.wasNavigateToCalledWith('https://oauth.provider.com')).toBe(true);
+ * ```
+ */
+import type { IRoutingService } from './IRoutingService';
+/**
+ * Mock Routing Service for testing
+ * Stores state in-memory and tracks navigation calls
+ */
+export declare class MockRoutingService implements IRoutingService {
+    private params;
+    private currentPath;
+    private navigationHistory;
+    private replaceHistory;
+    private popupCalls;
+    /**
+     * Set a URL parameter (for testing OAuth callbacks)
+     * @param key - Parameter name
+     * @param value - Parameter value
+     */
+    setSearchParam(key: string, value: string): void;
+    /**
+     * Set multiple parameters at once
+     * @param params - Object with key-value pairs
+     */
+    setSearchParams(params: Record<string, string>): void;
+    /**
+     * Set the current path
+     * @param path - Path with query string (e.g., "/dashboard?tab=settings")
+     */
+    setCurrentPath(path: string): void;
+    /**
+     * Clear all state (for test cleanup)
+     */
+    reset(): void;
+    /**
+     * Check if navigateTo was called with specific URL
+     * @param url - URL to check
+     * @returns True if navigateTo was called with this URL
+     */
+    wasNavigateToCalledWith(url: string): boolean;
+    /**
+     * Get all navigateTo calls
+     * @returns Array of URLs passed to navigateTo
+     */
+    getNavigationHistory(): string[];
+    /**
+     * Check if navigateReplace was called with specific path
+     * @param path - Path to check
+     * @returns True if navigateReplace was called with this path
+     */
+    wasReplaceCalledWith(path: string): boolean;
+    /**
+     * Get all navigateReplace calls
+     * @returns Array of paths passed to navigateReplace
+     */
+    getReplaceHistory(): string[];
+    /**
+     * Get all openPopup calls
+     * @returns Array of popup call parameters
+     */
+    getPopupCalls(): Array<{
+        url: string;
+        name: string;
+        features: string;
+    }>;
+    getSearchParam(key: string): string | null;
+    getAllSearchParams(): URLSearchParams;
+    getCurrentPath(): string;
+    navigateTo(url: string): void;
+    navigateReplace(path: string): void;
+    openPopup(url: string, name: string, features: string): Window | null;
+}

package/lib/services/MockRoutingService.example.js

@@ -0,0 +1,153 @@
+"use strict";
+/**
+ * Mock Routing Service for unit testing
+ *
+ * This is a simple in-memory implementation for testing purposes.
+ * Allows setting URL parameters and controlling navigation programmatically.
+ *
+ * @example
+ * ```typescript
+ * import { MockRoutingService } from './MockRoutingService';
+ *
+ * const mockRouting = new MockRoutingService();
+ *
+ * // Setup test data
+ * mockRouting.setSearchParam('code', 'test-auth-code-12345');
+ * mockRouting.setSearchParam('state', 'microsoft');
+ * mockRouting.setCurrentPath('/account/login?tab=oauth');
+ *
+ * setupSocialLogin(x => {
+ *     x.routingService = mockRouting;
+ *     // ... rest of test config
+ * });
+ *
+ * // In your test
+ * expect(mockRouting.getSearchParam('code')).toBe('test-auth-code-12345');
+ * expect(mockRouting.wasNavigateToCalledWith('https://oauth.provider.com')).toBe(true);
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MockRoutingService = void 0;
+/**
+ * Mock Routing Service for testing
+ * Stores state in-memory and tracks navigation calls
+ */
+class MockRoutingService {
+    params = new Map();
+    currentPath = '/';
+    navigationHistory = [];
+    replaceHistory = [];
+    popupCalls = [];
+    // ===== Setup Methods (for tests) =====
+    /**
+     * Set a URL parameter (for testing OAuth callbacks)
+     * @param key - Parameter name
+     * @param value - Parameter value
+     */
+    setSearchParam(key, value) {
+        this.params.set(key, value);
+    }
+    /**
+     * Set multiple parameters at once
+     * @param params - Object with key-value pairs
+     */
+    setSearchParams(params) {
+        Object.entries(params).forEach(([key, value]) => {
+            this.params.set(key, value);
+        });
+    }
+    /**
+     * Set the current path
+     * @param path - Path with query string (e.g., "/dashboard?tab=settings")
+     */
+    setCurrentPath(path) {
+        this.currentPath = path;
+    }
+    /**
+     * Clear all state (for test cleanup)
+     */
+    reset() {
+        this.params.clear();
+        this.currentPath = '/';
+        this.navigationHistory = [];
+        this.replaceHistory = [];
+        this.popupCalls = [];
+    }
+    // ===== Verification Methods (for test assertions) =====
+    /**
+     * Check if navigateTo was called with specific URL
+     * @param url - URL to check
+     * @returns True if navigateTo was called with this URL
+     */
+    wasNavigateToCalledWith(url) {
+        return this.navigationHistory.includes(url);
+    }
+    /**
+     * Get all navigateTo calls
+     * @returns Array of URLs passed to navigateTo
+     */
+    getNavigationHistory() {
+        return [...this.navigationHistory];
+    }
+    /**
+     * Check if navigateReplace was called with specific path
+     * @param path - Path to check
+     * @returns True if navigateReplace was called with this path
+     */
+    wasReplaceCalledWith(path) {
+        return this.replaceHistory.includes(path);
+    }
+    /**
+     * Get all navigateReplace calls
+     * @returns Array of paths passed to navigateReplace
+     */
+    getReplaceHistory() {
+        return [...this.replaceHistory];
+    }
+    /**
+     * Get all openPopup calls
+     * @returns Array of popup call parameters
+     */
+    getPopupCalls() {
+        return [...this.popupCalls];
+    }
+    // ===== IRoutingService Implementation =====
+    getSearchParam(key) {
+        return this.params.get(key) || null;
+    }
+    getAllSearchParams() {
+        const urlParams = new URLSearchParams();
+        this.params.forEach((value, key) => {
+            urlParams.set(key, value);
+        });
+        return urlParams;
+    }
+    getCurrentPath() {
+        return this.currentPath;
+    }
+    navigateTo(url) {
+        this.navigationHistory.push(url);
+        // In real scenario, external URLs would do full page navigation
+        // In tests, we just track the call
+        if (url.startsWith('http://') || url.startsWith('https://')) {
+            console.log('[MockRouting] External navigation (tracked):', url);
+        }
+        else {
+            console.log('[MockRouting] Internal navigation (tracked):', url);
+            this.currentPath = url;
+        }
+    }
+    navigateReplace(path) {
+        this.replaceHistory.push(path);
+        this.currentPath = path;
+        console.log('[MockRouting] Replace URL (tracked):', path);
+    }
+    openPopup(url, name, features) {
+        this.popupCalls.push({ url, name, features });
+        console.log('[MockRouting] Popup open (tracked):', { url, name });
+        // In tests, we don't actually open popups
+        // Return a mock Window object if needed for testing
+        return null;
+    }
+}
+exports.MockRoutingService = MockRoutingService;

package/lib/services/NextAppRouterRoutingService.example.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Unified Routing Service for Next.js App Router (v13+)
+ *
+ * This service handles both URL parameter reading and navigation for Next.js with App Router.
+ * Copy this file to your project and remove the `.example` extension.
+ *
+ * IMPORTANT: This must be used in Client Components ('use client')
+ *
+ * @example
+ * ```typescript
+ * 'use client';
+ *
+ * import { NextAppRouterRoutingService } from './NextAppRouterRoutingService';
+ * import { useRouter, usePathname, useSearchParams } from 'next/navigation';
+ *
+ * const routingService = new NextAppRouterRoutingService();
+ *
+ * setupSocialLogin(x => {
+ *     x.routingService = routingService;
+ * });
+ *
+ * export default function LoginPage() {
+ *     const router = useRouter();
+ *     const pathname = usePathname();
+ *     const searchParams = useSearchParams();
+ *
+ *     useEffect(() => {
+ *         // Single initialization with all hooks
+ *         routingService.initialize(router, pathname, searchParams);
+ *     }, [router, pathname, searchParams]);
+ *
+ *     return <div>Your login page</div>;
+ * }
+ * ```
+ */
+import type { IRoutingService } from './IRoutingService';
+/**
+ * Routing Service for Next.js App Router (v13+)
+ * Uses useRouter, usePathname, and useSearchParams from next/navigation
+ *
+ * NOTE: Only works in Client Components ('use client' directive required)
+ */
+export declare class NextAppRouterRoutingService implements IRoutingService {
+    private router;
+    private pathname;
+    private searchParams;
+    /**
+     * Initialize with Next.js navigation hooks
+     * MUST be called inside a Client Component ('use client')
+     *
+     * @param router - The router from useRouter() hook
+     * @param pathname - The pathname from usePathname() hook
+     * @param searchParams - The searchParams from useSearchParams() hook
+     *
+     * @example
+     * ```typescript
+     * 'use client';
+     *
+     * const router = useRouter();
+     * const pathname = usePathname();
+     * const searchParams = useSearchParams();
+     *
+     * useEffect(() => {
+     *     routingService.initialize(router, pathname, searchParams);
+     * }, [router, pathname, searchParams]);
+     * ```
+     */
+    initialize(router: any, pathname: string, searchParams: URLSearchParams | null): void;
+    getSearchParam(key: string): string | null;
+    getAllSearchParams(): URLSearchParams;
+    getCurrentPath(): string;
+    navigateTo(url: string): void;
+    navigateReplace(path: string): void;
+    openPopup(url: string, name: string, features: string): Window | null;
+}