import * as React from 'react';
import { ReactNode } from 'react';
import { ObjectStackClient, PaginatedResult } from '@objectstack/client';
export { ClientConfig, ObjectStackClient } from '@objectstack/client';
import { QueryAST, FilterCondition } from '@objectstack/spec/data';
import { DataEvent, MetadataEvent } from '@objectstack/spec/api';

/**
 * ObjectStack React Context
 *
 * Provides ObjectStackClient instance to React components via Context API
 */

interface ObjectStackProviderProps {
    client: ObjectStackClient;
    /**
     * Active UI locale (BCP-47, e.g. `'zh-CN'`). Keep this in sync with your
     * language switcher — the provider pushes it into the client (so requests
     * carry `Accept-Language`) and metadata hooks (`useObject`, `useView`,
     * `useMetadata`) re-fetch when it changes, so switching language relabels
     * the UI without a page refresh (issue #1319).
     */
    locale?: string;
    children: ReactNode;
}
declare const ObjectStackContext: React.Context<ObjectStackClient | null>;
/**
 * Carries the active UI locale separately from the client so existing
 * `useContext(ObjectStackContext)` consumers keep receiving the bare client
 * (no breaking change to that context's shape).
 */
declare const ObjectStackLocaleContext: React.Context<string | undefined>;
/**
 * Provider component that makes ObjectStackClient available to all child components
 *
 * @example
 * ```tsx
 * const client = new ObjectStackClient({ baseUrl: 'http://localhost:3000' });
 *
 * function App() {
 *   return (
 *     <ObjectStackProvider client={client} locale={language}>
 *       <YourComponents />
 *     </ObjectStackProvider>
 *   );
 * }
 * ```
 */
declare function ObjectStackProvider({ client, locale, children }: ObjectStackProviderProps): React.JSX.Element;
/**
 * Hook to read the active UI locale provided to {@link ObjectStackProvider}.
 * Returns `undefined` when no locale was supplied. Metadata hooks fold this
 * into their fetch dependencies so a locale change triggers a re-fetch.
 */
declare function useObjectStackLocale(): string | undefined;
/**
 * Hook to access the ObjectStackClient instance from context
 *
 * @throws Error if used outside of ObjectStackProvider
 *
 * @example
 * ```tsx
 * function MyComponent() {
 *   const client = useClient();
 *   // Use client.data.find(), etc.
 * }
 * ```
 */
declare function useClient(): ObjectStackClient;

/**
 * Query options for useQuery hook
 *
 * Supports both **canonical** (Spec protocol) and **legacy** field names.
 * Canonical names are preferred; legacy names are accepted for backward
 * compatibility and will be removed in a future major release.
 *
 * | Canonical | Legacy (deprecated) |
 * |-----------|---------------------|
 * | `where`   | `filters`           |
 * | `fields`  | `select`            |
 * | `orderBy` | `sort`              |
 * | `limit`   | `top`               |
 * | `offset`  | `skip`              |
 */
interface UseQueryOptions<T = any> {
    /** Query AST or simplified query options */
    query?: Partial<QueryAST>;
    /** Filter conditions (WHERE clause). */
    where?: FilterCondition;
    /** Fields to retrieve (SELECT clause). */
    fields?: string[];
    /** Sort definition (ORDER BY clause). */
    orderBy?: string | string[];
    /** Maximum number of records to return (LIMIT). */
    limit?: number;
    /** Number of records to skip (OFFSET). */
    offset?: number;
    /** @deprecated Use `fields` instead. */
    select?: string[];
    /** @deprecated Use `where` instead. */
    filters?: FilterCondition;
    /** @deprecated Use `orderBy` instead. */
    sort?: string | string[];
    /** @deprecated Use `limit` instead. */
    top?: number;
    /** @deprecated Use `offset` instead. */
    skip?: number;
    /** Enable/disable automatic query execution */
    enabled?: boolean;
    /** Refetch interval in milliseconds */
    refetchInterval?: number;
    /** Callback on successful query */
    onSuccess?: (data: PaginatedResult<T>) => void;
    /** Callback on error */
    onError?: (error: Error) => void;
}
/**
 * Query result for useQuery hook
 */
interface UseQueryResult<T = any> {
    /** Query result data */
    data: PaginatedResult<T> | null;
    /** Loading state */
    isLoading: boolean;
    /** Error state */
    error: Error | null;
    /** Refetch the query */
    refetch: () => Promise<void>;
    /** Is currently refetching */
    isRefetching: boolean;
}
/**
 * Hook for querying ObjectStack data with automatic caching and refetching
 *
 * @example
 * ```tsx
 * function TaskList() {
 *   const { data, isLoading, error, refetch } = useQuery('todo_task', {
 *     fields: ['id', 'subject', 'priority'],
 *     orderBy: ['-created_at'],
 *     limit: 20
 *   });
 *
 *   if (isLoading) return <div>Loading...</div>;
 *   if (error) return <div>Error: {error.message}</div>;
 *
 *   return (
 *     <div>
 *       {data?.value.map(task => (
 *         <div key={task.id}>{task.subject}</div>
 *       ))}
 *     </div>
 *   );
 * }
 * ```
 */
declare function useQuery<T = any>(object: string, options?: UseQueryOptions<T>): UseQueryResult<T>;
/**
 * Mutation options for useMutation hook
 */
interface UseMutationOptions<TData = any, TVariables = any> {
    /** Callback on successful mutation */
    onSuccess?: (data: TData, variables: TVariables) => void;
    /** Callback on error */
    onError?: (error: Error, variables: TVariables) => void;
    /** Callback when mutation is settled (success or error) */
    onSettled?: (data: TData | undefined, error: Error | null, variables: TVariables) => void;
}
/**
 * Mutation result for useMutation hook
 */
interface UseMutationResult<TData = any, TVariables = any> {
    /** Execute the mutation */
    mutate: (variables: TVariables) => Promise<TData>;
    /** Async version of mutate that throws errors */
    mutateAsync: (variables: TVariables) => Promise<TData>;
    /** Mutation result data */
    data: TData | null;
    /** Loading state */
    isLoading: boolean;
    /** Error state */
    error: Error | null;
    /** Reset mutation state */
    reset: () => void;
}
/**
 * Hook for creating, updating, or deleting ObjectStack data
 *
 * @example
 * ```tsx
 * function CreateTaskForm() {
 *   const { mutate, isLoading, error } = useMutation('todo_task', 'create', {
 *     onSuccess: (data) => {
 *       console.log('Task created:', data);
 *     }
 *   });
 *
 *   const handleSubmit = (formData) => {
 *     mutate(formData);
 *   };
 *
 *   return <form onSubmit={handleSubmit}>...</form>;
 * }
 * ```
 */
declare function useMutation<TData = any, TVariables = any>(object: string, operation: 'create' | 'update' | 'delete' | 'createMany' | 'updateMany' | 'deleteMany', options?: UseMutationOptions<TData, TVariables>): UseMutationResult<TData, TVariables>;
/**
 * Pagination options for usePagination hook
 */
interface UsePaginationOptions<T = any> extends Omit<UseQueryOptions<T>, 'top' | 'skip' | 'limit' | 'offset'> {
    /** Page size */
    pageSize?: number;
    /** Initial page (1-based) */
    initialPage?: number;
}
/**
 * Pagination result for usePagination hook
 */
interface UsePaginationResult<T = any> extends UseQueryResult<T> {
    /** Current page (1-based) */
    page: number;
    /** Total number of pages */
    totalPages: number;
    /** Total number of records */
    totalCount: number;
    /** Go to next page */
    nextPage: () => void;
    /** Go to previous page */
    previousPage: () => void;
    /** Go to specific page */
    goToPage: (page: number) => void;
    /** Whether there is a next page */
    hasNextPage: boolean;
    /** Whether there is a previous page */
    hasPreviousPage: boolean;
}
/**
 * Hook for paginated data queries
 *
 * @example
 * ```tsx
 * function PaginatedTaskList() {
 *   const {
 *     data,
 *     isLoading,
 *     page,
 *     totalPages,
 *     nextPage,
 *     previousPage,
 *     hasNextPage,
 *     hasPreviousPage
 *   } = usePagination('todo_task', {
 *     pageSize: 10,
 *     orderBy: ['-created_at']
 *   });
 *
 *   return (
 *     <div>
 *       {data?.value.map(task => <div key={task.id}>{task.subject}</div>)}
 *       <button onClick={previousPage} disabled={!hasPreviousPage}>Previous</button>
 *       <span>Page {page} of {totalPages}</span>
 *       <button onClick={nextPage} disabled={!hasNextPage}>Next</button>
 *     </div>
 *   );
 * }
 * ```
 */
declare function usePagination<T = any>(object: string, options?: UsePaginationOptions<T>): UsePaginationResult<T>;
/**
 * Infinite query options for useInfiniteQuery hook
 */
interface UseInfiniteQueryOptions<T = any> extends Omit<UseQueryOptions<T>, 'skip' | 'offset'> {
    /** Page size for each fetch */
    pageSize?: number;
    /** Get next page parameter */
    getNextPageParam?: (lastPage: PaginatedResult<T>, allPages: PaginatedResult<T>[]) => number | undefined;
}
/**
 * Infinite query result for useInfiniteQuery hook
 */
interface UseInfiniteQueryResult<T = any> {
    /** All pages of data */
    data: PaginatedResult<T>[];
    /** Flattened data from all pages */
    flatData: T[];
    /** Loading state */
    isLoading: boolean;
    /** Error state */
    error: Error | null;
    /** Load the next page */
    fetchNextPage: () => Promise<void>;
    /** Whether there are more pages */
    hasNextPage: boolean;
    /** Is currently fetching next page */
    isFetchingNextPage: boolean;
    /** Refetch all pages */
    refetch: () => Promise<void>;
}
/**
 * Hook for infinite scrolling / load more functionality
 *
 * @example
 * ```tsx
 * function InfiniteTaskList() {
 *   const {
 *     flatData,
 *     isLoading,
 *     fetchNextPage,
 *     hasNextPage,
 *     isFetchingNextPage
 *   } = useInfiniteQuery('todo_task', {
 *     pageSize: 20,
 *     orderBy: ['-created_at']
 *   });
 *
 *   return (
 *     <div>
 *       {flatData.map(task => <div key={task.id}>{task.subject}</div>)}
 *       {hasNextPage && (
 *         <button onClick={fetchNextPage} disabled={isFetchingNextPage}>
 *           {isFetchingNextPage ? 'Loading...' : 'Load More'}
 *         </button>
 *       )}
 *     </div>
 *   );
 * }
 * ```
 */
declare function useInfiniteQuery<T = any>(object: string, options?: UseInfiniteQueryOptions<T>): UseInfiniteQueryResult<T>;

/**
 * Metadata query options
 */
interface UseMetadataOptions {
    /** Enable/disable automatic query execution */
    enabled?: boolean;
    /** Use cached metadata if available */
    useCache?: boolean;
    /** ETag for conditional requests */
    ifNoneMatch?: string;
    /** If-Modified-Since header for conditional requests */
    ifModifiedSince?: string;
    /** Callback on successful query */
    onSuccess?: (data: any) => void;
    /** Callback on error */
    onError?: (error: Error) => void;
}
/**
 * Metadata query result
 */
interface UseMetadataResult<T = any> {
    /** Metadata data */
    data: T | null;
    /** Loading state */
    isLoading: boolean;
    /** Error state */
    error: Error | null;
    /** Refetch the metadata */
    refetch: () => Promise<void>;
    /** ETag from last fetch */
    etag?: string;
    /** Whether data came from cache (304 Not Modified) */
    fromCache: boolean;
}
/**
 * Hook for fetching object schema/metadata
 *
 * @example
 * ```tsx
 * function ObjectSchemaViewer({ objectName }: { objectName: string }) {
 *   const { data: schema, isLoading, error } = useObject(objectName);
 *
 *   if (isLoading) return <div>Loading schema...</div>;
 *   if (error) return <div>Error: {error.message}</div>;
 *
 *   return (
 *     <div>
 *       <h2>{schema.label}</h2>
 *       <p>Fields: {Object.keys(schema.fields).length}</p>
 *     </div>
 *   );
 * }
 * ```
 */
declare function useObject(objectName: string, options?: UseMetadataOptions): UseMetadataResult;
/**
 * Hook for fetching view configuration
 *
 * @example
 * ```tsx
 * function ViewConfiguration({ objectName }: { objectName: string }) {
 *   const { data: view, isLoading } = useView(objectName, 'list');
 *
 *   if (isLoading) return <div>Loading view...</div>;
 *
 *   return (
 *     <div>
 *       <h3>List View for {objectName}</h3>
 *       <p>Columns: {view?.columns?.length}</p>
 *     </div>
 *   );
 * }
 * ```
 */
declare function useView(objectName: string, viewType?: 'list' | 'form', options?: UseMetadataOptions): UseMetadataResult;
/**
 * Hook for extracting fields from object schema
 *
 * @example
 * ```tsx
 * function FieldList({ objectName }: { objectName: string }) {
 *   const { data: fields, isLoading } = useFields(objectName);
 *
 *   if (isLoading) return <div>Loading fields...</div>;
 *
 *   return (
 *     <ul>
 *       {fields?.map(field => (
 *         <li key={field.name}>{field.label} ({field.type})</li>
 *       ))}
 *     </ul>
 *   );
 * }
 * ```
 */
declare function useFields(objectName: string, options?: UseMetadataOptions): UseMetadataResult<any[]>;
/**
 * Generic metadata hook for custom metadata queries
 *
 * @example
 * ```tsx
 * function CustomMetadata() {
 *   const { data, isLoading } = useMetadata(async (client) => {
 *     // Custom metadata fetching logic
 *     const object = await client.meta.getObject('custom_object');
 *     const view = await client.meta.getView('custom_object', 'list');
 *     return { object, view };
 *   });
 *
 *   return <pre>{JSON.stringify(data, null, 2)}</pre>;
 * }
 * ```
 */
declare function useMetadata<T = any>(fetcher: (client: ReturnType<typeof useClient>) => Promise<T>, options?: Omit<UseMetadataOptions, 'useCache' | 'ifNoneMatch' | 'ifModifiedSince'>): UseMetadataResult<T>;

/**
 * Hook to subscribe to metadata events
 *
 * @param type - Metadata type to subscribe to (e.g., 'object', 'view', 'agent')
 * @param options - Optional filters (packageId)
 * @returns Latest metadata event or null
 *
 * @example
 * ```tsx
 * function ObjectList() {
 *   const event = useMetadataSubscription('object');
 *
 *   useEffect(() => {
 *     if (event?.type === 'metadata.object.created') {
 *       console.log('New object:', event.name);
 *       // Refresh list
 *     }
 *   }, [event]);
 *
 *   return <div>...</div>;
 * }
 * ```
 */
declare function useMetadataSubscription(type: string, options?: {
    packageId?: string;
}): MetadataEvent | null;
/**
 * Hook to subscribe to data record events
 *
 * @param object - Object name to subscribe to
 * @param options - Optional filters (recordId for specific record)
 * @returns Latest data event or null
 *
 * @example
 * ```tsx
 * function TaskDetail({ taskId }: { taskId: string }) {
 *   const event = useDataSubscription('project_task', { recordId: taskId });
 *
 *   useEffect(() => {
 *     if (event?.type === 'data.record.updated') {
 *       console.log('Task updated:', event.changes);
 *       // Refresh task data
 *     }
 *   }, [event]);
 *
 *   return <div>...</div>;
 * }
 * ```
 */
declare function useDataSubscription(object: string, options?: {
    recordId?: string;
}): DataEvent | null;
/**
 * Hook to subscribe to metadata events with a callback
 *
 * This variant doesn't store events in state, it just triggers a callback.
 * Useful for triggering refetches or side effects without re-renders.
 *
 * @param type - Metadata type to subscribe to
 * @param callback - Callback to invoke on events
 * @param options - Optional filters
 *
 * @example
 * ```tsx
 * function ObjectList() {
 *   const { refetch } = useQuery(...);
 *
 *   useMetadataSubscriptionCallback('object', () => {
 *     refetch(); // Refetch list when objects change
 *   });
 *
 *   return <div>...</div>;
 * }
 * ```
 */
declare function useMetadataSubscriptionCallback(type: string, callback: (event: MetadataEvent) => void, options?: {
    packageId?: string;
}): void;
/**
 * Hook to subscribe to data events with a callback
 *
 * @param object - Object name to subscribe to
 * @param callback - Callback to invoke on events
 * @param options - Optional filters
 *
 * @example
 * ```tsx
 * function TaskList() {
 *   const { refetch } = useQuery(...);
 *
 *   useDataSubscriptionCallback('project_task', () => {
 *     refetch(); // Refetch list when tasks change
 *   });
 *
 *   return <div>...</div>;
 * }
 * ```
 */
declare function useDataSubscriptionCallback(object: string, callback: (event: DataEvent) => void, options?: {
    recordId?: string;
}): void;
/**
 * Hook to get connection status of realtime events
 *
 * @returns Whether realtime is connected
 *
 * @example
 * ```tsx
 * function ConnectionIndicator() {
 *   const connected = useRealtimeConnection();
 *
 *   return (
 *     <div>
 *       {connected ? '🟢 Connected' : '🔴 Disconnected'}
 *     </div>
 *   );
 * }
 * ```
 */
declare function useRealtimeConnection(): boolean;
/**
 * Hook for auto-refreshing queries when data changes
 *
 * Combines data subscription with query refetch.
 *
 * @param object - Object name to watch
 * @param refetch - Refetch function from useQuery
 * @param options - Optional filters
 *
 * @example
 * ```tsx
 * function TaskList() {
 *   const { data, refetch } = useQuery('project_task', {});
 *
 *   useAutoRefresh('project_task', refetch);
 *
 *   return <div>{data.map(...)}</div>;
 * }
 * ```
 */
declare function useAutoRefresh(object: string, refetch: () => void, options?: {
    recordId?: string;
}): void;

export { ObjectStackContext, ObjectStackLocaleContext, ObjectStackProvider, type ObjectStackProviderProps, type UseInfiniteQueryOptions, type UseInfiniteQueryResult, type UseMetadataOptions, type UseMetadataResult, type UseMutationOptions, type UseMutationResult, type UsePaginationOptions, type UsePaginationResult, type UseQueryOptions, type UseQueryResult, useAutoRefresh, useClient, useDataSubscription, useDataSubscriptionCallback, useFields, useInfiniteQuery, useMetadata, useMetadataSubscription, useMetadataSubscriptionCallback, useMutation, useObject, useObjectStackLocale, usePagination, useQuery, useRealtimeConnection, useView };