@tern-secure/types 1.0.3 → 1.0.5

package/dist/index.d.mts

@@ -53,6 +53,7 @@ interface TernSecureConfig {
     appId: string;
     measurementId?: string;
     appName?: string;
+    tenantId?: string;
 }
 /**
  * Configuration validation result
@@ -94,6 +95,12 @@ interface TernSecureAdminConfig {
     clientEmail: string;
     privateKey: string;
 }
+/**
+ * Firebase Server configuration interface
+ */
+interface TernSecureServerConfig {
+    apiKey: string;
+}
 /**
  * Firebase Admin configuration validation result
  */
@@ -102,24 +109,38 @@ interface AdminConfigValidationResult {
     errors: string[];
     config: TernSecureAdminConfig;
 }
+/**
+ * Firebase Server configuration validation result
+ */
+interface ServerConfigValidationResult {
+    isValid: boolean;
+    errors: string[];
+    config: TernSecureServerConfig;
+}
+type InstanceType = 'production' | 'development';
 
-type ErrorCode = keyof typeof ERRORS;
-interface AuthErrorResponse {
-    success: false;
+interface TernSecureAPIError {
+    code: string;
     message: string;
-    code: ErrorCode;
 }
-interface AuthErrorTree extends Error {
-    code?: any | string;
-    message: string;
-    response?: any | string;
+
+interface CookieStore {
+    get(name: string): Promise<{
+        value: string | undefined;
+    }>;
+    set(name: string, value: string, options: CookieOptions): Promise<void>;
+    delete(name: string): Promise<void>;
 }
-interface SignInResponseTree {
-    success: boolean;
-    message?: string;
-    error?: any | undefined;
-    user?: any;
+interface CookieOptions {
+    maxAge?: number;
+    httpOnly?: boolean;
+    secure?: boolean;
+    sameSite?: 'strict' | 'lax' | 'none';
+    path?: string;
 }
+
+type AuthErrorCode = keyof typeof ERRORS;
+type ErrorCode = keyof typeof ERRORS;
 declare const ERRORS: {
     readonly SERVER_SIDE_INITIALIZATION: "TernSecure must be initialized on the client side";
     readonly REQUIRES_VERIFICATION: "AUTH_REQUIRES_VERIFICATION";
@@ -154,20 +175,6 @@ declare const ERRORS: {
     readonly INVALID_ID_TOKEN: "Invalid ID token.";
     readonly REDIRECT_LOOP: "Redirect loop detected.";
 };
-type AuthErrorCode = keyof typeof ERRORS;
-declare class TernSecureError extends Error {
-    code: ErrorCode;
-    constructor(code: ErrorCode, message?: string);
-}
-/**
- * Handles Firebase authentication errors with multiple fallback mechanisms
- */
-declare function handleFirebaseAuthError(error: unknown): AuthErrorResponse;
-/**
- * Type guard to check if a response is an AuthErrorResponse
- */
-declare function isAuthErrorResponse(response: unknown): response is AuthErrorResponse;
-declare function getErrorAlertVariant(error: any | undefined): "destructive" | "default";
 
 /**
  * Defines the basic structure for color theming.
@@ -372,7 +379,7 @@ interface SignUpProps extends RedirectConfig {
  * for managing the authentication lifecycle. It is designed to be used by
  * UI packages like tern-ui, which act as "dumb" renderers.
  */
-interface TernSecureInstance {
+interface TernSecureInstanceOld {
     /** Indicates if the user is currently signed in. */
     isSignedIn: () => boolean;
     /** The current authenticated user object, or null if not signed in. */
@@ -426,7 +433,7 @@ type SessionStatus = 'active' | 'expired' | 'revoked' | 'pending';
 /**
  * parsed can be replaced with
  */
-declare interface ParsedToken {
+interface ParsedToken {
     /** Expiration time of the token. */
     'exp'?: string;
     /** UID of the user. */
@@ -475,18 +482,21 @@ interface AuthenticatedSessionBase {
  */
 interface ActiveSession extends AuthenticatedSessionBase {
     status: 'active';
+    user?: TernSecureUser;
 }
 /**
  * Represents a session when the user was authenticated, but the token has expired.
  */
 interface ExpiredSession extends AuthenticatedSessionBase {
     status: 'expired';
+    user?: TernSecureUser;
 }
 /**
  * Represents a session that is awaiting some action.
  */
 interface PendingSession extends AuthenticatedSessionBase {
     status: 'pending';
+    user?: TernSecureUser;
 }
 /**
  * Defines the possible states of a user's session within TernSecure.
@@ -514,6 +524,22 @@ type SignInFormValuesTree = {
     password: string;
     phoneNumber?: string;
 };
+interface AuthErrorResponse {
+    success: false;
+    message: string;
+    code: ErrorCode;
+}
+interface AuthErrorTree extends Error {
+    code?: any | string;
+    message: string;
+    response?: any | string;
+}
+interface SignInResponseTree {
+    success: boolean;
+    message?: string;
+    error?: any | undefined;
+    user?: any;
+}
 type SignInInitialValueTree = Partial<SignInFormValuesTree>;
 interface ResendEmailVerification extends SignInResponseTree {
     isVerified?: boolean;
@@ -582,6 +608,88 @@ interface SignUpResource {
 }
 type SignUpStatus = 'missing_requirements' | 'complete' | 'abandoned';
 
+interface FirebaseClaims {
+    identities: {
+        [key: string]: unknown;
+    };
+    sign_in_provider: string;
+    sign_in_second_factor?: string;
+    second_factor_identifier?: string;
+    tenant?: string;
+    [key: string]: unknown;
+}
+interface DecodedIdToken {
+    aud: string;
+    auth_time: number;
+    email?: string;
+    email_verified?: boolean;
+    exp: number;
+    firebase: FirebaseClaims;
+    iat: number;
+    iss: string;
+    phone_number?: string;
+    picture?: string;
+    sub: string;
+    uid: string;
+    [key: string]: any;
+}
+interface VerifiedTokens {
+    IdToken: string;
+    DecodedIdToken: DecodedIdToken;
+}
+interface JWTProtectedHeader {
+    alg?: string;
+    kid?: string;
+    x5t?: string;
+    x5c?: string[];
+    x5u?: string;
+    jku?: string;
+    typ?: string;
+    cty?: string;
+    crit?: string[];
+    b64?: boolean;
+    enc?: string;
+    [propName: string]: unknown;
+}
+interface JWTPayload {
+    iss?: string;
+    sub?: string;
+    aud?: string | string[];
+    jti?: string;
+    nbf?: number;
+    exp?: number;
+    iat?: number;
+    [propName: string]: unknown;
+}
+type Jwt = {
+    header: JWTProtectedHeader;
+    payload: JWTPayload;
+    signature: Uint8Array;
+    raw: {
+        header: string;
+        payload: string;
+        signature: string;
+        text: string;
+    };
+};
+
+type SignInRedirectUrl = {
+    signInForceRedirectUrl?: string | null;
+};
+type SignUpRedirectUrl = {
+    signUpForceRedirectUrl?: string | null;
+};
+type AfterSignOutUrl = {
+    afterSignOutUrl?: string | null;
+};
+type RedirectOptions = SignInRedirectUrl | SignUpRedirectUrl;
+
+interface InitialState {
+    userId: string | null;
+    token: any | null;
+    email: string | null;
+    user?: TernSecureUser | null;
+}
 interface TernSecureState {
     userId: string | null;
     isLoaded: boolean;
@@ -594,7 +702,7 @@ interface TernSecureState {
     status: "loading" | "authenticated" | "unauthenticated" | "unverified";
     user?: TernSecureUser | null;
 }
-type AuthProviderStatus = 'idle' | 'pending' | 'error' | 'success';
+type AuthProviderStatus = "idle" | "pending" | "error" | "success";
 declare const DEFAULT_TERN_SECURE_STATE: TernSecureState;
 interface TernSecureAuthProvider {
     /** Current auth state */
@@ -606,25 +714,172 @@ interface TernSecureAuthProvider {
     /** Current session */
     currentSession: SignedInSession | null;
     /** Sign in resource for authentication operations */
-    signIn: SignInResource;
+    signIn: SignInResource | undefined;
     /** SignUp resource for authentication operations */
-    signUp: SignUpResource;
+    signUp: SignUpResource | undefined;
     /** The Firebase configuration used by this TernAuth instance. */
     ternSecureConfig?: TernSecureConfig;
     /** Sign out the current user */
     signOut(): Promise<void>;
 }
-
-type SignInRedirectUrl = {
-    signInForceRedirectUrl?: string | null;
+type Persistence = "local" | "session" | "browserCookie" | "none";
+type Mode$1 = "browser" | "server";
+type TernAuthSDK = {
+    /** SDK package name (e.g., @tern-secure/auth) */
+    name: string;
+    /** SDK version (e.g., 1.2.3) */
+    version: string;
+    /** Build environment (development, production, test) */
+    environment?: string;
+    /** Build date as ISO string */
+    buildDate?: string;
+    /** Additional build metadata */
+    buildInfo?: {
+        name: string;
+        version: string;
+        buildDate: string;
+        buildEnv: string;
+    };
 };
-type SignUpRedirectUrl = {
-    signUpForceRedirectUrl?: string | null;
+interface TernSecureResources {
+    user?: TernSecureUser | null;
+    session?: SignedInSession | null;
+}
+type TernSecureAuthOptions = {
+    apiUrl?: string;
+    sdkMetadata?: TernAuthSDK;
+    signInUrl?: string;
+    signUpUrl?: string;
+    mode?: Mode$1;
+    requiresVerification?: boolean;
+    isTernSecureDev?: boolean;
+    ternSecureConfig?: TernSecureConfig;
+    persistence?: Persistence;
+    enableServiceWorker?: boolean;
+} & SignInRedirectUrl & SignUpRedirectUrl & AfterSignOutUrl;
+type TernAuthListenerEventPayload = {
+    authStateChanged: TernSecureState;
+    userChanged: TernSecureUser;
+    sessionChanged: SignedInSession | null;
+    tokenRefreshed: string | null;
+};
+type TernAuthListenerEvent = keyof TernAuthListenerEventPayload;
+type ListenerCallback = (emission: TernSecureResources) => void;
+type UnsubscribeCallback = () => void;
+type TernSecureEvent = keyof TernAuthEventPayload;
+type EventHandler<Events extends TernSecureEvent> = (payload: TernAuthEventPayload[Events]) => void;
+type TernAuthEventPayload = {
+    status: TernSecureAuthStatus;
+};
+type TernSecureAuthStatus = "error" | "loading" | "ready";
+type onEventListener = <E extends TernSecureEvent>(event: E, handler: EventHandler<E>, opt?: {
+    notify?: boolean;
+}) => void;
+type OffEventListener = <E extends TernSecureEvent>(event: E, handler: EventHandler<E>) => void;
+type SignOutOptions = {
+    /** URL to redirect to after sign out */
+    redirectUrl?: string;
+    /** Callback to perform consumer-specific cleanup (e.g., delete session cookies) */
+    onBeforeSignOut?: () => Promise<void> | void;
+    /** Callback executed after successful sign out */
+    onAfterSignOut?: () => Promise<void> | void;
+};
+interface SignOut {
+    (options?: SignOutOptions): Promise<void>;
+}
+interface TernSecureAuth {
+    /** TernSecureAuth SDK version number */
+    version: string | undefined;
+    /** Metadata about the SDK instance */
+    sdkMetadata: TernAuthSDK | undefined;
+    /** Indicates if the TernSecureAuth instance is currently loading */
+    isLoading: boolean;
+    /** The current status of the TernSecureAuth instance */
+    status: TernSecureAuthStatus;
+    /** TernSecure API URL */
+    apiUrl: string;
+    /** TernSecure domain for API string */
+    domain: string;
+    /** TernSecure Proxy url */
+    proxyUrl?: string;
+    /** TernSecure Instance type */
+    instanceType: InstanceType | undefined;
+    /** Indicates if the TernSecureAuth instance is ready for use */
+    isReady: boolean;
+    /** Requires Verification */
+    requiresVerification: boolean;
+    /** Initialize TernSecureAuth */
+    initialize(options?: TernSecureAuthOptions): Promise<void>;
+    /** Current user*/
+    user: TernSecureUser | null | undefined;
+    /** Current session */
+    currentSession: SignedInSession | null;
+    /** Sign in resource for authentication operations */
+    signIn: SignInResource | undefined | null;
+    /** SignUp resource for authentication operations */
+    signUp: SignUpResource | undefined | null;
+    /** The Firebase configuration used by this TernAuth instance. */
+    ternSecureConfig?: TernSecureConfig;
+    /** Subscribe to auth state changes */
+    onAuthStateChanged(callback: (cb: any) => void): () => void;
+    /** Sign out the current user */
+    signOut: SignOut;
+    /** Subscribe to a single event */
+    on: onEventListener;
+    /** Remove event listener */
+    off: OffEventListener;
+    addListener: (callback: ListenerCallback) => UnsubscribeCallback;
+}
+interface TernSecureAuthFactory {
+    create(options?: TernSecureAuthOptions): TernSecureAuth;
+}
+type SharedSignInAuthObjectProperties = {
+    session: DecodedIdToken;
+    userId: string;
+};
+type CheckCustomClaims = {
+    role?: string | string[];
+    permissions?: string | string[];
+    [key: string]: any;
+};
+type CheckAuthorizationFromSessionClaims = (isAuthorizedParams: CheckCustomClaims) => boolean;
+type TernVerificationResult = (DecodedIdToken & {
+    valid: true;
+    token?: string;
+    error?: never;
+}) | {
+    valid: false;
+    error: AuthErrorResponse;
 };
-type RedirectOptions = SignInRedirectUrl | SignUpRedirectUrl;
 
 type Mode = 'browser' | 'server';
+type TernSecureSDK = {
+    /** SDK package name (e.g., @tern-secure/ui) */
+    name: string;
+    /** SDK version (e.g., 1.2.3) */
+    version: string;
+    /** Build environment (development, production, test) */
+    environment?: string;
+    /** Build date as ISO string */
+    buildDate?: string;
+    /** Additional build metadata */
+    buildInfo?: {
+        name: string;
+        version: string;
+        buildDate: string;
+        buildEnv: string;
+    };
+};
+type SignOutOptionsTree = {
+    /** URL to redirect to after sign out */
+    redirectUrl?: string;
+    /** Callback to perform consumer-specific cleanup (e.g., delete session cookies) */
+    onBeforeSignOut?: () => Promise<void> | void;
+    /** Callback executed after successful sign out */
+    onAfterSignOut?: () => Promise<void> | void;
+};
 type TernSecureInstanceTreeOptions = {
+    sdkMetadata?: TernSecureSDK;
     initialSession?: TernSecureSessionTree | null;
     defaultAppearance?: Appearance;
     signInUrl?: string;
@@ -632,17 +887,18 @@ type TernSecureInstanceTreeOptions = {
     mode?: Mode;
     onAuthStateChanged?: (user: TernSecureUser | null) => void;
     onError?: (error: AuthErrorTree) => void;
-    environment?: string | undefined;
     requiresVerification?: boolean;
     isTernSecureDev?: boolean;
     ternSecureConfig?: TernSecureConfig;
     enableServiceWorker?: boolean;
-} & SignInRedirectUrl & SignUpRedirectUrl;
+} & SignInRedirectUrl & SignUpRedirectUrl & AfterSignOutUrl;
 type TernSecureInstanceTreeStatus = 'error' | 'loading' | 'ready';
 /**
  * Instance interface for managing auth UI state
  */
 interface TernSecureInstanceTree {
+    version: string | undefined;
+    sdkMetadata: TernSecureSDK | undefined;
     customDomain?: string;
     proxyUrl?: string;
     apiKey?: string;
@@ -665,6 +921,8 @@ interface TernSecureInstanceTree {
     };
     /** Core Authentication Methods */
     ternAuth: TernSecureAuthProvider | undefined;
+    /** Sign out current user with optional cleanup */
+    signOut: (options?: SignOutOptionsTree) => Promise<void>;
     showSignIn: (targetNode: HTMLDivElement, config?: SignInPropsTree) => void;
     hideSignIn: (targetNode: HTMLDivElement) => void;
     showSignUp: (targetNode: HTMLDivElement, config?: SignUpPropsTree) => void;
@@ -695,6 +953,23 @@ interface TernSecureInstanceTree {
         onStatusChanged: (callback: (status: TernSecureInstanceTreeStatus) => void) => () => void;
     };
 }
+/**
+ * Instance interface for managing auth UI state
+ */
+interface TernSecureInstance {
+    customDomain?: string;
+    proxyUrl?: string;
+    apiKey?: string;
+    projectId?: string;
+    environment?: string | undefined;
+    mode?: Mode;
+    isReady: boolean;
+    isLoading: boolean;
+    error: Error | null;
+    requiresVerification: boolean;
+    /** Sign out current user with optional cleanup */
+    signOut: (options?: SignOutOptionsTree) => Promise<void>;
+}
 type SignUpFormValuesTree = {
     email: string;
     password: string;
@@ -736,4 +1011,44 @@ type SignUpPropsTree = {
 type SignInRedirectOptions = RedirectOptions;
 type SignUpRedirectOptions = RedirectOptions;
 
-export { type ActiveSession, type AdminConfigValidationResult, type Appearance, type AuthActions, type AuthError, type AuthErrorCode, type AuthErrorResponse, type AuthErrorTree, type AuthProviderStatus, type BaseAuthUIConfig, type ConfigValidationResult, DEFAULT_TERN_SECURE_STATE, ERRORS, type ErrorCode, type ExpiredSession, type FirebaseState, type IdTokenResult, type ParsedToken, type PendingSession, type RedirectConfig, type RedirectOptions, type ResendEmailVerification, type SessionParams, type SessionResult, type SessionStatus, type SignInFormValuesTree, type SignInInitialValue, type SignInInitialValueTree, type SignInProps, type SignInPropsTree, type SignInRedirectOptions, type SignInRedirectUrl, type SignInResource, type SignInResponse, type SignInResponseTree, type SignInStatus, type SignInUIConfig, type SignUpFormValuesTree, type SignUpInitialValue, type SignUpInitialValueTree, type SignUpProps, type SignUpPropsTree, type SignUpRedirectOptions, type SignUpRedirectUrl, type SignUpResource, type SignUpStatus, type SignUpUIConfig, type SignedInSession, type TernSecureAdminConfig, type TernSecureAuthProvider, type TernSecureConfig, TernSecureError, type TernSecureInstance, type TernSecureInstanceTree, type TernSecureInstanceTreeOptions, type TernSecureInstanceTreeStatus, type TernSecureOptions, type TernSecureSession, type TernSecureSessionTree, type TernSecureState, type TernSecureUser, type TernSecureUserData, type ThemeBorderRadius, type ThemeColors, type ThemeComponentStyles, type ThemeFonts, type ThemeSpacing, type UserInfo, getErrorAlertVariant, handleFirebaseAuthError, isAuthErrorResponse, isSignInResponse, isSignInResponseTree };
+interface TernSecureApiErrorJSON {
+    code: string;
+    message: string;
+}
+
+type UseAuthReturn = {
+    userId: string | null | undefined;
+    isLoaded: boolean;
+    isValid: boolean;
+    isVerified: boolean;
+    isAuthenticated: boolean;
+    token: any | null;
+    email: string | null;
+    status: "loading" | "authenticated" | "unauthenticated" | "unverified";
+    user?: TernSecureUser | null;
+    signOut: SignOut;
+};
+type UseSignInReturn = {
+    isLoaded: false;
+    signIn: undefined;
+} | {
+    isLoaded: true;
+    signIn: SignInResource;
+};
+
+type DomainOrProxyUrl = {
+    proxyUrl?: never;
+    domain?: string | ((url: URL) => string);
+} | {
+    proxyUrl?: string | ((url: URL) => string);
+    domain?: never;
+};
+
+/**
+ * Enables autocompletion for a union type, while keeping the ability to use any string
+ * or type of `T`
+ * @internal
+ */
+type Autocomplete<U extends T, T = string> = U | (T & Record<never, never>);
+
+export { type ActiveSession, type AdminConfigValidationResult, type AfterSignOutUrl, type Appearance, type AuthActions, type AuthError, type AuthErrorCode, type AuthErrorResponse, type AuthErrorTree, type AuthProviderStatus, type Autocomplete, type BaseAuthUIConfig, type CheckAuthorizationFromSessionClaims, type CheckCustomClaims, type ConfigValidationResult, type CookieOptions, type CookieStore, DEFAULT_TERN_SECURE_STATE, type DecodedIdToken, type DomainOrProxyUrl, ERRORS, type ErrorCode, type ExpiredSession, type FirebaseClaims, type FirebaseState, type IdTokenResult, type InitialState, type InstanceType, type JWTPayload, type JWTProtectedHeader, type Jwt, type ListenerCallback, type ParsedToken, type PendingSession, type Persistence, type RedirectConfig, type RedirectOptions, type ResendEmailVerification, type ServerConfigValidationResult, type SessionParams, type SessionResult, type SessionStatus, type SharedSignInAuthObjectProperties, type SignInFormValuesTree, type SignInInitialValue, type SignInInitialValueTree, type SignInProps, type SignInPropsTree, type SignInRedirectOptions, type SignInRedirectUrl, type SignInResource, type SignInResponse, type SignInResponseTree, type SignInStatus, type SignInUIConfig, type SignOut, type SignOutOptions, type SignOutOptionsTree, type SignUpFormValuesTree, type SignUpInitialValue, type SignUpInitialValueTree, type SignUpProps, type SignUpPropsTree, type SignUpRedirectOptions, type SignUpRedirectUrl, type SignUpResource, type SignUpStatus, type SignUpUIConfig, type SignedInSession, type TernAuthEventPayload, type TernAuthListenerEvent, type TernAuthListenerEventPayload, type TernAuthSDK, type TernSecureAPIError, type TernSecureAdminConfig, type TernSecureApiErrorJSON, type TernSecureAuth, type TernSecureAuthFactory, type TernSecureAuthOptions, type TernSecureAuthProvider, type TernSecureAuthStatus, type TernSecureConfig, type TernSecureInstance, type TernSecureInstanceOld, type TernSecureInstanceTree, type TernSecureInstanceTreeOptions, type TernSecureInstanceTreeStatus, type TernSecureOptions, type TernSecureResources, type TernSecureSDK, type TernSecureServerConfig, type TernSecureSession, type TernSecureSessionTree, type TernSecureState, type TernSecureUser, type TernSecureUserData, type TernVerificationResult, type ThemeBorderRadius, type ThemeColors, type ThemeComponentStyles, type ThemeFonts, type ThemeSpacing, type UnsubscribeCallback, type UseAuthReturn, type UseSignInReturn, type UserInfo, type VerifiedTokens, isSignInResponse, isSignInResponseTree };