Skip to main content

Server API

@flow-state-dev/server — Action runtime, stores, SSE streaming, orchestration.

Registry & Router​

createFlowRegistry()​

Create a registry for flow instances.

import { createFlowRegistry } from "@flow-state-dev/server";

const registry = createFlowRegistry();
registry.register(myFlow);

createFlowApiRouter(options)​

Create HTTP route handlers for the flow API.

import { createFlowApiRouter } from "@flow-state-dev/server";

const router = createFlowApiRouter({
  registry,
  stores: createFilesystemStores(),      // optional, default
  modelResolver: createModelResolver(),  // optional
  speechResolver: createAiSdkSpeechResolver(fn),       // optional, for TTS
  transcriptionResolver: createAiSdkTranscriptionResolver(fn), // optional, for STT
});

// Use with Next.js App Router:
export const GET = router.GET;
export const POST = router.POST;
export const DELETE = router.DELETE;

parseFlowRoute(path)​

Parse a flow API path into its components (kind, action, sessionId, etc.).

Execution​

createExecutionContext(options)​

Create a block execution context manually (for advanced use).

runAction(options)​

Execute a flow action programmatically.

executeBlock(block, input, ctx)​

Execute a block directly with a given context.

Stores​

createFilesystemStores(options?)​

Filesystem-backed persistence (default).

import { createFilesystemStores } from "@flow-state-dev/server";

const stores = createFilesystemStores({ basePath: ".flow-state" });

createInMemoryStores()​

In-memory persistence for testing.

import { createInMemoryStores } from "@flow-state-dev/server";

const stores = createInMemoryStores();

Model Resolution​

createModelResolver(options?)​

Create a model resolver. Auto-detects providers from environment variables with zero config, or accepts explicit keys, presets, and retry policy.

import { createModelResolver } from "@flow-state-dev/core/models";

// Zero-config: auto-detects from env vars
const resolver = createModelResolver();

// With options:
const resolver = createModelResolver({
  keys: { openai: "sk-..." },
  presets: { fast: { models: ["openai/gpt-5.4-mini"] } },
  retryPolicy: { maxAttemptsPerModel: 3 },
});

Model strings use slash format: "openai/gpt-5.4", "anthropic/claude-sonnet-4-6", "vercel/openai/gpt-5.4".

parseModelString(modelString)​

Parse a slash-format model string into its components (provider, model, gateway).

Voice​

createAiSdkSpeechResolver(resolver)​

Create a speech resolver (TTS) using AI SDK providers.

import { createAiSdkSpeechResolver } from "@flow-state-dev/core/models";

const speechResolver = createAiSdkSpeechResolver(
  (modelId) => openai.speech(modelId)
);

wrapAiSdkSpeechModel(model, modelId?)​

Wrap a single AI SDK speech model into a framework SpeechModel.

createAiSdkTranscriptionResolver(resolver)​

Create a transcription resolver (STT) using AI SDK providers.

import { createAiSdkTranscriptionResolver } from "@flow-state-dev/core/models";

const transcriptionResolver = createAiSdkTranscriptionResolver(
  (modelId) => openai.transcription(modelId)
);

wrapAiSdkTranscriptionModel(model, modelId?)​

Wrap a single AI SDK transcription model into a framework TranscriptionModel.

createSentenceBuffer()​

Create a sentence-boundary detection buffer for TTS text chunking.

createTTSPipeline(options)​

Create the synthesis pipeline that converts text deltas into OutputAudioContent.

createTTSEmitterHook(options)​

Create an event observer that wires the TTS pipeline to a ResponseEmitter.

Streaming​

createResponseEmitter(options)​

Create a stream emitter for manual event emission.

encodeStreamEvent(event)​

Encode an event for SSE transmission.

serializeSSEFrame(event)​

Serialize an event into SSE wire format.

replayRequestEvents(options)​

Replay stored events from a completed request (for resume).

Errors​

FlowError​

Base error class with code, retryable, blockName, scope, and cause.

Subclasses:

  • ValidationError — Schema validation failure (not retryable)
  • NetworkError — Network issues (retryable)
  • TimeoutError — Operation timeout (retryable)
  • RateLimitError — Rate limit hit (retryable)
  • ModelError — Model provider error (retryable)
  • ToolExecutionError — Tool block failure (varies)

normalizeError(error)​

Convert any thrown value to a FlowError.