@kahitsan/plugin-sdk 0.1.0-staging.2 → 0.1.0-staging.20

package/dist/flow-bundle.d.ts

@@ -0,0 +1,2 @@
+export { buildFlow, FlowSteps, runFlow, defineFlow, node, edge } from "./index.js";
+export type { FlowDefinition, FlowNodeDef, FlowNodeKind, FlowPort, FlowNode, ExecFlow, ExecNode, FlowContext, NodeExec } from "./index.js";

package/dist/flow-bundle.js

@@ -0,0 +1,195 @@
+// src/flow/flow-spec.ts
+function edge(to, label) {
+  return label === void 0 ? { id: "out", to } : { id: label, to, label };
+}
+function node(id, kind, label, opts) {
+  return { id, kind, label, detail: opts?.detail, out: opts?.out };
+}
+function defineFlow(def) {
+  const ids = new Set(def.nodes.map((n) => n.id));
+  for (const n of def.nodes) {
+    for (const p of n.out ?? []) {
+      if (!ids.has(p.to)) {
+        throw new Error(`flow "${def.id}": node "${n.id}" connects to unknown node "${p.to}"`);
+      }
+    }
+  }
+  return def;
+}
+
+// src/flow/flow-builder.ts
+var FlowSteps = class {
+  constructor(prefix) {
+    this.prefix = prefix;
+  }
+  prefix;
+  nodes = [];
+  make(kind, label, detail) {
+    const def = {
+      id: `${this.prefix}_${kind}_${this.nodes.length}`,
+      kind,
+      label,
+      ...detail ? { detail } : {}
+    };
+    this.nodes.push(def);
+    const handle = {
+      id: def.id,
+      to(target, label2) {
+        def.out = def.out ?? [];
+        def.out.push(label2 ? { id: label2, to: target.id, label: label2 } : { id: "out", to: target.id });
+        return target;
+      }
+    };
+    return handle;
+  }
+  /** A UI event that starts/continues the flow (a button, a selection). */
+  trigger(label) {
+    return this.make("trigger", label);
+  }
+  /** A data source / list the screen shows. */
+  data(label, detail) {
+    return this.make("data", label, detail);
+  }
+  /** A fetch/load into the current screen. */
+  load(label, detail) {
+    return this.make("load", label, detail);
+  }
+  /** Opens an overlay / form. */
+  modal(label) {
+    return this.make("modal", label);
+  }
+  /** A call out to another service/capability; `target` is its identifier. */
+  call(target, label) {
+    return this.make("call", label ?? target, target);
+  }
+  /** A pure computation (apply a discount, total a cart). */
+  compute(label) {
+    return this.make("compute", label);
+  }
+  /** A branch — wire its outcomes with `.to(target, "yes")` / `.to(target, "no")`. */
+  condition(label) {
+    return this.make("condition", label);
+  }
+  /** A write / command. */
+  commit(label, detail) {
+    return this.make("commit", label, detail);
+  }
+  /** Emits a domain event. */
+  emit(event) {
+    return this.make("emit", event);
+  }
+  /** A UI effect — refresh / toast / navigate / close. */
+  effect(label) {
+    return this.make("effect", label);
+  }
+  /** An end state. */
+  terminal(label) {
+    return this.make("terminal", label);
+  }
+};
+function buildFlow(id, title, build) {
+  const f = new FlowSteps(id.replace(/[^a-zA-Z0-9]+/g, "_"));
+  build(f);
+  return defineFlow({ id, title, nodes: f.nodes });
+}
+
+// src/flow/flow-runtime.ts
+function methodFor(kind, explicit) {
+  if (explicit) return explicit;
+  return kind === "load" ? "GET" : "POST";
+}
+function branchLabel(result) {
+  if (typeof result === "string") return result;
+  return result ? "yes" : "no";
+}
+async function runRequest(node2, ctx) {
+  if (!node2.request) return;
+  const spec = node2.request(ctx);
+  const init = { method: methodFor(node2.kind, spec.method) };
+  if (spec.body !== void 0) {
+    init.body = JSON.stringify(spec.body);
+    init.headers = { "Content-Type": "application/json" };
+  }
+  const res = await ctx.fetch(spec.url, init);
+  if (res.ok) {
+    ctx.state[node2.id] = await res.json().catch(() => null);
+  } else {
+    ctx.state[node2.id] = null;
+    ctx.state.__error = await res.json().catch(() => ({ error: res.statusText }));
+  }
+}
+function errorMessage(ctx) {
+  const err = ctx.state.__error;
+  return err?.error ?? err?.message;
+}
+function runEffect(node2, ctx) {
+  const ui = ctx.ui;
+  if (node2.effect === "refresh") ui?.refresh?.();
+  else if (node2.effect === "toast") ui?.toast?.(errorMessage(ctx) ?? node2.arg ?? node2.label);
+  else if (node2.effect === "close") ui?.close?.();
+  else if (node2.effect === "navigate") ui?.navigate?.(node2.arg ?? "/");
+}
+async function runModal(node2, ctx) {
+  if (!ctx.ui?.openModal) return {};
+  const input = await ctx.ui.openModal(node2);
+  if (input === null) return { halt: true };
+  Object.assign(ctx.state, input);
+  return {};
+}
+async function executeNode(node2, ctx) {
+  switch (node2.kind) {
+    case "load":
+    case "commit":
+      await runRequest(node2, ctx);
+      return {};
+    case "call":
+      if (node2.invoke && ctx.call) {
+        ctx.state[node2.id] = await ctx.call(node2.invoke.target, node2.invoke.args?.(ctx));
+      }
+      return {};
+    case "compute":
+      if (node2.compute) ctx.state[node2.id] = node2.compute(ctx);
+      return {};
+    case "condition":
+      return { branch: branchLabel(node2.when ? node2.when(ctx) : true) };
+    case "modal":
+      return runModal(node2, ctx);
+    case "effect":
+      runEffect(node2, ctx);
+      return {};
+    case "terminal":
+      return { halt: true };
+    default:
+      return {};
+  }
+}
+function pickNext(node2, branch) {
+  const outs = node2.out ?? [];
+  if (branch) return outs.find((o) => o.label === branch) ?? outs[0];
+  return outs[0];
+}
+async function runFlow(flow, startId, ctx) {
+  const byId = new Map(flow.nodes.map((n) => [n.id, n]));
+  const walked = /* @__PURE__ */ new Set();
+  let current = byId.get(startId);
+  while (current) {
+    const { branch, halt } = await executeNode(current, ctx);
+    if (halt) return;
+    const next = pickNext(current, branch);
+    if (!next) return;
+    const edgeKey = `${current.id}->${next.to}`;
+    if (walked.has(edgeKey)) return;
+    walked.add(edgeKey);
+    const target = byId.get(next.to);
+    if (target?.kind === "trigger") return;
+    current = target;
+  }
+}
+export {
+  FlowSteps,
+  buildFlow,
+  defineFlow,
+  edge,
+  node,
+  runFlow
+};

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { Router, Request, RequestHandler, Response, NextFunction, Express } from 'express';
+import { Router, Request, RequestHandler, Response as Response$1, NextFunction, Express } from 'express';
 export { Router } from 'express';
 import pg, { QueryResultRow, QueryResult, PoolClient, Pool } from 'pg';
 import { Server } from 'node:http';
@@ -231,10 +231,10 @@ interface JobDefinition {
     run: (ctx: JobContext) => Promise<void> | void;
 }
 declare function defineJob(name: string, run: (ctx: JobContext) => Promise<void> | void): JobDefinition;
-declare function requirePermission(...codes: string[]): (req: Request, res: Response, next: NextFunction) => void;
-declare function requireAuth(req: Request, res: Response, next: NextFunction): void;
-declare function requireWorkspace(req: Request, res: Response, next: NextFunction): void;
-declare function parseIdentity(req: Request, _res: Response, next: NextFunction): void;
+declare function requirePermission(...codes: string[]): (req: Request, res: Response$1, next: NextFunction) => void;
+declare function requireAuth(req: Request, res: Response$1, next: NextFunction): void;
+declare function requireWorkspace(req: Request, res: Response$1, next: NextFunction): void;
+declare function parseIdentity(req: Request, _res: Response$1, next: NextFunction): void;
 declare const IDENTITY_HEADER = "x-kserp-identity";
 declare const INTERNAL_SECRET_HEADER = "x-kserp-internal";
 declare const PROTOCOL_VERSION = 1;
@@ -310,7 +310,7 @@ interface TenantContext {
 }
 declare function runWithTenantContext<T>(ctx: TenantContext, fn: () => T): T;
 declare function applyTenantContext(client: PoolClient, ctx?: TenantContext | undefined): Promise<void>;
-declare function withTenantContext(req: Request, _res: Response, next: NextFunction): void;
+declare function withTenantContext(req: Request, _res: Response$1, next: NextFunction): void;
 type Engine = "postgres" | "sqlite";
 type ColumnKind = "id" | "string" | "text" | "int" | "bigint" | "float" | "decimal" | "boolean" | "timestamp" | "date" | "json" | "enum";
 type ColumnDefault = "now" | string | number | boolean | null;
@@ -405,9 +405,9 @@ interface MigrationOpts {
     useTransaction?: boolean;
 }
 declare function migration(name: string, up: (db: MigrationBuilder) => Promise<void>, opts?: MigrationOpts): Migration;
-declare function asyncHandler(fn: (req: Request, res: Response, next: NextFunction) => unknown | Promise<unknown>): RequestHandler;
+declare function asyncHandler(fn: (req: Request, res: Response$1, next: NextFunction) => unknown | Promise<unknown>): RequestHandler;
 declare function escapeLike(s: string): string;
-declare function checkProtocol(min?: number, max?: number): (req: Request, res: Response, next: NextFunction) => void;
+declare function checkProtocol(min?: number, max?: number): (req: Request, res: Response$1, next: NextFunction) => void;
 type ResourceColumns = Readonly<Record<string, ColumnDef>>;
 type IndexMember = string | {
     readonly ci: string;
@@ -669,6 +669,7 @@ type PluginServicesFactory = (ctx: PluginServerContext) => Record<string, Servic
 interface CreatePluginServerOptions {
     importMetaUrl: string;
     uiOnly?: boolean;
+    flows?: readonly unknown[];
     migrations?: boolean;
     settings?: boolean;
     assets?: boolean;
@@ -701,5 +702,84 @@ interface WsReceiverOptions {
     host?: string;
 }
 declare function mountWsReceiver(opts: WsReceiverOptions): WsServer | null;
-export { IDENTITY_HEADER, INTERNAL_SECRET_HEADER, MIGRATION_ADVISORY_LOCK_KEY, MigrationBuilder, PROTOCOL_VERSION, PluginUnavailableError, Types, applyTenantContext, asyncHandler, buildResourceRouter, buildResourceServices, callPlugin, checkInternalSecret, checkProtocol, compileCreateTable, composeWhere, createPlugin, createPluginServer, defineJob, defineResource, defineSchema, escapeLike, identityHeaderOf, indexExpr, loadMigrations, makeDataSurface, makeDatabaseService, migration, mountPluginServices, mountWsReceiver, parseIdentity, quoteIdent, readIdentity, requireAuth, requirePermission, requireWorkspace, resolveEngine, resourceMigrations, rollbackMigration, runMigrationList, runMigrations, runWithTenantContext, searchFragment, statusFilter, tenant, tryCallPlugin, verifyIdentity, withTenantContext };
-export type { AdditionalMount, AuthProvider, AuthProviderDecl, AuthService, AuthenticatedUser, BackfillOpts, ColumnDef, ColumnDefault, ColumnKind, ColumnOpts, CompileTableOpts, CoreServices, CreatePluginServerOptions, DataSurface, DecimalOpts, DefinedResource, Engine, EscapeHatch, FindOpts, ForwardedIdentity, Identity, IndexMember, IndexOpts, Logger, MemberDTO, Migration, MigrationContext, MigrationOpts, PermissionsService, PluginAsset, PluginAssets, PluginContext, PluginDb, PluginDefinition, PluginEvents, PluginInitInput, PluginInitOutput, PluginKernel, PluginManifest, PluginPeer, PluginRouterFactory, PluginRpc, PluginServerContext, PluginServerHandle, PluginServicesFactory, PluginSettings, PresignedAsset, ResourceColumns, ResourceCreateSpec, ResourceField, ResourceFields, ResourceFilter, ResourceIndex, ResourceListSpec, ResourcePagination, ResourceRouterDeps, ResourceSearch, ResourceService, ResourceSoftDelete, ResourceSort, ResourceSpec, ResourceUpdateSpec, RunMigrationsOptions, SchemaDef, SqlFragment, StringOpts, TableDef, TenantContext, TenantDb, WhereOpts, WorkspaceDTO, WsReceiverOptions };
+type FlowNodeKind = "data" | "trigger" | "modal" | "load" | "call" | "compute" | "condition" | "commit" | "emit" | "effect" | "terminal";
+interface FlowPort {
+    id: string;
+    to: string;
+    label?: string;
+}
+interface FlowNodeDef {
+    id: string;
+    kind: FlowNodeKind;
+    label: string;
+    detail?: string;
+    out?: FlowPort[];
+}
+interface FlowDefinition {
+    id: string;
+    title: string;
+    entry?: string;
+    nodes: FlowNodeDef[];
+}
+declare function edge(to: string, label?: string): FlowPort;
+declare function node(id: string, kind: FlowNodeKind, label: string, opts?: {
+    detail?: string;
+    out?: FlowPort[];
+}): FlowNodeDef;
+declare function defineFlow(def: FlowDefinition): FlowDefinition;
+interface FlowNode {
+    readonly id: string;
+    to(target: FlowNode, label?: string): FlowNode;
+}
+declare class FlowSteps {
+    readonly prefix: string;
+    readonly nodes: FlowNodeDef[];
+    constructor(prefix: string);
+    private make;
+    trigger(label: string): FlowNode;
+    data(label: string, detail?: string): FlowNode;
+    load(label: string, detail?: string): FlowNode;
+    modal(label: string): FlowNode;
+    call(target: string, label?: string): FlowNode;
+    compute(label: string): FlowNode;
+    condition(label: string): FlowNode;
+    commit(label: string, detail?: string): FlowNode;
+    emit(event: string): FlowNode;
+    effect(label: string): FlowNode;
+    terminal(label: string): FlowNode;
+}
+declare function buildFlow(id: string, title: string, build: (f: FlowSteps) => void): FlowDefinition;
+interface FlowContext {
+    state: Record<string, unknown>;
+    fetch: (url: string, init?: RequestInit) => Promise<Response>;
+    call?: (target: string, args?: unknown) => Promise<unknown>;
+    ui?: {
+        openModal?: (node: FlowNodeDef) => Promise<Record<string, unknown> | null>;
+        refresh?: () => void;
+        toast?: (msg: string) => void;
+        close?: () => void;
+        navigate?: (to: string) => void;
+    };
+}
+interface NodeExec {
+    request?: (ctx: FlowContext) => {
+        url: string;
+        method?: string;
+        body?: unknown;
+    };
+    when?: (ctx: FlowContext) => string | boolean;
+    compute?: (ctx: FlowContext) => unknown;
+    invoke?: {
+        target: string;
+        args?: (ctx: FlowContext) => unknown;
+    };
+    effect?: "refresh" | "toast" | "close" | "navigate";
+    arg?: string;
+}
+type ExecNode = FlowNodeDef & NodeExec;
+type ExecFlow = Omit<FlowDefinition, "nodes"> & {
+    nodes: ExecNode[];
+};
+declare function runFlow(flow: ExecFlow, startId: string, ctx: FlowContext): Promise<void>;
+export { FlowSteps, IDENTITY_HEADER, INTERNAL_SECRET_HEADER, MIGRATION_ADVISORY_LOCK_KEY, MigrationBuilder, PROTOCOL_VERSION, PluginUnavailableError, Types, applyTenantContext, asyncHandler, buildFlow, buildResourceRouter, buildResourceServices, callPlugin, checkInternalSecret, checkProtocol, compileCreateTable, composeWhere, createPlugin, createPluginServer, defineFlow, defineJob, defineResource, defineSchema, edge, escapeLike, identityHeaderOf, indexExpr, loadMigrations, makeDataSurface, makeDatabaseService, migration, mountPluginServices, mountWsReceiver, node, parseIdentity, quoteIdent, readIdentity, requireAuth, requirePermission, requireWorkspace, resolveEngine, resourceMigrations, rollbackMigration, runFlow, runMigrationList, runMigrations, runWithTenantContext, searchFragment, statusFilter, tenant, tryCallPlugin, verifyIdentity, withTenantContext };
+export type { AdditionalMount, AuthProvider, AuthProviderDecl, AuthService, AuthenticatedUser, BackfillOpts, ColumnDef, ColumnDefault, ColumnKind, ColumnOpts, CompileTableOpts, CoreServices, CreatePluginServerOptions, DataSurface, DecimalOpts, DefinedResource, Engine, EscapeHatch, ExecFlow, ExecNode, FindOpts, FlowContext, FlowDefinition, FlowNode, FlowNodeDef, FlowNodeKind, FlowPort, ForwardedIdentity, Identity, IndexMember, IndexOpts, Logger, MemberDTO, Migration, MigrationContext, MigrationOpts, NodeExec, PermissionsService, PluginAsset, PluginAssets, PluginContext, PluginDb, PluginDefinition, PluginEvents, PluginInitInput, PluginInitOutput, PluginKernel, PluginManifest, PluginPeer, PluginRouterFactory, PluginRpc, PluginServerContext, PluginServerHandle, PluginServicesFactory, PluginSettings, PresignedAsset, ResourceColumns, ResourceCreateSpec, ResourceField, ResourceFields, ResourceFilter, ResourceIndex, ResourceListSpec, ResourcePagination, ResourceRouterDeps, ResourceSearch, ResourceService, ResourceSoftDelete, ResourceSort, ResourceSpec, ResourceUpdateSpec, RunMigrationsOptions, SchemaDef, SqlFragment, StringOpts, TableDef, TenantContext, TenantDb, WhereOpts, WorkspaceDTO, WsReceiverOptions };