@swirls/sdk 0.0.11 → 0.0.12

package/README.md

@@ -34,6 +34,36 @@ The [`@swirls/sdk/form`](src/form/README.md) subpackage provides a form library
 import { useSwirlsFormAdapter } from '@swirls/sdk/form'
 ```
 
+### Graph Builder
+
+The [`@swirls/sdk/graph`](src/graph/README.md) subpackage lets you build and manipulate workflow graphs in code. Use a fluent API to add nodes and edges by name, then validate (DAG, single root), persist via the API with `save()`, or serialize with `toJSON()` for storage or version control. Dynamic values (e.g. LLM prompts, code transforms) use TypeScript function bodies with a `context` object; when you set `inputSchema` and `outputSchema` on nodes, `context.inputs` is typed for intellisense.
+
+```typescript
+import { Swirls } from '@swirls/sdk/client'
+import { GraphBuilder } from '@swirls/sdk/graph'
+
+const swirls = new Swirls({ apiKey: process.env.SWIRLS_API_KEY! })
+const graph = new GraphBuilder({ client: swirls.client })
+  .setName('my_workflow')
+  .setLabel('My Workflow')
+  .addNode('fetch', {
+    type: 'http',
+    label: 'Fetch',
+    config: { type: 'http', url: 'https://api.example.com/data', method: 'GET' },
+  })
+  .addNode('summarize', {
+    type: 'llm',
+    label: 'Summarize',
+    config: {
+      type: 'llm',
+      model: 'gpt-4o',
+      prompt: 'return `Summarize the following: ${context.inputs.fetch.output}`',
+    },
+  })
+  .addEdge({ source: 'fetch', target: 'summarize' })
+await graph.save({ projectId: '...' })
+```
+
 ## Installation
 
 ```sh
@@ -52,3 +82,4 @@ bun add @tanstack/react-query
 - [Client Documentation](src/client/README.md): API client and TanStack Query utils
 - [Config Documentation](src/config/README.md): Configuration reference
 - [Form Documentation](src/form/README.md): Complete guide to forms
+- [Graph Documentation](src/graph/README.md): Build and manipulate workflow graphs

package/dist/graph/index.d.ts

@@ -0,0 +1,263 @@
+import { NodeType, GraphNodeConfig, ReviewConfig, JsonSchema, Position } from '@swirls/core/schemas';
+
+/** Options for adding a node to a graph. Config is typed by node type. */
+type AddNodeOptions = {
+    type: NodeType;
+    label: string;
+    description?: string;
+    config: GraphNodeConfig;
+    reviewConfig?: ReviewConfig | null;
+    inputSchema?: JsonSchema | null;
+    outputSchema?: JsonSchema | null;
+    position?: Position;
+};
+/** Serialized node shape for toJSON/fromJSON. */
+type SerializedNode = {
+    id: string;
+    name: string;
+    label: string;
+    description?: string;
+    type: NodeType;
+    config: GraphNodeConfig;
+    reviewConfig?: ReviewConfig | null;
+    inputSchema?: JsonSchema | null;
+    outputSchema?: JsonSchema | null;
+    position?: Position;
+};
+/** Serialized edge shape for toJSON/fromJSON. */
+type SerializedEdge = {
+    id: string;
+    sourceNodeId: string;
+    targetNodeId: string;
+    label?: string | null;
+};
+/** Serialized graph shape for toJSON/fromJSON (no API-only fields). */
+type SerializedGraph = {
+    id: string;
+    name: string;
+    label: string;
+    description?: string | null;
+    projectId?: string;
+    folderId?: string | null;
+    nodes: SerializedNode[];
+    edges: SerializedEdge[];
+};
+/** Options for saving a graph to the Swirls API. */
+type SaveOptions = {
+    projectId: string;
+    folderId?: string | null;
+};
+/** Options for adding an edge by node names. */
+type AddEdgeOptions = {
+    source: string;
+    target: string;
+    label?: string | null;
+};
+/** Options for removing an edge by node names. */
+type RemoveEdgeOptions = {
+    source: string;
+    target: string;
+};
+/** Swirls client type: must have graphs.getGraph and graphs.syncGraph (and createGraph for new graphs). */
+type SwirlsGraphClient = {
+    graphs: {
+        getGraph: (input: {
+            input: {
+                id: string;
+            };
+        }) => Promise<{
+            id: string;
+            projectId: string;
+            folderId: string | null;
+            name: string;
+            label: string;
+            description: string | null;
+            nodes: Array<{
+                id: string;
+                graphId: string;
+                name: string;
+                label: string;
+                description: string | null;
+                type: string;
+                config: Record<string, unknown>;
+                reviewConfig: unknown;
+                position: {
+                    x: number;
+                    y: number;
+                } | null;
+                outputSchema: unknown;
+                inputSchema: unknown;
+            }>;
+            edges: Array<{
+                id: string;
+                graphId: string;
+                sourceNodeId: string;
+                targetNodeId: string;
+                label: string | null;
+            }>;
+        }>;
+        createGraph: (input: {
+            input: {
+                projectId: string;
+                folderId?: string | null;
+                name: string;
+                label: string;
+                description?: string;
+            };
+        }) => Promise<{
+            id: string;
+        }>;
+        syncGraph: (input: {
+            input: {
+                graphId: string;
+                nodes: Array<{
+                    id: string;
+                    name: string;
+                    label: string;
+                    description?: string;
+                    type: string;
+                    config: Record<string, unknown>;
+                    reviewConfig?: unknown;
+                    position?: {
+                        x: number;
+                        y: number;
+                    };
+                    outputSchema?: unknown;
+                    inputSchema?: unknown;
+                }>;
+                edges: Array<{
+                    id: string;
+                    sourceNodeId: string;
+                    targetNodeId: string;
+                    label?: string;
+                }>;
+            };
+        }) => Promise<{
+            id: string;
+            nodes: unknown[];
+            edges: unknown[];
+        }>;
+        executeGraph: (input: {
+            input: {
+                graphId: string;
+                input?: Record<string, unknown>;
+            };
+        }) => Promise<{
+            executionId: string;
+        }>;
+    };
+};
+
+type NodeRefUpdate = {
+    label?: string;
+    description?: string;
+    type?: NodeType;
+    config?: GraphNodeConfig;
+    reviewConfig?: ReviewConfig | null;
+    inputSchema?: JsonSchema | null;
+    outputSchema?: JsonSchema | null;
+    position?: Position;
+};
+/**
+ * Reference to a node within a graph. Created by GraphBuilder.addNode().
+ * incomingEdges/outgoingEdges are computed from the parent graph.
+ */
+declare class NodeRef {
+    readonly id: string;
+    readonly name: string;
+    label: string;
+    description: string | null;
+    type: NodeType;
+    config: GraphNodeConfig;
+    reviewConfig: ReviewConfig | null;
+    inputSchema: JsonSchema | null;
+    outputSchema: JsonSchema | null;
+    position: Position | null;
+    private getIncoming;
+    private getOutgoing;
+    constructor(data: SerializedNode, getIncoming: () => EdgeRef[], getOutgoing: () => EdgeRef[]);
+    get incomingEdges(): EdgeRef[];
+    get outgoingEdges(): EdgeRef[];
+    get isRootNode(): boolean;
+    update(options: NodeRefUpdate): this;
+    /** Serialize to plain object for toJSON/syncGraph. */
+    toJSON(): SerializedNode;
+}
+
+/**
+ * Reference to an edge within a graph. Created by GraphBuilder.addEdge().
+ * source and target resolve to NodeRefs from the parent graph.
+ */
+declare class EdgeRef {
+    readonly id: string;
+    readonly sourceNodeId: string;
+    readonly targetNodeId: string;
+    label: string | null;
+    private getSource;
+    private getTarget;
+    constructor(data: SerializedEdge, getSource: () => NodeRef | undefined, getTarget: () => NodeRef | undefined);
+    get source(): NodeRef | undefined;
+    get target(): NodeRef | undefined;
+    /** Serialize to plain object for toJSON/syncGraph. */
+    toJSON(): SerializedEdge;
+}
+
+/**
+ * Thrown when graph validation fails (cycles, multiple roots, invalid references, etc.).
+ */
+declare class GraphValidationError extends Error {
+    /** Machine-readable code for programmatic handling. */
+    readonly code: 'CYCLE_DETECTED' | 'NO_ROOT_NODE' | 'MULTIPLE_ROOT_NODES' | 'INVALID_SOURCE_NODE' | 'INVALID_TARGET_NODE' | 'SELF_LOOP' | 'DUPLICATE_NODE_NAME' | 'INVALID_NODE_NAME' | 'UNKNOWN';
+    /** Optional details (e.g. node names or IDs involved). */
+    readonly details?: Record<string, unknown>;
+    constructor(message: string, options?: {
+        code?: GraphValidationError['code'];
+        details?: Record<string, unknown>;
+    });
+}
+
+/**
+ * Builder for Swirls graphs. Build locally, then save() to the API or toJSON() for storage.
+ */
+declare class GraphBuilder {
+    id: string;
+    name: string;
+    label: string;
+    description: string | null;
+    private client;
+    private _nodesById;
+    private _nodesByName;
+    private _edgesById;
+    private _edges;
+    private _loadedFromApi;
+    constructor(options?: {
+        client?: SwirlsGraphClient;
+    });
+    setName(name: string): this;
+    setLabel(label: string): this;
+    setDescription(description: string | null): this;
+    getNode(name: string): NodeRef | undefined;
+    getNodeById(id: string): NodeRef | undefined;
+    private getEdgesByTargetId;
+    private getEdgesBySourceId;
+    addNode(name: string, options: AddNodeOptions): this;
+    private _addNodeRaw;
+    addEdge(options: AddEdgeOptions): this;
+    private _addEdgeRaw;
+    removeNode(name: string): this;
+    removeEdge(options: RemoveEdgeOptions): this;
+    get rootNode(): NodeRef | undefined;
+    get nodeList(): NodeRef[];
+    get edgeList(): EdgeRef[];
+    validate(): void;
+    save(options: SaveOptions): Promise<this>;
+    private _syncToApi;
+    saveExisting(_options: SaveOptions): Promise<this>;
+    execute(input?: Record<string, unknown>): Promise<string>;
+    toJSON(): SerializedGraph;
+    toMermaid(): string;
+    static fromJSON(json: string | SerializedGraph): GraphBuilder;
+    static fromAPI(client: SwirlsGraphClient, graphId: string): Promise<GraphBuilder>;
+}
+
+export { type AddEdgeOptions, type AddNodeOptions, EdgeRef, GraphBuilder, GraphValidationError, NodeRef, type NodeRefUpdate, type RemoveEdgeOptions, type SaveOptions, type SerializedEdge, type SerializedGraph, type SerializedNode, type SwirlsGraphClient };

package/dist/graph/index.js

@@ -0,0 +1,603 @@
+// src/graph/edge-ref.ts
+var EdgeRef = class {
+  id;
+  sourceNodeId;
+  targetNodeId;
+  label;
+  getSource;
+  getTarget;
+  constructor(data, getSource, getTarget) {
+    this.id = data.id;
+    this.sourceNodeId = data.sourceNodeId;
+    this.targetNodeId = data.targetNodeId;
+    this.label = data.label ?? null;
+    this.getSource = getSource;
+    this.getTarget = getTarget;
+  }
+  get source() {
+    return this.getSource();
+  }
+  get target() {
+    return this.getTarget();
+  }
+  /** Serialize to plain object for toJSON/syncGraph. */
+  toJSON() {
+    return {
+      id: this.id,
+      sourceNodeId: this.sourceNodeId,
+      targetNodeId: this.targetNodeId,
+      label: this.label ?? void 0
+    };
+  }
+};
+
+// src/graph/errors.ts
+var GraphValidationError = class extends Error {
+  /** Machine-readable code for programmatic handling. */
+  code;
+  /** Optional details (e.g. node names or IDs involved). */
+  details;
+  constructor(message, options) {
+    super(message);
+    this.name = "GraphValidationError";
+    this.code = options?.code ?? "UNKNOWN";
+    this.details = options?.details;
+  }
+};
+
+// src/graph/node-ref.ts
+var NodeRef = class {
+  id;
+  name;
+  label;
+  description;
+  type;
+  config;
+  reviewConfig;
+  inputSchema;
+  outputSchema;
+  position;
+  getIncoming;
+  getOutgoing;
+  constructor(data, getIncoming, getOutgoing) {
+    this.id = data.id;
+    this.name = data.name;
+    this.label = data.label;
+    this.description = data.description ?? null;
+    this.type = data.type;
+    this.config = { ...data.config };
+    this.reviewConfig = data.reviewConfig ?? null;
+    this.inputSchema = data.inputSchema ?? null;
+    this.outputSchema = data.outputSchema ?? null;
+    this.position = data.position ?? null;
+    this.getIncoming = getIncoming;
+    this.getOutgoing = getOutgoing;
+  }
+  get incomingEdges() {
+    return this.getIncoming();
+  }
+  get outgoingEdges() {
+    return this.getOutgoing();
+  }
+  get isRootNode() {
+    return this.incomingEdges.length === 0;
+  }
+  update(options) {
+    if (options.label !== void 0) {
+      this.label = options.label;
+    }
+    if (options.description !== void 0) {
+      this.description = options.description;
+    }
+    if (options.type !== void 0) {
+      this.type = options.type;
+    }
+    if (options.config !== void 0) {
+      this.config = { ...options.config };
+    }
+    if (options.reviewConfig !== void 0) {
+      this.reviewConfig = options.reviewConfig;
+    }
+    if (options.inputSchema !== void 0) {
+      this.inputSchema = options.inputSchema;
+    }
+    if (options.outputSchema !== void 0) {
+      this.outputSchema = options.outputSchema;
+    }
+    if (options.position !== void 0) {
+      this.position = options.position;
+    }
+    return this;
+  }
+  /** Serialize to plain object for toJSON/syncGraph. */
+  toJSON() {
+    return {
+      id: this.id,
+      name: this.name,
+      label: this.label,
+      description: this.description ?? void 0,
+      type: this.type,
+      config: this.config,
+      reviewConfig: this.reviewConfig ?? void 0,
+      inputSchema: this.inputSchema ?? void 0,
+      outputSchema: this.outputSchema ?? void 0,
+      position: this.position ?? void 0
+    };
+  }
+};
+
+// src/graph/utils.ts
+function mermaidSafeId(nameOrId) {
+  return nameOrId.replace(/[^a-zA-Z0-9_]/g, "_");
+}
+
+// src/graph/validation.ts
+function topologicalSort(nodes, edges) {
+  const nodeIds = new Set(nodes.map((n) => n.id));
+  const inDegree = /* @__PURE__ */ new Map();
+  const adjacentList = /* @__PURE__ */ new Map();
+  for (const node of nodes) {
+    inDegree.set(node.id, 0);
+    adjacentList.set(node.id, []);
+  }
+  for (const edge of edges) {
+    if (!nodeIds.has(edge.sourceNodeId)) {
+      throw new GraphValidationError(
+        `Edge references non-existent source node: ${edge.sourceNodeId}`,
+        {
+          code: "INVALID_SOURCE_NODE",
+          details: { sourceNodeId: edge.sourceNodeId }
+        }
+      );
+    }
+    if (!nodeIds.has(edge.targetNodeId)) {
+      throw new GraphValidationError(
+        `Edge references non-existent target node: ${edge.targetNodeId}`,
+        {
+          code: "INVALID_TARGET_NODE",
+          details: { targetNodeId: edge.targetNodeId }
+        }
+      );
+    }
+    if (edge.sourceNodeId === edge.targetNodeId) {
+      throw new GraphValidationError("Edge cannot connect a node to itself", {
+        code: "SELF_LOOP",
+        details: { nodeId: edge.sourceNodeId }
+      });
+    }
+    adjacentList.get(edge.sourceNodeId)?.push(edge.targetNodeId);
+    inDegree.set(edge.targetNodeId, (inDegree.get(edge.targetNodeId) ?? 0) + 1);
+  }
+  const queue = [];
+  for (const [nodeId, degree] of inDegree.entries()) {
+    if (degree === 0) {
+      queue.push(nodeId);
+    }
+  }
+  if (queue.length === 0) {
+    throw new GraphValidationError(
+      "Graph must have exactly one root node, but none were found.",
+      { code: "NO_ROOT_NODE" }
+    );
+  }
+  if (queue.length > 1) {
+    throw new GraphValidationError(
+      `Graph must have exactly one root node, but found ${queue.length}.`,
+      { code: "MULTIPLE_ROOT_NODES", details: { count: queue.length } }
+    );
+  }
+  const sorted = [];
+  while (queue.length > 0) {
+    const current = queue.shift();
+    if (current === void 0) {
+      break;
+    }
+    sorted.push(current);
+    const neighbors = adjacentList.get(current) ?? [];
+    for (const neighbor of neighbors) {
+      const newDegree = (inDegree.get(neighbor) ?? 0) - 1;
+      inDegree.set(neighbor, newDegree);
+      if (newDegree === 0) {
+        queue.push(neighbor);
+      }
+    }
+  }
+  if (sorted.length !== nodes.length) {
+    throw new GraphValidationError(
+      "Graph contains a cycle - DAG workflows cannot have cycles",
+      { code: "CYCLE_DETECTED" }
+    );
+  }
+  return sorted;
+}
+function validateNewEdge(nodes, edges, newEdge) {
+  const nodeIds = new Set(nodes.map((n) => n.id));
+  if (!nodeIds.has(newEdge.sourceNodeId)) {
+    throw new GraphValidationError(
+      `Source node does not exist: ${newEdge.sourceNodeId}`,
+      {
+        code: "INVALID_SOURCE_NODE",
+        details: { sourceNodeId: newEdge.sourceNodeId }
+      }
+    );
+  }
+  if (!nodeIds.has(newEdge.targetNodeId)) {
+    throw new GraphValidationError(
+      `Target node does not exist: ${newEdge.targetNodeId}`,
+      {
+        code: "INVALID_TARGET_NODE",
+        details: { targetNodeId: newEdge.targetNodeId }
+      }
+    );
+  }
+  if (newEdge.sourceNodeId === newEdge.targetNodeId) {
+    throw new GraphValidationError("Cannot create self-loop edge", {
+      code: "SELF_LOOP",
+      details: { nodeId: newEdge.sourceNodeId }
+    });
+  }
+  topologicalSort(nodes, [...edges, newEdge]);
+}
+var RESOURCE_NAME_REGEX = /^[a-zA-Z0-9_]+$/;
+function validateResourceName(name) {
+  if (!name || name.length === 0) {
+    throw new GraphValidationError("Name is required", {
+      code: "INVALID_NODE_NAME",
+      details: { name }
+    });
+  }
+  if (!RESOURCE_NAME_REGEX.test(name)) {
+    throw new GraphValidationError(
+      `Name must contain only letters, numbers, and underscores: ${name}`,
+      { code: "INVALID_NODE_NAME", details: { name } }
+    );
+  }
+}
+
+// src/graph/graph-builder.ts
+function randomId() {
+  return typeof crypto !== "undefined" && crypto.randomUUID ? crypto.randomUUID() : `gen-${Date.now()}-${Math.random().toString(36).slice(2, 11)}`;
+}
+var GraphBuilder = class _GraphBuilder {
+  id;
+  name;
+  label;
+  description;
+  client;
+  _nodesById = /* @__PURE__ */ new Map();
+  _nodesByName = /* @__PURE__ */ new Map();
+  _edgesById = /* @__PURE__ */ new Map();
+  _edges = [];
+  _loadedFromApi = false;
+  constructor(options) {
+    this.id = randomId();
+    this.name = "graph";
+    this.label = "Graph";
+    this.description = null;
+    this.client = options?.client ?? null;
+  }
+  setName(name) {
+    validateResourceName(name);
+    this.name = name;
+    return this;
+  }
+  setLabel(label) {
+    this.label = label;
+    return this;
+  }
+  setDescription(description) {
+    this.description = description;
+    return this;
+  }
+  getNode(name) {
+    return this._nodesByName.get(name);
+  }
+  getNodeById(id) {
+    return this._nodesById.get(id);
+  }
+  getEdgesByTargetId(id) {
+    return this._edges.filter((e) => e.targetNodeId === id);
+  }
+  getEdgesBySourceId(id) {
+    return this._edges.filter((e) => e.sourceNodeId === id);
+  }
+  addNode(name, options) {
+    validateResourceName(name);
+    if (this._nodesByName.has(name)) {
+      throw new GraphValidationError(`Duplicate node name: ${name}`, {
+        code: "DUPLICATE_NODE_NAME",
+        details: { name }
+      });
+    }
+    const config = options.config;
+    if (config?.type !== options.type) {
+      throw new GraphValidationError(
+        `Node config type "${String(config?.type)}" does not match options type "${options.type}"`,
+        { code: "INVALID_NODE_NAME", details: { name } }
+      );
+    }
+    const id = randomId();
+    const serialized = {
+      id,
+      name,
+      label: options.label,
+      description: options.description,
+      type: options.type,
+      config: options.config,
+      reviewConfig: options.reviewConfig ?? null,
+      inputSchema: options.inputSchema ?? null,
+      outputSchema: options.outputSchema ?? null,
+      position: options.position
+    };
+    this._addNodeRaw(serialized);
+    return this;
+  }
+  _addNodeRaw(data) {
+    const node = new NodeRef(
+      data,
+      () => this.getEdgesByTargetId(data.id),
+      () => this.getEdgesBySourceId(data.id)
+    );
+    this._nodesById.set(data.id, node);
+    this._nodesByName.set(data.name, node);
+  }
+  addEdge(options) {
+    const sourceNode = this._nodesByName.get(options.source);
+    const targetNode = this._nodesByName.get(options.target);
+    if (!sourceNode) {
+      throw new GraphValidationError(
+        `Source node not found: ${options.source}`,
+        {
+          code: "INVALID_SOURCE_NODE",
+          details: { source: options.source }
+        }
+      );
+    }
+    if (!targetNode) {
+      throw new GraphValidationError(
+        `Target node not found: ${options.target}`,
+        {
+          code: "INVALID_TARGET_NODE",
+          details: { target: options.target }
+        }
+      );
+    }
+    const validationNodes = Array.from(this._nodesById.values()).map((n) => ({
+      id: n.id
+    }));
+    const validationEdges = this._edges.map((e) => ({
+      sourceNodeId: e.sourceNodeId,
+      targetNodeId: e.targetNodeId
+    }));
+    const newEdge = {
+      sourceNodeId: sourceNode.id,
+      targetNodeId: targetNode.id
+    };
+    validateNewEdge(validationNodes, validationEdges, newEdge);
+    const id = randomId();
+    const serialized = {
+      id,
+      sourceNodeId: sourceNode.id,
+      targetNodeId: targetNode.id,
+      label: options.label ?? null
+    };
+    this._addEdgeRaw(serialized);
+    return this;
+  }
+  _addEdgeRaw(data) {
+    const edge = new EdgeRef(
+      data,
+      () => this.getNodeById(data.sourceNodeId),
+      () => this.getNodeById(data.targetNodeId)
+    );
+    this._edgesById.set(data.id, edge);
+    this._edges.push(edge);
+  }
+  removeNode(name) {
+    const node = this._nodesByName.get(name);
+    if (!node) {
+      return this;
+    }
+    const toRemove = this._edges.filter(
+      (e) => e.sourceNodeId === node.id || e.targetNodeId === node.id
+    );
+    for (const e of toRemove) {
+      this._edges = this._edges.filter((edge) => edge.id !== e.id);
+      this._edgesById.delete(e.id);
+    }
+    this._nodesById.delete(node.id);
+    this._nodesByName.delete(name);
+    return this;
+  }
+  removeEdge(options) {
+    const sourceNode = this._nodesByName.get(options.source);
+    const targetNode = this._nodesByName.get(options.target);
+    if (!sourceNode || !targetNode) {
+      return this;
+    }
+    const found = this._edges.find(
+      (e) => e.sourceNodeId === sourceNode.id && e.targetNodeId === targetNode.id
+    );
+    if (found) {
+      this._edges = this._edges.filter((edge) => edge.id !== found.id);
+      this._edgesById.delete(found.id);
+    }
+    return this;
+  }
+  get rootNode() {
+    const roots = this.nodeList.filter((n) => n.incomingEdges.length === 0);
+    return roots.length === 1 ? roots[0] : void 0;
+  }
+  get nodeList() {
+    return Array.from(this._nodesById.values());
+  }
+  get edgeList() {
+    return [...this._edges];
+  }
+  validate() {
+    const nodes = this.nodeList.map((n) => ({ id: n.id }));
+    const edges = this._edges.map((e) => ({
+      sourceNodeId: e.sourceNodeId,
+      targetNodeId: e.targetNodeId
+    }));
+    topologicalSort(nodes, edges);
+  }
+  async save(options) {
+    if (!this.client) {
+      throw new Error("Cannot save: no Swirls client provided");
+    }
+    this.validate();
+    if (!this._loadedFromApi) {
+      const created = await this.client.graphs.createGraph({
+        input: {
+          projectId: options.projectId,
+          folderId: options.folderId ?? null,
+          name: this.name,
+          label: this.label,
+          description: this.description ?? void 0
+        }
+      });
+      this.id = created.id;
+      this._loadedFromApi = true;
+    }
+    await this._syncToApi(this.id);
+    return this;
+  }
+  async _syncToApi(graphId) {
+    if (!this.client) {
+      return;
+    }
+    const nodes = this.nodeList.map((node) => {
+      const nodeJson = node.toJSON();
+      return {
+        id: nodeJson.id,
+        name: nodeJson.name,
+        label: nodeJson.label,
+        description: nodeJson.description,
+        type: nodeJson.type,
+        config: nodeJson.config,
+        reviewConfig: nodeJson.reviewConfig ?? void 0,
+        position: nodeJson.position,
+        outputSchema: nodeJson.outputSchema ?? void 0,
+        inputSchema: nodeJson.inputSchema ?? void 0
+      };
+    });
+    const edges = this._edges.map((e) => e.toJSON());
+    await this.client.graphs.syncGraph({
+      input: {
+        graphId,
+        nodes,
+        edges: edges.map((ed) => ({
+          id: ed.id,
+          sourceNodeId: ed.sourceNodeId,
+          targetNodeId: ed.targetNodeId,
+          label: ed.label ?? void 0
+        }))
+      }
+    });
+  }
+  async saveExisting(_options) {
+    if (!this.client) {
+      throw new Error("Cannot save: no Swirls client provided");
+    }
+    if (!this._loadedFromApi) {
+      throw new Error(
+        "saveExisting() can only be used for graphs loaded via fromAPI(). Use save() for new graphs."
+      );
+    }
+    this.validate();
+    await this._syncToApi(this.id);
+    return this;
+  }
+  async execute(input) {
+    if (!this.client) {
+      throw new Error("Cannot execute: no Swirls client provided");
+    }
+    this.validate();
+    const result = await this.client.graphs.executeGraph({
+      input: { graphId: this.id, input }
+    });
+    return result.executionId;
+  }
+  toJSON() {
+    return {
+      id: this.id,
+      name: this.name,
+      label: this.label,
+      description: this.description,
+      nodes: this.nodeList.map((n) => n.toJSON()),
+      edges: this._edges.map((e) => e.toJSON())
+    };
+  }
+  toMermaid() {
+    const lines = ["flowchart LR"];
+    const nodeIds = new Set(this.nodeList.map((n) => n.id));
+    const safeId = (id) => mermaidSafeId(this.getNodeById(id)?.name ?? id);
+    for (const node of this.nodeList) {
+      const sid = safeId(node.id);
+      lines.push(`  ${sid}["${node.label || node.name}"]`);
+    }
+    for (const edge of this._edges) {
+      if (nodeIds.has(edge.sourceNodeId) && nodeIds.has(edge.targetNodeId)) {
+        const from = safeId(edge.sourceNodeId);
+        const to = safeId(edge.targetNodeId);
+        const label = edge.label ? `|${edge.label}|` : "";
+        lines.push(`  ${from} -->${label} ${to}`);
+      }
+    }
+    return lines.join("\n");
+  }
+  static fromJSON(json) {
+    const data = typeof json === "string" ? JSON.parse(json) : json;
+    const g = new _GraphBuilder();
+    g.id = data.id;
+    g.name = data.name;
+    g.label = data.label;
+    g.description = data.description ?? null;
+    for (const node of data.nodes) {
+      g._addNodeRaw(node);
+    }
+    for (const edge of data.edges) {
+      g._addEdgeRaw(edge);
+    }
+    return g;
+  }
+  static async fromAPI(client, graphId) {
+    const res = await client.graphs.getGraph({ input: { id: graphId } });
+    const g = new _GraphBuilder({ client });
+    g.id = res.id;
+    g.name = res.name;
+    g.label = res.label;
+    g.description = res.description ?? null;
+    g._loadedFromApi = true;
+    for (const node of res.nodes) {
+      g._addNodeRaw({
+        id: node.id,
+        name: node.name,
+        label: node.label,
+        description: node.description ?? void 0,
+        type: node.type,
+        config: node.config,
+        reviewConfig: node.reviewConfig ?? void 0,
+        inputSchema: node.inputSchema ?? void 0,
+        outputSchema: node.outputSchema ?? void 0,
+        position: node.position ?? void 0
+      });
+    }
+    for (const edge of res.edges) {
+      g._addEdgeRaw({
+        id: edge.id,
+        sourceNodeId: edge.sourceNodeId,
+        targetNodeId: edge.targetNodeId,
+        label: edge.label ?? void 0
+      });
+    }
+    return g;
+  }
+};
+export {
+  EdgeRef,
+  GraphBuilder,
+  GraphValidationError,
+  NodeRef
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swirls/sdk",
-  "version": "0.0.11",
+  "version": "0.0.12",
   "description": "Swirls SDK",
   "author": {
     "name": "Swirls",
@@ -27,6 +27,11 @@
       "types": "./dist/config/config.d.ts",
       "import": "./dist/config/config.js",
       "default": "./dist/config/config.js"
+    },
+    "./graph": {
+      "types": "./dist/graph/index.d.ts",
+      "import": "./dist/graph/index.js",
+      "default": "./dist/graph/index.js"
     }
   },
   "files": [
@@ -48,6 +53,7 @@
   },
   "devDependencies": {
     "@swirls/core": "0.0.1",
+    "@types/bun": "1.3.9",
     "@types/node": "24.10.0",
     "@types/react": "19.2.6",
     "json-schema-to-zod": "2.7.0",