@archie/react-sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,246 @@
+import React from 'react';
+import { ArchieClient, Session, User, AuthSignInParams, ArchieError, AuthSignUpParams, AuthConfirmParams, AuthRecoverParams, AuthResetPasswordParams, ConnectionState, FileUploadOptions, FileUploadResult, IRestModule, RestRequestOptions } from '@archie/js-sdk';
+export { ArchieClient, ArchieClientOptions, ArchieError, AuthConfirmParams, AuthError, AuthEvent, AuthEventCallback, AuthRecoverParams, AuthResetPasswordParams, AuthSignInParams, AuthSignUpParams, BrowserLocalStorage, ConnectionState, ConnectionStateCallback, CsvUploadOptions, FileUploadOptions, FileUploadResult, GraphQLError, GraphQLRawRequest, GraphQLRequestOptions, GraphQLResponse, IAuthModule, IFileModule, IGraphQLModule, IHttpClient, IRealtimeModule, IRestModule, Logger, MemoryStorage, NetworkError, RealtimeChannel, RealtimeEvent, RestRequestOptions, Session, StorageAdapter, Subscription, SubscriptionCallbacks, TokenAccessor, User, createClient } from '@archie/js-sdk';
+
+interface ArchieContextValue {
+    client: ArchieClient;
+    session: Session | null;
+    isLoading: boolean;
+}
+interface ArchieProviderProps {
+    client: ArchieClient;
+    children: React.ReactNode;
+}
+/**
+ * ArchieProvider — wraps your React app to provide the Archie client and session state.
+ *
+ * @example
+ * ```tsx
+ * import { createClient } from '@archie/js-sdk'
+ * import { ArchieProvider } from '@archie/react-sdk'
+ *
+ * const archie = createClient({ projectId: '...' })
+ *
+ * function App() {
+ *   return (
+ *     <ArchieProvider client={archie}>
+ *       <MyApp />
+ *     </ArchieProvider>
+ *   )
+ * }
+ * ```
+ */
+declare function ArchieProvider({ client, children }: ArchieProviderProps): React.FunctionComponentElement<React.ProviderProps<ArchieContextValue | null>>;
+
+/**
+ * Returns the ArchieClient instance from context.
+ * Must be used within an ArchieProvider.
+ *
+ * @throws Error if used outside ArchieProvider
+ */
+declare function useArchieClient(): ArchieClient;
+
+interface UseAuthReturn {
+    user: User | null;
+    session: Session | null;
+    isLoading: boolean;
+    isAuthenticated: boolean;
+    signIn: (params: AuthSignInParams) => Promise<{
+        session: Session | null;
+        error: ArchieError | null;
+    }>;
+    signUp: (params: AuthSignUpParams) => Promise<{
+        data: {
+            userId: string;
+            message: string;
+        } | null;
+        error: ArchieError | null;
+    }>;
+    signOut: () => Promise<void>;
+    confirmSignUp: (params: AuthConfirmParams) => Promise<{
+        session: Session | null;
+        error: ArchieError | null;
+    }>;
+    recoverPassword: (params: AuthRecoverParams) => Promise<{
+        data: {
+            message: string;
+        } | null;
+        error: ArchieError | null;
+    }>;
+    resetPassword: (params: AuthResetPasswordParams) => Promise<{
+        data: {
+            message: string;
+        } | null;
+        error: ArchieError | null;
+    }>;
+    refreshSession: () => Promise<{
+        session: Session | null;
+        error: ArchieError | null;
+    }>;
+}
+/**
+ * Hook for authentication state and operations.
+ * All methods return `{ data/session, error }` (never throws).
+ */
+declare function useAuth(): UseAuthReturn;
+
+interface UseQueryOptions<T> {
+    enabled?: boolean;
+    refetchInterval?: number;
+    refetchOnWindowFocus?: boolean;
+    onSuccess?: (data: T) => void;
+    onError?: (error: ArchieError) => void;
+}
+interface UseQueryReturn<T> {
+    data: T | null;
+    error: ArchieError | null;
+    isLoading: boolean;
+    isRefetching: boolean;
+    refetch: () => Promise<void>;
+}
+/**
+ * Declarative GraphQL query hook with caching and stale-while-revalidate.
+ *
+ * @example
+ * ```tsx
+ * const { data, isLoading } = useQuery<{ users: User[] }>(
+ *   'query { users { id email name } }',
+ *   { limit: 10 }
+ * )
+ * ```
+ */
+declare function useQuery<T = unknown>(gql: string, variables?: Record<string, unknown>, options?: UseQueryOptions<T>): UseQueryReturn<T>;
+
+interface UseMutationOptions<T> {
+    onSuccess?: (data: T) => void;
+    onError?: (error: ArchieError) => void;
+    onSettled?: () => void;
+    /** Query substrings to invalidate (forcing refetch) after a successful mutation. */
+    invalidateQueries?: string[];
+}
+interface UseMutationReturn<T> {
+    mutate: (variables?: Record<string, unknown>) => void;
+    mutateAsync: (variables?: Record<string, unknown>) => Promise<T | null>;
+    data: T | null;
+    error: ArchieError | null;
+    isLoading: boolean;
+    reset: () => void;
+}
+/**
+ * Hook for GraphQL mutations.
+ *
+ * @example
+ * ```tsx
+ * const { mutate, isLoading } = useMutation<{ createUser: User }>(
+ *   'mutation($data: CreateUserInput!) { createUser(data: $data) { id email } }',
+ *   { invalidateQueries: ['users'] }
+ * )
+ *
+ * mutate({ data: { email: 'new@user.com', name: 'John' } })
+ * ```
+ */
+declare function useMutation<T = unknown>(gql: string, options?: UseMutationOptions<T>): UseMutationReturn<T>;
+
+interface UseSubscriptionOptions<T> {
+    enabled?: boolean;
+    onData?: (data: T) => void;
+    onError?: (error: ArchieError) => void;
+}
+interface UseSubscriptionReturn<T> {
+    data: T | null;
+    error: ArchieError | null;
+    connectionState: ConnectionState;
+}
+/**
+ * Hook for real-time GraphQL subscriptions.
+ * Subscribes on mount, unsubscribes on unmount.
+ *
+ * @example
+ * ```tsx
+ * const { data } = useSubscription<{ orderUpdated: Order }>(
+ *   'subscription { orderUpdated { id status total } }'
+ * )
+ * ```
+ */
+declare function useSubscription<T = unknown>(gql: string, variables?: Record<string, unknown>, options?: UseSubscriptionOptions<T>): UseSubscriptionReturn<T>;
+
+interface UseFileUploadReturn {
+    upload: (file: File | Blob, options?: FileUploadOptions) => Promise<void>;
+    progress: number;
+    isUploading: boolean;
+    data: FileUploadResult | null;
+    error: ArchieError | null;
+    reset: () => void;
+}
+/**
+ * Hook for file uploads with progress tracking.
+ *
+ * @example
+ * ```tsx
+ * const { upload, progress, isUploading } = useFileUpload()
+ *
+ * <input type="file" onChange={(e) => upload(e.target.files[0])} />
+ * {isUploading && <ProgressBar value={progress} />}
+ * ```
+ */
+declare function useFileUpload(): UseFileUploadReturn;
+
+/**
+ * Returns the REST module from the Archie client.
+ * Provides direct access to `get`, `post`, `put`, `patch`, `delete`.
+ *
+ * @example
+ * ```tsx
+ * const rest = useRest()
+ * const data = await rest.get('/api/products')
+ * await rest.post('/api/products', { name: 'Widget' })
+ * ```
+ */
+declare function useRest(): IRestModule;
+interface UseRestQueryReturn<T> {
+    data: T | null;
+    error: ArchieError | null;
+    isLoading: boolean;
+    refetch: () => Promise<void>;
+}
+/**
+ * Declarative hook for GET requests to custom REST APIs.
+ */
+declare function useRestQuery<T = unknown>(path: string, options?: RestRequestOptions & {
+    enabled?: boolean;
+}): UseRestQueryReturn<T>;
+interface UseRestMutationReturn<T> {
+    execute: (body?: unknown, overrideOptions?: RestRequestOptions) => Promise<T | null>;
+    data: T | null;
+    error: ArchieError | null;
+    isLoading: boolean;
+    reset: () => void;
+}
+/**
+ * Imperative hook for POST/PUT/PATCH/DELETE requests to custom REST APIs.
+ */
+declare function useRestMutation<T = unknown>(path: string, method?: 'POST' | 'PUT' | 'PATCH' | 'DELETE'): UseRestMutationReturn<T>;
+
+interface AuthGuardProps {
+    /** Content to show when authenticated (and authorized if roles specified). */
+    children: React.ReactNode;
+    /** Content to show when NOT authenticated. */
+    fallback?: React.ReactNode;
+    /** Content to show while session is loading. */
+    loadingComponent?: React.ReactNode;
+    /** If specified, user must have at least one of these roles. */
+    requiredRoles?: string[];
+}
+/**
+ * AuthGuard component — conditionally renders children based on auth state.
+ *
+ * @example
+ * ```tsx
+ * <AuthGuard fallback={<LoginPage />} requiredRoles={['admin']}>
+ *   <AdminPanel />
+ * </AuthGuard>
+ * ```
+ */
+declare function AuthGuard({ children, fallback, loadingComponent, requiredRoles, }: AuthGuardProps): React.FunctionComponentElement<React.FragmentProps>;
+
+export { ArchieProvider, type ArchieProviderProps, AuthGuard, type AuthGuardProps, useArchieClient, useAuth, useFileUpload, useMutation, useQuery, useRest, useRestMutation, useRestQuery, useSubscription };