@dev-fastn-ai/react-core/dist/index.d.ts

React hooks and components for integrating Fastn AI connector marketplace into your applications. Built on top of @fastn-ai/core with React Query for optimal performance.

import * as react_jsx_runtime from 'react/jsx-runtime';
import * as _tanstack_react_query from '@tanstack/react-query';
import { QueryClient } from '@tanstack/react-query';
import { GetConfigurationsInput, GetConfigurationFormInput, ConnectorField as ConnectorField$1, SelectOption as SelectOption$1 } from '@dev-fastn-ai/core';
export * from '@dev-fastn-ai/core';

type FastnEnvironment = 'LIVE' | 'DRAFT' | string;
interface FastnConfig {
    baseUrl?: string;
    environment?: FastnEnvironment;
    flowsEnvironment?: FastnEnvironment;
    authToken: string;
    tenantId: string;
    spaceId: string;
    customAuth?: boolean | undefined;
}

/**
 * Supported field types for connector forms.
 */
declare enum ConnectorFieldType {
    TEXT = "text",
    NUMBER = "number",
    CHECKBOX = "checkbox",
    DATE = "date",
    DATETIME = "datetime",
    TIME = "time",
    DATETIME_LOCAL = "datetime-local",
    MULTI_SELECT = "multi-select",
    SELECT = "select",
    GOOGLE_FILES_PICKER_SELECT = "google-files-picker-select",
    GOOGLE_FILES_PICKER_MULTI_SELECT = "google-files-picker-multi-select"
}
/**
 * Represents a form for configuring a connector or integration.
 */
interface ConfigurationForm {
    readonly name: string;
    readonly description: string;
    readonly imageUri: string;
    readonly fields: readonly ConnectorField[];
    readonly submitButtonLabel?: string;
    readonly loading?: boolean;
    readonly error?: string;
    readonly submitHandler?: (args: {
        formData: FormData;
    }) => Promise<void>;
}
/**
 * Supported action types for connectors and configurations.
 */
declare enum ConnectorActionType {
    ACTIVATION = "ACTIVATION",
    DEACTIVATION = "DEACTIVATION",
    NONE = "NONE",
    ENABLE = "ENABLE",
    DISABLE = "DISABLE",
    DELETE = "DELETE"
}
/**
 * Status of a connector.
 */
declare enum ConnectorStatus {
    ACTIVE = "ACTIVE",
    INACTIVE = "INACTIVE",
    ALL = "ALL"
}
/**
 * Supported action types for configuration actions.
 */
type ConfigurationActionType = ConnectorActionType.ENABLE | ConnectorActionType.DISABLE | ConnectorActionType.DELETE;
/**
 * Represents a configuration instance for a connector.
 */
interface Configuration {
    readonly id: string;
    readonly connectorId: string;
    readonly configurationId: string;
    readonly name: string;
    readonly flowId: string;
    readonly description: string;
    readonly imageUri: string;
    readonly status: string;
    readonly actions: readonly ConfigurationAction[];
    readonly metadata?: Record<string, Record<string, Primitive> | Record<string, Primitive>[] | undefined | null> | Record<string, Record<string, Primitive> | Record<string, Primitive>[] | undefined | null>[] | undefined | null;
}
/**
 * Represents an action available on a configuration.
 */
interface ConfigurationAction {
    readonly name: string;
    readonly actionType: ConfigurationActionType;
    readonly onClick?: () => Promise<ConnectorActionResult>;
    readonly form?: ConnectorForm | null;
    readonly onSubmit?: (formData: Record<string, Primitive>) => Promise<ConnectorActionResult>;
}
/**
 * Represents a selectable option in a dropdown or select field.
 */
interface SelectOption {
    readonly label: string;
    readonly value: string;
}
/**
 * Pagination information for select options.
 */
interface SelectOptionsResultPagination {
    readonly sourceId: string;
    readonly sourceProject: string;
    readonly limit?: number;
    readonly offset?: number;
    readonly cursor?: string;
    readonly type: "OFFSET" | "CURSOR";
    readonly hasNextPage?: boolean;
    readonly total?: number;
    readonly loaded?: number;
}
/**
 * Primitive types allowed in form data.
 */
type Primitive = string | number | boolean | null | undefined;
/**
 * Represents form data as a record of values.
 */
type FormData = Record<string, Record<string, Primitive> | Record<string, Primitive>[] | undefined | null> | Record<string, Record<string, Primitive> | Record<string, Primitive>[] | undefined | null>[] | undefined | null;
/**
 * Result of loading options for a select field.
 */
interface OptionsResult {
    readonly options: readonly SelectOption[];
    readonly pagination: SelectOptionsResultPagination;
}
/**
 * Source for select options, supporting static and dynamic loading.
 */
interface SelectOptionSource {
    readonly type: "STATIC" | "DYNAMIC" | "GOOGLE_FILES_PICKER";
    readonly openGoogleFilesPicker?: (args: OpenGoogleFilesPickerArgs) => Promise<void>;
    readonly staticOptions?: readonly SelectOption[];
    readonly pagination?: SelectOptionsResultPagination;
    readonly searchOptions?: (query: string, pagination: SelectOptionsResultPagination, context?: FormData) => Promise<OptionsResult>;
    readonly getOptions?: (pagination: SelectOptionsResultPagination, context?: FormData) => Promise<OptionsResult>;
    readonly loadMore?: (pagination: SelectOptionsResultPagination, context?: FormData) => Promise<OptionsResult>;
    readonly refresh?: (pagination: SelectOptionsResultPagination, context?: FormData) => Promise<OptionsResult>;
}
type OpenGoogleFilesPickerArgs = {
    onComplete: (files: readonly SelectOption[]) => Promise<void>;
    onError: (error: Error) => Promise<void>;
    apiKey?: string;
};
/**
 * Represents a field in a connector form.
 */
interface ConnectorField {
    readonly name: string;
    readonly key: string;
    readonly label: string;
    readonly type: ConnectorFieldType | string;
    readonly required: boolean;
    readonly placeholder: string;
    readonly description: string;
    readonly hidden?: boolean;
    readonly disabled?: boolean;
    readonly initialValue?: string;
    readonly optionsSource?: SelectOptionSource;
}
/**
 * Represents a form for a connector action.
 */
interface ConnectorForm {
    readonly description: string;
    readonly fields: readonly ConnectorField[];
    readonly submitButtonLabel?: string;
}
interface ConnectorActionResult {
    readonly data: Record<string, Primitive> | Record<string, Primitive>[] | undefined | null;
    readonly status: "SUCCESS" | "ERROR";
}
/**
 * Represents an action available on a connector.
 */
interface ConnectorAction {
    readonly name: string;
    readonly actionType: ConnectorActionType | string;
    readonly form?: ConnectorForm | null;
    readonly onClick?: () => Promise<ConnectorActionResult>;
    readonly onSubmit?: (formData: Record<string, Primitive>) => Promise<ConnectorActionResult>;
}
/**
 * Represents a connector (integration) instance.
 */
interface Connector {
    readonly id: string;
    readonly name: string;
    readonly description: string;
    readonly imageUri: string;
    readonly status: ConnectorStatus;
    readonly actions: readonly ConnectorAction[];
}

declare const FastnProvider: ({ children, config, queryClient, }: {
    children: React.ReactNode;
    config: FastnConfig;
    queryClient?: QueryClient;
}) => react_jsx_runtime.JSX.Element;

declare const useConfigurations: (input: GetConfigurationsInput) => _tanstack_react_query.UseQueryResult<Configuration[], Error>;

declare const useConfigurationForm: (input: GetConfigurationFormInput) => _tanstack_react_query.UseQueryResult<ConfigurationForm, Error>;

declare const useConnectors: () => _tanstack_react_query.UseQueryResult<Connector[], Error>;

/**
 * Custom hook to manage async select field options with search, pagination, and error handling using React Query.
 *
 * Benefits of React Query caching:
 * - Automatic caching with configurable stale time (5 minutes)
 * - Background refetching when data becomes stale
 * - Deduplication of requests
 * - Optimistic updates
 * - Automatic retry on failure
 * - Cache invalidation and garbage collection
 *
 * @param field ConnectorField - The field definition containing optionsSource
 * @returns { options, loading, loadingMore, hasNext, query, refresh, search, loadMore, error }
 *
 * @example
 * ```tsx
 * const { options, loading, loadingMore, hasNext, search, loadMore } = useFieldOptions(field);
 *
 * // Options are automatically cached and shared across components
 * // Loading states are handled automatically
 * // Pagination is managed with infinite query
 * ```
 */
declare function useFieldOptions(field: ConnectorField$1): {
    options: SelectOption$1[];
    loading: boolean;
    loadingMore: boolean;
    hasNext: boolean;
    query: string;
    refresh: () => Promise<void>;
    search: (query: string) => void;
    loadMore: () => Promise<void>;
    totalLoadedOptions: number;
    error: string | null;
};

export { FastnProvider, useConfigurationForm, useConfigurations, useConnectors, useFieldOptions };