@lastshotlabs/snapshot 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,396 @@
+import { UseMutationResult, QueryClient } from '@tanstack/react-query';
+import React from 'react';
+
+interface TokenStorage {
+    get: () => string | null;
+    set: (token: string) => void;
+    clear: () => void;
+    getRefreshToken: () => string | null;
+    setRefreshToken: (token: string) => void;
+    clearRefreshToken: () => void;
+}
+
+declare class ApiClient {
+    private readonly baseUrl;
+    private readonly authMode;
+    private readonly bearerToken;
+    private storage;
+    private onUnauthenticated;
+    private onForbidden;
+    private onMfaSetupRequired;
+    constructor(config: Pick<SnapshotConfig, 'apiUrl' | 'auth' | 'bearerToken' | 'onUnauthenticated' | 'onForbidden'> & {
+        onMfaSetupRequired?: () => void;
+    });
+    setStorage(storage: TokenStorage): void;
+    private buildHeaders;
+    private rawFetch;
+    private handleResponse;
+    private request;
+    get<T>(path: string, options?: RequestOptions): Promise<T>;
+    post<T>(path: string, body: unknown, options?: RequestOptions): Promise<T>;
+    put<T>(path: string, body: unknown, options?: RequestOptions): Promise<T>;
+    patch<T>(path: string, body: unknown, options?: RequestOptions): Promise<T>;
+    delete<T>(path: string, body?: unknown, options?: RequestOptions): Promise<T>;
+}
+
+declare class ApiError extends Error {
+    readonly status: number;
+    readonly body: unknown;
+    constructor(status: number, body: unknown, message?: string);
+}
+
+type WsConfig = NonNullable<SnapshotConfig['ws']>;
+declare class WebSocketManager<TEvents extends Record<string, unknown> = Record<string, unknown>> {
+    private ws;
+    private readonly rooms;
+    private readonly listeners;
+    private reconnectAttempts;
+    private reconnectTimer;
+    private destroyed;
+    private readonly url;
+    private readonly autoReconnect;
+    private readonly reconnectOnFocus;
+    private readonly maxReconnectAttempts;
+    private readonly reconnectBaseDelay;
+    private readonly reconnectMaxDelay;
+    private readonly onConnected;
+    private readonly onDisconnected;
+    private readonly onReconnecting;
+    private readonly onReconnectFailed;
+    constructor(config: WsConfig);
+    get isConnected(): boolean;
+    private handleVisibilityChange;
+    private connect;
+    private sendMessage;
+    private scheduleReconnect;
+    private clearReconnectTimer;
+    subscribe(room: string): void;
+    unsubscribe(room: string): void;
+    getRooms(): string[];
+    send(type: string, payload: unknown): void;
+    on<K extends keyof TEvents>(event: K, handler: (data: TEvents[K]) => void): void;
+    off<K extends keyof TEvents>(event: K, handler: (data: TEvents[K]) => void): void;
+    reconnect(): void;
+    disconnect(): void;
+}
+
+interface AuthUser {
+    id: string;
+    email: string;
+    [key: string]: unknown;
+}
+interface LoginBody {
+    email: string;
+    password: string;
+}
+interface RegisterBody {
+    email: string;
+    password: string;
+    [key: string]: unknown;
+}
+interface ForgotPasswordBody {
+    email: string;
+}
+type LoginVars = LoginBody & {
+    redirectTo?: string;
+};
+type RegisterVars = RegisterBody & {
+    redirectTo?: string;
+};
+interface LogoutVars {
+    redirectTo?: string;
+}
+type MfaMethod = 'totp' | 'emailOtp' | 'webauthn';
+/** Raw login response shape from bunshot (includes MFA fields) */
+interface LoginResponse {
+    token: string;
+    userId: string;
+    refreshToken?: string;
+    mfaRequired?: boolean;
+    mfaToken?: string;
+    mfaMethods?: MfaMethod[];
+}
+/** Returned by useLogin when mfaRequired is true */
+interface MfaChallenge {
+    mfaToken: string;
+    mfaMethods: MfaMethod[];
+}
+/** useLogin resolves to either a user or an MFA challenge */
+type LoginResult = AuthUser | MfaChallenge;
+declare function isMfaChallenge(result: LoginResult): result is MfaChallenge;
+interface MfaVerifyBody {
+    mfaToken: string;
+    code?: string;
+    method?: MfaMethod;
+    webauthnResponse?: unknown;
+}
+interface MfaSetupResponse {
+    secret: string;
+    uri: string;
+}
+interface MfaVerifySetupBody {
+    code: string;
+}
+interface MfaVerifySetupResponse {
+    message: string;
+    recoveryCodes: string[];
+}
+interface MfaDisableBody {
+    code: string;
+}
+interface MfaRecoveryCodesBody {
+    code: string;
+}
+interface MfaRecoveryCodesResponse {
+    recoveryCodes: string[];
+}
+interface MfaEmailOtpEnableResponse {
+    message: string;
+    setupToken: string;
+}
+interface MfaEmailOtpVerifySetupBody {
+    setupToken: string;
+    code: string;
+}
+interface MfaEmailOtpDisableBody {
+    code?: string;
+    password?: string;
+}
+interface MfaResendBody {
+    mfaToken: string;
+}
+interface MfaMethodsResponse {
+    methods: MfaMethod[];
+}
+interface ResetPasswordBody {
+    token: string;
+    password: string;
+}
+interface VerifyEmailBody {
+    token: string;
+}
+interface ResendVerificationBody {
+    email: string;
+}
+interface SetPasswordBody {
+    password: string;
+    currentPassword?: string;
+}
+interface DeleteAccountBody {
+    password?: string;
+}
+interface RefreshTokenBody {
+    refreshToken?: string;
+}
+interface RefreshTokenResponse {
+    token: string;
+    refreshToken?: string;
+    userId: string;
+}
+interface Session {
+    sessionId: string;
+    ipAddress?: string;
+    userAgent?: string;
+    createdAt: number;
+    lastActiveAt: number;
+    expiresAt: number;
+    isActive: boolean;
+}
+type OAuthProvider = 'google' | 'apple' | 'microsoft' | 'github';
+interface OAuthExchangeBody {
+    code: string;
+}
+interface OAuthExchangeResponse {
+    token: string;
+    userId: string;
+    email?: string;
+    refreshToken?: string;
+}
+interface WebAuthnRegisterOptionsResponse {
+    options: unknown;
+    registrationToken: string;
+}
+interface WebAuthnRegisterBody {
+    registrationToken: string;
+    attestationResponse: unknown;
+    name?: string;
+}
+interface WebAuthnCredential {
+    credentialId: string;
+    name?: string;
+    createdAt: number;
+    transports?: string[];
+}
+interface PasskeyLoginOptionsBody {
+    email?: string;
+}
+interface PasskeyLoginOptionsResponse {
+    options: unknown;
+    passkeyToken: string;
+}
+interface PasskeyLoginBody {
+    passkeyToken: string;
+    assertionResponse: unknown;
+}
+interface RequestOptions {
+    headers?: Record<string, string>;
+    signal?: AbortSignal;
+}
+interface SocketHook<TEvents = Record<string, unknown>> {
+    isConnected: boolean;
+    send: (type: string, payload: unknown) => void;
+    subscribe: (room: string) => void;
+    unsubscribe: (room: string) => void;
+    getRooms: () => string[];
+    on: <K extends keyof TEvents>(event: K, handler: (data: TEvents[K]) => void) => void;
+    off: <K extends keyof TEvents>(event: K, handler: (data: TEvents[K]) => void) => void;
+    reconnect: () => void;
+}
+interface SnapshotConfig {
+    apiUrl: string;
+    /** `'cookie'` is the default and is the recommended mode for browser apps. */
+    auth?: 'cookie' | 'token';
+    /**
+     * Static API credential. Not a user session token. Do not use in browser
+     * deployments — emits a runtime warning in browser contexts.
+     */
+    bearerToken?: string;
+    loginPath?: string;
+    homePath?: string;
+    forbiddenPath?: string;
+    mfaPath?: string;
+    mfaSetupPath?: string;
+    onUnauthenticated?: () => void;
+    onForbidden?: () => void;
+    /**
+     * When `auth: 'token'` is used, `'sessionStorage'` is the default (tab-scoped, survives
+     * refresh). `'memory'` is a stricter opt-in (loses state on page reload, does not share
+     * across tabs). `'localStorage'` is not recommended for auth tokens.
+     */
+    tokenStorage?: 'localStorage' | 'sessionStorage' | 'memory';
+    tokenKey?: string;
+    staleTime?: number;
+    gcTime?: number;
+    retry?: number;
+    ws?: {
+        url: string;
+        autoReconnect?: boolean;
+        reconnectOnLogin?: boolean;
+        reconnectOnFocus?: boolean;
+        maxReconnectAttempts?: number;
+        reconnectBaseDelay?: number;
+        reconnectMaxDelay?: number;
+        onConnected?: () => void;
+        onDisconnected?: () => void;
+        onReconnecting?: (attempt: number) => void;
+        onReconnectFailed?: () => void;
+    };
+}
+interface SnapshotInstance<TWSEvents extends Record<string, unknown> = Record<string, unknown>> {
+    useUser: () => {
+        user: AuthUser | null;
+        isLoading: boolean;
+        isError: boolean;
+    };
+    useLogin: () => UseMutationResult<LoginResult, ApiError, LoginVars>;
+    useLogout: () => UseMutationResult<void, ApiError, LogoutVars | void>;
+    useRegister: () => UseMutationResult<AuthUser, ApiError, RegisterVars>;
+    useForgotPassword: () => UseMutationResult<void, ApiError, ForgotPasswordBody>;
+    useSocket: () => SocketHook<TWSEvents>;
+    useRoom: (room: string) => {
+        isSubscribed: boolean;
+    };
+    useRoomEvent: <T>(room: string, event: string, handler: (data: T) => void) => void;
+    useTheme: () => {
+        theme: 'light' | 'dark';
+        toggle: () => void;
+        set: (t: 'light' | 'dark') => void;
+    };
+    usePendingMfaChallenge: () => MfaChallenge | null;
+    useMfaVerify: () => UseMutationResult<AuthUser, ApiError, Omit<MfaVerifyBody, 'mfaToken'>>;
+    useMfaSetup: () => UseMutationResult<MfaSetupResponse, ApiError, void>;
+    useMfaVerifySetup: () => UseMutationResult<MfaVerifySetupResponse, ApiError, MfaVerifySetupBody>;
+    useMfaDisable: () => UseMutationResult<{
+        message: string;
+    }, ApiError, MfaDisableBody>;
+    useMfaRecoveryCodes: () => UseMutationResult<MfaRecoveryCodesResponse, ApiError, MfaRecoveryCodesBody>;
+    useMfaEmailOtpEnable: () => UseMutationResult<MfaEmailOtpEnableResponse, ApiError, void>;
+    useMfaEmailOtpVerifySetup: () => UseMutationResult<MfaVerifySetupResponse, ApiError, MfaEmailOtpVerifySetupBody>;
+    useMfaEmailOtpDisable: () => UseMutationResult<{
+        message: string;
+    }, ApiError, MfaEmailOtpDisableBody>;
+    useMfaResend: () => UseMutationResult<{
+        message: string;
+    }, ApiError, MfaResendBody>;
+    useMfaMethods: () => {
+        methods: MfaMethod[] | null;
+        isLoading: boolean;
+        isError: boolean;
+    };
+    isMfaChallenge: typeof isMfaChallenge;
+    useResetPassword: () => UseMutationResult<{
+        message: string;
+    }, ApiError, ResetPasswordBody>;
+    useVerifyEmail: () => UseMutationResult<{
+        message: string;
+    }, ApiError, VerifyEmailBody>;
+    useResendVerification: () => UseMutationResult<{
+        message: string;
+    }, ApiError, ResendVerificationBody>;
+    useSetPassword: () => UseMutationResult<{
+        message: string;
+    }, ApiError, SetPasswordBody>;
+    useDeleteAccount: () => UseMutationResult<void, ApiError, DeleteAccountBody | void>;
+    useCancelDeletion: () => UseMutationResult<{
+        message: string;
+    }, ApiError, void>;
+    useRefreshToken: () => UseMutationResult<RefreshTokenResponse, ApiError, RefreshTokenBody | void>;
+    useSessions: () => {
+        sessions: Session[];
+        isLoading: boolean;
+        isError: boolean;
+    };
+    useRevokeSession: () => UseMutationResult<void, ApiError, string>;
+    useOAuthExchange: () => UseMutationResult<OAuthExchangeResponse, ApiError, OAuthExchangeBody>;
+    useOAuthUnlink: () => UseMutationResult<void, ApiError, OAuthProvider>;
+    getOAuthUrl: (provider: OAuthProvider) => string;
+    getLinkUrl: (provider: OAuthProvider) => string;
+    useWebAuthnRegisterOptions: () => UseMutationResult<WebAuthnRegisterOptionsResponse, ApiError, void>;
+    useWebAuthnRegister: () => UseMutationResult<{
+        message: string;
+    }, ApiError, WebAuthnRegisterBody>;
+    useWebAuthnCredentials: () => {
+        credentials: WebAuthnCredential[];
+        isLoading: boolean;
+        isError: boolean;
+    };
+    useWebAuthnRemoveCredential: () => UseMutationResult<{
+        message: string;
+    }, ApiError, string>;
+    useWebAuthnDisable: () => UseMutationResult<{
+        message: string;
+    }, ApiError, void>;
+    usePasskeyLoginOptions: () => UseMutationResult<PasskeyLoginOptionsResponse, ApiError, PasskeyLoginOptionsBody>;
+    usePasskeyLogin: () => UseMutationResult<LoginResult, ApiError, PasskeyLoginBody>;
+    api: ApiClient;
+    tokenStorage: TokenStorage;
+    queryClient: QueryClient;
+    useWebSocketManager: () => WebSocketManager<TWSEvents> | null;
+    protectedBeforeLoad: (ctx: {
+        context: {
+            queryClient: QueryClient;
+        };
+    }) => Promise<void>;
+    guestBeforeLoad: (ctx: {
+        context: {
+            queryClient: QueryClient;
+        };
+    }) => Promise<void>;
+    QueryProvider: React.FC<{
+        children: React.ReactNode;
+    }>;
+}
+
+declare function createSnapshot<TWSEvents extends Record<string, unknown> = Record<string, unknown>>(config: SnapshotConfig): SnapshotInstance<TWSEvents>;
+
+export { ApiError, type AuthUser, type DeleteAccountBody, type ForgotPasswordBody, type LoginBody, type LoginResponse, type LoginResult, type LoginVars, type LogoutVars, type MfaChallenge, type MfaDisableBody, type MfaEmailOtpDisableBody, type MfaEmailOtpEnableResponse, type MfaEmailOtpVerifySetupBody, type MfaMethod, type MfaMethodsResponse, type MfaRecoveryCodesBody, type MfaRecoveryCodesResponse, type MfaResendBody, type MfaSetupResponse, type MfaVerifyBody, type MfaVerifySetupBody, type MfaVerifySetupResponse, type OAuthExchangeBody, type OAuthExchangeResponse, type OAuthProvider, type PasskeyLoginBody, type PasskeyLoginOptionsBody, type PasskeyLoginOptionsResponse, type RefreshTokenBody, type RefreshTokenResponse, type RegisterBody, type RegisterVars, type RequestOptions, type ResendVerificationBody, type ResetPasswordBody, type Session, type SetPasswordBody, type SnapshotConfig, type SnapshotInstance, type SocketHook, type TokenStorage, type VerifyEmailBody, type WebAuthnCredential, type WebAuthnRegisterBody, type WebAuthnRegisterOptionsResponse, WebSocketManager, createSnapshot, isMfaChallenge };