@seontechnologies/playwright-utils 3.10.0

package/dist/types/auth-session/apply-user-cookies-to-browser-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply-user-cookies-to-browser-context.d.ts","sourceRoot":"","sources":["../../../src/auth-session/apply-user-cookies-to-browser-context.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA;AAGtD;;;;;;;GAOG;AACH,wBAAsB,gCAAgC,CACpD,OAAO,EAAE,cAAc,EACvB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACjC,OAAO,CAAC,cAAc,CAAC,CA0CzB"}

package/dist/types/auth-session/core.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Core authentication functionality for the auth session library
+ * This file is the single source of truth for the public API
+ * following SEON's functional programming principles
+ */
+import type { APIRequestContext } from '@playwright/test';
+import type { AuthSessionOptions, AuthIdentifiers } from './internal/types';
+import { AuthSessionManager } from './internal/auth-session';
+export { AuthSessionManager };
+export { setAuthProvider } from './internal/auth-provider';
+/**
+ * Load a token from storage if one exists
+ * Handles token expiration checking using registered token expiration function
+ *
+ * @param tokenPath Path to the token file
+ * @param checkExpiration Whether to check if the token is expired (defaults to true)
+ */
+export declare function loadTokenFromStorage(tokenPath: string, checkExpiration?: boolean): string | null;
+/**
+ * Save a token to storage
+ * @param tokenPath Path to the token file
+ * @param token Token to save
+ * @returns Boolean indicating whether the token was successfully saved
+ */
+export declare function saveTokenToStorage(tokenPath: string, token: string): boolean;
+/**
+ * Load a storage state file and parse it into an object in one step
+ * This simplifies token management by handling both loading and parsing
+ *
+ * Note: This function no longer performs automatic token validation.
+ * Applications should implement their own validation logic based on their
+ * specific token formats and requirements.
+ *
+ * @param tokenPath Path to the storage state file
+ * @returns The parsed storage state object or null if file doesn't exist or is invalid
+ */
+export declare function loadStorageState(tokenPath: string): Record<string, unknown> | null;
+/**
+ * Configure the authentication session with the provided options
+ * This is the main entry point for setting up the auth system
+ */
+export declare const configureAuthSession: (options: AuthSessionOptions) => void;
+/**
+ * Get an authentication token, fetching a new one if needed
+ * @param request The Playwright APIRequestContext
+ * @param options Optional environment and user identifier overrides
+ * @returns A promise that resolves to a storage state object compatible with Playwright context
+ */
+export declare function getAuthToken(request: APIRequestContext, options?: AuthIdentifiers): Promise<Record<string, unknown>>;
+/**
+ * Clear the authentication token from storage
+ * @param options Optional environment and user identifier overrides
+ * @returns Boolean indicating whether a token was successfully cleared
+ */
+export declare function clearAuthToken(options?: AuthIdentifiers): boolean;
+//# sourceMappingURL=core.d.ts.map

package/dist/types/auth-session/core.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../../../src/auth-session/core.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AAMzD,OAAO,KAAK,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAA;AAC3E,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAA;AAM5D,OAAO,EAAE,kBAAkB,EAAE,CAAA;AAG7B,OAAO,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAA;AA6D1D;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,MAAM,EACjB,eAAe,GAAE,OAAc,GAC9B,MAAM,GAAG,IAAI,CAmCf;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAiB5E;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,MAAM,GAChB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAqBhC;AAED;;;GAGG;AACH,eAAO,MAAM,oBAAoB,GAAI,SAAS,kBAAkB,SACxC,CAAA;AAExB;;;;;GAKG;AACH,wBAAsB,YAAY,CAChC,OAAO,EAAE,iBAAiB,EAC1B,OAAO,CAAC,EAAE,eAAe,GACxB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CA6ClC;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAgCjE"}

package/dist/types/auth-session/fixtures.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Playwright Auth Session Test Fixtures
+ * Provides factory functions to create test fixtures for authentication
+ */
+import type { APIRequestContext, BrowserContext, Page } from '@playwright/test';
+import type { AuthIdentifiers, AuthOptions } from './internal/types';
+/**
+ * Creates auth fixtures that can be used to extend Playwright's test object
+ * @returns An object with fixtures that can be used with test.extend()
+ */
+export declare function createAuthFixtures(): {
+    /** Auth options to configure environment and user identifier
+     * @default { environment: process.env.TEST_ENV || 'local', userIdentifier: 'default' }     */
+    authOptions: (AuthIdentifiers | {
+        option: boolean;
+    })[];
+    /** Toggle to enable/disable authentication session
+     * When false, auth token acquisition and applying to browser context will be skipped
+     * @default true */
+    authSessionEnabled: (boolean | {
+        option: boolean;
+    })[];
+    /**
+     * Authentication token fixture that reuses tokens across tests
+     * @example
+     * ```ts
+     * test('use auth token', async ({ authToken }) => {
+     *   // Use the token in API calls
+     *   const response = await fetch('/api/data', {
+     *     headers: { Authorization: authToken }
+     *   })
+     * })
+     * ```
+     */
+    authToken: ({ request, authOptions, authSessionEnabled }: {
+        request: APIRequestContext;
+        authOptions: AuthOptions;
+        authSessionEnabled: boolean;
+    }, use: (token: string) => Promise<void>) => Promise<void>;
+    /**
+     * Browser context with authentication applied
+     * @example
+     * ```ts
+     * test('use authenticated context', async ({ context }) => {
+     *   const page = await context.newPage()
+     *   await page.goto('/protected-page')
+     *   // Auth is already set up!
+     * })
+     * ```
+     */
+    context: ({ browser, request, authOptions, authSessionEnabled }: {
+        browser: any;
+        request: APIRequestContext;
+        authOptions: AuthOptions;
+        authSessionEnabled: boolean;
+    }, use: (context: BrowserContext) => Promise<void>) => Promise<void>;
+    /**
+     * Page with authentication applied
+     * @example
+     * ```ts
+     * test('use authenticated page', async ({ page }) => {
+     *   await page.goto('/protected-page')
+     *   // Auth is already set up!
+     * })
+     * ```
+     */
+    page: ({ context, authOptions: _authOptions }: {
+        context: BrowserContext;
+        authOptions: AuthOptions;
+    }, use: (page: Page) => Promise<void>) => Promise<void>;
+};
+/**
+ * Creates user-specific test fixtures
+ * @param testBase The base test object to extend
+ * @param userIdentifier The user identifier to authenticate as
+ * @returns A test object configured for the specified user
+ */
+export declare const createUserSpecificTest: (testBase: any, userIdentifier: string) => any;
+/**
+ * @deprecated Use createUserSpecificTest instead
+ */
+export declare const createRoleSpecificTest: (testBase: any, userIdentifier: string) => any;
+//# sourceMappingURL=fixtures.d.ts.map

package/dist/types/auth-session/fixtures.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fixtures.d.ts","sourceRoot":"","sources":["../../../src/auth-session/fixtures.ts"],"names":[],"mappings":"AACA;;;GAGG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAA;AAG/E,OAAO,KAAK,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAGpE;;;GAGG;AACH,wBAAgB,kBAAkB;IAS9B;kGAC8F;;;;IAG9F;;uBAEmB;;;;IAGnB;;;;;;;;;;;OAWG;8DAME;QACD,OAAO,EAAE,iBAAiB,CAAA;QAC1B,WAAW,EAAE,WAAW,CAAA;QACxB,kBAAkB,EAAE,OAAO,CAAA;KAC5B,OACI,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC;IAuBvC;;;;;;;;;;OAUG;qEAOE;QACD,OAAO,EAAE,GAAG,CAAA;QACZ,OAAO,EAAE,iBAAiB,CAAA;QAC1B,WAAW,EAAE,WAAW,CAAA;QACxB,kBAAkB,EAAE,OAAO,CAAA;KAC5B,OACI,CAAC,OAAO,EAAE,cAAc,KAAK,OAAO,CAAC,IAAI,CAAC;IA2DjD;;;;;;;;;OASG;mDAKE;QAAE,OAAO,EAAE,cAAc,CAAC;QAAC,WAAW,EAAE,WAAW,CAAA;KAAE,OACnD,CAAC,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,IAAI,CAAC;EAavC;AAED;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,GAAI,UAAU,GAAG,EAAE,gBAAgB,MAAM,QAGxE,CAAA;AAEJ;;GAEG;AACH,eAAO,MAAM,sBAAsB,aARc,GAAG,kBAAkB,MAAM,QAQhB,CAAA"}

package/dist/types/auth-session/global-setup-helper.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Global setup helper for Playwright Auth Session
+ * Provides utilities for initializing authentication in global setup
+ */
+import type { APIRequestContext } from '@playwright/test';
+/**
+ * Initialize authentication token during Playwright's global setup.
+ * This helper simplifies the integration into the globalSetup function.
+ *
+ * @param request - Playwright APIRequestContext for making API calls
+ * @param options - Optional environment and user identifier settings
+ * @returns Promise that resolves when auth initialization is complete
+ */
+export declare function initializeAuthForGlobalSetup(request: APIRequestContext, options?: {
+    environment?: string;
+    userIdentifier?: string;
+}): Promise<void>;
+//# sourceMappingURL=global-setup-helper.d.ts.map

package/dist/types/auth-session/global-setup-helper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"global-setup-helper.d.ts","sourceRoot":"","sources":["../../../src/auth-session/global-setup-helper.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AAGzD;;;;;;;GAOG;AACH,wBAAsB,4BAA4B,CAChD,OAAO,EAAE,iBAAiB,EAC1B,OAAO,CAAC,EAAE;IAAE,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,cAAc,CAAC,EAAE,MAAM,CAAA;CAAE,GAC1D,OAAO,CAAC,IAAI,CAAC,CAYf"}

package/dist/types/auth-session/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Playwright Auth Session Library
+ * A reusable authentication session management system for Playwright
+ */
+export type { TokenDataFormatter, PlaywrightStorageState, DefaultTokenDataFormatter, RetryConfig, AuthSessionOptions, AuthOptions, AuthFixtures } from './internal/types';
+export { configureAuthSession, getAuthToken, clearAuthToken, loadStorageState } from './core';
+export { initializeAuthForGlobalSetup } from './global-setup-helper';
+export { applyUserCookiesToBrowserContext } from './apply-user-cookies-to-browser-context';
+export { getStorageStatePath, getTokenFilePath, getStorageDir, saveStorageState } from './internal/auth-storage-utils';
+export { authStorageInit, authGlobalInit } from './internal/auth-global-setup';
+export { AuthSessionManager } from './internal/auth-session';
+export { type AuthProvider, setAuthProvider, getAuthProvider } from './internal/auth-provider';
+export { TokenCacheManager, globalTokenCache, type CacheConfig, type CacheMetrics } from './internal/cache-manager';
+export { createAuthFixtures, createRoleSpecificTest } from './fixtures';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/auth-session/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/auth-session/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,YAAY,EACV,kBAAkB,EAClB,sBAAsB,EACtB,yBAAyB,EACzB,WAAW,EACX,kBAAkB,EAClB,WAAW,EACX,YAAY,EACb,MAAM,kBAAkB,CAAA;AAGzB,OAAO,EACL,oBAAoB,EACpB,YAAY,EACZ,cAAc,EACd,gBAAgB,EACjB,MAAM,QAAQ,CAAA;AAGf,OAAO,EAAE,4BAA4B,EAAE,MAAM,uBAAuB,CAAA;AAGpE,OAAO,EAAE,gCAAgC,EAAE,MAAM,yCAAyC,CAAA;AAG1F,OAAO,EACL,mBAAmB,EACnB,gBAAgB,EAChB,aAAa,EACb,gBAAgB,EACjB,MAAM,+BAA+B,CAAA;AAGtC,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAA;AAG9E,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAA;AAG5D,OAAO,EACL,KAAK,YAAY,EACjB,eAAe,EACf,eAAe,EAChB,MAAM,0BAA0B,CAAA;AAGjC,OAAO,EACL,iBAAiB,EACjB,gBAAgB,EAChB,KAAK,WAAW,EAChB,KAAK,YAAY,EAClB,MAAM,0BAA0B,CAAA;AAGjC,OAAO,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAA"}

package/dist/types/auth-session/internal/auth-configure.d.ts

@@ -0,0 +1,19 @@
+/** Auth session setup for the current project
+ * Manages global authentication configuration */
+import type { AuthSessionOptions, AuthStorageConfig } from './types';
+/** Configure auth storage settings required by auth providers
+ *
+ * @param options Configuration options including storage paths and debug settings
+ */
+export declare function configureAuthSession(options?: Partial<AuthSessionOptions & AuthStorageConfig>): void;
+/**
+ * Get the current global auth session options
+ * @returns The global auth options or null if not configured
+ */
+export declare function getGlobalAuthOptions(): AuthSessionOptions | null;
+/**
+ * Initialize auth configuration with project defaults
+ * @returns The configuration options that were applied
+ */
+export declare function initializeDefaultConfiguration(): AuthSessionOptions;
+//# sourceMappingURL=auth-configure.d.ts.map

package/dist/types/auth-session/internal/auth-configure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-configure.d.ts","sourceRoot":"","sources":["../../../../src/auth-session/internal/auth-configure.ts"],"names":[],"mappings":"AAAA;iDACiD;AAKjD,OAAO,KAAK,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAA;AAkBpE;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,GAAE,OAAO,CAAC,kBAAkB,GAAG,iBAAiB,CAAM,QAiD9D;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,IAAI,kBAAkB,GAAG,IAAI,CAuBhE;AAED;;;GAGG;AACH,wBAAgB,8BAA8B,IAAI,kBAAkB,CAYnE"}

package/dist/types/auth-session/internal/auth-global-setup.d.ts

@@ -0,0 +1,33 @@
+/** Global initialization utilities for Playwright Auth Session
+ * Consolidates functions related to storage and auth token initialization */
+import type { AuthSessionConfig, AuthIdentifiers } from './types';
+/** Initialize auth session storage directories and files.
+ * Creates necessary directories and empty storage state files for Playwright.
+ * Call this in your global setup to ensure proper directory structure.
+ *
+ * @param options Optional environment and user identifier overrides
+ * @returns Object containing created storage paths */
+export declare const authStorageInit: (options?: AuthIdentifiers) => AuthSessionConfig;
+/**  Pre-fetch authentication tokens during global setup
+ *
+ * This function creates per-user Playwright request contexts and fetches tokens
+ * for specified user identifiers, storing them in isolated per-user storage locations.
+ * This ensures proper user isolation during global setup, matching the test execution phase.
+ *
+ * Use this in your global setup to improve test performance by
+ * avoiding repeated token fetches.
+ *
+ * @param options Configuration options
+ * @param options.baseURL Application base URL (defaults to process.env.BASE_URL)
+ * @param options.authBaseURL Authentication service base URL (defaults to options.baseURL or process.env.AUTH_BASE_URL)
+ * @param options.userIdentifiers Optional array of user identifiers to initialize tokens for (defaults to the provider's default identifier)
+ * @param options.environment Optional environment override (defaults to the provider's default environment)
+ * @returns Promise that resolves when auth initialization is complete
+ */
+export declare function authGlobalInit(options?: {
+    baseURL?: string;
+    authBaseURL?: string;
+    userIdentifiers?: string[];
+    environment?: string;
+}): Promise<boolean>;
+//# sourceMappingURL=auth-global-setup.d.ts.map

package/dist/types/auth-session/internal/auth-global-setup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-global-setup.d.ts","sourceRoot":"","sources":["../../../../src/auth-session/internal/auth-global-setup.ts"],"names":[],"mappings":"AACA;6EAC6E;AAQ7E,OAAO,KAAK,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AAIjE;;;;;sDAKsD;AACtD,eAAO,MAAM,eAAe,GAAI,UAAU,eAAe,KAAG,iBACtC,CAAA;AAEtB;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,cAAc,CAAC,OAAO,CAAC,EAAE;IAC7C,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,eAAe,CAAC,EAAE,MAAM,EAAE,CAAA;IAC1B,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB,GAAG,OAAO,CAAC,OAAO,CAAC,CA8InB"}

package/dist/types/auth-session/internal/auth-provider-validator.d.ts

@@ -0,0 +1,36 @@
+/**
+ * AuthProvider validation utilities
+ * Ensures AuthProvider implementations meet the required interface contract
+ */
+import type { AuthProvider } from './auth-provider';
+/** Configuration for validation behavior */
+export type ValidationConfig = {
+    /** Whether to throw errors on validation failures (default: true) */
+    throwOnError?: boolean;
+    /** Whether to run performance benchmarks (default: false) */
+    enableBenchmarks?: boolean;
+    /** Custom logger function for validation messages */
+    logger?: (message: string) => void;
+};
+/** Validation result information */
+export type ValidationResult = {
+    isValid: boolean;
+    errors: string[];
+    warnings: string[];
+    benchmarks?: Record<string, number>;
+};
+/**
+ * Validate that an AuthProvider implements all required methods with correct signatures
+ * @param provider The AuthProvider to validate
+ * @param config Optional validation configuration
+ * @returns Validation result with errors, warnings, and optional benchmarks
+ */
+export declare function validateAuthProvider(provider: AuthProvider, config?: ValidationConfig): ValidationResult;
+/**
+ * Convenience function to validate and set an AuthProvider with proper error handling
+ * @param provider The AuthProvider to validate and set
+ * @param config Optional validation configuration
+ * @returns Promise that resolves to whether the provider was successfully validated and set
+ */
+export declare function validateAndSetAuthProvider(provider: AuthProvider, config?: ValidationConfig): Promise<boolean>;
+//# sourceMappingURL=auth-provider-validator.d.ts.map

package/dist/types/auth-session/internal/auth-provider-validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-provider-validator.d.ts","sourceRoot":"","sources":["../../../../src/auth-session/internal/auth-provider-validator.ts"],"names":[],"mappings":"AACA;;;GAGG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAInD,4CAA4C;AAC5C,MAAM,MAAM,gBAAgB,GAAG;IAC7B,qEAAqE;IACrE,YAAY,CAAC,EAAE,OAAO,CAAA;IACtB,6DAA6D;IAC7D,gBAAgB,CAAC,EAAE,OAAO,CAAA;IAC1B,qDAAqD;IACrD,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;CACnC,CAAA;AAED,oCAAoC;AACpC,MAAM,MAAM,gBAAgB,GAAG;IAC7B,OAAO,EAAE,OAAO,CAAA;IAChB,MAAM,EAAE,MAAM,EAAE,CAAA;IAChB,QAAQ,EAAE,MAAM,EAAE,CAAA;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CACpC,CAAA;AAeD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,YAAY,EACtB,MAAM,GAAE,gBAAqB,GAC5B,gBAAgB,CA4ElB;AAoKD;;;;;GAKG;AACH,wBAAsB,0BAA0B,CAC9C,QAAQ,EAAE,YAAY,EACtB,MAAM,GAAE,gBAAqB,GAC5B,OAAO,CAAC,OAAO,CAAC,CAgClB"}

package/dist/types/auth-session/internal/auth-provider.d.ts

@@ -0,0 +1,92 @@
+/** Auth Provider Interface
+ * Defines the contract for authentication providers */
+import type { APIRequestContext } from '@playwright/test';
+import type { AuthOptions, AuthSessionOptions } from './types';
+/**
+ * Interface for auth provider implementations
+ *
+ * This allows for custom authentication logic to be plugged into the auth session system
+ * For example, you could implement an OAuth provider, a JWT provider, etc.
+ */
+export interface AuthProvider {
+    /**
+     * Get the current environment
+     * @param options Optional auth options that may override the provider's defaults
+     */
+    getEnvironment(options?: Partial<AuthOptions>): string;
+    /**
+     * Get the current user identifier
+     * @param options Optional auth options that may override the provider's defaults
+     */
+    getUserIdentifier(options?: Partial<AuthOptions>): string;
+    /**
+     * Extract the raw token from formatted token data
+     * This allows providers to access tokens from their specific formats
+     *
+     * @param tokenData The formatted token data
+     * @returns The raw token string or null if not extractable
+     */
+    extractToken(tokenData: Record<string, unknown>): string | null;
+    /**
+     * Extract cookies from formatted token data
+     * This allows providers to access cookies from their specific formats
+     *
+     * @param tokenData The formatted token data
+     * @returns Array of cookie objects ready for browser context
+     */
+    extractCookies(tokenData: Record<string, unknown>): Array<{
+        name: string;
+        value: string;
+        domain?: string;
+        path?: string;
+        expires?: number;
+        httpOnly?: boolean;
+        secure?: boolean;
+        sameSite?: 'Strict' | 'Lax' | 'None';
+    }>;
+    /**
+     * Check if a token is expired
+     * This allows providers to implement custom expiration logic
+     *
+     * @param rawToken The raw token string to check for expiration
+     * @returns True if the token is expired, false otherwise
+     */
+    isTokenExpired?(rawToken: string): boolean;
+    /**
+     * Manage authentication token lifecycle
+     * This handles checking storage, acquiring tokens when needed, and saving tokens
+     *
+     * @param request The Playwright API request context
+     * @param options Optional auth options that may override the provider's defaults
+     * @returns A storage state object compatible with Playwright's context APIs
+     */
+    manageAuthToken(request: APIRequestContext, options?: Partial<AuthOptions>): Promise<Record<string, unknown>>;
+    /**
+     * Clear the authentication token
+     * @param options Optional auth options that may override the provider's defaults
+     */
+    clearToken(options?: Partial<AuthOptions>): void;
+    /**
+     * Get the base URL for the current environment/configuration
+     * This allows providers to implement custom baseUrl resolution logic
+     *
+     * @param options Optional auth options that may override the provider's defaults
+     * @returns The base URL string or undefined if not available
+     */
+    getBaseUrl?(options?: Partial<AuthOptions>): string | undefined;
+}
+/**
+ * Set the auth provider to use for all auth session operations
+ * This is the recommended way to configure authentication
+ * Users MUST implement their own provider and set it here
+ *
+ * @param provider The auth provider to use
+ */
+export declare function setAuthProvider(provider: AuthProvider): void;
+/**
+ * Get the configured auth provider
+ * Returns the global provider if set, otherwise throws an error
+ */
+export declare function getAuthProvider(): AuthProvider;
+export declare function getGlobalAuthOptions(): AuthSessionOptions | null;
+//# sourceMappingURL=auth-provider.d.ts.map

package/dist/types/auth-session/internal/auth-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-provider.d.ts","sourceRoot":"","sources":["../../../../src/auth-session/internal/auth-provider.ts"],"names":[],"mappings":"AAAA;uDACuD;AACvD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AACzD,OAAO,KAAK,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAA;AAE9D;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,cAAc,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAAG,MAAM,CAAA;IAEtD;;;OAGG;IACH,iBAAiB,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAAG,MAAM,CAAA;IAEzD;;;;;;OAMG;IACH,YAAY,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,GAAG,IAAI,CAAA;IAE/D;;;;;;OAMG;IACH,cAAc,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,KAAK,CAAC;QACxD,IAAI,EAAE,MAAM,CAAA;QACZ,KAAK,EAAE,MAAM,CAAA;QACb,MAAM,CAAC,EAAE,MAAM,CAAA;QACf,IAAI,CAAC,EAAE,MAAM,CAAA;QACb,OAAO,CAAC,EAAE,MAAM,CAAA;QAChB,QAAQ,CAAC,EAAE,OAAO,CAAA;QAClB,MAAM,CAAC,EAAE,OAAO,CAAA;QAChB,QAAQ,CAAC,EAAE,QAAQ,GAAG,KAAK,GAAG,MAAM,CAAA;KACrC,CAAC,CAAA;IAEF;;;;;;OAMG;IACH,cAAc,CAAC,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAA;IAE1C;;;;;;;OAOG;IACH,eAAe,CACb,OAAO,EAAE,iBAAiB,EAC1B,OAAO,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAC7B,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;IAEnC;;;OAGG;IACH,UAAU,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAAG,IAAI,CAAA;IAEhD;;;;;;OAMG;IACH,UAAU,CAAC,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAAG,MAAM,GAAG,SAAS,CAAA;CAChE;AAKD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,YAAY,GAAG,IAAI,CAE5D;AAED;;;GAGG;AACH,wBAAgB,eAAe,IAAI,YAAY,CAQ9C;AAGD,wBAAgB,oBAAoB,IAAI,kBAAkB,GAAG,IAAI,CAQhE"}

package/dist/types/auth-session/internal/auth-session.d.ts

@@ -0,0 +1,76 @@
+/** Authentication session manager for use with playwright
+ * @internal This file contains implementation details that should not be directly imported
+ * Use the public API exported from index.ts instead */
+import type { APIRequestContext } from '@playwright/test';
+import type { AuthSessionOptions, DefaultTokenDataFormatter } from './types';
+/**
+ * Default token formatter for the standard Playwright storage state format
+ * This creates a properly formatted storage state with the raw token value
+ */
+export declare const defaultTokenFormatter: DefaultTokenDataFormatter;
+export declare class AuthSessionManager {
+    private static instances;
+    private readonly storageDir;
+    private readonly storageFile;
+    private readonly options;
+    private hasToken;
+    private token;
+    private constructor();
+    /**
+     * Save token to storage and update cache
+     * @param token The token to save - can be either a string or an object
+     */
+    saveToken(token: string | Record<string, unknown>): Promise<void>;
+    static getInstance(options?: AuthSessionOptions): AuthSessionManager;
+    /** Load token from storage if it exists */
+    private loadTokenFromStorage;
+    /** Cache a token in memory using advanced cache manager */
+    private cacheToken;
+    /** Save token to storage with retry logic and exponential backoff */
+    private saveTokenToStorageWithRetry;
+    /** Save token to storage with file locking to prevent concurrent access issues */
+    private saveTokenToStorage;
+    /**
+     * Clear the token from storage
+     * @returns Boolean indicating whether a token was successfully cleared
+     */
+    clearToken(): boolean;
+    /**
+     * Get a new token using the AuthProvider
+     *
+     * @param request The Playwright API request context
+     * @returns A promise that resolves to the authentication token string
+     */
+    private getTokenFromProvider;
+    /**
+     * Check if a token is expired
+     * Uses the in-memory cache first, then falls back to storage
+     * Avoids unnecessary file I/O operations
+     */
+    private isTokenExpired;
+    /**
+     * Check token expiration using the advanced cache manager
+     */
+    private checkTokenCacheExpiration;
+    /**
+     * Check token expiration using the auth provider
+     */
+    private checkProviderTokenExpiration;
+    /**
+     * Check token expiration by reading from storage
+     */
+    private checkStorageTokenExpiration;
+    /**
+     * Refresh the token if it's expired
+     * @param request The Playwright API request context
+     * @returns A promise that resolves to the refreshed token
+     */
+    private refreshTokenIfNeeded;
+    /**
+     * Manage the complete authentication token lifecycle
+     * Handles checking existing tokens, fetching new ones if needed, and persistence
+     * Uses advanced caching for better performance
+     */
+    manageAuthToken(request: APIRequestContext): Promise<string>;
+}
+//# sourceMappingURL=auth-session.d.ts.map

package/dist/types/auth-session/internal/auth-session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-session.d.ts","sourceRoot":"","sources":["../../../../src/auth-session/internal/auth-session.ts"],"names":[],"mappings":"AAAA;;uDAEuD;AAEvD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AAQzD,OAAO,KAAK,EACV,kBAAkB,EAElB,yBAAyB,EAE1B,MAAM,SAAS,CAAA;AAkJhB;;;GAGG;AACH,eAAO,MAAM,qBAAqB,EAAE,yBAgDnC,CAAA;AAmBD,qBAAa,kBAAkB;IAE7B,OAAO,CAAC,MAAM,CAAC,SAAS,CAA6C;IACrE,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAQ;IACnC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAQ;IACpC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoB;IAC5C,OAAO,CAAC,QAAQ,CAAiB;IACjC,OAAO,CAAC,KAAK,CAAsB;IAEnC,OAAO;IAwDP;;;OAGG;IACU,SAAS,CACpB,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACtC,OAAO,CAAC,IAAI,CAAC;WAgBF,WAAW,CAAC,OAAO,CAAC,EAAE,kBAAkB,GAAG,kBAAkB;IAkC3E,2CAA2C;IAC3C,OAAO,CAAC,oBAAoB;IAoE5B,2DAA2D;IAC3D,OAAO,CAAC,UAAU;IAmBlB,qEAAqE;YACvD,2BAA2B;IAUzC,kFAAkF;IAClF,OAAO,CAAC,kBAAkB;IAgE1B;;;OAGG;IACI,UAAU,IAAI,OAAO;IAoD5B;;;;;OAKG;YACW,oBAAoB;IAuClC;;;;OAIG;IACH,OAAO,CAAC,cAAc;IAoBtB;;OAEG;IACH,OAAO,CAAC,yBAAyB;IAajC;;OAEG;IACH,OAAO,CAAC,4BAA4B;IAsBpC;;OAEG;IACH,OAAO,CAAC,2BAA2B;IAyCnC;;;;OAIG;YACW,oBAAoB;IAqBlC;;;;OAIG;IACU,eAAe,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC;CAoC1E"}

package/dist/types/auth-session/internal/auth-storage-utils.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Storage utilities for Playwright testing
+ * Simple, explicit functions for managing test storage files
+ *
+ * Uses Playwright's storage state for auth sessions:
+ * @see https://playwright.dev/docs/api-testing#reusing-authentication-state
+ * @see https://playwright.dev/docs/api/class-apirequestcontext#api-request-context-storage-state
+ * @see https://playwright.dev/docs/api/class-browsercontext#browser-context-storage-state
+ */
+import type { AuthSessionConfig, AuthIdentifiers, AuthStorageConfig } from './types';
+/**
+ * Get the storage directory path based on environment and user identifier
+ * @param options Configuration options
+ * @param options.environment Test environment (e.g., 'local', 'dev', 'staging')
+ * @param options.userIdentifier User identifier for storage separation
+ * @param options.basePath Base path for storage (defaults to current working directory)
+ * @returns Path to the auth storage directory
+ */
+export declare const getStorageDir: (options?: AuthIdentifiers & AuthStorageConfig) => string;
+/**
+ * Get the storage state path for a specific environment and user identifier
+ * @param options Configuration options
+ * @param options.environment Test environment (e.g., 'local', 'dev', 'staging')
+ * @param options.userIdentifier User identifier for storage separation
+ * @param options.authStoragePath Custom storage path (defaults to process.cwd())
+ * @returns Path to the storage state file
+ */
+export declare const getStorageStatePath: (options?: AuthIdentifiers & AuthStorageConfig) => string;
+/**
+ * Get the file path for token storage
+ * @param options.environment Environment for storage separation
+ * @param options.userIdentifier User identifier for storage separation
+ * @param options.tokenFileName Custom token filename (ignored - always uses storage-state.json)
+ * @param options.authStoragePath Custom storage path (defaults to process.cwd())
+ * @param options.useDirectStoragePath Use direct storage path
+ * @returns Path to the token file
+ */
+export declare const getTokenFilePath: (options?: AuthIdentifiers & AuthStorageConfig & {
+    tokenFileName?: string;
+    useDirectStoragePath?: boolean;
+}) => string;
+export declare const storageDir: string;
+/**
+ * Save a complete storage state without any token extraction or processing
+ * Useful for cookie-based authentication that needs entire storage state preserved
+ *
+ * @param tokenPath - The full path to save the storage state to
+ * @param storageState - The storage state object (Playwright format with cookies and origins)
+ * @returns boolean - Whether the save was successful
+ */
+export declare const saveStorageState: (tokenPath: string, storageState: Record<string, unknown>) => boolean;
+export declare function safeWriteJsonFile<T>(filePath: string, data: T, pretty?: boolean): Promise<void>;
+/**
+ * Safely read a JSON file using file locking with retry mechanism and fallback for corrupted files
+ *
+ * @param filePath Path to the JSON file
+ * @param defaultValue Default value to return if file doesn't exist or is corrupted
+ * @returns Parsed JSON data or default value
+ */
+export declare function safeReadJsonFile<T>(filePath: string, defaultValue: T): Promise<T>;
+export declare function authStorageInit(options?: AuthIdentifiers): AuthSessionConfig;
+//# sourceMappingURL=auth-storage-utils.d.ts.map

package/dist/types/auth-session/internal/auth-storage-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-storage-utils.d.ts","sourceRoot":"","sources":["../../../../src/auth-session/internal/auth-storage-utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAOH,OAAO,KAAK,EACV,iBAAiB,EACjB,eAAe,EACf,iBAAiB,EAClB,MAAM,SAAS,CAAA;AAuDhB;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa,GACxB,UAAU,eAAe,GAAG,iBAAiB,KAC5C,MAKF,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,GAC9B,UAAU,eAAe,GAAG,iBAAiB,KAC5C,MAAiE,CAAA;AAEpE;;;;;;;;GAQG;AACH,eAAO,MAAM,gBAAgB,GAC3B,UAAU,eAAe,GACvB,iBAAiB,GAAG;IAClB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,oBAAoB,CAAC,EAAE,OAAO,CAAA;CAC/B,KACF,MASF,CAAA;AAGD,eAAO,MAAM,UAAU,QAAkB,CAAA;AAEzC;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB,GAC3B,WAAW,MAAM,EACjB,cAAc,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KACpC,OAiBF,CAAA;AAED,wBAAsB,iBAAiB,CAAC,CAAC,EACvC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,CAAC,EACP,MAAM,UAAO,GACZ,OAAO,CAAC,IAAI,CAAC,CAoEf;AAED;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CAAC,CAAC,EACtC,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,CAAC,GACd,OAAO,CAAC,CAAC,CAAC,CA0DZ;AAED,wBAAgB,eAAe,CAAC,OAAO,CAAC,EAAE,eAAe,GAAG,iBAAiB,CAmB5E"}