@oomol-lab/open-flow 0.1.0-beta.73 → 0.1.0-beta.75

package/src/control/common/api.ts

@@ -0,0 +1,1506 @@
+import type { CanvasCommand } from '../../canvas/common/commands.ts'
+
+import { currentEngineContract } from '../../execution/common/engineContract.ts'
+import { workflowContractSchema, workflowReferencesSchema } from '../../workflow/common/workflow.ts'
+export type { CanvasCommand, CanvasCommandSubscriber } from '../../canvas/common/commands.ts'
+import type { LiveDetails } from './liveDetails.ts'
+
+import { decodeLiveDetails } from './liveDetails.ts'
+export { liveEntries } from './liveDetails.ts'
+export { flowInputDefinitions } from './authoringFields.ts'
+export type { LiveDetails, LiveEntry } from './liveDetails.ts'
+import type { AuthoringRead, AuthoringSearch, AuthoringRequest, AuthoringType } from './authoringSchema.ts'
+import type { ProviderIconAppearance } from './providerIconSprite.ts'
+
+import { authoringReadResponse, authoringSearchResponse, authoringEditResponse, authoringCheckResponse } from './authoringSchema.ts'
+export { providerIconAppearance } from './providerIconSprite.ts'
+export type { ProviderIconAppearance, ProviderIconSprite, ProviderIconSpriteCatalog } from './providerIconSprite.ts'
+export { connectorAccess as decodeConnectorAccess, connectorAccessSnapshot as decodeConnectorAccessSnapshot } from './connectorDecoders.ts'
+import type { ProviderAccessIdentity, ProviderAccessReference } from './providerAccess.ts'
+export {
+  parseProviderAccessSource,
+  providerAccessBindingId,
+  type ProviderAccessIdentity,
+  type ProviderAccessReference,
+  type ProviderAccessSource,
+} from './providerAccess.ts'
+import type { DraftOperation } from './draftOperations.ts'
+export { inspectFlowDraft, flowInspection, actionSummary, nodeDetails } from './flowInspection.ts'
+export type { DraftOperation } from './draftOperations.ts'
+import type { SchemaMismatch } from '../../flow/common/change.ts'
+import type { CreateEventSource, UpdateEventSource, EventSource } from './eventSources.ts'
+
+import { decodeEventSource, decodeEventSources } from './eventSources.ts'
+export { decodeEventSource, decodeEventSources, type CreateEventSource, type UpdateEventSource, type EventSource } from './eventSources.ts'
+import type { TriggerCatalogCache } from './triggerCatalog.ts'
+
+import { decodeTriggerCatalog } from './triggerCatalog.ts'
+export { decodeTriggerCatalog, searchTriggerKeys, type TriggerCatalog, type TriggerCatalogCache, type TriggerDisplay } from './triggerCatalog.ts'
+import type { TriggerConfigOption } from '../../trigger/common/configOptions.ts'
+export type { TriggerConfigOption } from '../../trigger/common/configOptions.ts'
+import type { ResultQuery } from './results.ts'
+
+import { decodeResultList, decodeResultRead } from './results.ts'
+export {
+  readResult,
+  parseResultQuery,
+  decodeResultList,
+  decodeResultRead,
+  type ResultCall,
+  type ResultInfo,
+  type ResultPage,
+  type ResultQuery,
+} from './results.ts'
+import type { RunStatus } from '../../execution/common/runLifecycle.ts'
+import type { WorkflowFile } from '../../flow/common/workflowFile.ts'
+
+import { decodeWorkflowFile } from '../../flow/common/workflowFile.ts'
+export type { WorkflowFile, WorkflowCleanupSummary } from '../../flow/common/workflowFile.ts'
+import type { InputPortDefinition, JsonValue, PortDefinition, RevisionContent, TriggerKeySnapshot, WaitAction } from '../../flow/common/change.ts'
+import type { FlowResourceReferences } from '../../flow/common/semantics.ts'
+
+import { flowCheck } from './checkDecoders.ts'
+import { connection, connectorAccess, connectorAccessSnapshot, connectorAccessCandidatesBatch, connectorAction, leinaBots } from './connectorDecoders.ts'
+import { allConnectorConnectionsQuery, connectorActionQuery, connectorConnectionsQuery, connectorProvidersQuery } from './connectorQueries.ts'
+import { requiredFields, integer, invalidResponse, jsonValue, record, string } from './decoding.ts'
+import { errorListener, flow, flowPage, variable, variableListItem, variableReferences } from './flowDecoders.ts'
+import { live, publication, publicationPage, publishOperation } from './publicationDecoders.ts'
+import { draft, draftChange, draftSync, presentation } from './revisionDecoders.ts'
+import { runCancellation, runDetails, runPage, runResult, waitResolution } from './runDecoders.ts'
+import { pollTriggerTestResult, triggerActivityPage, triggerBinding, triggerBindingDetail, triggerKey, triggerKeySummary } from './triggerDecoders.ts'
+
+export type { JsonValue, TriggerKeySnapshot, WaitAction } from '../../flow/common/change.ts'
+export type { RunStatus } from '../../execution/common/runLifecycle.ts'
+export { ApiError, controlErrorCode, controlErrorMetadata, type ControlErrorCode } from './errors.ts'
+export type { FlowCatalogEvent, FlowChangeEvent } from './flowNotifications.ts'
+
+import { ApiError } from './errors.ts'
+import { randomId } from './random.ts'
+
+export interface CanvasBroadcast {
+  readonly version: 1
+  readonly flowId: string
+  readonly broadcast: true
+}
+
+export type ControlRequest = (path: string, init?: RequestInit) => Promise<Response>
+
+export interface ErrorListener {
+  readonly flowId: string
+  readonly flowName: string
+  readonly nodeId: string
+  readonly nodeName: string
+  readonly enabled: boolean
+}
+
+export interface FlowResources {
+  readonly draft: FlowResourceReferences | null
+  readonly sharedAccess: {
+    readonly accessRevision: number
+    readonly providerIds: readonly string[]
+    readonly bindings: readonly { readonly providerId: string; readonly connectionId: string | null; readonly accessBindingId: string }[]
+  }
+}
+
+export interface Flow {
+  readonly live?: { readonly enabled: boolean; readonly hasStart: boolean; readonly publicationId: string; readonly revisionId: string }
+
+  readonly createdAt: string
+  readonly draftRevisionId: string
+  readonly resourceReferences: FlowResources
+  readonly flowId: string
+  /** Connector Team scope used by the OOMOL resource cache. */
+  readonly connectorTeamId?: string
+  readonly name: string
+  readonly status: 'active' | 'retiring'
+  readonly updatedAt: string
+  readonly version: 1
+}
+
+export interface PublicationPresentation {
+  readonly version: 1
+  readonly presentation: Presentation | null
+}
+
+export interface Presentation {
+  readonly revision: number
+  readonly updatedAt: string
+  readonly value: Readonly<Record<string, JsonValue>>
+  readonly version: 1
+}
+
+export interface FlowListItem extends Flow {
+  readonly referenceCount: number
+}
+
+export interface FlowPage {
+  readonly flows: readonly FlowListItem[]
+  readonly nextCursor?: string
+  readonly total?: number
+  readonly version: 1
+}
+
+export interface VariableReference {
+  readonly flowId: string
+  readonly flowName: string
+  readonly draft: boolean
+  readonly live: { readonly publicationId: string; readonly enabled: boolean } | null
+}
+
+export interface VariableReferences {
+  readonly version: 1
+  readonly references: readonly VariableReference[]
+}
+
+export interface VariableListItem extends Variable {
+  readonly referenceCount: number
+}
+
+export interface Variable {
+  readonly name: string
+  readonly updatedAt: string
+  readonly value: string
+  readonly version: 1
+}
+
+export interface TriggerKeySummary {
+  readonly description: string
+  readonly displayName: string
+  readonly key: string
+  readonly name: string
+  readonly provider: string
+  readonly type: TriggerKeySnapshot['type']
+}
+
+export interface TriggerBinding {
+  readonly listener?: { readonly health: 'healthy' | 'failed' | 'needs_reauth'; readonly lastErrorCode?: string }
+  readonly currentPublicationId?: string
+  readonly currentRevisionId?: string
+  readonly endpointUrl?: string
+  readonly flowId: string
+  readonly health: 'failed' | 'healthy' | 'initializing' | 'needs_reauth' | 'suspended'
+  readonly kind: 'error' | 'cron' | 'integration' | 'poll' | 'webhook'
+  readonly lastErrorCode?: string
+  readonly runtimeVersion: number
+  readonly triggerNodeId: string
+  readonly updatedAt: string
+  readonly version: 1
+}
+
+export interface TriggerBindingDetail {
+  readonly binding: TriggerBinding
+  readonly version: 1
+}
+
+export type TriggerActivityKind =
+  | 'delivery.failed'
+  | 'health.failed'
+  | 'health.needs_reauth'
+  | 'health.recovered'
+  | 'health.suspended'
+  | 'operator.paused'
+  | 'operator.resumed'
+
+export interface TriggerActivity {
+  readonly activityId: string
+  readonly createdAt: string
+  readonly errorCode?: string
+  readonly errorMessage?: string
+  readonly kind: TriggerActivityKind
+}
+
+export interface TriggerActivityPage {
+  readonly activities: readonly TriggerActivity[]
+  readonly nextCursor?: string
+  readonly version: 1
+}
+
+export interface PollTriggerTestResult {
+  readonly events: readonly Readonly<Record<string, JsonValue>>[]
+  readonly filtered: number
+  readonly hasMore: boolean
+  readonly version: 1
+}
+
+export interface ConnectorConnection {
+  readonly providerAccountId?: string
+  readonly builtInAccount?: boolean
+  readonly alias?: string
+  readonly connectionId: string
+  readonly displayName: string
+  readonly isDefault: boolean
+  readonly serviceId: string
+  readonly status: 'active' | 'disconnected' | 'error' | 'reauth_required'
+}
+
+/** Action metadata independent of account availability and selection. */
+export interface ConnectorActionMetadata extends ProviderIconAppearance {
+  /** Upstream operation classification; unknown values remain uncategorized. */
+  readonly operationType?: string
+  readonly inputSchema?: JsonValue
+  readonly outputSchema?: JsonValue
+  readonly actionId: string
+  readonly authenticated: boolean
+  readonly description: string
+  readonly homepageUrl?: string
+  readonly icon?: string
+  readonly inputs: Readonly<Record<string, InputPortDefinition>>
+  readonly name: string
+  readonly outputs: Readonly<Record<string, PortDefinition>>
+  readonly serviceId: string
+  readonly serviceName: string
+}
+
+/** Existing CLI/MCP representation, including the currently preferred account. */
+export interface ConnectorAction extends ConnectorActionMetadata {
+  readonly defaultConnection?: ConnectorConnection
+}
+
+export interface ConnectorProvider extends ProviderIconAppearance {
+  readonly noSetup?: boolean
+  readonly homepageUrl?: string
+  readonly icon?: string
+  readonly serviceId: string
+  readonly serviceName: string
+}
+
+export type ConnectorAccessMode = 'implicit' | 'selectable'
+
+export interface LeinaBot {
+  readonly leinaId: string
+  readonly name: string
+  readonly status: string
+  readonly platforms: readonly string[]
+}
+export type ProviderAccessBindingStatus = 'active' | 'forbidden' | 'invalid' | 'missing'
+
+export type ProviderAccessBinding = (
+  | (ProviderAccessIdentity & { readonly status: ProviderAccessBindingStatus })
+  | (Extract<ProviderAccessReference, { readonly source: null }> & { readonly status: 'invalid' })
+) & {
+  readonly connectionDisplayName: string
+  readonly permissionGroupName?: string | null
+  readonly policyRevision?: string
+  readonly providerId: string
+}
+
+export interface ProviderAccessBindingCandidate extends ProviderAccessIdentity {
+  readonly connectionDisplayName: string
+  readonly isDefault?: boolean
+  readonly permissions?: {
+    readonly actionIds: readonly string[]
+    readonly allActions: boolean
+    readonly triggerIds: readonly string[]
+    readonly allTriggers: boolean
+    readonly configured: boolean
+    readonly proxy: boolean
+  }
+  readonly permissionGroupName?: string | null
+  readonly policyRevision?: string
+  readonly providerId: string
+}
+
+export interface ConnectorAccess {
+  readonly discardedBindingCount?: number
+  readonly providerIds?: readonly string[]
+  readonly accessRevision: number
+  readonly bindings: readonly ProviderAccessBinding[]
+  readonly mode: ConnectorAccessMode
+  readonly sharedAccessDigest: string
+  readonly version: 1
+}
+
+export type ConnectorAccessGrant = ProviderAccessIdentity & {
+  readonly connectionDisplayName: string
+  readonly permissionGroupName?: string | null
+}
+
+export interface ConnectorAccessSnapshot {
+  readonly mode: ConnectorAccessMode
+  readonly sharedAccessDigest: string
+  readonly sharedBindings: readonly ConnectorAccessGrant[]
+  readonly selectedBindings: readonly ConnectorAccessGrant[]
+  readonly version: 2
+}
+
+export interface ConnectorAccessCandidates {
+  readonly candidates: readonly ProviderAccessBindingCandidate[]
+  readonly mode: ConnectorAccessMode
+  readonly providerId: string
+  readonly version: 1
+}
+
+export interface ConnectorAccessCandidatesBatch {
+  readonly results: readonly (
+    | ConnectorAccessCandidates
+    | { readonly providerId: string; readonly error: { readonly code: string; readonly message: string } }
+  )[]
+  readonly version: 1
+}
+
+export interface RevisionMetadata {
+  readonly actorId: string
+  readonly createdAt: string
+  readonly digest: string
+  readonly modelVersion: number
+  readonly parentRevisionId: string | null
+  readonly flowId: string
+  readonly revisionId: string
+  readonly version: 1
+}
+
+export interface Draft extends RevisionMetadata {
+  readonly content: RevisionContent
+}
+
+export interface DraftChange {
+  readonly revision: RevisionMetadata
+  readonly version: 1
+}
+
+export interface DraftSync {
+  readonly draft: Draft
+  readonly kind: 'snapshot'
+  readonly version: 1
+}
+
+export interface Publication {
+  readonly liveEnd?: { readonly enabled: boolean; readonly endedAt: string }
+  readonly actorId: string
+  readonly closureDigest: string
+  readonly createdAt: string
+  readonly engineContract: string
+  readonly flowId: string
+  readonly modelVersion: number
+  readonly operation: 'publish' | 'rollback'
+  readonly publicationId: string
+  readonly sharedAccessDigest: string
+  readonly revisionDigest: string
+  readonly revisionId: string
+  readonly sourcePublicationId?: string
+  readonly version: 1
+}
+
+export type PublishOperation =
+  | {
+      readonly createdAt: string
+      readonly flowId: string
+      readonly operationId: string
+      readonly revisionId: string
+      readonly status: 'pending'
+      readonly updatedAt: string
+      readonly version: 1
+    }
+  | {
+      readonly createdAt: string
+      readonly flowId: string
+      readonly operationId: string
+      readonly publicationId: string
+      readonly revisionId: string
+      readonly status: 'succeeded'
+      readonly updatedAt: string
+      readonly version: 1
+    }
+  | {
+      readonly createdAt: string
+      readonly flowId: string
+      readonly issue: { readonly code: string; readonly message: string; readonly nodeId?: string }
+      readonly operationId: string
+      readonly revisionId: string
+      readonly status: 'failed'
+      readonly updatedAt: string
+      readonly version: 1
+    }
+
+export interface Diagnostic {
+  readonly code: string
+  readonly column: number
+  readonly fields?: readonly string[]
+  readonly line: number
+  readonly message: string
+  readonly mismatch?: SchemaMismatch
+  readonly path: string
+  readonly values?: Readonly<Record<string, string | number>>
+}
+
+export interface FlowCheck {
+  readonly closureDigest: string
+  readonly diagnostics: readonly Diagnostic[]
+  readonly engineContract: string
+  readonly flowId: string
+  readonly modelVersion: number
+  readonly revisionDigest: string
+  readonly revisionId: string
+  readonly valid: boolean
+  readonly version: 1
+}
+
+export interface Live {
+  readonly flowId: string
+  readonly hasUnpublishedChanges: boolean
+  readonly publication: Publication | null
+  readonly revision: number
+  readonly status: 'not-published' | 'runnable' | 'suspended'
+  readonly version: 1
+}
+
+export interface PublicationPage {
+  readonly nextCursor?: string
+  readonly publications: readonly Publication[]
+  readonly total?: number
+  readonly version: 1
+}
+
+export type RunChannel = 'workbench' | 'cli' | 'mcp' | 'api' | 'trigger' | 'workflow'
+
+export interface RunInitiator {
+  readonly actorId?: string
+  readonly channel: RunChannel
+}
+
+export interface Run {
+  readonly createdAt: string
+  readonly finishedAt?: string
+  readonly flowId: string
+  readonly revisionId: string
+  readonly runId: string
+  readonly source: 'draft' | 'live'
+  readonly startedAt?: string
+  readonly status: RunStatus
+  readonly version: 1
+}
+
+export interface RunWait {
+  readonly autoContinueAt?: string
+  readonly actions: readonly ['continue'] | readonly ['approve', 'reject']
+  readonly expiresAt: string
+  readonly nodeId: string
+  readonly prompt: string
+  readonly waitId: string
+  readonly waitingSince: string
+}
+
+export type ErrorDispatch =
+  | { readonly status: 'pending'; readonly flowId: string }
+  | { readonly status: 'dispatched'; readonly flowId: string; readonly runId: string }
+  | { readonly status: 'failed'; readonly flowId: string; readonly message: string }
+
+export interface WorkflowCaller {
+  readonly callId?: string
+  readonly flowId: string
+  readonly runId: string
+  readonly nodeId: string
+  readonly executionId: string
+}
+export interface WorkflowRunCall extends WorkflowCaller {
+  readonly status: RunStatus | null
+}
+
+type RunDetailsBase = Run & {
+  readonly initiator?: RunInitiator
+  readonly caller?: WorkflowCaller
+  readonly calls?: readonly WorkflowRunCall[]
+  readonly triggerNodeId?: string
+  readonly errorDispatches?: readonly ErrorDispatch[]
+  readonly errorSource?: { readonly flowId: string; readonly runId: string }
+  readonly closureDigest: string
+  readonly engineContract: string
+  readonly engineDigest: string
+  readonly eventsExpiresAt?: string
+  readonly modelVersion: number
+  readonly sharedAccessDigest: string
+  readonly revisionDigest: string
+  readonly waits: readonly RunWait[]
+}
+
+export type DraftRun = RunDetailsBase & { readonly source: 'draft' }
+export type LiveRun = RunDetailsBase & {
+  readonly publicationId: string
+  readonly source: 'live'
+  readonly occurrenceId?: string
+  readonly triggerNodeId?: string
+}
+export type RunDetails = DraftRun | LiveRun
+
+export interface RunPage {
+  readonly flowId: string
+  readonly nextCursor?: string
+  readonly runs: readonly Run[]
+  readonly version: 1
+}
+
+/** Run-level events have no node identity; callers may inspect it without narrowing the event kind. */
+type EventWithNodeContext<Event> = Event extends { readonly payload: infer Payload }
+  ? Readonly<Event & { readonly payload: Payload & { readonly nodeId?: string } }>
+  : never
+export type RunEvent = EventWithNodeContext<ReturnType<typeof decodeRunEvent>>
+export type RunEventKind = RunEvent['kind']
+
+export function isRunTerminalEvent(event: RunEvent | undefined): boolean {
+  return event?.kind == 'run.completed' || event?.kind == 'run.failed' || event?.kind == 'run.canceled' || event?.kind == 'run.indeterminate'
+}
+
+export interface RunEvents {
+  readonly done: boolean
+  readonly events: readonly RunEvent[]
+  readonly eventsExpiresAt?: string
+  readonly historyComplete: boolean
+  readonly nextAfter: number
+  readonly runId: string
+  readonly version: 1
+}
+
+export interface RunCancellation {
+  readonly cancelAccepted: boolean
+  readonly runId: string
+  readonly status: Extract<RunStatus, 'canceled' | 'completed' | 'failed' | 'indeterminate'>
+  readonly version: 1
+}
+
+export interface RunFailure {
+  readonly code: string
+  readonly message: string
+  readonly nodeId?: string
+  readonly jobId?: string
+  readonly path?: readonly string[]
+}
+
+export type RunResult =
+  | { readonly finishedAt: string; readonly result: JsonValue; readonly runId: string; readonly status: 'completed'; readonly version: 1 }
+  | {
+      readonly error: RunFailure
+      readonly finishedAt: string
+      readonly runId: string
+      readonly status: 'failed' | 'indeterminate'
+      readonly version: 1
+    }
+  | { readonly finishedAt: string; readonly runId: string; readonly status: 'canceled'; readonly version: 1 }
+
+interface RunOptions {
+  readonly trigger: { readonly nodeId: string; readonly outputs: Readonly<Record<string, JsonValue>> }
+  readonly idempotencyKey?: string
+  readonly inputs?: Readonly<Record<string, Readonly<Record<string, JsonValue>>>>
+}
+
+interface PublicationOptions {
+  readonly idempotencyKey?: string
+}
+
+export function decodeRunEvent(value: unknown) {
+  const source = record(value)
+  const sequence = integer(source.sequence)
+  if (sequence < 0) return invalidResponse()
+  const base = {
+    createdAt: string(source.createdAt),
+    sequence,
+  }
+  const payload = record(source.payload)
+  const kind = source.kind
+  switch (kind) {
+    case 'run.queued':
+      return { ...base, kind, payload: {} } as const
+    case 'run.started':
+      return {
+        ...base,
+        kind,
+        payload: {
+          flowId: string(payload.flowId),
+          scopeId: string(payload.scopeId),
+          ...(payload.parentScopeId === undefined ? {} : { parentScopeId: string(payload.parentScopeId) }),
+        },
+      } as const
+    case 'run.progress':
+      return {
+        ...base,
+        kind,
+        payload: { flowId: string(payload.flowId), scopeId: string(payload.scopeId), progress: eventProgress(payload.progress) },
+      } as const
+    case 'run.waiting':
+      if (!Array.isArray(payload.waitIds)) return invalidResponse()
+      return { ...base, kind, payload: { waitIds: payload.waitIds.map((id) => string(id)) } } as const
+    case 'wait.created': {
+      const timing: { readonly autoContinueAt?: string } = payload.autoContinueAt === undefined ? {} : { autoContinueAt: string(payload.autoContinueAt) }
+      return {
+        ...base,
+        kind,
+        payload: {
+          ...timing,
+          expiresAt: string(payload.expiresAt),
+          nodeId: string(payload.nodeId),
+          waitId: string(payload.waitId),
+          waitingSince: string(payload.waitingSince),
+        },
+      } as const
+    }
+    case 'run.resolved': {
+      const action = payload.action
+      const resolutionSource = payload.source
+      if (resolutionSource !== undefined && resolutionSource !== 'manual' && resolutionSource !== 'automatic') return invalidResponse()
+      const audit: { readonly source?: 'manual' | 'automatic' } = resolutionSource === undefined ? {} : { source: resolutionSource }
+      if (action !== 'approve' && action !== 'continue' && action !== 'reject') return invalidResponse()
+      if (payload.comment !== null && typeof payload.comment != 'string') return invalidResponse()
+      return {
+        ...base,
+        kind,
+        payload: { ...audit, action, comment: payload.comment as string | null, resolvedAt: string(payload.resolvedAt), waitId: string(payload.waitId) },
+      } as const
+    }
+    case 'run.completed':
+    case 'run.canceled':
+    case 'run.failed':
+    case 'run.indeterminate':
+      return { ...base, kind, payload: { result: jsonValue(payload.result) } } as const
+    case 'run.events-truncated':
+      return { ...base, kind, payload: Object.fromEntries(Object.entries(payload).map(([key, item]) => [key, jsonValue(item)])) } as const
+    case 'node.started':
+    case 'node.completed':
+    case 'node.failed':
+    case 'node.log':
+    case 'node.progress':
+    case 'node.artifact': {
+      const node = {
+        flowId: string(payload.flowId),
+        scopeId: string(payload.scopeId),
+        nodeId: string(payload.nodeId),
+        executionId: string(payload.executionId),
+      }
+      switch (kind) {
+        case 'node.started': {
+          const nodeKind = payload.nodeKind
+          if (
+            nodeKind !== undefined &&
+            nodeKind !== 'approval' &&
+            nodeKind !== 'condition' &&
+            nodeKind !== 'connector' &&
+            nodeKind !== 'javascript' &&
+            nodeKind !== 'decision' &&
+            nodeKind !== 'openapi' &&
+            nodeKind !== 'http-request' &&
+            nodeKind !== 'llm' &&
+            nodeKind !== 'agent' &&
+            nodeKind !== 'value' &&
+            nodeKind !== 'outputs' &&
+            nodeKind !== 'webhook-response' &&
+            nodeKind !== 'workflow' &&
+            nodeKind !== 'wait'
+          )
+            return invalidResponse()
+          return {
+            ...base,
+            kind,
+            payload: {
+              ...node,
+              ...(nodeKind === undefined ? {} : { nodeKind }),
+              ...(payload.nodeTitle === undefined ? {} : { nodeTitle: string(payload.nodeTitle) }),
+              ...(payload.operation === undefined ? {} : { operation: string(payload.operation) }),
+            },
+          } as const
+        }
+        case 'node.completed':
+          return {
+            ...base,
+            kind,
+            payload: {
+              ...node,
+              ...(payload.systemOutputs === undefined
+                ? {}
+                : { systemOutputs: Object.fromEntries(Object.entries(record(payload.systemOutputs)).map(([key, item]) => [key, jsonValue(item)])) }),
+              outputs: Object.fromEntries(Object.entries(record(payload.outputs)).map(([key, item]) => [key, jsonValue(item)])),
+            },
+          } as const
+        case 'node.failed': {
+          const error = record(payload.error)
+          return {
+            ...base,
+            kind,
+            payload: {
+              ...node,
+              ...(payload.handled === true ? { handled: true as const } : {}),
+              ...(payload.systemOutputs === undefined
+                ? {}
+                : { systemOutputs: Object.fromEntries(Object.entries(record(payload.systemOutputs)).map(([key, item]) => [key, jsonValue(item)])) }),
+              error: { code: string(error.code), message: string(error.message) },
+            },
+          } as const
+        }
+        case 'node.log': {
+          const level = payload.level
+          if (level !== 'debug' && level !== 'info' && level !== 'warn' && level !== 'error') return invalidResponse()
+          return { ...base, kind, payload: { ...node, level, message: string(payload.message) } } as const
+        }
+        case 'node.progress':
+          return { ...base, kind, payload: { ...node, progress: eventProgress(payload.progress) } } as const
+        case 'node.artifact': {
+          const artifact = record(payload.artifact)
+          const size = integer(artifact.size)
+          const digest = string(artifact.digest)
+          if (artifact.kind != 'artifact' || size < 0 || !/^sha256:[0-9a-f]{64}$/.test(digest)) return invalidResponse()
+          return {
+            ...base,
+            kind,
+            payload: {
+              ...node,
+              artifact: {
+                kind: 'artifact',
+                id: string(artifact.id),
+                name: string(artifact.name),
+                size,
+                digest,
+                ...(artifact.mediaType === undefined ? {} : { mediaType: string(artifact.mediaType) }),
+              },
+            },
+          } as const
+        }
+      }
+    }
+    default:
+      return invalidResponse()
+  }
+}
+
+function eventProgress(value: unknown): number {
+  return typeof value == 'number' && Number.isFinite(value) && value >= 0 && value <= 100 ? value : invalidResponse()
+}
+
+function runEvents(value: unknown): RunEvents {
+  const source = record(value)
+  const eventsExpiresAt = source.eventsExpiresAt
+  const nextAfter = integer(source.nextAfter)
+  if (source.version != 1 || !Array.isArray(source.events) || typeof source.done != 'boolean' || typeof source.historyComplete != 'boolean') {
+    return invalidResponse()
+  }
+  if (eventsExpiresAt != null && typeof eventsExpiresAt != 'string') return invalidResponse()
+  if (nextAfter < 0) return invalidResponse()
+  return {
+    done: source.done,
+    events: source.events.map(decodeRunEvent),
+    ...(eventsExpiresAt == null ? {} : { eventsExpiresAt }),
+    historyComplete: source.historyComplete,
+    nextAfter,
+    runId: string(source.runId),
+    version: 1,
+  }
+}
+
+const segment = encodeURIComponent
+
+function operationKey(operation: string): string {
+  return `${operation}-${randomId()}`
+}
+
+export type ConditionalResult<T> =
+  | { readonly modified: true; readonly data: T; readonly etag: string | null }
+  | { readonly modified: false; readonly etag: string | null }
+
+export class ControlClient {
+  private readonly requestControl: ControlRequest
+  private readonly channel: 'workbench' | 'cli' | 'api'
+
+  constructor(requestControl: ControlRequest, channel: 'workbench' | 'cli' | 'api' = 'api') {
+    this.channel = channel
+    this.requestControl = requestControl
+  }
+
+  async loadOpenApiDocument(url: string, signal?: AbortSignal): Promise<JsonValue> {
+    const result = record(await this.request('/v1/openapi/document', { method: 'POST', body: JSON.stringify({ url, version: 1 }), signal }))
+    if (result.version != 1) return invalidResponse()
+    return jsonValue(result.document)
+  }
+
+  async listFlows(
+    options: { readonly cursor?: string; readonly includeTotal?: boolean; readonly limit?: number; readonly signal?: AbortSignal } = {},
+  ): Promise<FlowPage> {
+    const parameters = new URLSearchParams()
+    if (options.cursor != null) parameters.set('cursor', options.cursor)
+    if (options.limit != null) parameters.set('limit', String(options.limit))
+    if (options.includeTotal != null) parameters.set('includeTotal', String(options.includeTotal))
+    const query = parameters.size == 0 ? '' : `?${parameters}`
+    return flowPage(await this.request(`/v1/flows${query}`, options.signal == null ? undefined : { signal: options.signal }))
+  }
+
+  async listEventSources(
+    flowId?: string,
+    signal?: AbortSignal,
+  ): Promise<{ readonly version: 1; readonly sources: readonly EventSource[]; readonly teamId?: string | null }> {
+    return decodeEventSources(await this.request('/v1/event-sources' + (flowId == null ? '' : `?flowId=${segment(flowId)}`), { signal }))
+  }
+
+  async listEventSourceConnections(
+    teamId: string | null,
+    signal?: AbortSignal,
+    kind: 'feishu' | 'slack' | 'intercom' | 'sentry' | 'zoom' | 'fireflies' | 'jira' = 'feishu',
+  ): Promise<readonly ConnectorConnection[]> {
+    const source = record(await this.request(`/v1/event-sources/connections?kind=${kind}${teamId == null ? '' : `&teamId=${segment(teamId)}`}`, { signal }))
+    requiredFields(source, ['version', 'connections'])
+    if (source.version != 1 || !Array.isArray(source.connections)) return invalidResponse()
+    return source.connections.map(connection)
+  }
+
+  async createEventSource(input: CreateEventSource): Promise<EventSource> {
+    return decodeEventSource(await this.request('/v1/event-sources', { method: 'POST', body: JSON.stringify(input) }))
+  }
+
+  async updateEventSource(sourceId: string, input: UpdateEventSource): Promise<EventSource> {
+    return decodeEventSource(await this.request(`/v1/event-sources/${segment(sourceId)}`, { method: 'PUT', body: JSON.stringify(input) }))
+  }
+
+  async deleteEventSource(sourceId: string, expectedRevision: number): Promise<void> {
+    await this.request(`/v1/event-sources/${segment(sourceId)}`, { method: 'DELETE', body: JSON.stringify({ version: 1, expectedRevision }) })
+  }
+
+  async listVariables(): Promise<{ readonly variables: readonly VariableListItem[]; readonly version: 1 }> {
+    const source = record(await this.request('/v1/variables'))
+    requiredFields(source, ['variables', 'version'])
+    if (source.version != 1 || !Array.isArray(source.variables)) return invalidResponse()
+    return { variables: source.variables.map(variableListItem), version: 1 }
+  }
+
+  async getFlowReferences(flowId: string, options: { direction?: 'incoming' | 'outgoing'; offset?: number; limit?: number; signal?: AbortSignal } = {}) {
+    const query = new URLSearchParams({ direction: options.direction ?? 'incoming', offset: String(options.offset ?? 0), limit: String(options.limit ?? 50) })
+    return workflowReferencesSchema.parse(await this.request(`/v1/flows/${segment(flowId)}/references?${query}`, { signal: options.signal }))
+  }
+
+  async getWorkflowContract(flowId: string, signal?: AbortSignal) {
+    return workflowContractSchema.parse(await this.request(`/v1/flows/${segment(flowId)}/call-contract`, { signal }))
+  }
+
+  async getVariableReferences(name: string, signal?: AbortSignal): Promise<VariableReferences> {
+    return variableReferences(await this.request(`/v1/variables/${segment(name)}/references`, { signal }))
+  }
+
+  async getVariable(name: string): Promise<Variable> {
+    return variable(await this.request(`/v1/variables/${segment(name)}`))
+  }
+
+  async putVariable(name: string, value: string): Promise<Variable> {
+    return variable(
+      await this.request(`/v1/variables/${segment(name)}`, {
+        body: JSON.stringify({ value }),
+        method: 'PUT',
+      }),
+    )
+  }
+
+  async deleteVariable(name: string): Promise<void> {
+    const source = record(await this.request(`/v1/variables/${segment(name)}`, { method: 'DELETE' }))
+    requiredFields(source, ['version'])
+    if (source.version != 1) return invalidResponse()
+  }
+
+  async exportFlow(flowId: string): Promise<WorkflowFile> {
+    const value = await this.request(`/v1/flows/${segment(flowId)}/export`)
+    try {
+      return decodeWorkflowFile(value)
+    } catch {
+      return invalidResponse()
+    }
+  }
+
+  async importFlow(file: WorkflowFile, options: { readonly name?: string; readonly teamId?: string; readonly idempotencyKey?: string } = {}): Promise<Flow> {
+    return flow(
+      await this.request('/v1/flows/import', {
+        method: 'POST',
+        headers: { 'Idempotency-Key': options.idempotencyKey ?? `flow-${randomId()}` },
+        body: JSON.stringify({ file, name: options.name, teamId: options.teamId, version: 1 }),
+      }),
+    )
+  }
+
+  async createFlow(name: string, idempotencyKey = `flow-${randomId()}`, teamId?: string): Promise<Flow> {
+    return flow(
+      await this.request('/v1/flows', {
+        body: JSON.stringify({ name, ...(teamId == null ? {} : { teamId }), version: 1 }),
+        headers: { 'idempotency-key': idempotencyKey },
+        method: 'POST',
+      }),
+    )
+  }
+
+  async broadcastCanvas(flowId: string, command: CanvasCommand): Promise<CanvasBroadcast> {
+    const source = record(
+      await this.request(`/v1/flows/${segment(flowId)}/canvas`, {
+        method: 'POST',
+        body: JSON.stringify({ version: 1, command }),
+      }),
+    )
+    requiredFields(source, ['version', 'flowId', 'broadcast'])
+    if (source.version != 1 || source.broadcast !== true || source.flowId !== flowId) return invalidResponse()
+    return { version: 1, flowId: string(source.flowId), broadcast: true }
+  }
+
+  async getFlow(flowId: string): Promise<Flow> {
+    return flow(await this.request(`/v1/flows/${segment(flowId)}`))
+  }
+
+  async getErrorListeners(flowId: string, signal?: AbortSignal): Promise<readonly ErrorListener[]> {
+    const source = record(await this.request(`/v1/flows/${segment(flowId)}/error-listeners`, { signal }))
+    if (source.version != 1 || !Array.isArray(source.listeners)) return invalidResponse()
+    return source.listeners.map(errorListener)
+  }
+
+  async renameFlow(flowId: string, name: string): Promise<Flow> {
+    return flow(
+      await this.request(`/v1/flows/${segment(flowId)}`, {
+        body: JSON.stringify({ name, version: 1 }),
+        method: 'PATCH',
+      }),
+    )
+  }
+
+  async deleteFlow(flowId: string): Promise<Flow> {
+    return flow(await this.request(`/v1/flows/${segment(flowId)}`, { method: 'DELETE' }))
+  }
+
+  async listTriggerKeys(signal?: AbortSignal, locale?: string): Promise<readonly TriggerKeySummary[]> {
+    const source = record(await this.request(`/v1/trigger-keys${locale == null ? '' : `?locale=${encodeURIComponent(locale)}`}`, { signal }))
+    if (source.version != 1 || !Array.isArray(source.keys)) return invalidResponse()
+    return source.keys.map(triggerKeySummary)
+  }
+
+  async listTriggerDefinitions(signal?: AbortSignal): Promise<readonly TriggerKeySnapshot[]> {
+    const source = record(await this.request('/v1/trigger-keys/catalog', { signal }))
+    if (source.version != 2 || !Array.isArray(source.definitions)) return invalidResponse()
+    return source.definitions.map(triggerKey)
+  }
+
+  async readCatalog<T>(
+    query: { readonly path: string; readonly decode: (data: unknown) => T },
+    etag: string | null,
+    signal?: AbortSignal,
+  ): Promise<ConditionalResult<T>> {
+    const headers = new Headers()
+    if (etag) headers.set('if-none-match', etag)
+    const response = await this.response(query.path, { headers, signal }, true)
+    const nextETag = response.headers.get('etag')?.trim() || null
+    if (response.status == 304) return { modified: false, etag: nextETag }
+    return { modified: true, data: query.decode(await response.json()), etag: nextETag }
+  }
+
+  async getTriggerCatalog(locale: string, cached?: TriggerCatalogCache, signal?: AbortSignal): Promise<TriggerCatalogCache> {
+    const headers = new Headers()
+    if (cached?.etag) headers.set('if-none-match', cached.etag)
+    const response = await this.response(`/v1/trigger-keys/catalog?locale=${encodeURIComponent(locale)}`, { headers, signal }, true)
+    if (response.status == 304) {
+      if (cached == null) return invalidResponse()
+      return { ...cached, etag: response.headers.get('etag')?.trim() || cached.etag }
+    }
+    return { data: decodeTriggerCatalog(await response.json()), etag: response.headers.get('etag')?.trim() || null }
+  }
+
+  async getTriggerKey(key: string, signal?: AbortSignal): Promise<TriggerKeySnapshot> {
+    const source = record(await this.request(`/v1/trigger-keys/${segment(key)}`, { signal }))
+    if (source.version != 1) return invalidResponse()
+    return triggerKey(source.definition)
+  }
+
+  async listFlowTriggerBindings(flowId: string, signal?: AbortSignal): Promise<readonly TriggerBinding[]> {
+    const source = record(await this.request(`/v1/flows/${segment(flowId)}/triggers`, { signal }))
+    if (source.version != 1 || string(source.flowId) != flowId || !Array.isArray(source.bindings)) {
+      return invalidResponse()
+    }
+    return source.bindings.map(triggerBinding)
+  }
+
+  async getFlowTriggerBinding(flowId: string, triggerNodeId: string): Promise<TriggerBindingDetail> {
+    return triggerBindingDetail(await this.request(`/v1/flows/${segment(flowId)}/triggers/${segment(triggerNodeId)}`))
+  }
+
+  async listFlowTriggerActivities(
+    flowId: string,
+    triggerNodeId: string,
+    options: { readonly cursor?: string; readonly limit?: number } = {},
+  ): Promise<TriggerActivityPage> {
+    const parameters = new URLSearchParams()
+    if (options.cursor != null) parameters.set('cursor', options.cursor)
+    if (options.limit != null) parameters.set('limit', String(options.limit))
+    const query = parameters.size == 0 ? '' : `?${parameters}`
+    return triggerActivityPage(await this.request(`/v1/flows/${segment(flowId)}/triggers/${segment(triggerNodeId)}/activities${query}`))
+  }
+
+  async testFlowPollTrigger(flowId: string, triggerNodeId: string): Promise<PollTriggerTestResult> {
+    return pollTriggerTestResult(
+      await this.request(`/v1/flows/${segment(flowId)}/triggers/${segment(triggerNodeId)}/test`, {
+        body: JSON.stringify({ version: 1 }),
+        method: 'POST',
+      }),
+    )
+  }
+
+  async getEditor(
+    flowId: string,
+  ): Promise<{ readonly flow: Flow; readonly draft: Draft; readonly live: Live; readonly presentation: Presentation; readonly version: 1 }> {
+    const source = record(await this.request(`/v1/flows/${segment(flowId)}/editor`))
+    if (source.version != 1) return invalidResponse()
+    const result = {
+      flow: flow(source.flow),
+      draft: draft(source.draft),
+      live: live(source.live),
+      presentation: presentation(source.presentation),
+      version: 1 as const,
+    }
+    if (result.flow.flowId != flowId || result.draft.flowId != flowId || result.live.flowId != flowId || result.flow.draftRevisionId != result.draft.revisionId)
+      return invalidResponse()
+    return result
+  }
+
+  async getPublicationPresentation(flowId: string, publicationId: string, signal?: AbortSignal): Promise<PublicationPresentation> {
+    const source = record(await this.request(`/v1/flows/${segment(flowId)}/publications/${segment(publicationId)}/presentation`, { signal }))
+    if (source.version != 1) return invalidResponse()
+    return { version: 1, presentation: source.presentation === null ? null : presentation(source.presentation) }
+  }
+
+  async getPresentation(flowId: string): Promise<Presentation> {
+    return presentation(await this.request(`/v1/flows/${segment(flowId)}/presentation`))
+  }
+
+  async getDraft(flowId: string): Promise<Draft> {
+    return draft(await this.request(`/v1/flows/${segment(flowId)}/draft`))
+  }
+
+  async syncDraft(flowId: string): Promise<DraftSync> {
+    return draftSync(await this.request(`/v1/flows/${segment(flowId)}/draft/sync`))
+  }
+
+  async getRevision(flowId: string, revisionId: string, signal?: AbortSignal): Promise<Draft> {
+    return draft(await this.request(`/v1/flows/${segment(flowId)}/revisions/${segment(revisionId)}`, { signal }))
+  }
+
+  async listTriggerConfigOptions(flowId: string, nodeId: string, field: string, signal?: AbortSignal): Promise<readonly TriggerConfigOption[]> {
+    const source = record(await this.request(`/v1/flows/${segment(flowId)}/triggers/${segment(nodeId)}/options/${segment(field)}`, { signal }))
+    requiredFields(source, ['options', 'version'])
+    if (source.version != 1 || !Array.isArray(source.options) || source.options.length > 1000) return invalidResponse()
+    return source.options.map((value) => {
+      const item = record(value)
+      requiredFields(item, ['value', 'label', ...(item.color == null ? [] : ['color'])])
+      const color = item.color == null ? undefined : string(item.color)
+      if (color != null && !/^#[0-9a-fA-F]{6}$/.test(color)) return invalidResponse()
+      return color == null ? { value: string(item.value), label: string(item.label) } : { value: string(item.value), label: string(item.label), color }
+    })
+  }
+
+  async listConnectorTeams(signal?: AbortSignal) {
+    const source = record(await this.request('/v1/connector/teams', { signal }))
+    requiredFields(source, ['enabled', 'teams', 'version'])
+    if (source.version != 1 || typeof source.enabled != 'boolean' || !Array.isArray(source.teams)) return invalidResponse()
+    return {
+      enabled: source.enabled,
+      teams: source.teams.map((value: unknown) => {
+        const team = record(value)
+        requiredFields(team, ['id', 'name', 'systemCreated'])
+        if (typeof team.systemCreated != 'boolean') return invalidResponse()
+        return { id: string(team.id), name: string(team.name), systemCreated: team.systemCreated }
+      }),
+      version: 1 as const,
+    }
+  }
+
+  async listConnectorProviders(signal?: AbortSignal, flowId?: string, locale?: string): Promise<readonly ConnectorProvider[]> {
+    const query = connectorProvidersQuery(flowId, locale)
+    return this.connectorRequest(query.path, 'providers', signal, query.decode)
+  }
+
+  async listLeinaBots(flowId: string, signal?: AbortSignal): Promise<readonly LeinaBot[]> {
+    return leinaBots(await this.request(`/v1/connector/leina/bots?flowId=${segment(flowId)}`, { signal }))
+  }
+
+  async removeConnectionUsage(
+    flowId: string,
+    connectionId: string,
+    expectedRevisionId: string,
+    expectedAccessRevision: number,
+    idempotencyKey: string,
+  ): Promise<DraftChange> {
+    return draftChange(
+      await this.request(`/v1/flows/${segment(flowId)}/connection-usage/remove`, {
+        method: 'POST',
+        headers: { 'idempotency-key': idempotencyKey },
+        body: JSON.stringify({ connectionId, expectedRevisionId, expectedAccessRevision, version: 1 }),
+      }),
+    )
+  }
+
+  async getConnectorAccess(flowId: string, signal?: AbortSignal): Promise<ConnectorAccess> {
+    return connectorAccess(await this.request(`/v1/flows/${segment(flowId)}/connector-access`, { signal }))
+  }
+
+  async getPublishedConnectorAccess(flowId: string, publicationId: string, signal?: AbortSignal): Promise<ConnectorAccessSnapshot> {
+    return connectorAccessSnapshot(await this.request(`/v1/flows/${segment(flowId)}/connector-access?publicationId=${segment(publicationId)}`, { signal }))
+  }
+
+  async listProviderAccessBindingCandidates(flowId: string, providerIds: readonly string[], signal?: AbortSignal): Promise<ConnectorAccessCandidatesBatch> {
+    return connectorAccessCandidatesBatch(
+      await this.request(`/v1/flows/${segment(flowId)}/connector-access/candidates/query`, {
+        method: 'POST',
+        body: JSON.stringify({ providerIds, version: 1 }),
+        signal,
+      }),
+      providerIds,
+    )
+  }
+
+  async setConnectorService(flowId: string, providerId: string, selected: boolean, expectedAccessRevision: number): Promise<ConnectorAccess> {
+    return connectorAccess(
+      await this.request(`/v1/flows/${segment(flowId)}/connector-access/${segment(providerId)}/service`, {
+        body: JSON.stringify({ expectedAccessRevision, version: 1 }),
+        method: selected ? 'PUT' : 'DELETE',
+      }),
+    )
+  }
+
+  async addProviderAccessBinding(flowId: string, providerId: string, accessBindingId: string, expectedAccessRevision: number): Promise<ConnectorAccess> {
+    return connectorAccess(
+      await this.request(`/v1/flows/${segment(flowId)}/connector-access/${segment(providerId)}`, {
+        body: JSON.stringify({ accessBindingId, expectedAccessRevision, version: 1 }),
+        method: 'PUT',
+      }),
+    )
+  }
+
+  async removeProviderAccessBinding(flowId: string, providerId: string, accessBindingId: string, expectedAccessRevision: number): Promise<ConnectorAccess> {
+    return connectorAccess(
+      await this.request(`/v1/flows/${segment(flowId)}/connector-access/${segment(providerId)}`, {
+        body: JSON.stringify({ accessBindingId, expectedAccessRevision, version: 1 }),
+        method: 'DELETE',
+      }),
+    )
+  }
+
+  async listConnectorActions(serviceId?: string, signal?: AbortSignal, flowId?: string, locale?: string): Promise<readonly ConnectorAction[]> {
+    return await this.connectorActions(
+      { ...(locale == null ? {} : { locale }), ...(flowId == null ? {} : { flowId }), ...(serviceId == null ? {} : { service: serviceId }) },
+      signal,
+    )
+  }
+
+  async searchConnectorActions(query: string, signal?: AbortSignal, flowId?: string, locale?: string): Promise<readonly ConnectorAction[]> {
+    return await this.connectorActions({ ...(locale == null ? {} : { locale }), ...(flowId == null ? {} : { flowId }), q: query.trim() }, signal)
+  }
+
+  async getConnectorAction(actionId: string, signal?: AbortSignal, flowId?: string, locale?: string, fresh = false): Promise<ConnectorAction> {
+    const query = connectorActionQuery(actionId, flowId, locale)
+    return this.connectorRequest(query.path, 'actions', signal, query.decode, fresh)
+  }
+
+  async listAllConnectorConnections(signal?: AbortSignal, flowId?: string, fresh = false): Promise<readonly ConnectorConnection[]> {
+    const query = allConnectorConnectionsQuery(flowId)
+    return this.connectorRequest(query.path, 'connections', signal, query.decode, fresh)
+  }
+
+  async listConnectorConnections(serviceId: string, signal?: AbortSignal, flowId?: string, fresh = false): Promise<readonly ConnectorConnection[]> {
+    const query = connectorConnectionsQuery(serviceId, flowId)
+    return this.connectorRequest(query.path, 'connections', signal, query.decode, fresh)
+  }
+
+  async createConnectorConnectionPage(serviceId: string, flowId?: string, teamId?: string): Promise<string> {
+    const parameters = new URLSearchParams()
+    if (flowId != null) parameters.set('flowId', flowId)
+    if (teamId != null) parameters.set('teamId', teamId)
+    const source = record(
+      await this.request(`/v1/connector/connections/${segment(serviceId)}/page${parameters.size == 0 ? '' : `?${parameters}`}`, {
+        body: JSON.stringify({ version: 1 }),
+        method: 'POST',
+      }),
+    )
+    requiredFields(source, ['url', 'version'])
+    if (source.version != 1) return invalidResponse()
+    try {
+      const url = new URL(string(source.url))
+      if (url.protocol != 'http:' && url.protocol != 'https:') return invalidResponse()
+      return url.href
+    } catch {
+      return invalidResponse()
+    }
+  }
+
+  async readAuthoring(flowId: string, query: AuthoringRead = {}) {
+    return authoringReadResponse.parse(await this.request(`/v1/flows/${segment(flowId)}/authoring/read`, { method: 'POST', body: JSON.stringify(query) }))
+  }
+
+  async searchAuthoring(flowId: string, query: AuthoringSearch) {
+    return authoringSearchResponse.parse(await this.request(`/v1/flows/${segment(flowId)}/authoring/search`, { method: 'POST', body: JSON.stringify(query) }))
+  }
+
+  async authoringSchema(flowId: string, query: { type?: AuthoringType; action?: string }) {
+    return record(await this.request(`/v1/flows/${segment(flowId)}/authoring/schema`, { method: 'POST', body: JSON.stringify(query) }))
+  }
+
+  async editAuthoring(flowId: string, request: AuthoringRequest) {
+    return authoringEditResponse.parse(
+      await this.request(`/v1/flows/${segment(flowId)}/authoring/edit`, {
+        method: 'POST',
+        headers: { 'idempotency-key': request.requestId },
+        body: JSON.stringify(request),
+      }),
+    )
+  }
+
+  async checkAuthoring(flowId: string, revisionId: string) {
+    return authoringCheckResponse.parse(
+      await this.request(`/v1/flows/${segment(flowId)}/authoring/check`, { method: 'POST', body: JSON.stringify({ revisionId }) }),
+    )
+  }
+
+  async changeDraft(
+    flowId: string,
+    expectedRevisionId: string,
+    operations: readonly DraftOperation[],
+    changeId = operationKey('change'),
+  ): Promise<DraftChange> {
+    return draftChange(
+      await this.request(`/v1/flows/${segment(flowId)}/draft/changes`, {
+        body: JSON.stringify({ expectedRevisionId, operations, version: 1 }),
+        headers: { 'idempotency-key': changeId },
+        method: 'POST',
+      }),
+    )
+  }
+
+  async repairDraft(flowId: string, expectedRevisionId: string, changeId = operationKey('repair')): Promise<DraftChange> {
+    return draftChange(
+      await this.request(`/v1/flows/${segment(flowId)}/draft/repair`, {
+        body: JSON.stringify({ expectedRevisionId, version: 1 }),
+        headers: { 'idempotency-key': changeId },
+        method: 'POST',
+      }),
+    )
+  }
+
+  async upgradeDraft(flowId: string, expectedRevisionId: string, options: { readonly idempotencyKey?: string } = {}): Promise<DraftChange> {
+    return draftChange(
+      await this.request(`/v1/flows/${segment(flowId)}/draft/upgrade`, {
+        body: JSON.stringify({ expectedRevisionId, version: 1 }),
+        headers: { 'idempotency-key': options.idempotencyKey ?? operationKey('upgrade') },
+        method: 'POST',
+      }),
+    )
+  }
+
+  async checkFlow(flowId: string, revisionId: string): Promise<FlowCheck> {
+    return flowCheck(
+      await this.request(`/v1/flows/${segment(flowId)}/revisions/${segment(revisionId)}/check`, {
+        body: JSON.stringify({ engineContract: currentEngineContract, version: 1 }),
+        method: 'POST',
+      }),
+    )
+  }
+
+  async getLiveDetails(flowId: string, signal?: AbortSignal): Promise<LiveDetails> {
+    const details = decodeLiveDetails(await this.request(`/v1/flows/${segment(flowId)}/live/details`, { signal }))
+    if (details.flowId != flowId) return invalidResponse()
+    return details
+  }
+
+  async getLive(flowId: string, signal?: AbortSignal): Promise<Live> {
+    return live(await this.request(`/v1/flows/${segment(flowId)}/live`, { signal }))
+  }
+
+  async listPublications(
+    flowId: string,
+    options: { readonly cursor?: string; readonly includeTotal?: boolean; readonly limit?: number } = {},
+    signal?: AbortSignal,
+  ): Promise<PublicationPage> {
+    const parameters = new URLSearchParams()
+    if (options.cursor != null) parameters.set('cursor', options.cursor)
+    if (options.limit != null) parameters.set('limit', String(options.limit))
+    if (options.includeTotal != null) parameters.set('includeTotal', String(options.includeTotal))
+    const query = parameters.size == 0 ? '' : `?${parameters}`
+    return publicationPage(await this.request(`/v1/flows/${segment(flowId)}/publications${query}`, { signal }))
+  }
+
+  async createDraftRun(flowId: string, revisionId: string, options: RunOptions): Promise<DraftRun> {
+    const created = runDetails(
+      await this.request(`/v1/flows/${segment(flowId)}/revisions/${segment(revisionId)}/runs`, {
+        body: JSON.stringify({ engineContract: currentEngineContract, inputs: options.inputs ?? {}, trigger: options.trigger, version: 2 }),
+        headers: { 'idempotency-key': options.idempotencyKey ?? operationKey('run'), 'x-open-flow-client': this.channel },
+        method: 'POST',
+      }),
+    )
+    return created.source == 'draft' ? created : invalidResponse()
+  }
+
+  async createLiveRun(publicationId: string, options: RunOptions): Promise<LiveRun> {
+    const created = runDetails(
+      await this.request('/v1/runs', {
+        body: JSON.stringify({ inputs: options.inputs ?? {}, trigger: options.trigger, publicationId, version: 2 }),
+        headers: { 'idempotency-key': options.idempotencyKey ?? operationKey('run'), 'x-open-flow-client': this.channel },
+        method: 'POST',
+      }),
+    )
+    return created.source == 'live' ? created : invalidResponse()
+  }
+
+  async setFlowEnabled(flowId: string, publicationId: string, enabled: boolean): Promise<Flow> {
+    return flow(
+      await this.request(`/v1/flows/${segment(flowId)}/enabled`, {
+        method: 'PUT',
+        body: JSON.stringify({ enabled, expectedPublicationId: publicationId, version: 1 }),
+      }),
+    )
+  }
+
+  async publishFlow(flowId: string, revisionId: string, expectedLivePublicationId: string | null, options: PublicationOptions = {}): Promise<PublishOperation> {
+    return publishOperation(
+      await this.request(`/v1/flows/${segment(flowId)}/revisions/${segment(revisionId)}/publications`, {
+        body: JSON.stringify({ engineContract: currentEngineContract, expectedLivePublicationId, version: 1 }),
+        headers: { 'idempotency-key': options.idempotencyKey ?? operationKey('publication') },
+        method: 'POST',
+      }),
+    )
+  }
+
+  async getPublishOperation(flowId: string, operationId: string, signal?: AbortSignal): Promise<PublishOperation> {
+    return publishOperation(await this.request(`/v1/flows/${segment(flowId)}/publish-operations/${segment(operationId)}`, { signal }))
+  }
+
+  async rollbackFlow(flowId: string, publicationId: string, expectedLivePublicationId: string, options: PublicationOptions = {}): Promise<Publication> {
+    return publication(
+      await this.request(`/v1/flows/${segment(flowId)}/publications/${segment(publicationId)}/rollback`, {
+        body: JSON.stringify({ expectedLivePublicationId, version: 1 }),
+        headers: { 'idempotency-key': options.idempotencyKey ?? operationKey('publication') },
+        method: 'POST',
+      }),
+    )
+  }
+
+  async getRun(runId: string, signal?: AbortSignal): Promise<RunDetails> {
+    return runDetails(await this.request(`/v1/runs/${segment(runId)}`, { signal }))
+  }
+
+  async listRuns(
+    flowId: string,
+    options: {
+      readonly createdBefore?: string
+      readonly createdFrom?: string
+      readonly cursor?: string
+      readonly limit?: number
+      readonly pendingWait?: boolean
+      readonly runId?: string
+      readonly source?: Run['source']
+      readonly status?: RunStatus
+    } = {},
+  ): Promise<RunPage> {
+    const parameters = new URLSearchParams()
+    if (options.cursor != null) parameters.set('cursor', options.cursor)
+    if (options.limit != null) parameters.set('limit', String(options.limit))
+    if (options.status != null) parameters.set('status', options.status)
+    if (options.pendingWait != null) parameters.set('pendingWait', String(options.pendingWait))
+    if (options.source != null) parameters.set('source', options.source)
+    if (options.createdFrom != null) parameters.set('createdFrom', options.createdFrom)
+    if (options.createdBefore != null) parameters.set('createdBefore', options.createdBefore)
+    if (options.runId != null) parameters.set('runId', options.runId)
+    const query = parameters.size == 0 ? '' : `?${parameters}`
+    return runPage(await this.request(`/v1/flows/${segment(flowId)}/runs${query}`))
+  }
+
+  async getRunEvents(runId: string, options: { readonly after?: number; readonly limit?: number } = {}, signal?: AbortSignal): Promise<RunEvents> {
+    const parameters = new URLSearchParams()
+    if (options.after != null) parameters.set('after', String(options.after))
+    if (options.limit != null) parameters.set('limit', String(options.limit))
+    const query = parameters.size == 0 ? '' : `?${parameters}`
+    return runEvents(await this.request(`/v1/runs/${segment(runId)}/events${query}`, { signal }))
+  }
+
+  async listRunResults(runId: string, after?: string, signal?: AbortSignal): Promise<ReturnType<typeof decodeResultList>> {
+    return decodeResultList(await this.request(`/v1/runs/${segment(runId)}/results${after == null ? '' : `?after=${encodeURIComponent(after)}`}`, { signal }))
+  }
+
+  async readRunResult(runId: string, resultId: string, options: ResultQuery = {}, signal?: AbortSignal): Promise<ReturnType<typeof decodeResultRead>> {
+    const parameters = new URLSearchParams(Object.entries(options).map(([key, value]) => [key, String(value)]))
+    return decodeResultRead(await this.request(`/v1/runs/${segment(runId)}/results/${segment(resultId)}?${parameters}`, { signal }))
+  }
+
+  async downloadRunResult(runId: string, resultId: string, signal?: AbortSignal): Promise<Blob> {
+    return (await this.response(`/v1/runs/${segment(runId)}/results/${segment(resultId)}/content`, { signal })).blob()
+  }
+
+  async getRunResult(runId: string, signal?: AbortSignal): Promise<RunResult> {
+    return runResult(await this.request(`/v1/runs/${segment(runId)}/result`, { signal }))
+  }
+
+  async cancelRun(runId: string): Promise<RunCancellation> {
+    return runCancellation(
+      await this.request(`/v1/runs/${segment(runId)}/cancel`, {
+        body: JSON.stringify({ version: 1 }),
+        method: 'POST',
+      }),
+    )
+  }
+
+  async resolveRunWait(
+    runId: string,
+    waitId: string,
+    action: WaitAction,
+    comment?: string | null,
+  ): Promise<{
+    readonly action: WaitAction | null
+    readonly comment: string | null
+    readonly resolutionAccepted: boolean
+    readonly resolvedAt: string | null
+    readonly runId: string
+    readonly status: RunStatus
+    readonly version: 1
+    readonly waitId: string
+  }> {
+    return waitResolution(
+      await this.request(`/v1/runs/${segment(runId)}/waits/${segment(waitId)}/resolve`, {
+        body: JSON.stringify({ action, comment, version: 1 }),
+        method: 'POST',
+      }),
+    )
+  }
+
+  private async connectorActions(parameters: Readonly<Record<string, string>>, signal?: AbortSignal): Promise<readonly ConnectorAction[]> {
+    const query = Object.entries(parameters)
+      .map(([key, value]) => `${segment(key)}=${segment(value)}`)
+      .join('&')
+    const suffix = query == '' ? '' : `?${query}`
+    return this.connectorRequest(`/v1/connector/actions${suffix}`, 'actions', signal, (value) => {
+      const source = record(value)
+      requiredFields(source, ['actions', 'version'])
+      if (source.version != 1 || !Array.isArray(source.actions)) return invalidResponse()
+      return source.actions.map(connectorAction)
+    })
+  }
+
+  protected async connectorRequest<Value>(
+    path: string,
+    _kind: 'providers' | 'actions' | 'connections',
+    signal: AbortSignal | undefined,
+    decode: (value: unknown) => Value,
+    _fresh = false,
+  ): Promise<Value> {
+    return decode(await this.request(path, { signal }))
+  }
+
+  protected async response(path: string, init: RequestInit, allowNotModified = false): Promise<Response> {
+    const headers = new Headers(init.headers)
+    if (init.body != null) headers.set('content-type', 'application/json')
+    const response = await this.requestControl(path, { ...init, headers })
+    if (!response.ok && !(allowNotModified && response.status == 304)) {
+      let value: unknown
+      try {
+        value = await response.json()
+      } catch {
+        return invalidResponse()
+      }
+      const error = record(value).error
+      const source = error == null ? undefined : record(error)
+      throw new ApiError(
+        response.status,
+        typeof source?.code == 'string' ? source.code : 'request.failed',
+        typeof source?.message == 'string' ? source.message : `Request failed with status ${response.status}.`,
+        source?.details == null ? undefined : record(source.details),
+      )
+    }
+    return response
+  }
+
+  protected async request<Value = unknown>(path: string, init: RequestInit = {}): Promise<Value> {
+    const response = await this.response(path, init)
+    try {
+      return (await response.json()) as Value
+    } catch {
+      return invalidResponse()
+    }
+  }
+}