toolroll 0.9.6 → 0.9.8

package/dist/flow-share.d.ts

@@ -0,0 +1,102 @@
+import { type ScriptDraft } from "./flow-scripts.js";
+import { type FlowDefinition } from "./flows.js";
+import type { FlowRow, Store } from "./store.js";
+export declare const FLOW_FILE_FORMAT = "toolroll-flow";
+export declare const FLOW_FILE_VERSION = 1;
+/** The largest flow file Toolroll reads or fetches. */
+export declare const FLOW_FILE_MAX_BYTES: number;
+export declare const FLOW_FILE_SUFFIX = ".toolroll-flow.json";
+/** Something the import asks for: `{{param.<id>}}` in a zone or trigger is replaced by its value. */
+export type FlowFileParameter = {
+    id: string;
+    about: string;
+    default?: string;
+    optional?: boolean;
+};
+export type FlowFileScript = {
+    name: string;
+    about: string;
+    language: ScriptDraft["language"];
+    timeoutMinutes: number;
+    body?: string;
+    file?: string;
+};
+export type FlowFile = {
+    format: typeof FLOW_FILE_FORMAT;
+    version: typeof FLOW_FILE_VERSION;
+    name: string;
+    about: string;
+    needs: string[];
+    parameters: FlowFileParameter[];
+    /** The zones in the lead's step vocabulary, the start first. */
+    zones: Record<string, unknown>[];
+    /** Each trigger's settings, as `toolroll flows trigger add` takes them. */
+    triggers: Record<string, unknown>[];
+    scripts: FlowFileScript[];
+};
+export type FlowExported = {
+    file: FlowFile;
+    json: string;
+    fileName: string;
+    left: string[];
+};
+/** A flow as a file: its zones and paths, its triggers' settings and the scripts it runs, nothing of this installation's. */
+export declare function exportFlow(store: Store, flow: FlowRow, dir: string | null): FlowExported;
+export declare class FlowFileError extends Error {
+}
+/** Read a flow file: its size, its JSON, its format and version, and every zone, trigger, script and parameter. Throws FlowFileError in plain words. */
+export declare function parseFlowFile(text: string): FlowFile;
+/** --param k=v lines (or a form's fields) as values; refuses parameters the file doesn't ask for. */
+export declare function parameterValues(file: FlowFile, given: Record<string, string>): Record<string, string>;
+export declare function needWords(need: string): string;
+export type FlowImportPlan = {
+    name: string;
+    repo: string;
+    definition: FlowDefinition;
+    triggers: Record<string, unknown>[];
+    /** Scripts to add (held until approved), and those the project already has exactly. */
+    scripts: {
+        add: FlowFileScript[];
+        kept: string[];
+    };
+    values: Record<string, string>;
+    title: string;
+    /** The whole preview, line by line (the CLI's); `parts` is the same, grouped for the console's page. */
+    terms: string[];
+    parts: {
+        about: string | null;
+        steps: string[];
+        notes: string[];
+        triggers: string[];
+        scripts: string[];
+        kept: string[];
+        filled: string | null;
+        needs: string | null;
+    };
+};
+/** The import in plain words, checked against the project it lands in. Throws FlowFileError. */
+export declare function planFlowImport(store: Store, repo: string, file: FlowFile, given: Record<string, string>, actor: string): FlowImportPlan;
+/** Make the planned flow: scripts held, the flow, and its triggers switched off. One transaction. */
+export declare function importFlow(store: Store, plan: FlowImportPlan, actor: string, now: Date, dir: string | null): {
+    id: number;
+    said: string;
+};
+/** What a flow's zones and paths are, without where they sit on the canvas: what a round trip keeps. */
+export declare function flowShape(definition: FlowDefinition): string;
+/** A gist or GitHub file page as the address of its raw text; null when it isn't one Toolroll fetches. */
+export declare function rawFlowUrl(address: string): string | null;
+export type FetchLike = (url: string, init: {
+    redirect: "follow";
+    signal: AbortSignal;
+    headers: Record<string, string>;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    url?: string;
+    headers: {
+        get(name: string): string | null;
+    };
+    body: ReadableStream<Uint8Array> | null;
+}>;
+/** A flow file from a gist or GitHub, over HTTPS only, refused past the size cap. Throws FlowFileError in plain words. */
+export declare function fetchFlowFile(address: string, fetcher?: FetchLike): Promise<string>;