@kairos-sdk/core 0.4.0 → 0.4.5

package/dist/reader-CpUcHhKW.d.cts

@@ -0,0 +1,566 @@
+interface Tag {
+    id: string;
+    name: string;
+}
+interface N8nCredentialReference {
+    id: string;
+    name: string;
+}
+type ConnectionPort = {
+    node: string;
+    type: string;
+    index: number;
+};
+type ConnectionPortList = ConnectionPort[];
+interface N8nConnections {
+    [nodeName: string]: {
+        main?: ConnectionPortList[];
+        ai_languageModel?: ConnectionPortList[];
+        ai_memory?: ConnectionPortList[];
+        ai_tool?: ConnectionPortList[];
+        ai_document?: ConnectionPortList[];
+        ai_embedding?: ConnectionPortList[];
+        ai_vectorStore?: ConnectionPortList[];
+        ai_retriever?: ConnectionPortList[];
+        ai_outputParser?: ConnectionPortList[];
+        ai_textSplitter?: ConnectionPortList[];
+        [key: string]: ConnectionPortList[] | undefined;
+    };
+}
+interface N8nNode {
+    id: string;
+    name: string;
+    type: string;
+    typeVersion: number;
+    position: [number, number];
+    parameters: Record<string, unknown>;
+    credentials?: Record<string, N8nCredentialReference>;
+    disabled?: boolean;
+    notes?: string;
+    notesInFlow?: boolean;
+    continueOnFail?: boolean;
+    retryOnFail?: boolean;
+    maxTries?: number;
+    waitBetweenTries?: number;
+}
+interface N8nSettings {
+    executionOrder?: 'v0' | 'v1';
+    saveManualExecutions?: boolean;
+    callerPolicy?: string;
+    errorWorkflow?: string;
+    timezone?: string;
+    [key: string]: unknown;
+}
+interface N8nWorkflow {
+    name: string;
+    nodes: N8nNode[];
+    connections: N8nConnections;
+    settings?: N8nSettings;
+    tags?: Tag[];
+}
+
+interface CredentialRequirement {
+    service: string;
+    credentialType: string;
+    description: string;
+}
+interface BuildResult {
+    workflowId: string | null;
+    name: string;
+    workflow: N8nWorkflow;
+    credentialsNeeded: CredentialRequirement[];
+    activationRequired: boolean;
+    generationAttempts: number;
+    dryRun: boolean;
+}
+interface DeployResult {
+    workflowId: string;
+    name: string;
+}
+interface WorkflowListItem {
+    id: string;
+    name: string;
+    active: boolean;
+    createdAt: string;
+    updatedAt: string;
+    tags?: Array<{
+        id: string;
+        name: string;
+    }>;
+}
+interface ExecutionSummary {
+    id: string;
+    workflowId: string;
+    status: 'success' | 'error' | 'waiting' | 'running' | 'canceled';
+    startedAt: string;
+    stoppedAt?: string;
+    mode: string;
+}
+interface ExecutionDetail extends ExecutionSummary {
+    data?: unknown;
+    workflowData?: unknown;
+}
+
+interface ILogger {
+    debug(msg: string, meta?: Record<string, unknown>): void;
+    info(msg: string, meta?: Record<string, unknown>): void;
+    warn(msg: string, meta?: Record<string, unknown>): void;
+    error(msg: string, meta?: Record<string, unknown>): void;
+}
+declare const nullLogger: ILogger;
+
+interface FailurePattern {
+    rule: number;
+    message: string;
+    occurrences: number;
+}
+type SourceKind = 'organic' | 'n8n-template' | 'imported';
+type TrustLevel = 'safe' | 'review' | 'blocked';
+interface WorkflowMetadataInput {
+    description: string;
+    tags?: string[];
+    platform?: string;
+    failurePatterns?: Array<{
+        rule: number;
+        message: string;
+    }>;
+    sourceWorkflowIds?: string[];
+    generationMode?: 'direct' | 'reference' | 'scratch';
+    topMatchScore?: number;
+    generationAttempts?: number;
+    credentialsNeeded?: CredentialRequirement[];
+    sourceKind?: SourceKind;
+    sourceId?: string;
+    sourceUrl?: string;
+    trustLevel?: TrustLevel;
+}
+interface OutcomeData {
+    attempts: number;
+    firstTryPass: boolean;
+    failedRules: number[];
+    mode: 'direct' | 'reference';
+}
+interface OutcomeStats {
+    totalUses: number;
+    totalAttempts: number;
+    firstTryPasses: number;
+    failedRules: Record<string, number>;
+}
+interface StoredWorkflow {
+    id: string;
+    workflow: N8nWorkflow;
+    description: string;
+    tags: string[];
+    platform: string;
+    deployCount: number;
+    createdAt: string;
+    lastDeployedAt?: string;
+    failurePatterns?: FailurePattern[];
+    sourceWorkflowIds?: string[];
+    generationMode?: 'direct' | 'reference' | 'scratch';
+    topMatchScore?: number;
+    generationAttempts?: number;
+    credentialsNeeded?: CredentialRequirement[];
+    sourceKind?: SourceKind;
+    sourceId?: string;
+    sourceUrl?: string;
+    trustLevel?: TrustLevel;
+    timesRetrieved?: number;
+    timesUsedAsDirect?: number;
+    timesUsedAsReference?: number;
+    outcomeStats?: OutcomeStats;
+}
+interface WorkflowMatch {
+    workflow: StoredWorkflow;
+    score: number;
+    mode: 'direct' | 'reference' | 'scratch';
+}
+interface SearchOptions {
+    limit?: number;
+    platform?: string;
+}
+interface LibraryFilters {
+    platform?: string;
+    tags?: string[];
+}
+interface IWorkflowLibrary {
+    initialize(): Promise<void>;
+    search(description: string, options?: SearchOptions): Promise<WorkflowMatch[]>;
+    save(workflow: N8nWorkflow, metadata: WorkflowMetadataInput): Promise<string>;
+    recordDeployment(id: string): Promise<void>;
+    recordOutcome(id: string, outcome: OutcomeData): Promise<void>;
+    get(id: string): Promise<StoredWorkflow | null>;
+    list(filters?: LibraryFilters): Promise<StoredWorkflow[]>;
+}
+
+interface ClientOptions {
+    anthropicApiKey: string;
+    n8nBaseUrl?: string;
+    n8nApiKey?: string;
+    model?: string;
+    logger?: ILogger;
+    library?: IWorkflowLibrary;
+    telemetry?: boolean | string;
+}
+interface BuildOptions {
+    dryRun?: boolean;
+    activate?: boolean;
+    name?: string;
+}
+interface DeleteOptions {
+    confirm: true;
+}
+interface ExecutionFilter {
+    status?: 'success' | 'error' | 'waiting' | 'running';
+    limit?: number;
+    cursor?: string;
+}
+
+interface IProvider {
+    readonly platform: string;
+    deploy(workflow: N8nWorkflow): Promise<DeployResult>;
+    update(id: string, workflow: N8nWorkflow): Promise<DeployResult>;
+    get(id: string): Promise<N8nWorkflow>;
+    list(): Promise<WorkflowListItem[]>;
+    activate(id: string): Promise<void>;
+    deactivate(id: string): Promise<void>;
+    delete(id: string, options: DeleteOptions): Promise<void>;
+    executions(workflowId?: string, filter?: ExecutionFilter): Promise<ExecutionSummary[]>;
+    execution(id: string): Promise<ExecutionDetail>;
+    tag(workflowId: string, tagIds: string[]): Promise<void>;
+    untag(workflowId: string, tagIds: string[]): Promise<void>;
+    listTags(): Promise<Tag[]>;
+    createTag(name: string): Promise<Tag>;
+}
+
+interface N8nWorkflowResponse {
+    id: string;
+    name: string;
+    active: boolean;
+    nodes: N8nNode[];
+    connections: N8nConnections;
+    settings?: N8nSettings;
+    tags?: Tag[];
+    createdAt: string;
+    updatedAt: string;
+    versionId?: string;
+    meta?: Record<string, unknown>;
+    pinData?: Record<string, unknown>;
+    staticData?: unknown;
+    triggerCount?: number;
+    shared?: boolean;
+    isArchived?: boolean;
+}
+interface N8nNodeTypeInfo {
+    name: string;
+    displayName: string;
+    version: number | number[];
+    description?: string;
+    group?: string[];
+    credentials?: Array<{
+        name: string;
+        required?: boolean;
+    }>;
+}
+
+declare class N8nApiClient {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly logger;
+    constructor(baseUrl: string, apiKey: string, logger: ILogger);
+    private request;
+    private singleRequest;
+    createWorkflow(workflow: N8nWorkflow): Promise<N8nWorkflowResponse>;
+    updateWorkflow(id: string, workflow: N8nWorkflow): Promise<N8nWorkflowResponse>;
+    getWorkflow(id: string): Promise<N8nWorkflowResponse>;
+    listWorkflows(): Promise<WorkflowListItem[]>;
+    deleteWorkflow(id: string): Promise<void>;
+    activateWorkflow(id: string): Promise<void>;
+    deactivateWorkflow(id: string): Promise<void>;
+    getExecutions(workflowId?: string, filter?: ExecutionFilter): Promise<ExecutionSummary[]>;
+    getExecution(id: string): Promise<ExecutionDetail>;
+    listTags(): Promise<Tag[]>;
+    createTag(name: string): Promise<Tag>;
+    tagWorkflow(workflowId: string, tagIds: string[]): Promise<void>;
+    untagWorkflow(workflowId: string, tagIds: string[]): Promise<void>;
+    getNodeTypes(): Promise<N8nNodeTypeInfo[]>;
+    private mapExecution;
+}
+
+declare class N8nFieldStripper {
+    stripForCreate(workflow: N8nWorkflow): N8nWorkflow;
+    stripForUpdate(workflow: N8nWorkflow): N8nWorkflow;
+    private strip;
+}
+
+declare class N8nProvider implements IProvider {
+    private readonly client;
+    private readonly stripper;
+    readonly platform = "n8n";
+    constructor(client: N8nApiClient, stripper: N8nFieldStripper);
+    deploy(workflow: N8nWorkflow): Promise<DeployResult>;
+    update(id: string, workflow: N8nWorkflow): Promise<DeployResult>;
+    get(id: string): Promise<N8nWorkflow>;
+    list(): Promise<WorkflowListItem[]>;
+    activate(id: string): Promise<void>;
+    deactivate(id: string): Promise<void>;
+    delete(id: string, options: DeleteOptions): Promise<void>;
+    executions(workflowId?: string, filter?: ExecutionFilter): Promise<ExecutionSummary[]>;
+    execution(id: string): Promise<ExecutionDetail>;
+    listTags(): Promise<Tag[]>;
+    createTag(name: string): Promise<Tag>;
+    tag(workflowId: string, tagIds: string[]): Promise<void>;
+    untag(workflowId: string, tagIds: string[]): Promise<void>;
+}
+
+declare class NullLibrary implements IWorkflowLibrary {
+    initialize(): Promise<void>;
+    search(_description: string, _options?: SearchOptions): Promise<WorkflowMatch[]>;
+    save(_workflow: N8nWorkflow, _metadata: WorkflowMetadataInput): Promise<string>;
+    recordDeployment(_id: string): Promise<void>;
+    recordOutcome(_id: string, _outcome: OutcomeData): Promise<void>;
+    get(_id: string): Promise<StoredWorkflow | null>;
+    list(_filters?: LibraryFilters): Promise<StoredWorkflow[]>;
+}
+
+declare function tokenize(text: string): string[];
+declare function buildSearchCorpus(w: StoredWorkflow): string;
+declare class FileLibrary implements IWorkflowLibrary {
+    private readonly dir;
+    private meta;
+    private initPromise;
+    private writeQueue;
+    constructor(dir?: string);
+    private get workflowsDir();
+    private workflowFilePath;
+    initialize(): Promise<void>;
+    private doInitialize;
+    /**
+     * One-time transparent migration from v0.4.x monolithic index.json.
+     * Splits each stored workflow into a per-file workflow JSON and a lightweight
+     * meta entry. Rewrites index.json in the new format.
+     */
+    private migrateFromMonolithic;
+    private loadWorkflowFile;
+    private writeWorkflowFile;
+    /**
+     * Build a lightweight StoredWorkflow shell from a meta entry for use in
+     * scoring / clustering. Only node.type is populated in each node — no other
+     * node fields are used by hybridScore or clusterWorkflows.
+     */
+    private makeSearchShell;
+    search(description: string, options?: SearchOptions): Promise<WorkflowMatch[]>;
+    save(workflow: N8nWorkflow, metadata: WorkflowMetadataInput): Promise<string>;
+    recordDeployment(id: string): Promise<void>;
+    recordOutcome(id: string, outcome: OutcomeData): Promise<void>;
+    drain(): Promise<void>;
+    get(id: string): Promise<StoredWorkflow | null>;
+    list(filters?: LibraryFilters): Promise<StoredWorkflow[]>;
+    private deduplicateFailurePatterns;
+    /**
+     * Direct write used only during migration (before writeQueue is needed).
+     */
+    private persistNow;
+    private persist;
+}
+
+interface ScoredEntry {
+    workflow: StoredWorkflow;
+    score: number;
+    signals: {
+        tfidf: number;
+        nodeFingerprint: number;
+        outcome: number;
+        deploy: number;
+    };
+}
+declare function hybridScore(queryTokens: string[], queryDescription: string, workflows: StoredWorkflow[], docTokenArrays: string[][], idf: Map<string, number>): ScoredEntry[];
+
+interface WorkflowCluster {
+    pattern: string;
+    fingerprint: string[];
+    members: StoredWorkflow[];
+    avgFirstTryPassRate: number;
+    avgAttempts: number;
+    commonFailedRules: Array<{
+        rule: number;
+        frequency: number;
+    }>;
+}
+declare function clusterWorkflows(workflows: StoredWorkflow[]): WorkflowCluster[];
+declare function rerank(candidates: Array<{
+    workflow: StoredWorkflow;
+    score: number;
+}>, clusters: WorkflowCluster[]): Array<{
+    workflow: StoredWorkflow;
+    score: number;
+    clusterPattern?: string;
+}>;
+
+interface ValidationIssue {
+    rule: number;
+    severity: 'error' | 'warn';
+    message: string;
+    nodeId?: string;
+    nodeType?: string;
+}
+interface ValidationResult {
+    valid: boolean;
+    issues: ValidationIssue[];
+}
+
+interface NodeDefinition {
+    type: string;
+    safeTypeVersions: number[];
+    requiredParams: string[];
+    credentialType?: string;
+    isTrigger?: boolean;
+}
+declare const DEFAULT_REGISTRY: NodeDefinition[];
+declare class NodeRegistry {
+    private readonly byType;
+    constructor(definitions?: NodeDefinition[]);
+    get(type: string): NodeDefinition | undefined;
+    isTrigger(type: string): boolean;
+    isKnown(type: string): boolean;
+    isVersionSafe(type: string, version: number): boolean;
+    getRequiredParams(type: string): string[];
+}
+
+declare class N8nValidator {
+    private readonly registry;
+    constructor(registry?: NodeRegistry);
+    validate(workflow: N8nWorkflow): ValidationResult;
+    private err;
+    private warn;
+    private isTriggerNode;
+    private checkRule1;
+    private checkRule2;
+    private checkRule3;
+    private checkRule4;
+    private checkRule5;
+    private checkRule6;
+    private checkRule7;
+    private checkRule8;
+    private checkRule9;
+    private checkRule10;
+    private checkRule11;
+    private checkRule12;
+    private checkRule13;
+    private checkRule14;
+    private checkRule15;
+    private checkRule16;
+    private checkRule17;
+    private checkRule18;
+    private checkRule19;
+    private checkRule20;
+    private checkRule22;
+    private checkRule23;
+    private checkRule24;
+    private checkRule25;
+    private checkRule26;
+    private extractExpressions;
+    private checkRule21;
+}
+
+declare class KairosError extends Error {
+    readonly cause?: unknown | undefined;
+    constructor(message: string, cause?: unknown | undefined);
+}
+
+interface TelemetryEvent {
+    schemaVersion: number;
+    timestamp: string;
+    sessionId: string;
+    runId?: string;
+    eventType: 'build_start' | 'generation_attempt' | 'build_complete';
+    data: Record<string, unknown>;
+}
+interface AttemptMetadata {
+    attempt: number;
+    temperature: number;
+    durationMs: number;
+    tokensInput: number;
+    tokensOutput: number;
+    validationPassed: boolean;
+    issues: ValidationIssue[];
+}
+
+declare class ValidationError extends KairosError {
+    readonly issues: ValidationIssue[];
+    readonly attemptMetadata?: AttemptMetadata[] | undefined;
+    readonly warnedRules?: number[] | undefined;
+    constructor(message: string, issues: ValidationIssue[], attemptMetadata?: AttemptMetadata[] | undefined, warnedRules?: number[] | undefined);
+}
+
+declare class GenerationError extends KairosError {
+    constructor(message: string, cause?: unknown);
+}
+
+declare class ResponseParseError extends KairosError {
+    constructor(message: string, cause?: unknown);
+}
+
+declare class ProviderError extends KairosError {
+    constructor(message: string, cause?: unknown);
+}
+
+declare class ApiError extends KairosError {
+    readonly statusCode: number;
+    constructor(message: string, statusCode: number, cause?: unknown);
+}
+
+declare class GuardError extends KairosError {
+    constructor(message: string);
+}
+
+interface SyncProgress {
+    total: number;
+    processed: number;
+    saved: number;
+    skippedPaid: number;
+    skippedDuplicate: number;
+    blocked: number;
+    reviewed: number;
+}
+
+interface SyncOptions {
+    maxTemplates?: number;
+    onProgress?: (progress: SyncProgress) => void;
+}
+declare class TemplateSyncer {
+    private readonly library;
+    private readonly validator;
+    private readonly logger;
+    constructor(library: IWorkflowLibrary, logger: ILogger);
+    sync(options?: SyncOptions): Promise<SyncProgress>;
+    private fetchTemplateIds;
+    private processTemplate;
+    private cleanDescription;
+}
+
+declare class TelemetryCollector {
+    private readonly dir;
+    readonly sessionId: string;
+    private dirReady;
+    constructor(dir?: string);
+    emit(eventType: TelemetryEvent['eventType'], data: Record<string, unknown>, runId?: string): Promise<void>;
+}
+
+interface RuleFailureRate {
+    rule: number;
+    failureCount: number;
+    totalBuilds: number;
+    rate: number;
+    commonMessage: string;
+}
+declare class TelemetryReader {
+    private readonly dir;
+    private cache;
+    private cacheTime;
+    constructor(dir?: string);
+    getFailureRates(days?: number): Promise<RuleFailureRate[]>;
+    private readRecentEvents;
+}
+
+export { clusterWorkflows as $, ApiError as A, type BuildOptions as B, type ClientOptions as C, type DeleteOptions as D, type ExecutionFilter as E, type FailurePattern as F, GenerationError as G, type TelemetryEvent as H, type ILogger as I, TelemetryReader as J, KairosError as K, TemplateSyncer as L, type TrustLevel as M, type N8nWorkflow as N, type OutcomeData as O, ProviderError as P, type ValidationIssue as Q, ResponseParseError as R, type ScoredEntry as S, type Tag as T, type ValidationResult as U, ValidationError as V, type WorkflowListItem as W, type WorkflowCluster as X, type WorkflowMatch as Y, type WorkflowMetadataInput as Z, buildSearchCorpus as _, type BuildResult as a, hybridScore as a0, nullLogger as a1, rerank as a2, tokenize as a3, type ExecutionSummary as b, type ExecutionDetail as c, type AttemptMetadata as d, type CredentialRequirement as e, DEFAULT_REGISTRY as f, type DeployResult as g, FileLibrary as h, GuardError as i, type IProvider as j, type IWorkflowLibrary as k, N8nApiClient as l, type N8nConnections as m, N8nFieldStripper as n, type N8nNode as o, N8nProvider as p, type N8nSettings as q, N8nValidator as r, NodeRegistry as s, NullLibrary as t, type OutcomeStats as u, type RuleFailureRate as v, type SourceKind as w, type StoredWorkflow as x, type SyncProgress as y, TelemetryCollector as z };