@dev-fastn-ai/react-core 1.0.5 → 1.0.6

package/dist/index.d.ts

@@ -0,0 +1,248 @@
+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;
+    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?: unknown;
+}
+/**
+ * Represents an action available on a configuration.
+ */
+interface ConfigurationAction {
+    readonly name: string;
+    readonly actionType: ConfigurationActionType;
+    readonly onClick?: () => Promise<void>;
+    readonly form?: ConnectorForm | null;
+    readonly onSubmit?: (formData: unknown) => Promise<void>;
+}
+/**
+ * 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, Primitive | Primitive[] | Record<string, Primitive> | Record<string, Primitive>[]>;
+/**
+ * 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: unknown;
+    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?: (data?: unknown) => Promise<ConnectorActionResult>;
+    readonly onSubmit?: (formData: Record<string, unknown>) => 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 };