@curatedotfun/types/dist/index.d.ts

Type definitions for curatedotfun plugins

export type PluginType = "transformer" | "distributor" | "source";
/**
 * Configuration for registering a plugin in the application.
 * TConfig is the static configuration for the plugin instance.
 */
export interface PluginRegistrationConfig<PType extends PluginType = PluginType, TConfig = Record<string, unknown>> {
    type: PType;
    url: string;
    config?: TConfig;
}
export interface BotPlugin<TConfig extends Record<string, unknown> = Record<string, unknown>> {
    type: PluginType;
    initialize: (config?: TConfig) => Promise<void>;
    shutdown?: () => Promise<void>;
}
export interface TransformerPlugin<TInput = unknown, TOutput = unknown, TConfig extends Record<string, unknown> = Record<string, unknown>> extends BotPlugin<TConfig> {
    type: "transformer";
    transform: (args: ActionArgs<TInput, TConfig>) => Promise<TOutput>;
}
export interface DistributorPlugin<TInput = unknown, TConfig extends Record<string, unknown> = Record<string, unknown>> extends BotPlugin<TConfig> {
    type: "distributor";
    distribute: (args: ActionArgs<TInput, TConfig>) => Promise<void>;
}
export interface ActionArgs<TInput = unknown, TConfig = unknown> {
    input: TInput;
    config?: TConfig;
}
/**
 * Plugin configuration
 */
export interface PluginConfig<T extends PluginType, TConfig = Record<string, unknown>> {
    type: T;
    url: string;
    config?: TConfig;
}
/**
 * Plugin type mapping
 */
export type PluginTypeMap<TInput = unknown, TOutput = unknown, TConfig extends Record<string, unknown> = Record<string, unknown>, TItem extends SourceItem = SourceItem> = {
    transformer: TransformerPlugin<TInput, TOutput, TConfig>;
    distributor: DistributorPlugin<TInput, TConfig>;
    source: SourcePlugin<TItem, TConfig>;
};
/**
 * State passed between search calls to enable resumption.
 * TData is expected to be an object conforming to PlatformState or a derivative.
 */
export interface LastProcessedState<TData extends PlatformState = PlatformState> {
    data: TData;
}
/**
 * Configuration options for a specific search operation by a SourcePlugin.
 * TPlatformOpts allows for platform-specific arguments.
 */
export interface SourcePluginSearchOptions<TPlatformOpts = Record<string, any>> {
    type: string;
    query?: string;
    pageSize?: number;
    platformArgs?: TPlatformOpts;
    [key: string]: any;
}
/**
 * Results of a search operation from a SourcePlugin.
 * TItem is the type of items (e.g., SourceItem or MasaSearchResult).
 * TPlatformState is the platform-specific state for resumption.
 */
export interface SourcePluginSearchResults<TItem extends SourceItem = SourceItem, TPlatformState extends PlatformState = PlatformState> {
    items: TItem[];
    nextLastProcessedState: LastProcessedState<TPlatformState> | null;
}
/**
 * Interface for a source plugin.
 * TItem is the type of items the plugin produces (should extend SourceItem).
 * TConfig is the plugin's instance-level configuration.
 * TPlatformState is the platform-specific state used for resumable searches.
 */
export interface SourcePlugin<TItem extends SourceItem = SourceItem, TConfig extends Record<string, unknown> = Record<string, unknown>, // Configuration for the plugin instance
TPlatformState extends PlatformState = PlatformState> extends BotPlugin<TConfig> {
    type: "source";
    /**
     * Performs a search operation based on the provided state and options.
     * The plugin instance should be initialized with its specific configuration (TConfig)
     * which might include API keys or other static settings.
     *
     * @param lastProcessedState The state from the previous search call, allowing resumption.
     *                           Null if this is the first call or if state is not applicable/reset.
     *                           Now uses the generic LastProcessedState with TPlatformState.
     * @param options An object containing dynamic configuration options for this specific search
     *                call, such as the query, type, and page size.
     * @returns A promise that resolves with the search results and the state to be used
     *          for the next call. SearchResults also becomes generic.
     */
    search(lastProcessedState: LastProcessedState<TPlatformState> | null, options: SourcePluginSearchOptions<any>): Promise<SourcePluginSearchResults<TItem, TPlatformState>>;
}
/**
 * Defines the progress of a job submitted to an external asynchronous service (e.g., Masa).
 */
export interface AsyncJobProgress {
    jobId: string;
    status: "submitted" | "pending" | "processing" | "done" | "error" | "timeout";
    submittedAt: string;
    lastCheckedAt?: string;
    errorMessage?: string;
}
/**
 * Generic platform-specific state for managing resumable searches and long-running jobs.
 * This is the `TData` type for `LastProcessedState`.
 */
export interface PlatformState {
    latestProcessedId?: string | number | Record<string, any>;
    currentAsyncJob?: AsyncJobProgress | null;
    [key: string]: any;
}
export interface IPlatformSearchService<TItem extends SourceItem, TPlatformOptions = Record<string, unknown>, TPlatformState extends PlatformState = PlatformState> {
    initialize?(config?: any): Promise<void>;
    search(options: TPlatformOptions, currentState: LastProcessedState<TPlatformState> | null): Promise<{
        items: TItem[];
        nextStateData: TPlatformState | null;
    }>;
    shutdown?(): Promise<void>;
}
/**
 * The structure of an individual item returned by a source plugin.
 * This is the `TItem` in `SourcePluginSearchResults`.
 */
export interface SourceItem {
    id: string;
    externalId: string;
    content: string;
    createdAt?: string;
    author?: {
        id?: string;
        username?: string;
        displayName?: string;
        [key: string]: any;
    };
    metadata?: {
        sourcePlugin: string;
        searchType: string;
        url?: string;
        language?: string;
        isReply?: boolean;
        inReplyToId?: string;
        conversationId?: string;
        [key: string]: any;
    };
    raw?: any;
    [key: string]: any;
}