@dypai-ai/flow 0.1.0

package/flows/create-booking.flow.ts

@@ -0,0 +1,41 @@
+import { flow } from "../src/builder.ts";
+import { db, email } from "../src/nodes.ts";
+import { ref } from "../src/ref.ts";
+import { s } from "../src/schema.ts";
+
+export default flow("create-booking")
+  .sourceFile("dypai/flows/create-booking.flow.ts")
+  .http({ method: "POST", auth: "jwt", roles: ["authenticated"] })
+  .input({
+    name: s.string(),
+    email: s.email(),
+    date: s.date(),
+  })
+  .output({
+    booking: s.object({
+      id: s.string(),
+      name: s.string(),
+      email: s.email(),
+      date: s.date(),
+    }),
+  })
+  .step("booking", db.insert({
+    table: "public.bookings",
+    values: {
+      name: ref.input("name"),
+      email: ref.input("email"),
+      date: ref.input("date"),
+      user_id: ref.currentUserId(),
+    },
+    returning: ["id", "name", "email", "date"],
+  }))
+  .step("confirmation", email.send({
+    to: ref.input("email"),
+    template: "booking_confirmation",
+    variables: {
+      booking: ref.step("booking"),
+    },
+  }))
+  .return({
+    booking: ref.step("booking"),
+  });

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@dypai-ai/flow",
+  "version": "0.1.0",
+  "description": "Typed Flow DSL for authoring DYPAI backend endpoints in TypeScript",
+  "type": "module",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/DYPAI-SOLUTIONS/dypai.git"
+  },
+  "homepage": "https://dypai.ai",
+  "keywords": [
+    "dypai",
+    "flow",
+    "workflow",
+    "backend",
+    "endpoints"
+  ],
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src/",
+    "flows/",
+    "tsconfig.json"
+  ],
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "bunx tsc --noEmit"
+  },
+  "dependencies": {
+    "@dypai/workflow-core": "npm:@dypai-ai/workflow-core@^0.1.0"
+  },
+  "devDependencies": {
+    "@dypai/workflow-core": "file:../dypai-workflow-core",
+    "@types/bun": "^1.1.14",
+    "typescript": "^5.7.2"
+  }
+}

package/src/builder.ts

@@ -0,0 +1,144 @@
+import type {
+  AuthIR,
+  FlowDefinition,
+  JsonSchema,
+  RefIR,
+  ResponseIR,
+  TriggerIR,
+} from "@dypai/workflow-core";
+import { inferOutputSchemaFromReturns, objectSchemaFromFields, type SchemaField } from "./schema";
+import type { FlowStepCall } from "./types";
+
+type HttpOptions = {
+  method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+  auth: "public" | "jwt";
+  roles?: string[];
+};
+
+export class FlowBuilder {
+  private triggerValue?: TriggerIR;
+  private authValue?: AuthIR;
+  private inputValue?: JsonSchema;
+  private outputValue?: JsonSchema;
+  private responseValue: ResponseIR = { cardinality: "single" };
+  private stepsValue: FlowDefinition["steps"] = [];
+  private sourcePath?: string;
+  private endpointMeta: FlowDefinition["endpoint"];
+
+  constructor(private readonly flowName: string) {}
+
+  sourceFile(path: string): this {
+    this.sourcePath = path;
+    return this;
+  }
+
+  http(options: HttpOptions): this {
+    this.triggerValue = { type: "http", method: options.method };
+    this.authValue = options.auth === "public"
+      ? { mode: "public" }
+      : {
+          mode: "jwt",
+          allowedRoles: options.roles !== undefined ? options.roles : [],
+        };
+    return this;
+  }
+
+  description(text: string): this {
+    this.endpointMeta = { ...(this.endpointMeta || {}), description: text };
+    return this;
+  }
+
+  tool(options?: { description?: string }): this {
+    this.endpointMeta = {
+      ...(this.endpointMeta || {}),
+      isTool: true,
+      ...(options?.description ? { toolDescription: options.description } : {}),
+    };
+    return this;
+  }
+
+  input(fields: Record<string, SchemaField>): this {
+    this.inputValue = objectSchemaFromFields(fields);
+    return this;
+  }
+
+  output(fields: Record<string, SchemaField>): this {
+    this.outputValue = objectSchemaFromFields(fields);
+    return this;
+  }
+
+  response(cardinality: ResponseIR["cardinality"] | "array"): this {
+    this.responseValue = { cardinality: cardinality === "array" ? "many" : cardinality };
+    return this;
+  }
+
+  step(id: string, stepCall: FlowStepCall): this {
+    this.stepsValue.push({
+      id,
+      call: stepCall.call,
+      config: stepCall.config,
+      ...(this.sourcePath ? {
+        source: {
+          file: this.sourcePath,
+          stepId: id,
+        },
+      } : {}),
+    });
+    return this;
+  }
+
+  return(returns: Record<string, RefIR>): FlowDefinition {
+    return this.build(returns);
+  }
+
+  build(returns?: Record<string, RefIR>): FlowDefinition {
+    if (!this.triggerValue || !this.authValue) {
+      throw new Error(`Flow '${this.flowName}' must declare .http(...) before building.`);
+    }
+    if (!this.inputValue) {
+      throw new Error(`Flow '${this.flowName}' must declare .input(...) before building.`);
+    }
+    if (!returns || !Object.keys(returns).length) {
+      throw new Error(`Flow '${this.flowName}' must declare .return({...}).`);
+    }
+    if (!this.stepsValue.length) {
+      throw new Error(`Flow '${this.flowName}' must declare at least one .step(...).`);
+    }
+
+    const outputSchema = this.outputValue ?? inferOutputSchemaFromReturns(returns);
+    const edges: Array<{ from: string; to: string }> = [];
+    if (this.stepsValue.length) {
+      edges.push({ from: "$trigger", to: this.stepsValue[0].id });
+      for (let i = 0; i < this.stepsValue.length - 1; i += 1) {
+        edges.push({ from: this.stepsValue[i].id, to: this.stepsValue[i + 1].id });
+      }
+      edges.push({ from: this.stepsValue[this.stepsValue.length - 1].id, to: "return" });
+    }
+
+    return {
+      name: this.flowName,
+      ...(this.sourcePath ? {
+        source: {
+          kind: "flow-ts",
+          file: this.sourcePath,
+        },
+      } : {}),
+      ...(this.endpointMeta ? { endpoint: this.endpointMeta } : {}),
+      trigger: this.triggerValue,
+      auth: this.authValue,
+      input: this.inputValue,
+      output: outputSchema,
+      response: this.responseValue,
+      steps: this.stepsValue,
+      returns,
+      edges,
+    };
+  }
+}
+
+export function flow(name: string): FlowBuilder {
+  if (!/^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/.test(name)) {
+    throw new Error(`Flow name '${name}' must be a kebab-case slug.`);
+  }
+  return new FlowBuilder(name);
+}

package/src/capabilities.test.ts

@@ -0,0 +1,69 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, test } from "bun:test";
+import type { CapabilityCatalog } from "@dypai/workflow-core";
+import {
+  capability,
+  compileFlowDefinition,
+  dypai,
+  flow,
+  generateCapabilityWrappersSource,
+  ref,
+  s,
+} from "./index";
+
+const fixturePath = join(
+  dirname(fileURLToPath(import.meta.url)),
+  "..",
+  "..",
+  "dypai-workflow-core",
+  "fixtures",
+  "capability-catalog.json",
+);
+const fixtureCatalog = JSON.parse(readFileSync(fixturePath, "utf-8")) as CapabilityCatalog;
+
+describe("@dypai/flow dynamic capabilities", () => {
+  test("capability() emits grouped calls", () => {
+    expect(capability("stripe.checkout", "createSession", { price_id: "price_123" })).toEqual({
+      call: "stripe.checkout.createSession",
+      config: { price_id: "price_123" },
+    });
+  });
+
+  test("generates wrapper source from catalog fixture", () => {
+    const source = generateCapabilityWrappersSource(fixtureCatalog);
+    expect(source).toContain('capability("stripe.checkout", "createSession", config)');
+    expect(source).toContain('capability("google.sheets", "readRows", config)');
+  });
+
+  test("compiles grouped flow definition with catalog fixture", () => {
+    const definition = flow("checkout-session")
+      .http({ method: "POST", auth: "public" })
+      .input({ priceId: s.string() })
+      .step("checkout", capability("stripe.checkout", "createSession", {
+        mode: "payment",
+        price_id: ref.input("priceId"),
+        success_url: "https://example.com/success",
+        cancel_url: "https://example.com/cancel",
+      }))
+      .step("sheet", capability("google.sheets", "readRows", {
+        spreadsheet_id: "sheet_123",
+      }))
+      .return({
+        checkout: ref.step("checkout"),
+        rows: ref.step("sheet", "rows"),
+      });
+
+    const compiled = compileFlowDefinition(definition, { capabilityCatalog: fixtureCatalog });
+    expect(compiled.ok).toBe(true);
+    expect(compiled.workflowCode?.nodes.some((node) =>
+      node.node_type === "stripe"
+      && node.parameters.operation === "stripe_create_checkout_session",
+    )).toBe(true);
+  });
+
+  test("legacy db helper still works", () => {
+    expect(dypai.db.query({ sql: "SELECT 1" }).call).toBe("dypai.db.query");
+  });
+});

package/src/compiler.ts

@@ -0,0 +1,147 @@
+import {
+  flowDefinitionToIr,
+  irToWorkflowCodeV2,
+  type CapabilityCatalog,
+  type FlowDefinition,
+  type IRDiagnostic,
+  type WorkflowIR,
+  validateWorkflowIR,
+} from "@dypai/workflow-core";
+import { createHash } from "node:crypto";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import type { CompileFlowResult, FlowCompileDiagnostic } from "./types";
+
+const DEFAULT_COMPILE_TIMEOUT_MS = 5_000;
+const FLOW_PACKAGE_SRC = fileURLToPath(new URL(".", import.meta.url));
+const FLOW_COMPILE_CACHE_DIR = fileURLToPath(new URL("../.flow-compile-cache", import.meta.url));
+
+async function materializeFlowFileForImport(sourcePath: string): Promise<string> {
+  const raw = await readFile(sourcePath, "utf-8");
+  if (!raw.includes("@dypai/flow")) {
+    return sourcePath;
+  }
+
+  const flowEntry = join(FLOW_PACKAGE_SRC, "index.ts").replace(/\\/g, "/");
+  const rewritten = raw.replace(/from\s+["']@dypai\/flow["']/g, `from "${flowEntry}"`);
+  const cacheKey = createHash("sha256").update(`${sourcePath}\0${rewritten}`).digest("hex");
+  await mkdir(FLOW_COMPILE_CACHE_DIR, { recursive: true });
+  const cachePath = join(FLOW_COMPILE_CACHE_DIR, `${cacheKey}.flow.ts`);
+  await writeFile(cachePath, rewritten);
+  return cachePath;
+}
+
+function mapDiagnostic(item: IRDiagnostic): FlowCompileDiagnostic {
+  return {
+    severity: item.severity,
+    rule: item.rule,
+    message: item.message,
+    fixHint: item.fixHint,
+    file: item.location?.file,
+  };
+}
+
+function isFlowDefinition(value: unknown): value is FlowDefinition {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const candidate = value as FlowDefinition;
+  return typeof candidate.name === "string"
+    && Array.isArray(candidate.steps)
+    && candidate.input !== undefined
+    && candidate.output !== undefined
+    && candidate.returns !== undefined;
+}
+
+export function compileFlowDefinition(
+  definition: FlowDefinition,
+  options: { adapt?: boolean; capabilityCatalog?: CapabilityCatalog } = {},
+): CompileFlowResult {
+  const diagnostics: FlowCompileDiagnostic[] = [];
+  const compileContext = options.capabilityCatalog
+    ? { capabilityCatalog: options.capabilityCatalog }
+    : {};
+  const workflow = flowDefinitionToIr(definition, compileContext);
+  const validation = validateWorkflowIR(workflow, {
+    capabilityCatalog: options.capabilityCatalog,
+  });
+  diagnostics.push(...validation.diagnostics.map(mapDiagnostic));
+
+  if (!validation.ok) {
+    return { ok: false, definition, workflow, diagnostics };
+  }
+
+  if (options.adapt === false) {
+    return { ok: true, definition, workflow, diagnostics };
+  }
+
+  const adapted = irToWorkflowCodeV2(workflow, {
+    capabilityCatalog: options.capabilityCatalog,
+  });
+  diagnostics.push(...adapted.diagnostics.map(mapDiagnostic));
+  if (!adapted.ok || !adapted.value) {
+    return { ok: false, definition, workflow, diagnostics };
+  }
+
+  return {
+    ok: true,
+    definition,
+    workflow,
+    workflowCode: adapted.value,
+    diagnostics,
+  };
+}
+
+async function importFlowModule(filePath: string, timeoutMs: number): Promise<unknown> {
+  const url = `${pathToFileURL(filePath).href}?flow-compile=${Date.now()}`;
+  const imported = Promise.resolve(import(url));
+  const timeout = new Promise<never>((_, reject) => {
+    setTimeout(() => reject(new Error(`Flow compile timed out after ${timeoutMs}ms.`)), timeoutMs);
+  });
+  return Promise.race([imported, timeout]);
+}
+
+export async function compileFlowFile(
+  filePath: string,
+  options: { timeoutMs?: number; adapt?: boolean; capabilityCatalog?: CapabilityCatalog } = {},
+): Promise<CompileFlowResult> {
+  const diagnostics: FlowCompileDiagnostic[] = [];
+  const timeoutMs = options.timeoutMs ?? DEFAULT_COMPILE_TIMEOUT_MS;
+
+  try {
+    const resolvedPath = await materializeFlowFileForImport(filePath);
+    const mod = await importFlowModule(resolvedPath, timeoutMs) as { default?: unknown };
+    const definition = mod.default;
+    if (!isFlowDefinition(definition)) {
+      diagnostics.push({
+        severity: "error",
+        rule: "flow_invalid_default_export",
+        message: `Flow file '${filePath}' must default-export a FlowDefinition from flow(...).return(...).`,
+        file: filePath,
+        fixHint: "Use export default flow(\"my-endpoint\").http(...).input(...).step(...).return(...).",
+      });
+      return { ok: false, diagnostics };
+    }
+
+    const withSource: FlowDefinition = {
+      ...definition,
+      source: definition.source ?? { kind: "flow-ts", file: filePath },
+    };
+
+    return compileFlowDefinition(withSource, {
+      adapt: options.adapt,
+      capabilityCatalog: options.capabilityCatalog,
+    });
+  } catch (error) {
+    diagnostics.push({
+      severity: "error",
+      rule: "flow_compile_failed",
+      message: error instanceof Error ? error.message : "Failed to compile flow file.",
+      file: filePath,
+    });
+    return { ok: false, diagnostics };
+  }
+}
+
+export function compileFlowDefinitionToIr(definition: FlowDefinition): WorkflowIR {
+  return flowDefinitionToIr(definition);
+}

package/src/flow.test.ts

@@ -0,0 +1,134 @@
+import { mkdtemp, writeFile, rm } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { tmpdir } from "node:os";
+import { fileURLToPath } from "node:url";
+import { describe, expect, test } from "bun:test";
+import {
+  compileFlowDefinition,
+  compileFlowFile,
+  db,
+  email,
+  flow,
+  ref,
+  s,
+} from "./index";
+
+const demoFlowPath = join(
+  dirname(fileURLToPath(import.meta.url)),
+  "..",
+  "flows",
+  "create-booking.flow.ts",
+);
+
+describe("@dypai/flow schema helpers", () => {
+  test("s helpers produce JSON Schema fragments", () => {
+    expect(s.string()).toEqual({ type: "string" });
+    expect(s.email()).toEqual({ type: "string", format: "email" });
+    expect(s.date()).toEqual({ type: "string", format: "date" });
+    expect(s.optional(s.string())).toEqual({ type: "string", optional: true });
+  });
+});
+
+describe("@dypai/flow ref helpers", () => {
+  test("ref helpers produce canonical RefIR", () => {
+    expect(ref.input("email")).toEqual({ kind: "input", path: ["email"] });
+    expect(ref.currentUserId()).toEqual({ kind: "currentUserId" });
+    expect(ref.step("booking", "id")).toEqual({ kind: "step", stepId: "booking", path: ["id"] });
+    expect(ref.literal(true)).toEqual({ kind: "literal", value: true });
+  });
+});
+
+describe("flow() builder", () => {
+  test("produces FlowDefinition with mapped node calls", () => {
+    const definition = flow("create-booking")
+      .http({ method: "POST", auth: "jwt", roles: ["authenticated"] })
+      .input({
+        name: s.string(),
+        email: s.email(),
+        date: s.date(),
+      })
+      .step("booking", db.insert({
+        table: "public.bookings",
+        values: {
+          name: ref.input("name"),
+          email: ref.input("email"),
+          date: ref.input("date"),
+          user_id: ref.currentUserId(),
+        },
+      }))
+      .step("confirmation", email.send({
+        to: ref.input("email"),
+        template: "booking_confirmation",
+        body: "fallback",
+      }))
+      .return({
+        booking: ref.step("booking"),
+      });
+
+    expect(definition.name).toBe("create-booking");
+    expect(definition.steps[0]?.call).toBe("dypai.db.insert");
+    expect(definition.steps[1]?.call).toBe("dypai.email.send");
+    expect(definition.auth).toEqual({ mode: "jwt", allowedRoles: ["authenticated"] });
+  });
+
+  test("jwt without explicit roles defaults to empty allowed_roles", () => {
+    const definition = flow("open-dashboard")
+      .http({ method: "GET", auth: "jwt" })
+      .input({ _unused: s.optional(s.string()) })
+      .step("main", db.query({ sql: "SELECT 1" }))
+      .return({ data: ref.step("main") });
+
+    expect(definition.auth).toEqual({ mode: "jwt", allowedRoles: [] });
+  });
+
+  test("response alias array maps to many", () => {
+    const definition = flow("weekly-stats")
+      .http({ method: "GET", auth: "jwt" })
+      .response("array")
+      .input({ _unused: s.optional(s.string()) })
+      .step("main", db.query({ sql: "SELECT 1" }))
+      .return({ data: ref.step("main") });
+
+    expect(definition.response).toEqual({ cardinality: "many" });
+  });
+});
+
+describe("flow compiler", () => {
+  test("compiles create-booking.flow.ts to valid WorkflowIR and workflow_code", async () => {
+    const compiled = await compileFlowFile(demoFlowPath);
+    expect(compiled.ok).toBe(true);
+    expect(compiled.definition?.name).toBe("create-booking");
+    expect(compiled.workflow?.steps.some((step) => step.node === "dypai.db" && step.operation === "insert")).toBe(true);
+    expect(compiled.workflow?.steps.some((step) => step.node === "dypai.email" && step.operation === "send")).toBe(true);
+    expect(compiled.workflowCode?.nodes.some((node) => node.node_type === "dypai_database")).toBe(true);
+    expect(compiled.workflowCode?.nodes.some((node) => node.node_type === "resend")).toBe(true);
+    expect(compiled.workflowCode?.nodes.some((node) => node.node_type === "set_fields" && node.is_return)).toBe(true);
+  });
+
+  test("returns actionable diagnostics for invalid flow files", async () => {
+    const root = await mkdtemp(join(tmpdir(), "dypai-flow-invalid-"));
+    const badPath = join(root, "bad.flow.ts");
+    await writeFile(badPath, "export default { name: 'nope' };\n");
+
+    try {
+      const compiled = await compileFlowFile(badPath);
+      expect(compiled.ok).toBe(false);
+      expect(compiled.diagnostics.some((item) => item.rule === "flow_invalid_default_export")).toBe(true);
+    } finally {
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+
+  test("compileFlowDefinition adapts IR without YAML", () => {
+    const definition = flow("ping")
+      .http({ method: "GET", auth: "public" })
+      .input({ ok: s.optional(s.boolean()) })
+      .step("noop", db.query({ sql: "SELECT 1 AS ok" }))
+      .return({ ok: ref.literal(true) });
+
+    const compiled = compileFlowDefinition(definition);
+    expect(compiled.ok).toBe(true);
+    expect(compiled.workflow?.version).toBe("workflow-ir.v1");
+    expect(compiled.workflowCode?.schema_version).toBe("2.0");
+  });
+});

package/src/generateCapabilityWrappers.ts

@@ -0,0 +1,38 @@
+import type { CapabilityCatalog } from "@dypai/workflow-core";
+
+export function generateCapabilityWrappersSource(catalog: CapabilityCatalog): string {
+  const lines = [
+    "// Auto-generated from dypai/capability-catalog.json. Do not edit by hand.",
+    'import { capability } from "@dypai/flow";',
+    "",
+  ];
+
+  const namespaces = new Map<string, Map<string, Array<{ operation: string; groupId: string }>>>();
+
+  for (const group of catalog.groups) {
+    const resourceMap = namespaces.get(group.namespace) ?? new Map();
+    namespaces.set(group.namespace, resourceMap);
+    const operations = resourceMap.get(group.resource) ?? [];
+    resourceMap.set(group.resource, operations);
+    for (const operation of group.operations) {
+      operations.push({ operation: operation.operation, groupId: group.id });
+    }
+  }
+
+  for (const [namespace, resources] of namespaces) {
+    lines.push(`export const ${namespace} = {`);
+    for (const [resource, operations] of resources) {
+      lines.push(`  ${resource}: {`);
+      for (const item of operations) {
+        lines.push(`    ${item.operation}(config: Record<string, unknown>) {`);
+        lines.push(`      return capability("${item.groupId}", "${item.operation}", config);`);
+        lines.push("    },");
+      }
+      lines.push("  },");
+    }
+    lines.push("};");
+    lines.push("");
+  }
+
+  return `${lines.join("\n").trimEnd()}\n`;
+}

package/src/index.ts

@@ -0,0 +1,14 @@
+export { flow, FlowBuilder } from "./builder";
+export { compileFlowDefinition, compileFlowDefinitionToIr, compileFlowFile } from "./compiler";
+export { capability, db, email, dypai } from "./nodes";
+export { generateCapabilityWrappersSource } from "./generateCapabilityWrappers";
+export { ref } from "./ref";
+export { inferOutputSchemaFromReturns, objectSchemaFromFields, s, type SchemaField } from "./schema";
+export type { CompileFlowResult, FlowCompileDiagnostic, FlowStepCall } from "./types";
+
+export type {
+  CapabilityCatalog,
+  FlowDefinition,
+  FlowStepDefinition,
+  WorkflowIR,
+} from "@dypai/workflow-core";

package/src/nodes.ts

@@ -0,0 +1,62 @@
+export type { FlowStepCall } from "./types";
+
+export function capability(
+  groupId: string,
+  operation: string,
+  config: Record<string, unknown>,
+): import("./types").FlowStepCall {
+  return {
+    call: `${groupId}.${operation}`,
+    config,
+  };
+}
+
+export const db = {
+  query(config: { sql: string; params?: Record<string, unknown> }) {
+    return capability("dypai.db", "query", config);
+  },
+  insert(config: { table: string; values: Record<string, unknown>; returning?: string[] }) {
+    return capability("dypai.db", "insert", config);
+  },
+  update(config: {
+    table: string;
+    where: Record<string, unknown>;
+    set: Record<string, unknown>;
+    returning?: string[];
+  }) {
+    return capability("dypai.db", "update", config);
+  },
+  list(config: {
+    table: string;
+    where?: Record<string, unknown>;
+    orderBy?: string;
+    limit?: unknown;
+    offset?: unknown;
+  }) {
+    return capability("dypai.db", "list", config);
+  },
+};
+
+export const email = {
+  send(config: {
+    to: unknown;
+    subject?: string;
+    body?: string;
+    template?: string;
+    variables?: Record<string, unknown>;
+    data?: Record<string, unknown>;
+  }) {
+    const { data, variables, ...rest } = config;
+    return capability("dypai.email", "send", {
+      ...rest,
+      ...(variables ? { variables } : {}),
+      ...(data ? { variables: data } : {}),
+    });
+  },
+};
+
+export const dypai = {
+  db,
+  email,
+  capability,
+};

package/src/ref.ts

@@ -0,0 +1,27 @@
+import type { RefIR } from "@dypai/workflow-core";
+
+export const ref = {
+  input(key: string, ...path: string[]): RefIR {
+    return { kind: "input", path: [key, ...path] };
+  },
+
+  currentUserId(): RefIR {
+    return { kind: "currentUserId" };
+  },
+
+  step(stepId: string, ...path: string[]): RefIR {
+    return path.length
+      ? { kind: "step", stepId, path }
+      : { kind: "step", stepId };
+  },
+
+  literal(value: unknown): RefIR {
+    return { kind: "literal", value };
+  },
+
+  env(name: string): RefIR {
+    return { kind: "env", name };
+  },
+};
+
+export type { RefIR };

package/src/schema.ts

@@ -0,0 +1,100 @@
+import type { JsonSchema } from "@dypai/workflow-core";
+
+export type SchemaField = JsonSchema & {
+  optional?: boolean;
+};
+
+function isSchemaField(value: unknown): value is SchemaField {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+export function objectSchemaFromFields(fields: Record<string, SchemaField>): JsonSchema {
+  const properties: Record<string, JsonSchema> = {};
+  const required: string[] = [];
+
+  for (const [key, field] of Object.entries(fields)) {
+    const { optional, ...schema } = field;
+    properties[key] = schema;
+    if (!optional) required.push(key);
+  }
+
+  return {
+    type: "object",
+    additionalProperties: false,
+    ...(required.length ? { required } : {}),
+    properties,
+  };
+}
+
+export const s = {
+  string(options?: { format?: string; minLength?: number }): SchemaField {
+    return {
+      type: "string",
+      ...(options?.format ? { format: options.format } : {}),
+      ...(options?.minLength ? { minLength: options.minLength } : {}),
+    };
+  },
+
+  email(): SchemaField {
+    return { type: "string", format: "email" };
+  },
+
+  number(): SchemaField {
+    return { type: "number" };
+  },
+
+  integer(): SchemaField {
+    return { type: "integer" };
+  },
+
+  boolean(): SchemaField {
+    return { type: "boolean" };
+  },
+
+  date(): SchemaField {
+    return { type: "string", format: "date" };
+  },
+
+  optional(field: SchemaField): SchemaField {
+    return { ...field, optional: true };
+  },
+
+  array(items: SchemaField): SchemaField {
+    const { optional, ...itemSchema } = items;
+    return {
+      type: "array",
+      items: itemSchema,
+      ...(optional ? { optional: true } : {}),
+    };
+  },
+
+  object(properties: Record<string, SchemaField>, options?: { required?: string[] }): SchemaField {
+    const schema = objectSchemaFromFields(properties);
+    if (options?.required) {
+      schema.required = options.required;
+    }
+    return schema;
+  },
+
+  uuid(): SchemaField {
+    return { type: "string", format: "uuid" };
+  },
+};
+
+export function inferOutputSchemaFromReturns(
+  returns: Record<string, unknown>,
+): JsonSchema {
+  const properties: Record<string, JsonSchema> = {};
+  for (const key of Object.keys(returns)) {
+    properties[key] = { type: "object" };
+  }
+  return {
+    type: "object",
+    additionalProperties: false,
+    properties,
+  };
+}
+
+export function isSchemaFieldValue(value: unknown): value is SchemaField {
+  return isSchemaField(value);
+}

package/src/types.ts

@@ -0,0 +1,20 @@
+export type FlowStepCall = {
+  call: string;
+  config: Record<string, unknown>;
+};
+
+export type FlowCompileDiagnostic = {
+  severity: "error" | "warn";
+  rule: string;
+  message: string;
+  file?: string;
+  fixHint?: string;
+};
+
+export type CompileFlowResult = {
+  ok: boolean;
+  definition?: import("@dypai/workflow-core").FlowDefinition;
+  workflow?: import("@dypai/workflow-core").WorkflowIR;
+  workflowCode?: import("@dypai/workflow-core").WorkflowCodeV2;
+  diagnostics: FlowCompileDiagnostic[];
+};

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "allowImportingTsExtensions": true,
+    "types": ["bun"]
+  },
+  "include": ["src/**/*.ts", "flows/**/*.ts"]
+}