@startsimpli/api 0.5.21 → 0.5.22

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/api",
-  "version": "0.5.21",
+  "version": "0.5.22",
   "description": "Type-safe Django REST API client for StartSimpli apps",
   "main": "./src/index.ts",
   "types": "./src/index.ts",

package/src/index.ts

@@ -18,6 +18,21 @@ export { ContactsApi } from './lib/contacts-api';
 export { OrganizationsApi } from './lib/organizations-api';
 export { EntitiesApi } from './lib/entities-api';
 export { WorkflowsApi } from './lib/workflows-api';
+export type {
+  Workflow,
+  WorkflowNode,
+  WorkflowInput,
+  WorkflowListParams,
+  NodeTypeDef,
+  NodeStatus,
+  RunStatus,
+  ExecutionMode,
+  WorkflowExecution,
+  WorkflowNodeExecution,
+  WorkflowExecutionDetail,
+  ExecuteWorkflowResponse,
+  ExecutionListParams,
+} from './lib/workflows-api';
 export { MessagesApi } from './lib/messages-api';
 export type { Message, MessageStatus as MessageApiStatus, MessageRecipient, MessagingChannel as MessagingChannelType, MessageFilters, CreateMessageInput, ScheduleMessageInput, SendTestInput } from './lib/messages-api';
 export { calculateStatsFromMessages } from './lib/message-stats';
@@ -164,6 +179,7 @@ import { TargetListsApi } from './lib/target-lists-api';
 import { MessageTemplatesApi } from './lib/message-templates-api';
 import { MarketsApi } from './lib/markets-api';
 import { VaultApi } from './lib/vault-api';
+import { PresentationsApi } from './lib/presentations-api';
 import { CompaniesApi } from './lib/companies-api';
 import { TeamsApi } from './lib/teams-api';
 import { TeamInvitationsApi } from './lib/team-invitations-api';
@@ -193,6 +209,7 @@ export function createStartSimpliApi(config: ApiClientConfig = {}) {
     messageTemplates: new MessageTemplatesApi(client),
     markets: new MarketsApi(client),
     vault: new VaultApi(client),
+    presentations: new PresentationsApi(client),
     companies: new CompaniesApi(client),
     teams: new TeamsApi(client),
     teamInvitations: new TeamInvitationsApi(client),
@@ -222,6 +239,23 @@ export type {
   VaultListParams,
 } from './lib/vault-api';
 
+// Presentations API
+export { PresentationsApi } from './lib/presentations-api';
+export type {
+  Deck,
+  DeckInput,
+  DeckStatus,
+  DeckListParams,
+  DeckGenerationStatus,
+  GenerateDeckInput,
+  Slide,
+  SlideInput,
+  SlideStatus,
+  RegenerateSlideInput,
+  RenderMode,
+  CompileResult,
+} from './lib/presentations-api';
+
 // Markets API
 export { MarketsApi } from './lib/markets-api';
 export type {

package/src/lib/presentations-api.test.ts

@@ -0,0 +1,104 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { PresentationsApi } from './presentations-api';
+
+function makeApi() {
+  const fetch = { get: vi.fn(), post: vi.fn(), patch: vi.fn(), delete: vi.fn() };
+  const api = new PresentationsApi({ fetch } as never);
+  return { api, fetch };
+}
+
+describe('PresentationsApi', () => {
+  let api: PresentationsApi;
+  let fetch: { get: ReturnType<typeof vi.fn>; post: ReturnType<typeof vi.fn>; patch: ReturnType<typeof vi.fn>; delete: ReturnType<typeof vi.fn> };
+
+  beforeEach(() => {
+    ({ api, fetch } = makeApi());
+  });
+
+  it('listDecks hits the decks endpoint with params', async () => {
+    fetch.get.mockResolvedValue({ results: [], count: 0 });
+    await api.listDecks({ page: 2 });
+    expect(fetch.get).toHaveBeenCalledWith('api/v1/presentations/decks', { params: { page: 2 } });
+  });
+
+  it('getDeck fetches a single deck by id', async () => {
+    fetch.get.mockResolvedValue({ id: 'd1', title: 'Pitch' });
+    const d = await api.getDeck('d1');
+    expect(fetch.get).toHaveBeenCalledWith('api/v1/presentations/decks/d1');
+    expect(d.title).toBe('Pitch');
+  });
+
+  it('createDeck posts the deck input', async () => {
+    fetch.post.mockResolvedValue({ id: 'd1', title: 'Pitch' });
+    await api.createDeck({ title: 'Pitch', outline: 'Slide 1...', audience: 'VCs' });
+    expect(fetch.post).toHaveBeenCalledWith('api/v1/presentations/decks', {
+      title: 'Pitch',
+      outline: 'Slide 1...',
+      audience: 'VCs',
+    });
+  });
+
+  it('updateDeck patches by id', async () => {
+    fetch.patch.mockResolvedValue({ id: 'd1', title: 'New' });
+    await api.updateDeck('d1', { title: 'New' });
+    expect(fetch.patch).toHaveBeenCalledWith('api/v1/presentations/decks/d1', { title: 'New' });
+  });
+
+  it('deleteDeck deletes by id', async () => {
+    fetch.delete.mockResolvedValue(undefined);
+    await api.deleteDeck('d1');
+    expect(fetch.delete).toHaveBeenCalledWith('api/v1/presentations/decks/d1');
+  });
+
+  it('generateDeck kicks off generation (derive style + slides)', async () => {
+    fetch.post.mockResolvedValue({ id: 'd1', status: 'generating' });
+    await api.generateDeck('d1', { outline: 'Slide 1: Title' });
+    expect(fetch.post).toHaveBeenCalledWith('api/v1/presentations/decks/d1/generate', {
+      outline: 'Slide 1: Title',
+    });
+  });
+
+  it('getDeckStatus polls the status endpoint', async () => {
+    fetch.get.mockResolvedValue({ status: 'generating', slides: [] });
+    await api.getDeckStatus('d1');
+    expect(fetch.get).toHaveBeenCalledWith('api/v1/presentations/decks/d1/status');
+  });
+
+  it('listSlides fetches the deck slides', async () => {
+    fetch.get.mockResolvedValue([{ id: 's1', slideNumber: 1 }]);
+    await api.listSlides('d1');
+    expect(fetch.get).toHaveBeenCalledWith('api/v1/presentations/decks/d1/slides');
+  });
+
+  it('updateSlide patches a slide by number', async () => {
+    fetch.patch.mockResolvedValue({ id: 's2', slideNumber: 2 });
+    await api.updateSlide('d1', 2, { content: 'Revised' });
+    expect(fetch.patch).toHaveBeenCalledWith('api/v1/presentations/decks/d1/slides/2', {
+      content: 'Revised',
+    });
+  });
+
+  it('regenerateSlide posts an instruction for one slide', async () => {
+    fetch.post.mockResolvedValue({ id: 's2', slideNumber: 2, status: 'generating' });
+    await api.regenerateSlide('d1', 2, { instruction: 'make it punchier' });
+    expect(fetch.post).toHaveBeenCalledWith('api/v1/presentations/decks/d1/slides/2/regenerate', {
+      instruction: 'make it punchier',
+    });
+  });
+
+  it('reorderSlides posts the new order', async () => {
+    fetch.post.mockResolvedValue(undefined);
+    await api.reorderSlides('d1', [3, 1, 2]);
+    expect(fetch.post).toHaveBeenCalledWith('api/v1/presentations/decks/d1/slides/reorder', {
+      order: [3, 1, 2],
+    });
+  });
+
+  it('compileDeck builds PPTX + PDF and returns artifact urls', async () => {
+    fetch.post.mockResolvedValue({ status: 'ready', pptxUrl: 'p.pptx', pdfUrl: 'p.pdf' });
+    const r = await api.compileDeck('d1');
+    expect(fetch.post).toHaveBeenCalledWith('api/v1/presentations/decks/d1/compile', undefined);
+    expect(r.pptxUrl).toBe('p.pptx');
+    expect(r.pdfUrl).toBe('p.pdf');
+  });
+});

package/src/lib/presentations-api.ts

@@ -0,0 +1,166 @@
+/** Presentations API client — AI-generated slide decks (epic startsim-3ks).
+
+Mirrors the other @startsimpli/api wrappers and the proven n8n "Slide Deck
+Agent v9" pipeline: a deck has ONE derived style spec applied verbatim to every
+slide; each slide is a full-bleed 16:9 image (image render mode), compiled into
+PPTX + PDF. The client auto-transforms snake_case <-> camelCase, so types here
+are camelCase.
+*/
+
+import type { PaginatedResponse } from '../types';
+import type { ApiClient } from './api-client';
+
+const E = {
+  decks: 'api/v1/presentations/decks',
+  deck: (id: string) => `api/v1/presentations/decks/${id}`,
+  generate: (id: string) => `api/v1/presentations/decks/${id}/generate`,
+  compile: (id: string) => `api/v1/presentations/decks/${id}/compile`,
+  status: (id: string) => `api/v1/presentations/decks/${id}/status`,
+  slides: (id: string) => `api/v1/presentations/decks/${id}/slides`,
+  slide: (id: string, n: number) => `api/v1/presentations/decks/${id}/slides/${n}`,
+  regenerate: (id: string, n: number) => `api/v1/presentations/decks/${id}/slides/${n}/regenerate`,
+  reorder: (id: string) => `api/v1/presentations/decks/${id}/slides/reorder`,
+};
+
+export type DeckStatus = 'draft' | 'generating' | 'ready' | 'error';
+export type SlideStatus = 'pending' | 'generating' | 'ready' | 'error';
+export type RenderMode = 'image' | 'structured';
+
+export interface Slide {
+  id: string;
+  deckId: string;
+  slideNumber: number;
+  title?: string;
+  /** Raw text content / outline for this slide. */
+  content: string;
+  /** The full image-generation prompt (style spec + slide content). */
+  imagePrompt?: string;
+  /** Full-bleed slide image (image render mode). */
+  imageUrl?: string;
+  status: SlideStatus;
+  renderMode: RenderMode;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface Deck {
+  id: string;
+  title: string;
+  /** Pasted outline the deck was generated from. */
+  outline: string;
+  /** Free-text audience / context that informs the style spec. */
+  audience: string;
+  /** The single derived STYLE SPEC, reused verbatim on every slide. */
+  styleSpec: string;
+  status: DeckStatus;
+  renderMode: RenderMode;
+  slideCount: number;
+  /** Compiled artifacts (present once compiled). */
+  pptxUrl?: string | null;
+  pdfUrl?: string | null;
+  createdAt: string;
+  updatedAt: string;
+  /** Present on detail responses. */
+  slides?: Slide[];
+}
+
+export interface DeckInput {
+  title: string;
+  outline?: string;
+  audience?: string;
+  renderMode?: RenderMode;
+}
+
+export interface GenerateDeckInput {
+  /** Outline to (re)generate from; defaults to the deck's stored outline. */
+  outline?: string;
+  /** Optional explicit style spec; otherwise the backend derives one. */
+  styleSpec?: string;
+}
+
+export interface SlideInput {
+  title?: string;
+  content?: string;
+  imagePrompt?: string;
+}
+
+export interface RegenerateSlideInput {
+  /** Revised content for the slide. */
+  content?: string;
+  /** Natural-language change request ("make it punchier"). */
+  instruction?: string;
+}
+
+/** Lightweight per-slide progress for polling during generation. */
+export interface DeckGenerationStatus {
+  status: DeckStatus;
+  slides: Array<{
+    slideNumber: number;
+    status: SlideStatus;
+    imageUrl?: string;
+  }>;
+}
+
+export interface CompileResult {
+  status: DeckStatus;
+  pptxUrl: string;
+  pdfUrl: string;
+}
+
+export interface DeckListParams {
+  page?: number;
+  pageSize?: number;
+  search?: string;
+  ordering?: string;
+  [key: string]: unknown;
+}
+
+export class PresentationsApi {
+  constructor(private client: ApiClient) {}
+
+  // --- Decks ---
+  listDecks(params?: DeckListParams): Promise<PaginatedResponse<Deck>> {
+    return this.client.fetch.get<PaginatedResponse<Deck>>(E.decks, { params });
+  }
+  getDeck(id: string): Promise<Deck> {
+    return this.client.fetch.get<Deck>(E.deck(id));
+  }
+  createDeck(data: DeckInput): Promise<Deck> {
+    return this.client.fetch.post<Deck>(E.decks, data);
+  }
+  updateDeck(id: string, data: Partial<DeckInput>): Promise<Deck> {
+    return this.client.fetch.patch<Deck>(E.deck(id), data);
+  }
+  deleteDeck(id: string): Promise<void> {
+    return this.client.fetch.delete<void>(E.deck(id));
+  }
+
+  // --- Generation pipeline (mirrors the n8n agent tools) ---
+  /** Derive the style spec (if absent) and generate every slide image async. */
+  generateDeck(id: string, data?: GenerateDeckInput): Promise<Deck> {
+    return this.client.fetch.post<Deck>(E.generate(id), data);
+  }
+  /** Per-slide progress, for polling while generation/compile runs. */
+  getDeckStatus(id: string): Promise<DeckGenerationStatus> {
+    return this.client.fetch.get<DeckGenerationStatus>(E.status(id));
+  }
+  /** Build the Google-Slides-equivalent deck and export PPTX + PDF. */
+  compileDeck(id: string): Promise<CompileResult> {
+    return this.client.fetch.post<CompileResult>(E.compile(id), undefined);
+  }
+
+  // --- Slides ---
+  listSlides(id: string): Promise<Slide[]> {
+    return this.client.fetch.get<Slide[]>(E.slides(id));
+  }
+  updateSlide(id: string, slideNumber: number, data: SlideInput): Promise<Slide> {
+    return this.client.fetch.patch<Slide>(E.slide(id, slideNumber), data);
+  }
+  /** Regenerate a single slide image (keeps the deck style spec). */
+  regenerateSlide(id: string, slideNumber: number, data?: RegenerateSlideInput): Promise<Slide> {
+    return this.client.fetch.post<Slide>(E.regenerate(id, slideNumber), data);
+  }
+  reorderSlides(id: string, order: number[]): Promise<void> {
+    return this.client.fetch.post<void>(E.reorder(id), { order });
+  }
+}

package/src/lib/workflows-api.test.ts

@@ -0,0 +1,129 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { WorkflowsApi } from './workflows-api';
+
+function makeApi() {
+  const fetch = { get: vi.fn(), post: vi.fn(), patch: vi.fn(), delete: vi.fn() };
+  const api = new WorkflowsApi({ fetch } as never);
+  return { api, fetch };
+}
+
+describe('WorkflowsApi', () => {
+  let api: WorkflowsApi;
+  let fetch: {
+    get: ReturnType<typeof vi.fn>;
+    post: ReturnType<typeof vi.fn>;
+    patch: ReturnType<typeof vi.fn>;
+    delete: ReturnType<typeof vi.fn>;
+  };
+
+  beforeEach(() => {
+    ({ api, fetch } = makeApi());
+  });
+
+  // --- Workflows CRUD ---
+  it('listWorkflows hits the workflows endpoint with params', async () => {
+    fetch.get.mockResolvedValue({ results: [], count: 0 });
+    await api.listWorkflows({ page: 2 });
+    expect(fetch.get).toHaveBeenCalledWith('api/v1/workflows', { params: { page: 2 } });
+  });
+
+  it('getWorkflow fetches a single workflow by id', async () => {
+    fetch.get.mockResolvedValue({ id: 'w1', name: 'Onboarding' });
+    const w = await api.getWorkflow('w1');
+    expect(fetch.get).toHaveBeenCalledWith('api/v1/workflows/w1');
+    expect(w.name).toBe('Onboarding');
+  });
+
+  it('createWorkflow posts the workflow input', async () => {
+    fetch.post.mockResolvedValue({ id: 'w1', name: 'Onboarding' });
+    await api.createWorkflow({ name: 'Onboarding', description: 'desc' });
+    expect(fetch.post).toHaveBeenCalledWith('api/v1/workflows', {
+      name: 'Onboarding',
+      description: 'desc',
+    });
+  });
+
+  it('updateWorkflow patches by id', async () => {
+    fetch.patch.mockResolvedValue({ id: 'w1', name: 'New' });
+    await api.updateWorkflow('w1', { name: 'New' });
+    expect(fetch.patch).toHaveBeenCalledWith('api/v1/workflows/w1', { name: 'New' });
+  });
+
+  it('deleteWorkflow deletes by id', async () => {
+    fetch.delete.mockResolvedValue(undefined);
+    await api.deleteWorkflow('w1');
+    expect(fetch.delete).toHaveBeenCalledWith('api/v1/workflows/w1');
+  });
+
+  // --- Node types ---
+  it('getNodeTypes fetches the node-type registry', async () => {
+    fetch.get.mockResolvedValue([
+      { slug: 'http', category: 'action', label: 'HTTP Request', parameterSchema: {}, outputLabels: ['main'] },
+    ]);
+    const types = await api.getNodeTypes();
+    expect(fetch.get).toHaveBeenCalledWith('api/v1/workflows/node-types');
+    expect(types[0].slug).toBe('http');
+  });
+
+  // --- Execution ---
+  it('executeWorkflow posts context and returns an executionId', async () => {
+    fetch.post.mockResolvedValue({ executionId: 'e1', status: 'running' });
+    const res = await api.executeWorkflow('w1', { foo: 'bar' });
+    expect(fetch.post).toHaveBeenCalledWith('api/v1/workflows/w1/execute', { contextData: { foo: 'bar' } });
+    expect(res.executionId).toBe('e1');
+    expect(res.status).toBe('running');
+  });
+
+  it('executeWorkflow works with no context data', async () => {
+    fetch.post.mockResolvedValue({ executionId: 'e2', status: 'pending' });
+    await api.executeWorkflow('w1');
+    expect(fetch.post).toHaveBeenCalledWith('api/v1/workflows/w1/execute', { contextData: undefined });
+  });
+
+  it('getExecution fetches a single execution detail by executionId', async () => {
+    fetch.get.mockResolvedValue({ status: 'running', state: {}, nodeExecutions: [] });
+    const e = await api.getExecution('e1');
+    expect(fetch.get).toHaveBeenCalledWith('api/v1/workflows/executions/e1');
+    expect(e.status).toBe('running');
+  });
+
+  it('listExecutions fetches executions for a workflow with params', async () => {
+    fetch.get.mockResolvedValue({ results: [], count: 0 });
+    await api.listExecutions('w1', { page: 1 });
+    expect(fetch.get).toHaveBeenCalledWith('api/v1/workflows/w1/executions', { params: { page: 1 } });
+  });
+
+  it('cancelExecution posts to the cancel endpoint', async () => {
+    fetch.post.mockResolvedValue({ id: 'e1', status: 'cancelled' });
+    await api.cancelExecution('e1');
+    expect(fetch.post).toHaveBeenCalledWith('api/v1/workflows/executions/e1/cancel', undefined);
+  });
+
+  it('retryExecution posts to the retry endpoint and returns an executionId', async () => {
+    fetch.post.mockResolvedValue({ executionId: 'e2', status: 'pending' });
+    const res = await api.retryExecution('e1');
+    expect(fetch.post).toHaveBeenCalledWith('api/v1/workflows/executions/e1/retry', undefined);
+    expect(res.executionId).toBe('e2');
+  });
+
+  // --- Lifecycle ---
+  it('cloneWorkflow posts to the clone endpoint', async () => {
+    fetch.post.mockResolvedValue({ id: 'w2', name: 'Onboarding (copy)' });
+    const w = await api.cloneWorkflow('w1');
+    expect(fetch.post).toHaveBeenCalledWith('api/v1/workflows/w1/clone', undefined);
+    expect(w.id).toBe('w2');
+  });
+
+  it('publishWorkflow posts to the publish endpoint', async () => {
+    fetch.post.mockResolvedValue({ id: 'w1', isActive: true });
+    await api.publishWorkflow('w1');
+    expect(fetch.post).toHaveBeenCalledWith('api/v1/workflows/w1/publish', undefined);
+  });
+
+  it('getVersions fetches the workflow version history', async () => {
+    fetch.get.mockResolvedValue([{ id: 'w1', version: 1 }]);
+    const versions = await api.getVersions('w1');
+    expect(fetch.get).toHaveBeenCalledWith('api/v1/workflows/w1/versions');
+    expect(versions[0].version).toBe(1);
+  });
+});

package/src/lib/workflows-api.ts

@@ -1,159 +1,205 @@
-/**
- * Workflows API wrapper
+/** Workflows API client — generic node-based workflow engine (epic startsim-xsh.11).
  *
- * Provides type-safe access to Django Workflows API
+ * Mirrors the other @startsimpli/api wrappers: an E-map of endpoints under
+ * `api/v1/workflows/`, the `client.fetch.{get,post,patch,delete}` convention,
+ * and the auto snake_case <-> camelCase transform (so all types here are
+ * camelCase).
+ *
+ * The execution detail type (`WorkflowExecutionDetail`) is deliberately shaped
+ * to match present-web's `run-to-builder-state.ts` `WorkflowRunDetail`, so a
+ * `getExecution(...)` response can be fed straight into `runToBuilderState`.
  */
 
+import type { PaginatedResponse } from '../types';
 import type { ApiClient } from './api-client';
 
-export type WorkflowStatus = 'draft' | 'active' | 'paused';
+const E = {
+  workflows: 'api/v1/workflows',
+  workflow: (id: string) => `api/v1/workflows/${id}`,
+  nodeTypes: 'api/v1/workflows/node-types',
+  execute: (id: string) => `api/v1/workflows/${id}/execute`,
+  executions: (id: string) => `api/v1/workflows/${id}/executions`,
+  execution: (executionId: string) => `api/v1/workflows/executions/${executionId}`,
+  cancel: (executionId: string) => `api/v1/workflows/executions/${executionId}/cancel`,
+  retry: (executionId: string) => `api/v1/workflows/executions/${executionId}/retry`,
+  clone: (id: string) => `api/v1/workflows/${id}/clone`,
+  publish: (id: string) => `api/v1/workflows/${id}/publish`,
+  versions: (id: string) => `api/v1/workflows/${id}/versions`,
+};
+
+/** Run lifecycle status — matches run-to-builder-state's `WorkflowRunStatus`. */
+export type RunStatus =
+  | 'pending'
+  | 'running'
+  | 'completed'
+  | 'failed'
+  | 'cancelled'
+  | 'waiting';
+
+/** Per-node status — matches run-to-builder-state's `WorkflowNodeStatus`. */
+export type NodeStatus =
+  | 'idle'
+  | 'pending'
+  | 'running'
+  | 'success'
+  | 'error'
+  | 'skipped';
+
+export type ExecutionMode = 'manual' | 'trigger' | 'webhook';
+
+/** A node placed in a workflow graph (engine-defined shape). */
+export interface WorkflowNode {
+  id: string;
+  type: string;
+  parameters?: Record<string, unknown>;
+  position?: [number, number];
+  [key: string]: unknown;
+}
 
 export interface Workflow {
   id: string;
   name: string;
   description: string;
-  team: string;
-  createdBy: string | null;
-  nodes: any[];
-  connections: Record<string, any>;
-  settings: Record<string, any>;
-  staticData: Record<string, any>;
+  nodes: WorkflowNode[];
+  connections: Record<string, unknown>;
   isActive: boolean;
-  version: number;
-  isTemplate: boolean;
-  templateSource: string | null;
-  executionsCount: number;
-  createdAt: string;
-  updatedAt: string;
+  version?: number;
+  isTemplate?: boolean;
+  settings?: Record<string, unknown>;
+  executionsCount?: number;
+  createdAt?: string;
+  updatedAt?: string;
+}
+
+/** A registered node type the builder can place. */
+export interface NodeTypeDef {
+  slug: string;
+  category: string;
+  label: string;
+  /** JSON-schema-ish description of the node's parameters. */
+  parameterSchema: Record<string, unknown>;
+  /** Names of the node's output connectors. */
+  outputLabels: string[];
 }
 
+/** Lightweight execution summary (list rows). */
 export interface WorkflowExecution {
   id: string;
-  workflow: string;
-  workflowVersion: number;
-  triggeredBy: string;
-  status: 'pending' | 'running' | 'completed' | 'failed' | 'paused';
-  mode: 'manual' | 'trigger' | 'webhook';
-  contextData: Record<string, any>;
-  state: Record<string, any>;
+  workflowId: string;
+  status: RunStatus;
+  mode: ExecutionMode;
+  source?: string;
   startedAt: string | null;
   completedAt: string | null;
-  waitUntil: string | null;
-  errorMessage: string | null;
-  createdAt: string;
-  updatedAt: string;
 }
 
-export interface WorkflowFilters {
-  team?: string;
-  isActive?: boolean;
-  isTemplate?: boolean;
-  page?: number;
-  pageSize?: number;
-  ordering?: string;
+/** One node's execution record — matches run-to-builder-state's `RunNodeExecution`. */
+export interface WorkflowNodeExecution {
+  nodeId: string;
+  nodeName?: string;
+  nodeType?: string;
+  status: NodeStatus;
+  executionOrder?: number;
+  output?: Record<string, unknown> | null;
+}
+
+/** Full execution detail. Structurally matches present-web's `WorkflowRunDetail`
+ * so a response can be passed directly to `runToBuilderState`. */
+export interface WorkflowExecutionDetail {
+  status: RunStatus;
+  state: Record<string, unknown>;
+  nodeExecutions: WorkflowNodeExecution[];
+  contextData?: Record<string, unknown>;
 }
 
-export interface ExecuteWorkflowInput {
-  contextData?: Record<string, any>;
-  mode?: 'manual' | 'trigger' | 'webhook';
+/** The contract returned by POST execute/retry: carries the executionId. */
+export interface ExecuteWorkflowResponse {
+  executionId: string;
+  status: RunStatus;
 }
 
-export interface CreateWorkflowInput {
+export interface WorkflowInput {
   name: string;
   description?: string;
-  team: string;
-  nodes?: any[];
-  connections?: Record<string, any>;
-  settings?: Record<string, any>;
+  nodes?: WorkflowNode[];
+  connections?: Record<string, unknown>;
   isActive?: boolean;
+  settings?: Record<string, unknown>;
+}
+
+export interface WorkflowListParams {
+  page?: number;
+  pageSize?: number;
+  search?: string;
+  ordering?: string;
+  isActive?: boolean;
+  isTemplate?: boolean;
+  [key: string]: unknown;
+}
+
+export interface ExecutionListParams {
+  page?: number;
+  pageSize?: number;
+  status?: RunStatus;
+  ordering?: string;
+  [key: string]: unknown;
 }
 
 export class WorkflowsApi {
   constructor(private client: ApiClient) {}
 
-  /**
-   * List workflows with optional filters
-   */
-  async list(filters?: WorkflowFilters) {
-    const params = new URLSearchParams();
-
-    if (filters?.team) params.append('team', filters.team);
-    if (filters?.isActive !== undefined) params.append('isActive', String(filters.isActive));
-    if (filters?.isTemplate !== undefined) params.append('isTemplate', String(filters.isTemplate));
-    if (filters?.page) params.append('page', String(filters.page));
-    if (filters?.pageSize) params.append('pageSize', String(filters.pageSize));
-    if (filters?.ordering) params.append('ordering', filters.ordering);
-
-    return this.client.get<{ results: Workflow[]; count: number; next: string | null; previous: string | null }>(
-      `/api/v1/workflows/?${params.toString()}`
-    );
+  // --- Workflows ---
+  listWorkflows(params?: WorkflowListParams): Promise<PaginatedResponse<Workflow>> {
+    return this.client.fetch.get<PaginatedResponse<Workflow>>(E.workflows, { params });
   }
-
-  /**
-   * Get workflow by ID
-   */
-  async get(id: string) {
-    return this.client.get<Workflow>(`/api/v1/workflows/${id}/`);
+  getWorkflow(id: string): Promise<Workflow> {
+    return this.client.fetch.get<Workflow>(E.workflow(id));
   }
-
-  /**
-   * Create a new workflow
-   */
-  async create(data: CreateWorkflowInput) {
-    return this.client.post<Workflow>('/api/v1/workflows/', data);
+  createWorkflow(data: WorkflowInput): Promise<Workflow> {
+    return this.client.fetch.post<Workflow>(E.workflows, data);
   }
-
-  /**
-   * Update workflow
-   */
-  async update(id: string, data: Partial<CreateWorkflowInput>) {
-    return this.client.patch<Workflow>(`/api/v1/workflows/${id}/`, data);
+  updateWorkflow(id: string, data: Partial<WorkflowInput>): Promise<Workflow> {
+    return this.client.fetch.patch<Workflow>(E.workflow(id), data);
   }
-
-  /**
-   * Delete workflow
-   */
-  async delete(id: string) {
-    return this.client.delete(`/api/v1/workflows/${id}/`);
+  deleteWorkflow(id: string): Promise<void> {
+    return this.client.fetch.delete<void>(E.workflow(id));
   }
 
-  /**
-   * Execute workflow
-   */
-  async execute(id: string, input?: ExecuteWorkflowInput) {
-    return this.client.post<WorkflowExecution>(
-      `/api/v1/workflows/${id}/execute/`,
-      input || {}
-    );
+  // --- Node type registry ---
+  getNodeTypes(): Promise<NodeTypeDef[]> {
+    return this.client.fetch.get<NodeTypeDef[]>(E.nodeTypes);
   }
 
-  /**
-   * Get workflow templates
-   */
-  async templates() {
-    return this.client.get<Workflow[]>('/api/v1/workflows/templates/');
+  // --- Execution ---
+  /** Kick off a run. The response carries the executionId (the contract). */
+  executeWorkflow(id: string, contextData?: Record<string, unknown>): Promise<ExecuteWorkflowResponse> {
+    return this.client.fetch.post<ExecuteWorkflowResponse>(E.execute(id), { contextData });
   }
-
-  /**
-   * List workflow executions
-   */
-  async listExecutions(filters?: { workflow?: string; status?: string; page?: number; pageSize?: number }) {
-    const params = new URLSearchParams();
-
-    if (filters?.workflow) params.append('workflow', filters.workflow);
-    if (filters?.status) params.append('status', filters.status);
-    if (filters?.page) params.append('page', String(filters.page));
-    if (filters?.pageSize) params.append('pageSize', String(filters.pageSize));
-
-    return this.client.get<{ results: WorkflowExecution[]; count: number }>(
-      `/api/v1/workflow-executions/?${params.toString()}`
-    );
+  getExecution(executionId: string): Promise<WorkflowExecutionDetail> {
+    return this.client.fetch.get<WorkflowExecutionDetail>(E.execution(executionId));
+  }
+  listExecutions(
+    workflowId: string,
+    params?: ExecutionListParams,
+  ): Promise<PaginatedResponse<WorkflowExecution>> {
+    return this.client.fetch.get<PaginatedResponse<WorkflowExecution>>(E.executions(workflowId), { params });
+  }
+  cancelExecution(executionId: string): Promise<WorkflowExecution> {
+    return this.client.fetch.post<WorkflowExecution>(E.cancel(executionId), undefined);
+  }
+  /** Re-run a failed/cancelled execution; response carries the new executionId. */
+  retryExecution(executionId: string): Promise<ExecuteWorkflowResponse> {
+    return this.client.fetch.post<ExecuteWorkflowResponse>(E.retry(executionId), undefined);
   }
 
-  /**
-   * Get workflow execution details
-   */
-  async getExecution(id: string) {
-    return this.client.get<WorkflowExecution>(`/api/v1/workflow-executions/${id}/`);
+  // --- Lifecycle ---
+  cloneWorkflow(id: string): Promise<Workflow> {
+    return this.client.fetch.post<Workflow>(E.clone(id), undefined);
+  }
+  publishWorkflow(id: string): Promise<Workflow> {
+    return this.client.fetch.post<Workflow>(E.publish(id), undefined);
+  }
+  getVersions(id: string): Promise<Workflow[]> {
+    return this.client.fetch.get<Workflow[]>(E.versions(id));
   }
 }