@lume-ai/typescript-sdk/dist/index.d.ts

Lume SDK for Typescript to automate data mappings with AI. Learn more at docs.lume.ai

import { AxiosInstance, AxiosRequestConfig } from 'axios';

type UUID = string;
interface Page<T> {
    items: T[];
    total?: number | null;
    page?: number | null;
    size?: number | null;
    pages?: number | null;
}

/**
 * Schema alias for Record<string, any>
 */
type Schema = Record<string, any>;
/**
 * TargetSchema type
 */
type TargetSchema$1 = {
    /**
     * The id of the target schema.
     */
    readonly id: UUID;
    /**
     * The user id of the target schema.
     */
    readonly user_id: UUID;
    /**
     * The name of the target schema.
     */
    readonly name: string | null;
    /**
     * The file name of the target schema.
     */
    readonly filename: string | null;
    /**
     * The schema of the target schema.
     */
    readonly schema?: Schema | null;
};

/**
 * Represents a tag filter with a key-value pair.
 * Example: { key: "color", value: "blue" }
 */
interface TagFilter {
    key: string;
    value?: string;
}
/**
 * Logical AND operation for multiple filters.
 * Example: { "and_": [ { key: "color", value: "blue" }, { key: "size", value: "large" } ] }
 */
interface AndOp<T> {
    and_: BoolFilter<T>[];
}
/**
 * Logical OR operation for multiple filters.
 * Example: { "or_": [ { key: "color", value: "blue" }, { key: "color", value: "yellow" } ] }
 */
interface OrOp<T> {
    or_: BoolFilter<T>[];
}
/**
 * Logical NOT operation to negate a filter.
 * Example: { "not_": { key: "color", value: "blue" } }
 */
interface NotOp<T> {
    not_: BoolFilter<T>;
}
/**
 * BoolFilter - A union type that allows:
 * - A single tag filter
 * - A combination of AND, OR, or NOT operations
 */
type BoolFilter<T> = T | AndOp<T> | OrOp<T> | NotOp<T>;

declare enum Status {
    SUCCEEDED = "SUCCEEDED",
    RUNNING = "RUNNING",
    INCOMPLETE = "INCOMPLETE",
    FAILED = "FAILED",
    CREATED = "CREATED",
    PENDING = "PENDING",
    CRASHED = "CRASHED"
}

interface BaseModel {
    id: string;
    type: string;
    status: Status;
    created_at: string;
    updated_at: string;
    user_id: string;
    flow_id: string;
}
interface Steps {
    id: any;
    name: string;
    status: string;
    type: string;
}

interface Flow$1 extends BaseModel {
    name: string;
    version: number;
    tags: Tag[];
    description: string;
    steps: Steps[];
}
interface Tag {
    key: string;
    value: string;
}
interface CreateFlowDto {
    name: string;
    description?: string;
    target_schema: Schema;
    tags?: Tag[];
}
interface SearchFlowsDto {
    name?: string;
    tags_filter?: BoolFilter<TagFilter>;
}
interface SearchRunsDto {
    name?: string;
    tags_filter?: BoolFilter<TagFilter>;
    version_id?: string;
}
interface Run$1 extends BaseModel {
    metadata: any;
    steps?: Steps[];
    runId?: string;
    file_name?: string;
}
interface CreateRunDto {
    source_data: any[];
}
interface CreateDataJoinRunDto {
    files: File[];
    topSheetName: string;
    name: string;
    metadata?: RelationshipDefinition;
}
interface RelationshipDefinition {
    [tableName: string]: {
        primary_key: string[];
        foreign_keys: {
            [foreignKeyColumn: string]: string;
        };
    };
}

interface SchemaTransformerInput {
    source_data: {
        items: Array<Record<string, any>>;
        pages: number;
        page: number;
        size: number;
        total: number;
    };
    target_schema: TargetSchema;
}
interface SchemaTransformerTargetField {
    id: string;
    schemaId?: string;
    name: string;
    status: Status;
    type: string | string[];
    edit?: {
        updated_at: string;
        id: string;
        status: Status;
    };
    updated_at: string;
}
interface ErrorStats {
    error_count: number;
    null_count: number;
    total_count: number;
    missing_count: number;
}
interface SampleItem {
    index: number;
    value: any;
}
interface ValidationErrorDetail {
    error_type: "pattern" | "required" | "type" | "custom" | "unknown" | "enum" | "array" | "duplicate" | "unsupported" | "unsupported_type" | "unsupported_enum" | "unsupported_array" | "unsupported_duplicate" | "unsupported_custom" | "unsupported_unknown";
    statistics: ErrorStats;
    schema_path: string;
    error_sample: SampleItem[];
    check: any;
}
interface ValidationTree {
    [pathSegment: string]: ValidationErrorDetail[] | ValidationTree;
}
interface SchemaTransformerOutput {
    mapped_data: {
        items: Array<Record<string, any>>;
    };
    no_data_idxs?: number[];
    errors?: ValidationTree;
}
interface TargetSchema {
    type: string;
    properties: Record<string, any>;
    required: string[];
}
interface SchemaTransformer extends BaseModel {
    edit?: {
        id: string;
        status: Status;
    };
    input: SchemaTransformerInput;
    output: SchemaTransformerOutput;
    target_fields: SchemaTransformerTargetField[];
}

/**
 * Base service class providing common functionality for other services.
 */
declare class ApiClient {
    protected httpClient: AxiosInstance;
    constructor(apiKey: string, baseURL: string);
    private initializeInterceptors;
    private handleRequest;
    private handleResponse;
    private handleError;
    get<T>(url: string, config?: AxiosRequestConfig, baseURLOverride?: string): Promise<T>;
    post<T>(url: string, data?: any, config?: AxiosRequestConfig, baseURLOverride?: string): Promise<T>;
    patch<T>(url: string, data?: any, config?: AxiosRequestConfig, baseURLOverride?: string): Promise<T>;
    delete<T>(url: string, config?: AxiosRequestConfig, baseURLOverride?: string): Promise<T>;
}

/**
 * Represents a single execution of a flow.
 * The internal steps array may include a schema transform step
 * that we use to retrieve final mapped data.
 */
declare class Run {
    private apiClient;
    id: string;
    type: string;
    status: Status;
    created_at: string;
    updated_at: string;
    user_id: string;
    flow_id: string;
    metadata: any;
    steps?: Steps[];
    runId?: string;
    file_name?: string;
    constructor(apiClient: ApiClient, runData: any, flow_id: string, run_id?: string);
    /**
     * Polls until the run is complete (status = SUCCEEDED/FAILED/CRASHED).
     * If the run ends with a fail status, we throw a RunError with details.
     */
    waitForCompletion(pollIntervalMs?: number): Promise<void>;
    /**
     * Refresh the Run instance with the latest data from the API.
     * (Your existing code uses the same endpoint to fetch flow data with run_id param.)
     */
    get(): Promise<void>;
    /**
     * Private: returns a typed representation of this run.
     * Possibly used internally for debugging or logging.
     */
    private getValues;
    /**
     * (Internal Use Only)
     * Called by Flow.getRunResults() to retrieve the "schema_transform" step's final output.
     * We do not expose "SchemaTransformer" to the user directly.
     */
    _getTransformationOutput(page?: number, size?: number): Promise<SchemaTransformerOutput | null>;
}

/**
 * Represents a data transformation Flow in Lume.
 * You can create multiple runs, fetch them, or do a quick "process" method.
 */
declare class Flow {
    id: string;
    user_id: string;
    version: number;
    tags: string[];
    description: string;
    steps: Steps[];
    name: string;
    status: Status;
    created_at: string;
    updated_at: string;
    private apiClient;
    constructor(apiClient: ApiClient, data: Flow$1);
    /**
     * Refreshes the flow's data from the API.
     */
    get(): Promise<void>;
    /**
     * Creates a new run of this flow with provided data.
     * If wait=true, this method polls until the run is complete.
     */
    createRun(data: CreateRunDto, wait?: boolean): Promise<Run>;
    /**
     * Fetches a specific run by run ID from this flow.
     */
    getRun(run_id: string): Promise<Run>;
    /**
     * Fetches all runs for this flow.
     */
    getRuns(page?: number, size?: number): Promise<Page<Run>>;
    /**
     * Searches for runs by name, tags_filter, and version_id
     */
    searchRuns(searchDto: SearchRunsDto, page?: number, size?: number): Promise<Page<Run>>;
    /**
     * High-level method: processes new data through this flow,
     * waits for the run to complete, and returns the final mapped results.
     */
    process(sourceData: any[], page?: number, size?: number): Promise<Page<any>>;
    /**
     * Gets results from a specific run with pagination.
     * Internally calls run.getSchemaTransformerOutput,
     * which is where the real step logic is hidden.
     */
    getRunResults(run: Run, page?: number, size?: number): Promise<Page<any>>;
    /**
     * A new method that directly fetches run results by run ID.
     * Useful in concurrency scenarios: you always fetch the exact run you want.
     */
    getRunResultsById(runId: string, page?: number, size?: number): Promise<Page<any>>;
    /**
     * Gets the results from the most recent successful run,
     * or null if none exist.
     */
    getLatestRunResults(page?: number, size?: number): Promise<Page<any> | null>;
}

/**
 * An optional concurrency or callback-based approach.
 * If concurrency is set, we wrap calls in throat. Otherwise, no limit.
 */
declare class FlowService {
    private apiClient;
    private concurrencyLimit;
    private requestQueue;
    constructor(apiClient: ApiClient, concurrencyLimit?: number);
    /**
     * Creates a new flow, THEN executes the initial run using runData.
     * If `wait` is true, it waits for that initial run to finish.
     *
     * Some users prefer a single call so that no flow is created without data.
     */
    createAndRunFlow(flowData: CreateFlowDto, runData: CreateRunDto, wait?: boolean): Promise<Flow>;
    /**
     * Retrieves a flow by ID.
     */
    getFlow(id: string): Promise<Flow>;
    /**
     * Creates a new flow without an initial run (less common),
     * but you can still do `flow.createRun(...)` after.
     */
    createFlow(data: CreateFlowDto): Promise<Flow>;
    /**
     * Retrieves all flows.
     */
    getFlows(page?: number, size?: number): Promise<Page<Flow>>;
    /**
     * Searches for flows by name or tags_filter.
     */
    searchFlows(searchDto: SearchFlowsDto, page?: number, size?: number): Promise<Page<Flow>>;
}

/**
 * Lume AI TypeScript SDK
 * Main entry point for interacting with the Lume AI API.
 *
 * @example
 * ```typescript
 * import { Lume } from '@lume-ai/typescript-sdk';
 *
 * const lume = new Lume('your-api-key');
 * const flow = await lume.flowService.createFlow({
 *   name: 'My Flow',
 *   description: 'Data transformation flow',
 *   target_schema: mySchema,
 *   tags: ['production']
 * });
 * ```
 */
declare class Lume {
    flowService: FlowService;
    private apiClient;
    /**
     * Initializes the Lume SDK.
     * @param apiKey - Your Lume API authentication key
     * @param baseURL - Optional custom API endpoint (defaults to production)
     */
    constructor(apiKey: string, baseURL?: string);
}

export { type BaseModel, type CreateDataJoinRunDto, type CreateFlowDto, type CreateRunDto, type Flow$1 as Flow, Flow as FlowClass, Lume, type Page, type Run$1 as Run, Run as RunClass, type Schema, type SchemaTransformer, type SchemaTransformerInput, type SchemaTransformerOutput, type SchemaTransformerTargetField, type SearchFlowsDto, type SearchRunsDto, Status, type Steps, type TargetSchema$1 as TargetSchema };