@ccatto/react-auth 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,296 @@
+export { C as CattoAuthClientConfig, a as CattoAuthDatabaseClient, b as CattoAuthServerConfig, c as CattoAuthSocialProvider, d as CattoSessionProviderConfig } from './config-CvzbPvtw.cjs';
+
+/**
+ * @ccatto/react-auth - Session Types
+ *
+ * Types for enriched sessions, users, and compatibility with NextAuth patterns.
+ */
+interface EnrichedUser {
+    id: string;
+    email: string;
+    name: string | null;
+    image: string | null;
+    /** Custom fields added by enrichSession hook */
+    playerID?: number;
+    role: string;
+    organizationId: string | null;
+    organizations: Array<{
+        id: string;
+        name: string;
+        slug: string;
+        role: string;
+        permissions: string[];
+    }>;
+    /** Allow additional custom fields from enrichSession */
+    [key: string]: unknown;
+}
+interface EnrichedSession {
+    user: EnrichedUser;
+    session: {
+        id: string;
+        expiresAt: Date;
+        token: string;
+        createdAt: Date;
+        updatedAt: Date;
+        userId: string;
+    };
+}
+interface CompatSessionUser {
+    id: string;
+    email: string;
+    name: string | null;
+    image: string | null;
+    playerID?: number;
+    role: string;
+    organizationId: string | null;
+    organizations: Array<{
+        id: string;
+        name: string;
+        slug: string;
+        role: string;
+        permissions: string[];
+    }>;
+}
+interface CompatSession {
+    user: CompatSessionUser;
+    expires: string;
+}
+interface AuthStoreUser {
+    userId: string;
+    email: string;
+    name?: string;
+    image?: string;
+    role?: string;
+    playerID?: number;
+    organizationId?: string;
+    organizations?: Array<{
+        id: string;
+        name: string;
+        slug: string;
+        role: string;
+        permissions: string[];
+    }>;
+}
+
+/**
+ * @ccatto/react-auth - Session Store
+ *
+ * Synchronous session state store for sharing auth session with Apollo Client.
+ * Avoids network calls in Apollo's authLink.
+ *
+ * @example
+ * // Write (from SessionSync component in React tree)
+ * sessionStore.setSession(session);
+ *
+ * // Read (from Apollo authLink — synchronous, no network call)
+ * const session = sessionStore.getSession();
+ */
+
+declare const sessionStore: {
+    /** Get the current session (synchronous, no network call) */
+    getSession(): CompatSession | null;
+    /** Update the session (called by SessionSync component) */
+    setSession(session: CompatSession | null): void;
+    /** Subscribe to session changes */
+    subscribe(listener: (session: CompatSession | null) => void): () => void;
+    /** Get the user ID from the current session (convenience method) */
+    getUserId(): string | null;
+};
+
+/**
+ * @ccatto/react-auth - Auth Storage Interface
+ *
+ * Platform-agnostic interface for auth token storage.
+ * Implementations handle platform-specific storage (web vs mobile).
+ */
+interface IAuthStorage {
+    /** Store access token */
+    setAccessToken(token: string): Promise<void>;
+    /** Retrieve access token */
+    getAccessToken(): Promise<string | null>;
+    /** Store refresh token */
+    setRefreshToken(token: string): Promise<void>;
+    /** Retrieve refresh token */
+    getRefreshToken(): Promise<string | null>;
+    /** Remove all tokens (logout) */
+    clearTokens(): Promise<void>;
+    /** Check if user has valid tokens */
+    hasTokens(): Promise<boolean>;
+}
+
+/**
+ * @ccatto/react-auth - Auth API Interface
+ *
+ * Abstract interface for auth API calls. Apps provide their own
+ * implementation (e.g., GraphQL, REST, etc.).
+ */
+interface AuthUser {
+    id: string;
+    email: string;
+    name: string | null;
+    role: string;
+    playerID?: number;
+    organizationId?: string | null;
+}
+interface LoginCredentials {
+    email: string;
+    password: string;
+}
+interface RegisterData {
+    email: string;
+    password: string;
+    name: string;
+}
+interface AuthTokens {
+    accessToken: string;
+    refreshToken: string;
+}
+interface LoginResponse extends AuthTokens {
+    user: AuthUser;
+}
+interface PasskeyAuthenticationOptions {
+    options: string;
+    sessionId: string;
+}
+interface SendOtpResponse {
+    success: boolean;
+    message: string;
+    expiresIn: number;
+}
+interface VerifyOtpSuccess {
+    success: true;
+    message: string;
+    accessToken: string;
+    refreshToken: string;
+    isNewUser?: boolean;
+    userId?: string;
+}
+interface VerifyOtpFailure {
+    success: false;
+    message: string;
+}
+type VerifyOtpResponse = VerifyOtpSuccess | VerifyOtpFailure;
+/**
+ * Auth API service interface.
+ * Implement this with your API layer (GraphQL, REST, etc.).
+ */
+interface IAuthApiService {
+    login(credentials: LoginCredentials): Promise<LoginResponse>;
+    register(data: RegisterData): Promise<LoginResponse>;
+    logout(refreshToken: string): Promise<void>;
+    refreshToken(refreshToken: string): Promise<{
+        accessToken: string;
+    }>;
+    forgotPassword?(email: string): Promise<{
+        message: string;
+        resetToken?: string;
+    }>;
+    resetPassword?(resetToken: string, newPassword: string): Promise<{
+        message: string;
+    }>;
+    sendPhoneOtp?(phoneNumber: string): Promise<SendOtpResponse>;
+    verifyPhoneOtp?(phoneNumber: string, code: string): Promise<VerifyOtpResponse>;
+    generatePasskeyAuthenticationOptions?(email?: string): Promise<PasskeyAuthenticationOptions>;
+    verifyPasskeyAuthentication?(sessionId: string, response: string): Promise<LoginResponse>;
+}
+/**
+ * Optional logger interface for auth services.
+ * Implement with your logging framework (Pino, Winston, console, etc.).
+ */
+interface IAuthLogger {
+    info(message: string, data?: Record<string, unknown>): void;
+    warn(message: string, data?: Record<string, unknown>): void;
+    error(message: string, data?: Record<string, unknown>): void;
+}
+
+/**
+ * @ccatto/react-auth - JWT Auth Service
+ *
+ * Platform-agnostic JWT authentication service.
+ * Handles token storage, login, register, refresh, and passkey auth.
+ *
+ * Uses IAuthStorage for token persistence and IAuthApiService for API calls.
+ *
+ * @example
+ * ```typescript
+ * import { JwtAuthService, CapacitorAuthStorage } from '@ccatto/react-auth';
+ *
+ * const storage = new CapacitorAuthStorage({ keyPrefix: 'myapp' });
+ * const authService = new JwtAuthService(storage, myApiService, undefined, {
+ *   onSessionExpired: () => router.push('/login'),
+ * });
+ * await authService.login({ email, password });
+ * ```
+ */
+
+interface JwtAuthServiceOptions {
+    /** Called when session expires (refresh token fails). Use to redirect to login. */
+    onSessionExpired?: () => void;
+}
+declare class JwtAuthService {
+    private storage;
+    private api;
+    private log;
+    private options;
+    private cachedTokenExp;
+    private refreshPromise;
+    private lastRefreshFailure;
+    private static REFRESH_COOLDOWN_MS;
+    constructor(storage: IAuthStorage, api: IAuthApiService, logger?: IAuthLogger, options?: JwtAuthServiceOptions);
+    /** Login with email and password */
+    login(credentials: LoginCredentials): Promise<LoginResponse>;
+    /** Register new user */
+    register(data: RegisterData): Promise<LoginResponse>;
+    /** Logout (clear tokens) */
+    logout(): Promise<void>;
+    /** Refresh access token */
+    refreshAccessToken(): Promise<string>;
+    /** Get current access token */
+    getAccessToken(): Promise<string | null>;
+    /** Check if a JWT token is expired or about to expire */
+    private isTokenExpiredOrExpiring;
+    /**
+     * Get auth headers for API requests.
+     * Proactively refreshes the access token if it's expired or about to expire.
+     * Includes cooldown to prevent repeated refresh attempts after failure.
+     */
+    getAuthHeaders(): Promise<Record<string, string>>;
+    /** Check if user is authenticated */
+    isAuthenticated(): Promise<boolean>;
+    /** Check if tokens exist in storage */
+    hasTokens(): Promise<boolean>;
+    /** Decode JWT token (client-side only — for user info, NOT for security) */
+    decodeToken(token: string): AuthUser | null;
+    /** Get current user from token (client-side decode) */
+    getCurrentUser(): Promise<AuthUser | null>;
+    /** Login with passkey (WebAuthn/FIDO2) */
+    loginWithPasskey(): Promise<LoginResponse>;
+    /** Send OTP to phone number for phone-based login */
+    sendPhoneOtp(phoneNumber: string): Promise<{
+        success: boolean;
+        message: string;
+        expiresIn: number;
+    }>;
+    /** Verify OTP and login/register user */
+    verifyPhoneOtp(phoneNumber: string, code: string): Promise<LoginResponse & {
+        isNewUser: boolean;
+    }>;
+}
+
+interface CapacitorAuthStorageOptions {
+    /** Key prefix for stored tokens (default: 'catto_auth') */
+    keyPrefix?: string;
+}
+declare class CapacitorAuthStorage implements IAuthStorage {
+    private readonly ACCESS_TOKEN_KEY;
+    private readonly REFRESH_TOKEN_KEY;
+    constructor(options?: CapacitorAuthStorageOptions);
+    setAccessToken(token: string): Promise<void>;
+    getAccessToken(): Promise<string | null>;
+    setRefreshToken(token: string): Promise<void>;
+    getRefreshToken(): Promise<string | null>;
+    clearTokens(): Promise<void>;
+    hasTokens(): Promise<boolean>;
+}
+
+export { type AuthStoreUser, type AuthTokens, type AuthUser, CapacitorAuthStorage, type CapacitorAuthStorageOptions, type CompatSession, type CompatSessionUser, type EnrichedSession, type EnrichedUser, type IAuthApiService, type IAuthLogger, type IAuthStorage, JwtAuthService, type LoginCredentials, type LoginResponse, type PasskeyAuthenticationOptions, type RegisterData, type SendOtpResponse, type VerifyOtpFailure, type VerifyOtpResponse, type VerifyOtpSuccess, sessionStore };

package/dist/index.d.ts

@@ -0,0 +1,296 @@
+export { C as CattoAuthClientConfig, a as CattoAuthDatabaseClient, b as CattoAuthServerConfig, c as CattoAuthSocialProvider, d as CattoSessionProviderConfig } from './config-CvzbPvtw.js';
+
+/**
+ * @ccatto/react-auth - Session Types
+ *
+ * Types for enriched sessions, users, and compatibility with NextAuth patterns.
+ */
+interface EnrichedUser {
+    id: string;
+    email: string;
+    name: string | null;
+    image: string | null;
+    /** Custom fields added by enrichSession hook */
+    playerID?: number;
+    role: string;
+    organizationId: string | null;
+    organizations: Array<{
+        id: string;
+        name: string;
+        slug: string;
+        role: string;
+        permissions: string[];
+    }>;
+    /** Allow additional custom fields from enrichSession */
+    [key: string]: unknown;
+}
+interface EnrichedSession {
+    user: EnrichedUser;
+    session: {
+        id: string;
+        expiresAt: Date;
+        token: string;
+        createdAt: Date;
+        updatedAt: Date;
+        userId: string;
+    };
+}
+interface CompatSessionUser {
+    id: string;
+    email: string;
+    name: string | null;
+    image: string | null;
+    playerID?: number;
+    role: string;
+    organizationId: string | null;
+    organizations: Array<{
+        id: string;
+        name: string;
+        slug: string;
+        role: string;
+        permissions: string[];
+    }>;
+}
+interface CompatSession {
+    user: CompatSessionUser;
+    expires: string;
+}
+interface AuthStoreUser {
+    userId: string;
+    email: string;
+    name?: string;
+    image?: string;
+    role?: string;
+    playerID?: number;
+    organizationId?: string;
+    organizations?: Array<{
+        id: string;
+        name: string;
+        slug: string;
+        role: string;
+        permissions: string[];
+    }>;
+}
+
+/**
+ * @ccatto/react-auth - Session Store
+ *
+ * Synchronous session state store for sharing auth session with Apollo Client.
+ * Avoids network calls in Apollo's authLink.
+ *
+ * @example
+ * // Write (from SessionSync component in React tree)
+ * sessionStore.setSession(session);
+ *
+ * // Read (from Apollo authLink — synchronous, no network call)
+ * const session = sessionStore.getSession();
+ */
+
+declare const sessionStore: {
+    /** Get the current session (synchronous, no network call) */
+    getSession(): CompatSession | null;
+    /** Update the session (called by SessionSync component) */
+    setSession(session: CompatSession | null): void;
+    /** Subscribe to session changes */
+    subscribe(listener: (session: CompatSession | null) => void): () => void;
+    /** Get the user ID from the current session (convenience method) */
+    getUserId(): string | null;
+};
+
+/**
+ * @ccatto/react-auth - Auth Storage Interface
+ *
+ * Platform-agnostic interface for auth token storage.
+ * Implementations handle platform-specific storage (web vs mobile).
+ */
+interface IAuthStorage {
+    /** Store access token */
+    setAccessToken(token: string): Promise<void>;
+    /** Retrieve access token */
+    getAccessToken(): Promise<string | null>;
+    /** Store refresh token */
+    setRefreshToken(token: string): Promise<void>;
+    /** Retrieve refresh token */
+    getRefreshToken(): Promise<string | null>;
+    /** Remove all tokens (logout) */
+    clearTokens(): Promise<void>;
+    /** Check if user has valid tokens */
+    hasTokens(): Promise<boolean>;
+}
+
+/**
+ * @ccatto/react-auth - Auth API Interface
+ *
+ * Abstract interface for auth API calls. Apps provide their own
+ * implementation (e.g., GraphQL, REST, etc.).
+ */
+interface AuthUser {
+    id: string;
+    email: string;
+    name: string | null;
+    role: string;
+    playerID?: number;
+    organizationId?: string | null;
+}
+interface LoginCredentials {
+    email: string;
+    password: string;
+}
+interface RegisterData {
+    email: string;
+    password: string;
+    name: string;
+}
+interface AuthTokens {
+    accessToken: string;
+    refreshToken: string;
+}
+interface LoginResponse extends AuthTokens {
+    user: AuthUser;
+}
+interface PasskeyAuthenticationOptions {
+    options: string;
+    sessionId: string;
+}
+interface SendOtpResponse {
+    success: boolean;
+    message: string;
+    expiresIn: number;
+}
+interface VerifyOtpSuccess {
+    success: true;
+    message: string;
+    accessToken: string;
+    refreshToken: string;
+    isNewUser?: boolean;
+    userId?: string;
+}
+interface VerifyOtpFailure {
+    success: false;
+    message: string;
+}
+type VerifyOtpResponse = VerifyOtpSuccess | VerifyOtpFailure;
+/**
+ * Auth API service interface.
+ * Implement this with your API layer (GraphQL, REST, etc.).
+ */
+interface IAuthApiService {
+    login(credentials: LoginCredentials): Promise<LoginResponse>;
+    register(data: RegisterData): Promise<LoginResponse>;
+    logout(refreshToken: string): Promise<void>;
+    refreshToken(refreshToken: string): Promise<{
+        accessToken: string;
+    }>;
+    forgotPassword?(email: string): Promise<{
+        message: string;
+        resetToken?: string;
+    }>;
+    resetPassword?(resetToken: string, newPassword: string): Promise<{
+        message: string;
+    }>;
+    sendPhoneOtp?(phoneNumber: string): Promise<SendOtpResponse>;
+    verifyPhoneOtp?(phoneNumber: string, code: string): Promise<VerifyOtpResponse>;
+    generatePasskeyAuthenticationOptions?(email?: string): Promise<PasskeyAuthenticationOptions>;
+    verifyPasskeyAuthentication?(sessionId: string, response: string): Promise<LoginResponse>;
+}
+/**
+ * Optional logger interface for auth services.
+ * Implement with your logging framework (Pino, Winston, console, etc.).
+ */
+interface IAuthLogger {
+    info(message: string, data?: Record<string, unknown>): void;
+    warn(message: string, data?: Record<string, unknown>): void;
+    error(message: string, data?: Record<string, unknown>): void;
+}
+
+/**
+ * @ccatto/react-auth - JWT Auth Service
+ *
+ * Platform-agnostic JWT authentication service.
+ * Handles token storage, login, register, refresh, and passkey auth.
+ *
+ * Uses IAuthStorage for token persistence and IAuthApiService for API calls.
+ *
+ * @example
+ * ```typescript
+ * import { JwtAuthService, CapacitorAuthStorage } from '@ccatto/react-auth';
+ *
+ * const storage = new CapacitorAuthStorage({ keyPrefix: 'myapp' });
+ * const authService = new JwtAuthService(storage, myApiService, undefined, {
+ *   onSessionExpired: () => router.push('/login'),
+ * });
+ * await authService.login({ email, password });
+ * ```
+ */
+
+interface JwtAuthServiceOptions {
+    /** Called when session expires (refresh token fails). Use to redirect to login. */
+    onSessionExpired?: () => void;
+}
+declare class JwtAuthService {
+    private storage;
+    private api;
+    private log;
+    private options;
+    private cachedTokenExp;
+    private refreshPromise;
+    private lastRefreshFailure;
+    private static REFRESH_COOLDOWN_MS;
+    constructor(storage: IAuthStorage, api: IAuthApiService, logger?: IAuthLogger, options?: JwtAuthServiceOptions);
+    /** Login with email and password */
+    login(credentials: LoginCredentials): Promise<LoginResponse>;
+    /** Register new user */
+    register(data: RegisterData): Promise<LoginResponse>;
+    /** Logout (clear tokens) */
+    logout(): Promise<void>;
+    /** Refresh access token */
+    refreshAccessToken(): Promise<string>;
+    /** Get current access token */
+    getAccessToken(): Promise<string | null>;
+    /** Check if a JWT token is expired or about to expire */
+    private isTokenExpiredOrExpiring;
+    /**
+     * Get auth headers for API requests.
+     * Proactively refreshes the access token if it's expired or about to expire.
+     * Includes cooldown to prevent repeated refresh attempts after failure.
+     */
+    getAuthHeaders(): Promise<Record<string, string>>;
+    /** Check if user is authenticated */
+    isAuthenticated(): Promise<boolean>;
+    /** Check if tokens exist in storage */
+    hasTokens(): Promise<boolean>;
+    /** Decode JWT token (client-side only — for user info, NOT for security) */
+    decodeToken(token: string): AuthUser | null;
+    /** Get current user from token (client-side decode) */
+    getCurrentUser(): Promise<AuthUser | null>;
+    /** Login with passkey (WebAuthn/FIDO2) */
+    loginWithPasskey(): Promise<LoginResponse>;
+    /** Send OTP to phone number for phone-based login */
+    sendPhoneOtp(phoneNumber: string): Promise<{
+        success: boolean;
+        message: string;
+        expiresIn: number;
+    }>;
+    /** Verify OTP and login/register user */
+    verifyPhoneOtp(phoneNumber: string, code: string): Promise<LoginResponse & {
+        isNewUser: boolean;
+    }>;
+}
+
+interface CapacitorAuthStorageOptions {
+    /** Key prefix for stored tokens (default: 'catto_auth') */
+    keyPrefix?: string;
+}
+declare class CapacitorAuthStorage implements IAuthStorage {
+    private readonly ACCESS_TOKEN_KEY;
+    private readonly REFRESH_TOKEN_KEY;
+    constructor(options?: CapacitorAuthStorageOptions);
+    setAccessToken(token: string): Promise<void>;
+    getAccessToken(): Promise<string | null>;
+    setRefreshToken(token: string): Promise<void>;
+    getRefreshToken(): Promise<string | null>;
+    clearTokens(): Promise<void>;
+    hasTokens(): Promise<boolean>;
+}
+
+export { type AuthStoreUser, type AuthTokens, type AuthUser, CapacitorAuthStorage, type CapacitorAuthStorageOptions, type CompatSession, type CompatSessionUser, type EnrichedSession, type EnrichedUser, type IAuthApiService, type IAuthLogger, type IAuthStorage, JwtAuthService, type LoginCredentials, type LoginResponse, type PasskeyAuthenticationOptions, type RegisterData, type SendOtpResponse, type VerifyOtpFailure, type VerifyOtpResponse, type VerifyOtpSuccess, sessionStore };