@civic/auth 0.6.0-beta.3 → 0.6.1-beta.1

package/dist/vanillajs/auth/CivicAuth.d.ts

@@ -0,0 +1,205 @@
+import type { AuthenticationEvents } from "./AuthenticationEvents.js";
+import type { DisplayMode, AuthStorage } from "../../types.js";
+import type { AuthResult, Session } from "../types/index.js";
+/**
+ * Error codes for CivicAuth errors
+ */
+export declare enum CivicAuthErrorCode {
+    CONFIG_REQUIRED = "CONFIG_REQUIRED",
+    INIT_FAILED = "INIT_FAILED",
+    ENDPOINTS_NOT_INITIALIZED = "ENDPOINTS_NOT_INITIALIZED",
+    CONTAINER_NOT_FOUND = "CONTAINER_NOT_FOUND",
+    AUTH_PROCESS_TIMEOUT = "AUTH_PROCESS_TIMEOUT",
+    IFRAME_LOAD_ERROR = "IFRAME_LOAD_ERROR",
+    INVALID_MESSAGE = "INVALID_MESSAGE"
+}
+/**
+ * Configuration options for the CivicAuth client
+ */
+export interface CivicAuthClientConfig {
+    /** OAuth client ID */
+    clientId: string;
+    /** URL to redirect to after authentication */
+    redirectUrl: string;
+    /** Base URL of the OAuth server */
+    oauthServerBaseUrl: string;
+    /** Array of OAuth scopes to request */
+    scopes: string[];
+    /** HTML element or element ID where the auth iframe will be mounted */
+    targetContainerElement: HTMLElement | string;
+    /** Text signals for success and error states */
+    textSignals: {
+        /** Text to display on successful authentication */
+        success: string;
+        /** Optional text to display on authentication error */
+        error?: string;
+    };
+    /** Display mode for the authentication UI */
+    displayMode?: DisplayMode;
+    /** Display mode for iframe rendering - modal (full-screen overlay) or embedded (within container) */
+    iframeDisplayMode?: "modal" | "embedded";
+    /**
+     * Timeout duration in milliseconds for the entire authentication process.
+     * If the authentication process takes longer than this duration, it will be cancelled
+     * and an error will be thrown.
+     */
+    authProcessTimeout?: number;
+    /** Event handlers for authentication events */
+    events?: AuthenticationEvents;
+    /** Custom ID for the auth iframe */
+    iframeId?: string;
+    /** Custom storage adapter for auth state - uses shared AuthStorage interface */
+    storageAdapter?: AuthStorage;
+    /** OAuth prompt parameter */
+    prompt?: string;
+    /** Initial state for OAuth flow */
+    initialState?: string;
+    /** Logging configuration */
+    logging?: LoggingConfig;
+}
+export interface LoggingConfig {
+    enabled: boolean;
+    namespace?: string;
+    level?: "debug" | "info" | "warn" | "error";
+}
+/**
+ * CivicAuth client for handling OAuth authentication
+ */
+export declare class CivicAuth {
+    /**
+     * Internal configuration with all optional properties resolved to required ones.
+     *
+     * We extend CivicAuthClientConfig rather than making these properties required
+     * in the public interface to maintain better DX (optional properties) while
+     * ensuring type safety internally after defaults are applied.
+     */
+    private config;
+    private iframeElement?;
+    private observer?;
+    private authPromise?;
+    private authPromiseResolve?;
+    private authPromiseReject?;
+    private authProcessTimeoutHandle?;
+    private messageEventHandler?;
+    private storage;
+    private endpoints?;
+    private logger;
+    private sessionManager?;
+    private iframeManager?;
+    /**
+     * Private constructor for CivicAuth.
+     * Use {@link CivicAuth.create} to create a new instance.
+     * @param config - Configuration options for the auth client
+     * @throws {CivicAuthError} If required configuration is missing
+     * @private
+     */
+    private constructor();
+    /**
+     * Creates and initializes a new instance of CivicAuth.
+     * This is the recommended way to create a CivicAuth instance.
+     *
+     * @param config - Configuration options for the auth client
+     * @returns A promise that resolves with the initialized CivicAuth instance
+     * @throws {CivicAuthError} If initialization fails or required configuration is missing
+     *
+     * @example
+     * ```typescript
+     * const auth = await CivicAuth.create({
+     *   clientId: "your-client-id",
+     *   redirectUrl: "https://your-app.com/callback",
+     *   oauthServerBaseUrl: "https://auth-server.com/",
+     *   scopes: ["openid", "profile"],
+     *   targetContainerElement: "auth-container",
+     *   textSignals: {
+     *     success: "Authentication successful!"
+     *   }
+     * });
+     * ```
+     */
+    static create(config: CivicAuthClientConfig): Promise<CivicAuth>;
+    /**
+     * Initializes the auth client and checks for callback handling
+     * @throws {CivicAuthError} If initialization fails
+     */
+    private init;
+    /**
+     * Gets the container element for the auth iframe
+     * @returns The container element or null if not found
+     */
+    private getContainerElement;
+    /**
+     * Determines the appropriate iframe display mode based on container characteristics
+     * @param container The HTML element that will contain the iframe
+     * @returns "modal" for full-screen overlay or "embedded" for in-container display
+     */
+    private determineIframeDisplayMode;
+    /**
+     * Builds the authentication URL with PKCE challenge
+     * @returns The complete authentication URL
+     * @throws {CivicAuthError} If endpoints are not initialized
+     */
+    private buildAuthUrl;
+    private handleIframeMessage;
+    private logIncomingMessage;
+    private isValidMessageSource;
+    private handleValidMessage;
+    private handleAuthSuccess;
+    private handleAuthError;
+    private setupSignalObserver;
+    private handleNewTabAuth;
+    private handleIframeAuth;
+    /**
+     * Starts the authentication process
+     * @returns A promise that resolves with the authentication result
+     * @throws {CivicAuthError} If authentication fails or times out
+     */
+    startAuthentication(): Promise<AuthResult>;
+    /**
+     * Cleans up resources and event listeners
+     */
+    cleanup(): void;
+    private handleCallback;
+    /**
+     * Get the current session
+     */
+    getCurrentSession(): Promise<Session | null>;
+    /**
+     * Check if user is authenticated
+     */
+    isAuthenticated(): Promise<boolean>;
+    /**
+     * Get the current user
+     */
+    getCurrentUser(): Promise<import("../../types.js").BaseUser | null>;
+    /**
+     * Clear the current session
+     */
+    clearSession(): Promise<void>;
+    /**
+     * Manually refresh tokens
+     */
+    refreshTokens(): Promise<void>;
+    /**
+     * Get token refresher state for debugging
+     */
+    getTokenRefresherState(): {
+        isInitialized: boolean;
+        isAuthenticated: boolean;
+        isAutoRefreshActive: boolean;
+    } | null;
+    /**
+     * Update the iframe display mode
+     * @param mode - The display mode to use for the iframe
+     */
+    setIframeDisplayMode(mode: "modal" | "embedded"): void;
+    /**
+     * Get the current iframe display mode
+     * @returns The current iframe display mode
+     */
+    getIframeDisplayMode(): "modal" | "embedded" | undefined;
+    /**
+     * Destroy the auth client and clean up all resources
+     */
+    destroy(): Promise<void>;
+}
+//# sourceMappingURL=CivicAuth.d.ts.map

package/dist/vanillajs/auth/CivicAuth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CivicAuth.d.ts","sourceRoot":"","sources":["../../../src/vanillajs/auth/CivicAuth.ts"],"names":[],"mappings":"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"}