@rolealpha/n8n-nodes-rolealpha 0.5.1 → 0.7.0

package/dist/lib/workflows.d.ts

@@ -0,0 +1,170 @@
+/**
+ * Workflows that follow the organisation. When a step, role or agent is created or changed
+ * in roleALPHA, a model proposes to create, update or deactivate an n8n workflow. The
+ * proposal never goes live by itself: it becomes an inactive draft, a person filling the
+ * deciding role approves it, and only then is it applied.
+ *
+ * The model call stays outside: buildPlanInput prepares it, checkPlan checks the answer.
+ * The model can neither pick node types outside the allow list, nor bring in credentials
+ * it has not seen, nor bake persons, addresses or UUIDs into a workflow, nor touch a
+ * workflow that is not managed.
+ */
+import type { EntityChange } from './changes';
+import { type GraphSource } from './graph';
+export declare const MANAGED_TAG = "rolealpha-managed";
+export declare const DRAFT_TAG = "rolealpha-draft";
+export declare const MARKER_NAME = "roleALPHA binding";
+export declare const DRAFT_PREFIX = "Draft: ";
+export declare const DEFAULT_NODE_TYPES: string[];
+export interface N8nNode {
+    id?: string;
+    name: string;
+    type: string;
+    typeVersion: number;
+    position: [number, number];
+    parameters: Record<string, unknown>;
+    credentials?: Record<string, {
+        id: string;
+        name: string;
+    }>;
+    webhookId?: string;
+    disabled?: boolean;
+}
+export type N8nConnections = Record<string, Record<string, Array<Array<{
+    node: string;
+    type: string;
+    index: number;
+}>>>>;
+export interface N8nWorkflow {
+    id?: string;
+    name: string;
+    active?: boolean;
+    nodes: N8nNode[];
+    connections: N8nConnections;
+    settings?: Record<string, unknown>;
+    tags?: Array<{
+        id?: string;
+        name: string;
+    }>;
+    versionId?: string;
+    updatedAt?: string;
+}
+/** What a draft carries about itself, so Apply needs nothing but the draft. */
+export interface DraftInfo {
+    action: 'create' | 'update' | 'deactivate';
+    targetWorkflowId: string | null;
+    /** versionId (or updatedAt) of the target when the draft was made; Apply refuses if it moved on. */
+    targetVersion: string | null;
+    entityUuid: string;
+    change: string;
+    contentHash: string;
+    reason: string;
+}
+export interface Binding {
+    managed: true;
+    entities: string[];
+    draft?: DraftInfo;
+}
+export interface KnownCredential {
+    id: string;
+    name: string;
+    type: string;
+}
+export interface ManagedWorkflow {
+    id: string;
+    name: string;
+    active: boolean;
+    entities: string[];
+    isDraft: boolean;
+    versionId: string | null;
+    nodes: Array<{
+        name: string;
+        type: string;
+        parameters: string;
+        credentials: string[];
+    }>;
+    connections: string[];
+}
+export declare function readBinding(wf: Pick<N8nWorkflow, 'nodes'>): Binding | null;
+export declare function markerNode(binding: Binding, position?: [number, number]): N8nNode;
+/** Hash of exactly what runs: names, types, versions, parameters, credentials and connections. */
+export declare function contentHash(wf: Pick<N8nWorkflow, 'nodes' | 'connections'>): string;
+export declare function summarizeWorkflows(raw: unknown[]): {
+    workflows: ManagedWorkflow[];
+    credentials: KnownCredential[];
+};
+export interface PlanContext {
+    change: EntityChange;
+    /** What roleALPHA says about the entity now: details, step, relationships. Never persons. */
+    entity: unknown;
+    workflows: ManagedWorkflow[];
+    credentials: KnownCredential[];
+    nodeTypes: string[];
+    extraRules?: string[];
+}
+export interface PlanInput {
+    systemMessage: string;
+    prompt: string;
+    schema: Record<string, unknown>;
+}
+export declare const PLAN_SCHEMA: Record<string, unknown>;
+export declare function buildPlanInput(ctx: PlanContext): PlanInput;
+/** Takes the JSON object out of a model answer (plain, fenced, or with text around it). */
+export declare function parseAnswer(answer: unknown): unknown;
+export interface PlanCheck {
+    ok: boolean;
+    action: 'create' | 'update' | 'deactivate' | 'none';
+    reason: string;
+    targetWorkflowId: string | null;
+    targetVersion: string | null;
+    entityUuid: string;
+    /** Blocking: the proposal is not used. */
+    problems: string[];
+    /** Not blocking, for the person who approves (e.g. a credential to set). */
+    notes: string[];
+    workflow: N8nWorkflow | null;
+    contentHash: string | null;
+}
+export declare function checkPlan(ctx: PlanContext, answerRaw: unknown, existing?: N8nWorkflow | null): PlanCheck;
+export declare function draftWorkflow(plan: PlanCheck, change: EntityChange, target?: N8nWorkflow | null): N8nWorkflow;
+/** The hash a draft stands for: its content, or for a deactivation the target and its version. */
+export declare function draftHash(draft: N8nWorkflow): {
+    info: DraftInfo;
+    hash: string;
+};
+export type N8nRequest = (method: 'GET' | 'POST' | 'PUT' | 'DELETE', path: string, body?: unknown, qs?: Record<string, string | number>) => Promise<unknown>;
+export declare class N8nApi {
+    private readonly request;
+    constructor(request: N8nRequest);
+    listWorkflows(tag: string): Promise<N8nWorkflow[]>;
+    get(id: string): Promise<N8nWorkflow>;
+    create(wf: N8nWorkflow): Promise<N8nWorkflow>;
+    update(id: string, wf: N8nWorkflow): Promise<N8nWorkflow>;
+    remove(id: string): Promise<void>;
+    activate(id: string): Promise<void>;
+    deactivate(id: string): Promise<void>;
+    /** Sets the tags of a workflow by name, creating tags that do not exist yet. */
+    setTags(id: string, names: string[]): Promise<void>;
+}
+export interface ApplyResult {
+    applied: boolean;
+    action: DraftInfo['action'];
+    workflowId: string;
+    draftId: string;
+    activated: boolean;
+    reason: string;
+}
+/**
+ * Applies an approved draft. Fail-closed: the draft must still hash to what was approved,
+ * and the target must still be the version the draft was made from.
+ */
+export declare function applyDraft(api: N8nApi, draftId: string, approvedHash: string, opts?: {
+    activate?: boolean;
+}): Promise<ApplyResult>;
+/** Deletes a rejected draft. Refuses anything that is not a draft. */
+export declare function discardDraft(api: N8nApi, draftId: string): Promise<{
+    discarded: boolean;
+    draftId: string;
+}>;
+/** The entity as roleALPHA shows it now, without persons: a step with its roles, anything else with its edges. */
+export declare function entityContext(src: GraphSource, change: EntityChange): Promise<unknown>;