khotan-data 0.0.1 → 0.1.1

package/dist/factory.d.cts

@@ -0,0 +1,662 @@
+import { PgDatabase } from 'drizzle-orm/pg-core';
+
+type ResourceConnectField = string | [string, ...string[]];
+interface ResourcePlugParticipation {
+    uniqueIdentifier: string;
+}
+interface ResourceMappingRegistration {
+    connectField: ResourceConnectField;
+    plugs?: Record<string, ResourcePlugParticipation>;
+}
+interface ResourceRegistration {
+    name: string;
+    description?: string;
+    mapping: ResourceMappingRegistration;
+}
+type FlowType = "inflow" | "outflow" | "relay" | "webhook";
+type KhotanRunStatus = "pending" | "running" | "completed" | "partial" | "failed" | "cancelled";
+type KhotanTerminalRunStatus = "completed" | "partial" | "failed" | "cancelled";
+interface FlowRunResult {
+    status?: KhotanTerminalRunStatus;
+    extracted?: number;
+    transformed?: number;
+    created?: number;
+    updated?: number;
+    deleted?: number;
+    failed?: number;
+    error?: string | null;
+    metadata?: Record<string, unknown> | null;
+}
+interface BoundPlug {
+    get<T>(path: string, options?: {
+        params?: Record<string, unknown>;
+        headers?: Record<string, string>;
+    }): Promise<T>;
+    post<T>(path: string, options?: {
+        body?: unknown;
+        headers?: Record<string, string>;
+    }): Promise<T>;
+    put<T>(path: string, options?: {
+        body?: unknown;
+        headers?: Record<string, string>;
+    }): Promise<T>;
+    patch<T>(path: string, options?: {
+        body?: unknown;
+        headers?: Record<string, string>;
+    }): Promise<T>;
+    delete<T>(path: string, options?: {
+        headers?: Record<string, string>;
+    }): Promise<T>;
+}
+interface BindablePlug {
+    get<T>(path: string, options?: {
+        params?: Record<string, unknown>;
+        headers?: Record<string, string>;
+        vars?: Record<string, string>;
+        _setVars?: (updates: Record<string, string>) => Promise<void>;
+    }): Promise<T>;
+    post<T>(path: string, options?: {
+        body?: unknown;
+        headers?: Record<string, string>;
+        vars?: Record<string, string>;
+        _setVars?: (updates: Record<string, string>) => Promise<void>;
+    }): Promise<T>;
+    put<T>(path: string, options?: {
+        body?: unknown;
+        headers?: Record<string, string>;
+        vars?: Record<string, string>;
+        _setVars?: (updates: Record<string, string>) => Promise<void>;
+    }): Promise<T>;
+    patch<T>(path: string, options?: {
+        body?: unknown;
+        headers?: Record<string, string>;
+        vars?: Record<string, string>;
+        _setVars?: (updates: Record<string, string>) => Promise<void>;
+    }): Promise<T>;
+    delete<T>(path: string, options?: {
+        headers?: Record<string, string>;
+        vars?: Record<string, string>;
+        _setVars?: (updates: Record<string, string>) => Promise<void>;
+    }): Promise<T>;
+}
+interface FlowRunContext {
+    plug: BoundPlug;
+    flow: {
+        id: string;
+        name: string;
+        plugName: string;
+        type: FlowType;
+        resource?: string | null;
+        to?: string | null;
+    };
+    runType: string;
+    body?: unknown;
+    vars: Record<string, string>;
+    setVars(updates: Record<string, string>): Promise<void>;
+    cache(cacheName: string): CacheInstance;
+}
+interface FlowWorkflowContext {
+    flow: {
+        id: string;
+        name: string;
+        plugName: string;
+        type: FlowType;
+        resource?: string | null;
+        to?: string | null;
+    };
+    runType: string;
+    body?: unknown;
+    vars: Record<string, string>;
+    plugVarsByName?: Record<string, Record<string, string>>;
+    khotanRunId: string;
+    khotanInstanceId: string;
+}
+declare function bindWorkflowPlug(plug: BindablePlug, ctx: FlowWorkflowContext, plugName?: string): BoundPlug;
+interface KhotanRunUpdate {
+    type?: "progress" | "log" | "metric" | "error";
+    message: string;
+    progress?: number;
+    extracted?: number;
+    transformed?: number;
+    created?: number;
+    updated?: number;
+    deleted?: number;
+    failed?: number;
+    metadata?: Record<string, unknown>;
+}
+interface FlowRegistration {
+    name: string;
+    type: FlowType;
+    schedule?: string;
+    resource?: string;
+    to?: string;
+    workflow?(ctx: FlowWorkflowContext): Promise<FlowRunResult | void>;
+    run?(ctx: FlowRunContext): Promise<FlowRunResult | void>;
+}
+interface WireSubscribeContext {
+    plug: {
+        get<T>(path: string, options?: {
+            params?: Record<string, unknown>;
+            headers?: Record<string, string>;
+        }): Promise<T>;
+        post<T>(path: string, options?: {
+            body?: unknown;
+            headers?: Record<string, string>;
+        }): Promise<T>;
+        put<T>(path: string, options?: {
+            body?: unknown;
+            headers?: Record<string, string>;
+        }): Promise<T>;
+        patch<T>(path: string, options?: {
+            body?: unknown;
+            headers?: Record<string, string>;
+        }): Promise<T>;
+        delete<T>(path: string, options?: {
+            headers?: Record<string, string>;
+        }): Promise<T>;
+    };
+    callbackUrl: string;
+    events: string[];
+    wireVars: Record<string, string>;
+    setWireVars(updates: Record<string, string>): Promise<void>;
+}
+interface WireUnsubscribeContext {
+    plug: {
+        get<T>(path: string, options?: {
+            params?: Record<string, unknown>;
+            headers?: Record<string, string>;
+        }): Promise<T>;
+        post<T>(path: string, options?: {
+            body?: unknown;
+            headers?: Record<string, string>;
+        }): Promise<T>;
+        put<T>(path: string, options?: {
+            body?: unknown;
+            headers?: Record<string, string>;
+        }): Promise<T>;
+        patch<T>(path: string, options?: {
+            body?: unknown;
+            headers?: Record<string, string>;
+        }): Promise<T>;
+        delete<T>(path: string, options?: {
+            headers?: Record<string, string>;
+        }): Promise<T>;
+    };
+    remoteId: string;
+    wireVars: Record<string, string>;
+    setWireVars(updates: Record<string, string>): Promise<void>;
+}
+interface WireVerifyContext {
+    headers: Record<string, string>;
+    body: string;
+    wireVars: Record<string, string>;
+}
+interface WireRegistration {
+    events: string[];
+    onSubscribe(ctx: WireSubscribeContext): Promise<{
+        remoteId: string;
+    }>;
+    onUnsubscribe(ctx: WireUnsubscribeContext): Promise<void>;
+    onVerify?(ctx: WireVerifyContext): Promise<boolean>;
+}
+interface CatchRegistration {
+    type: "catch";
+    name: string;
+    events?: string[];
+    workflow: (ctx: CatchWorkflowContext) => Promise<void>;
+}
+interface PassRegistration {
+    type: "pass";
+    name: string;
+    to: string;
+    events?: string[];
+    workflow: (ctx: PassWorkflowContext) => Promise<void>;
+}
+type WebhookRegistration = CatchRegistration | PassRegistration;
+interface CacheScope {
+    plug?: string;
+    resource?: string;
+    flow?: string;
+}
+interface CacheRegistration {
+    name: string;
+    scope?: CacheScope;
+    ttl?: string | number;
+}
+interface CacheEntryRecord {
+    id: string;
+    cacheId: string;
+    key: string;
+    value: unknown;
+    expiresAt: Date | null;
+    createdAt?: Date | undefined;
+    updatedAt?: Date | undefined;
+}
+interface CacheInstance {
+    get<T = unknown>(key: string): Promise<T | null>;
+    set<T = unknown>(key: string, value: T): Promise<T>;
+    delete(key: string): Promise<void>;
+}
+interface CatchWorkflowContext {
+    event: Record<string, unknown>;
+    eventType: string;
+    headers: Record<string, string>;
+    khotanRunId: string;
+    khotanInstanceId: string;
+}
+interface PassWorkflowContext {
+    event: Record<string, unknown>;
+    eventType: string;
+    headers: Record<string, string>;
+    destVars: Record<string, string>;
+    khotanRunId: string;
+    khotanInstanceId: string;
+}
+interface KhotanWorkflowContextRef {
+    khotanInstanceId: string;
+}
+declare function khotanCache(ctx: KhotanWorkflowContextRef, cacheName: string): CacheInstance;
+declare function khotanMappings(ctx: KhotanWorkflowContextRef): {
+    list: (params: {
+        resourceId: string;
+        limit?: number;
+        offset?: number;
+        search?: string;
+    }) => Promise<{
+        items: Record<string, unknown>[];
+        page: {
+            limit: number;
+            offset: number;
+            hasMore: boolean;
+            prevOffset: number;
+            nextOffset: number;
+            total: number;
+        };
+    }>;
+    lookup: (params: {
+        resourceId: string;
+        connectValue: string | string[];
+    } | {
+        resourceId: string;
+        plugName: string;
+        ref: string;
+    }) => Promise<Record<string, unknown> | null>;
+    upsert: (mapping: {
+        resourceId: string;
+        connectValue: string | string[];
+        refs: Record<string, string>;
+        metadata?: Record<string, unknown> | null;
+    }) => Promise<Record<string, unknown>>;
+    update: (id: string, mapping: {
+        resourceId: string;
+        connectValue: string | string[];
+        refs: Record<string, string>;
+        metadata?: Record<string, unknown> | null;
+    }) => Promise<Record<string, unknown>>;
+    delete: (id: string) => Promise<void>;
+};
+interface VarField {
+    readonly key: string;
+    label: string;
+    type: "text" | "password" | "url";
+    secret?: boolean;
+    hidden?: boolean;
+    required?: boolean;
+    placeholder?: string;
+    defaultValue?: string;
+}
+interface PlugRegistration {
+    name: string;
+    plug: {
+        baseUrl: string;
+        authType: string;
+        varFields?: readonly VarField[];
+        endpoints?: Record<string, {
+            method: string;
+            path: string;
+            description?: string;
+            body?: {
+                _def?: unknown;
+                shape?: Record<string, unknown>;
+            };
+            query?: {
+                _def?: unknown;
+                shape?: Record<string, unknown>;
+            };
+            responses?: Record<number, {
+                _def?: unknown;
+                shape?: Record<string, unknown>;
+            }>;
+        }>;
+        get<T>(path: string, options?: {
+            params?: Record<string, unknown>;
+            headers?: Record<string, string>;
+            vars?: Record<string, string>;
+            _setVars?: (updates: Record<string, string>) => Promise<void>;
+            _skipHooks?: boolean;
+        }): Promise<T>;
+        post<T>(path: string, options?: {
+            body?: unknown;
+            headers?: Record<string, string>;
+            vars?: Record<string, string>;
+            _setVars?: (updates: Record<string, string>) => Promise<void>;
+            _skipHooks?: boolean;
+        }): Promise<T>;
+        put<T>(path: string, options?: {
+            body?: unknown;
+            headers?: Record<string, string>;
+            vars?: Record<string, string>;
+            _setVars?: (updates: Record<string, string>) => Promise<void>;
+            _skipHooks?: boolean;
+        }): Promise<T>;
+        patch<T>(path: string, options?: {
+            body?: unknown;
+            headers?: Record<string, string>;
+            vars?: Record<string, string>;
+            _setVars?: (updates: Record<string, string>) => Promise<void>;
+            _skipHooks?: boolean;
+        }): Promise<T>;
+        delete<T>(path: string, options?: {
+            headers?: Record<string, string>;
+            vars?: Record<string, string>;
+            _setVars?: (updates: Record<string, string>) => Promise<void>;
+            _skipHooks?: boolean;
+        }): Promise<T>;
+    };
+    vars?: VarField[];
+    flows?: FlowRegistration[];
+    endpoints?: Record<string, {
+        method: string;
+        path: string;
+    }>;
+    wires?: WireRegistration[];
+    webhooks?: WebhookRegistration[];
+    catches?: CatchRegistration[];
+    passes?: PassRegistration[];
+}
+interface KhotanAdapter {
+    upsertPlug(plug: {
+        name: string;
+        baseUrl: string;
+        authType: string;
+    }): Promise<{
+        id: string;
+    }>;
+    upsertFlow(flow: {
+        plugId: string;
+        name: string;
+        type: string;
+        schedule?: string | null;
+    }): Promise<{
+        id: string;
+    }>;
+    listPlugs(): Promise<Record<string, unknown>[]>;
+    getPlug(id: string): Promise<Record<string, unknown> | null>;
+    getPlugFlows(plugId: string): Promise<Record<string, unknown>[]>;
+    getFlow(flowId: string): Promise<Record<string, unknown> | null>;
+    listFlows(): Promise<Record<string, unknown>[]>;
+    getRun(runId: string): Promise<Record<string, unknown> | null>;
+    listRuns(flowId: string): Promise<Record<string, unknown>[]>;
+    listRunsPage(params: {
+        limit: number;
+        offset: number;
+    }): Promise<{
+        items: Record<string, unknown>[];
+        hasMore: boolean;
+    }>;
+    upsertResource(resource: {
+        name: string;
+        connectField: ResourceConnectField;
+        description?: string | null;
+    }): Promise<{
+        id: string;
+    }>;
+    upsertCache(cache: {
+        name: string;
+        scope?: CacheScope | null;
+        ttlSeconds?: number | null;
+    }): Promise<{
+        id: string;
+    }>;
+    getCacheByName(name: string): Promise<Record<string, unknown> | null>;
+    getCacheEntry(cacheId: string, key: string): Promise<Record<string, unknown> | null>;
+    upsertCacheEntry(entry: {
+        cacheId: string;
+        key: string;
+        value: unknown;
+        expiresAt?: Date | null;
+    }): Promise<{
+        id: string;
+        created: boolean;
+    }>;
+    deleteCacheEntry(cacheId: string, key: string): Promise<void>;
+    listResources(): Promise<Record<string, unknown>[]>;
+    getResource(id: string): Promise<Record<string, unknown> | null>;
+    getResourceFlows(resourceId: string): Promise<Record<string, unknown>[]>;
+    upsertMapping(mapping: {
+        id?: string;
+        resourceId: string;
+        connectValue: string;
+        refs: Record<string, string>;
+        metadata?: Record<string, unknown> | null;
+    }): Promise<{
+        id: string;
+        created: boolean;
+    }>;
+    getMapping(id: string): Promise<Record<string, unknown> | null>;
+    listMappings(params: {
+        resourceId: string;
+        limit: number;
+        offset: number;
+        search?: string;
+    }): Promise<{
+        items: Record<string, unknown>[];
+        hasMore: boolean;
+        total: number;
+    }>;
+    deleteMapping(id: string): Promise<void>;
+    lookupMapping(params: {
+        resourceId: string;
+        connectValue: string;
+    } | {
+        resourceId: string;
+        plugName: string;
+        ref: string;
+    }): Promise<Record<string, unknown> | null>;
+    updateFlowResourceId(flowId: string, resourceId: string): Promise<void>;
+    togglePlugEnabled(plugId: string, enabled: boolean): Promise<void>;
+    toggleFlowEnabled(flowId: string, enabled: boolean): Promise<void>;
+    toggleWebhookHandlerEnabled(handlerId: string, enabled: boolean): Promise<void>;
+    insertWire(wire: {
+        plugId: string;
+        remoteId: string;
+        callbackUrl: string;
+        eventTypes: string[];
+    }): Promise<{
+        id: string;
+    }>;
+    upsertWire(wire: {
+        plugId: string;
+    }): Promise<{
+        id: string;
+    }>;
+    getActiveWire(plugId: string): Promise<Record<string, unknown> | null>;
+    getPlugWire(plugId: string): Promise<Record<string, unknown> | null>;
+    getWire(wireId: string): Promise<Record<string, unknown> | null>;
+    updateWireStatus(wireId: string, status: "active" | "disabled" | "pending"): Promise<void>;
+    updateWireDetails(wireId: string, details: {
+        remoteId: string;
+        callbackUrl: string;
+        eventTypes: string[];
+        status: "active";
+    }): Promise<void>;
+    getWireMetadata(wireId: string): Promise<string | null>;
+    updateWireMetadata(wireId: string, metadata: string): Promise<void>;
+    getEncryptedVariables(plugId: string): Promise<string | null>;
+    setEncryptedVariables(plugId: string, encrypted: string): Promise<void>;
+    clearEncryptedVariables(plugId: string): Promise<void>;
+    upsertWebhookHandler(handler: {
+        wireId: string;
+        name: string;
+        type: "catch" | "pass";
+        destinationPlugId?: string | null;
+    }): Promise<{
+        id: string;
+    }>;
+    listWebhookHandlers(wireId: string): Promise<Record<string, unknown>[]>;
+    getLatestWebhookHandlerRun(handlerId: string): Promise<Record<string, unknown> | null>;
+    insertRun(run: {
+        flowId?: string | null;
+        wireId?: string | null;
+        webhookHandlerId?: string | null;
+        workflowRunId?: string | null;
+        runType: string;
+        status: string;
+    }): Promise<{
+        id: string;
+    }>;
+    updateRun(runId: string, updates: {
+        status: KhotanRunStatus;
+        workflowRunId?: string | null;
+        completedAt?: Date;
+        durationMs?: number;
+        extracted?: number;
+        transformed?: number;
+        created?: number;
+        updated?: number;
+        deleted?: number;
+        failed?: number;
+        error?: string | null;
+        metadata?: Record<string, unknown> | null;
+    }): Promise<void>;
+    insertWebhookEvent(event: {
+        wireId: string;
+        webhookHandlerId: string;
+        khotanRunId: string;
+        eventType: string;
+        payload: Record<string, unknown>;
+        headers: Record<string, string>;
+    }): Promise<{
+        id: string;
+    }>;
+    listWebhookEventsPage(params: {
+        limit: number;
+        offset: number;
+    }): Promise<{
+        items: Record<string, unknown>[];
+        hasMore: boolean;
+    }>;
+    updateFlowLastRun(flowId: string, updates: {
+        lastRunAt: Date;
+        lastRunStatus: KhotanTerminalRunStatus;
+    }): Promise<void>;
+}
+interface KhotanConfig {
+    adapter: KhotanAdapter;
+    plugs: PlugRegistration[];
+    resources?: ResourceRegistration[];
+    caches?: CacheRegistration[];
+    secret?: string;
+}
+type KhotanHandler = (request: Request) => Promise<Response>;
+interface WireInstance {
+    create(callbackUrl: string): Promise<Record<string, unknown>>;
+    delete(wireId: string): Promise<void>;
+    get(): Promise<Record<string, unknown> | null>;
+}
+interface FlowStartOptions {
+    runType?: string;
+    body?: unknown;
+}
+interface FlowSelectorOptions {
+    plugName?: string;
+}
+interface FlowInstance {
+    start(options?: FlowStartOptions): Promise<Record<string, unknown>>;
+}
+interface KhotanInstance {
+    handler: KhotanHandler;
+    init(): Promise<void>;
+    flow(flowNameOrId: string, options?: FlowSelectorOptions): FlowInstance;
+    wire(plugName: string): WireInstance;
+    cache(cacheName: string): CacheInstance;
+    listMappings(params: {
+        resourceId: string;
+        limit?: number;
+        offset?: number;
+        search?: string;
+    }): Promise<{
+        items: Record<string, unknown>[];
+        page: {
+            limit: number;
+            offset: number;
+            hasMore: boolean;
+            prevOffset: number;
+            nextOffset: number;
+            total: number;
+        };
+    }>;
+    lookupMapping(params: {
+        resourceId: string;
+        connectValue: string | string[];
+    } | {
+        resourceId: string;
+        plugName: string;
+        ref: string;
+    }): Promise<Record<string, unknown> | null>;
+    upsertMapping(mapping: {
+        resourceId: string;
+        connectValue: string | string[];
+        refs: Record<string, string>;
+        metadata?: Record<string, unknown> | null;
+    }): Promise<Record<string, unknown>>;
+    updateMapping(id: string, mapping: {
+        resourceId: string;
+        connectValue: string | string[];
+        refs: Record<string, string>;
+        metadata?: Record<string, unknown> | null;
+    }): Promise<Record<string, unknown>>;
+    deleteMapping(id: string): Promise<void>;
+    getVars(plugName: string): Promise<Record<string, string>>;
+    setVars(plugName: string, vars: Record<string, string>): Promise<void>;
+    clearVars(plugName: string): Promise<void>;
+    hasVars(plugName: string): Promise<boolean>;
+    getVarFields(plugName: string): readonly VarField[];
+    getPlug(plugName: string): PlugRegistration["plug"];
+}
+declare function drizzleAdapter(db: PgDatabase<any, any, any>): KhotanAdapter;
+type WorkflowStartFn = (workflowFn: (...args: any[]) => any, args: unknown[]) => Promise<unknown>;
+interface WorkflowRunHandle {
+    runId?: string;
+    status?: Promise<string>;
+    returnValue?: Promise<unknown>;
+    cancel?: () => Promise<void>;
+    getReadable?: (options?: {
+        startIndex?: number;
+        namespace?: string;
+    }) => ReadableStream;
+}
+type WorkflowGetRunFn = (runId: string) => WorkflowRunHandle;
+type WorkflowGetWritableFn = <T = unknown>(options?: {
+    namespace?: string;
+}) => WritableStream<T>;
+declare function __setWorkflowStartForTests(start: WorkflowStartFn | null): void;
+declare function __setWorkflowGetRunForTests(getRun: WorkflowGetRunFn | null): void;
+declare function __setWorkflowGetWritableForTests(getWritable: WorkflowGetWritableFn | null): void;
+declare function sendUpdate(update: KhotanRunUpdate | string, options?: {
+    namespace?: string;
+}): Promise<void>;
+declare function khotan(config: KhotanConfig): KhotanInstance;
+interface NextJsRequest extends Request {
+    nextUrl?: URL;
+}
+interface NextJsRouteHandlers {
+    GET: (req: NextJsRequest) => Promise<Response>;
+    POST: (req: NextJsRequest) => Promise<Response>;
+    PUT: (req: NextJsRequest) => Promise<Response>;
+    PATCH: (req: NextJsRequest) => Promise<Response>;
+    DELETE: (req: NextJsRequest) => Promise<Response>;
+}
+declare function toNextJsHandler(factoryHandler: KhotanHandler): NextJsRouteHandlers;
+
+export { type BindablePlug, type BoundPlug, type CacheEntryRecord, type CacheInstance, type CacheRegistration, type CacheScope, type CatchRegistration, type CatchWorkflowContext, type FlowInstance, type FlowRegistration, type FlowRunContext, type FlowRunResult, type FlowSelectorOptions, type FlowStartOptions, type FlowType, type FlowWorkflowContext, type KhotanAdapter, type KhotanConfig, type KhotanHandler, type KhotanInstance, type KhotanRunStatus, type KhotanRunUpdate, type KhotanTerminalRunStatus, type PassRegistration, type PassWorkflowContext, type PlugRegistration, type ResourceConnectField, type ResourceMappingRegistration, type ResourcePlugParticipation, type ResourceRegistration, type VarField, type WebhookRegistration, type WireInstance, type WireRegistration, type WireSubscribeContext, type WireUnsubscribeContext, type WireVerifyContext, __setWorkflowGetRunForTests, __setWorkflowGetWritableForTests, __setWorkflowStartForTests, bindWorkflowPlug, drizzleAdapter, khotan, khotanCache, khotanMappings, sendUpdate, toNextJsHandler };