@kairos-sdk/core 0.4.0 → 0.5.0

package/dist/reader-B5mV20H6.d.ts

@@ -0,0 +1,596 @@
+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;
+}
+type SmokeTestStatus = 'passed' | 'failed' | 'error' | 'skipped' | 'not-applicable';
+interface SmokeTestResult {
+    status: SmokeTestStatus;
+    triggerType: 'manual' | 'webhook' | 'not-applicable';
+    executionId?: string;
+    durationMs?: number;
+    error?: string;
+}
+interface BuildResult {
+    workflowId: string | null;
+    name: string;
+    workflow: N8nWorkflow;
+    credentialsNeeded: CredentialRequirement[];
+    activationRequired: boolean;
+    generationAttempts: number;
+    dryRun: boolean;
+    smokeTest?: SmokeTestResult;
+}
+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;
+    n8nWorkflowId?: string;
+}
+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;
+    n8nWorkflowId?: string;
+}
+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, n8nWorkflowId?: 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;
+    smokeTest?: boolean;
+}
+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[]>;
+    triggerManual(workflowId: string): Promise<string>;
+    triggerWebhookTest(path: string): Promise<number>;
+    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>;
+    smokeTest(workflowId: string, workflow: N8nWorkflow): Promise<SmokeTestResult>;
+    private detectTrigger;
+    private pollExecution;
+}
+
+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;
+    private scanForOrphansAndCleanup;
+    /**
+     * 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, n8nWorkflowId?: 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;
+    private get lockPath();
+    private acquireLock;
+    /**
+     * 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;
+    isVersionNewer(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 checkRule21;
+    private checkRule22;
+    private checkRule23;
+    private checkRule24;
+    private checkRule25;
+    private checkRule26;
+    private extractExpressions;
+    private checkRule27;
+    private checkRule28;
+    private checkRule29;
+    private checkRule30;
+    private checkRule31;
+    private checkRule32;
+    private checkRule33;
+    private checkRule34;
+}
+
+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 fetchWithBackoff;
+    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 { buildSearchCorpus 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, TelemetryCollector as H, type ILogger as I, type TelemetryEvent as J, KairosError as K, TelemetryReader as L, TemplateSyncer as M, type N8nWorkflow as N, type OutcomeData as O, ProviderError as P, type TrustLevel as Q, ResponseParseError as R, type ScoredEntry as S, type Tag as T, type ValidationIssue as U, ValidationError as V, type WorkflowListItem as W, type ValidationResult as X, type WorkflowCluster as Y, type WorkflowMatch as Z, type WorkflowMetadataInput as _, type BuildResult as a, clusterWorkflows as a0, hybridScore as a1, nullLogger as a2, rerank as a3, tokenize as a4, type SmokeTestStatus as a5, 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 SmokeTestResult as w, type SourceKind as x, type StoredWorkflow as y, type SyncProgress as z };