@oomol-lab/open-flow 0.1.0-beta.72 → 0.1.0-beta.74

package/src/control/common/connectorDecoders.ts

@@ -0,0 +1,370 @@
+import type { InputPortDefinition } from '../../flow/common/change.ts'
+import type {
+  ConnectorAccess,
+  ConnectorAccessSnapshot,
+  ConnectorAccessGrant,
+  ConnectorAccessCandidates,
+  ConnectorAccessCandidatesBatch,
+  ConnectorAction,
+  ConnectorActionMetadata,
+  ConnectorConnection,
+  ConnectorProvider,
+  LeinaBot,
+  ProviderAccessBinding,
+  ProviderAccessBindingCandidate,
+} from './api.ts'
+
+import { exact, requiredFields, integer, invalidResponse, jsonValue, record, string } from './decoding.ts'
+import { ApiError } from './errors.ts'
+import { parseProviderAccessSource } from './providerAccess.ts'
+import { providerIconAppearance } from './providerIconSprite.ts'
+
+export function leinaBots(value: unknown): readonly LeinaBot[] {
+  const source = record(value)
+  if (!Array.isArray(source.bots)) return invalidResponse('Leina bots: expected an array.')
+  const bots = source.bots.map((entry) => {
+    const bot = record(entry)
+    if (!Array.isArray(bot.platforms)) return invalidResponse('Leina platforms: expected an array.')
+    return { leinaId: string(bot.leinaId), name: string(bot.name), status: string(bot.status), platforms: bot.platforms.map(string) }
+  })
+  if (new Set(bots.map((bot) => bot.leinaId)).size != bots.length) return invalidResponse('Leina bots: duplicate identifiers.')
+  return bots
+}
+
+function accessPermissions(value: unknown): NonNullable<ProviderAccessBindingCandidate['permissions']> {
+  const source = record(value)
+  exact(source, ['actionIds', 'allActions', 'triggerIds', 'allTriggers', 'configured', 'proxy'])
+  if (!Array.isArray(source.actionIds)) return invalidResponse('permissions.actionIds: expected an array.')
+  if (!Array.isArray(source.triggerIds)) return invalidResponse('permissions.triggerIds: expected an array.')
+  if (typeof source.allActions != 'boolean') return invalidResponse('permissions.allActions: expected a boolean.')
+  if (typeof source.allTriggers != 'boolean') return invalidResponse('permissions.allTriggers: expected a boolean.')
+  if (typeof source.configured != 'boolean') return invalidResponse('permissions.configured: expected a boolean.')
+  if (typeof source.proxy != 'boolean') return invalidResponse('permissions.proxy: expected a boolean.')
+  const actionIds = source.actionIds.map(string)
+  const triggerIds = source.triggerIds.map(string)
+  if (new Set(actionIds).size != actionIds.length) return invalidResponse('permissions.actionIds: duplicate IDs.')
+  if (source.allActions && actionIds.length != 0) return invalidResponse('permissions.actionIds: must be empty when allActions is true.')
+  if (new Set(triggerIds).size != triggerIds.length) return invalidResponse('permissions.triggerIds: duplicate IDs.')
+  if (source.allTriggers && triggerIds.length != 0) return invalidResponse('permissions.triggerIds: must be empty when allTriggers is true.')
+  if (source.proxy && (!source.allActions || !source.allTriggers || source.configured)) {
+    return invalidResponse('permissions.proxy: requires allActions=true, allTriggers=true and configured=false.')
+  }
+  return { actionIds, triggerIds, allTriggers: source.allTriggers, allActions: source.allActions, configured: source.configured, proxy: source.proxy }
+}
+
+function accessBinding(value: unknown, candidate: true): ProviderAccessBindingCandidate
+function accessBinding(value: unknown, candidate: false): ProviderAccessBinding
+function accessBinding(value: unknown, candidate: boolean): ProviderAccessBinding | ProviderAccessBindingCandidate {
+  const source = record(value)
+  const policyRevision = source.policyRevision
+  const status = source.status
+  const isDefault = source.isDefault
+  const legacy = Object.hasOwn(source, 'displayName') && !Object.hasOwn(source, 'connectionDisplayName')
+  const permissions = candidate && Object.hasOwn(source, 'permissions') ? accessPermissions(source.permissions) : undefined
+  const permissionGroupName = source.permissionGroupName
+  exact(source, [
+    'accessBindingId',
+    'connectionId',
+    'source',
+    legacy ? 'displayName' : 'connectionDisplayName',
+    ...(candidate && Object.hasOwn(source, 'isDefault') ? ['isDefault'] : []),
+    ...(candidate && permissions != null ? ['permissions'] : []),
+    ...(Object.hasOwn(source, 'permissionGroupName') ? ['permissionGroupName'] : []),
+    ...(policyRevision == null ? [] : ['policyRevision']),
+    'providerId',
+    ...(candidate ? [] : ['status']),
+  ])
+  if (policyRevision != null && typeof policyRevision != 'string') return invalidResponse('policyRevision: expected a string.')
+  if (candidate && isDefault !== undefined && typeof isDefault != 'boolean') return invalidResponse('isDefault: expected a boolean.')
+  if (permissionGroupName !== undefined && permissionGroupName !== null && typeof permissionGroupName != 'string')
+    return invalidResponse('permissionGroupName: expected a string or null.')
+  if (!candidate && status != 'active' && status != 'forbidden' && status != 'invalid' && status != 'missing') return invalidResponse()
+  let bindingSource
+  try {
+    bindingSource = parseProviderAccessSource(source.source)
+  } catch {
+    return invalidResponse("source: expected { kind: 'admin-delegation' } or { kind: 'policy', ruleId: string | null }.")
+  }
+  return {
+    accessBindingId: string(source.accessBindingId),
+    connectionId: string(source.connectionId),
+    source: bindingSource,
+    connectionDisplayName: string(legacy ? source.displayName : source.connectionDisplayName),
+    ...(candidate && typeof isDefault == 'boolean' ? { isDefault } : {}),
+    ...(permissions == null ? {} : { permissions }),
+    ...(permissionGroupName === undefined ? {} : { permissionGroupName }),
+    ...(policyRevision == null ? {} : { policyRevision }),
+    providerId: string(source.providerId),
+    ...(candidate ? {} : { status: status as ProviderAccessBinding['status'] }),
+  }
+}
+
+function accessMode(value: unknown): ConnectorAccess['mode'] {
+  if (value != 'implicit' && value != 'selectable') return invalidResponse('mode: expected implicit or selectable.')
+  return value as ConnectorAccess['mode']
+}
+
+export function connectorAccess(value: unknown): ConnectorAccess {
+  const source = record(value)
+  exact(source, [
+    'accessRevision',
+    'bindings',
+    'mode',
+    'sharedAccessDigest',
+    ...('providerIds' in source ? ['providerIds'] : []),
+    ...('discardedBindingCount' in source ? ['discardedBindingCount'] : []),
+    'version',
+  ])
+  const accessRevision = integer(source.accessRevision)
+  if (source.version != 1 || accessRevision < 0 || !Array.isArray(source.bindings)) return invalidResponse()
+  if ('providerIds' in source && !Array.isArray(source.providerIds)) return invalidResponse()
+  const providerIds = source.providerIds == null ? undefined : (source.providerIds as unknown[]).map((id) => string(id))
+  if (providerIds != null && new Set(providerIds).size != providerIds.length) return invalidResponse()
+  let discardedBindingCount = source.discardedBindingCount == null ? 0 : integer(source.discardedBindingCount)
+  if (discardedBindingCount < 0) return invalidResponse()
+  const bindings: ProviderAccessBinding[] = []
+  for (const entry of source.bindings) {
+    try {
+      bindings.push(accessBinding(entry, false))
+    } catch (error) {
+      if (!(error instanceof ApiError) || error.code != 'response.invalid') throw error
+      if (
+        entry != null &&
+        typeof entry == 'object' &&
+        !Array.isArray(entry) &&
+        typeof entry.accessBindingId == 'string' &&
+        entry.accessBindingId.length > 0 &&
+        typeof entry.providerId == 'string' &&
+        entry.providerId.length > 0
+      ) {
+        bindings.push({
+          accessBindingId: entry.accessBindingId,
+          providerId: entry.providerId,
+          connectionId: null,
+          source: null,
+          status: 'invalid',
+          connectionDisplayName:
+            typeof entry.connectionDisplayName == 'string' && entry.connectionDisplayName.length > 0
+              ? entry.connectionDisplayName
+              : typeof entry.displayName == 'string' && entry.displayName.length > 0
+                ? entry.displayName
+                : entry.providerId,
+          permissionGroupName: typeof entry.permissionGroupName == 'string' ? entry.permissionGroupName : null,
+        })
+      } else discardedBindingCount++
+    }
+  }
+  if (new Set(bindings.map((binding) => binding.accessBindingId)).size != bindings.length) return invalidResponse()
+  return {
+    accessRevision,
+    ...(discardedBindingCount == 0 ? {} : { discardedBindingCount }),
+    ...(providerIds == null ? {} : { providerIds }),
+    bindings,
+    mode: accessMode(source.mode),
+    sharedAccessDigest: string(source.sharedAccessDigest),
+    version: 1,
+  }
+}
+
+function accessGrants(value: unknown): readonly ConnectorAccessGrant[] {
+  if (!Array.isArray(value)) return invalidResponse()
+  const bindings = value.map((candidate) => {
+    const entry = record(candidate)
+    exact(entry, [
+      'accessBindingId',
+      'connectionId',
+      'providerId',
+      'source',
+      'connectionDisplayName',
+      ...('permissionGroupName' in entry ? ['permissionGroupName'] : []),
+    ])
+    let identity
+    try {
+      identity = parseProviderAccessSource(entry.source)
+    } catch {
+      return invalidResponse()
+    }
+    if (entry.permissionGroupName != null && typeof entry.permissionGroupName != 'string') return invalidResponse()
+    return {
+      accessBindingId: string(entry.accessBindingId),
+      connectionId: string(entry.connectionId),
+      providerId: string(entry.providerId),
+      source: identity,
+      connectionDisplayName: string(entry.connectionDisplayName),
+      ...('permissionGroupName' in entry ? { permissionGroupName: entry.permissionGroupName as string | null } : {}),
+    }
+  })
+  if (new Set(bindings.map((binding) => binding.accessBindingId)).size != bindings.length) return invalidResponse()
+  return bindings
+}
+
+export function connectorAccessSnapshot(value: unknown): ConnectorAccessSnapshot {
+  const source = record(value)
+  exact(source, ['mode', 'sharedAccessDigest', 'sharedBindings', 'selectedBindings', 'version'])
+  if (source.version != 2) return invalidResponse()
+  const mode = accessMode(source.mode)
+  const sharedBindings = accessGrants(source.sharedBindings)
+  const selectedBindings = accessGrants(source.selectedBindings)
+  if (mode == 'implicit' && (sharedBindings.length > 0 || selectedBindings.length > 0)) return invalidResponse()
+  return { mode, sharedAccessDigest: string(source.sharedAccessDigest), sharedBindings, selectedBindings, version: 2 }
+}
+
+export function connectorAccessCandidates(value: unknown, providerId: string): ConnectorAccessCandidates {
+  const source = record(value)
+  exact(source, ['candidates', 'mode', 'providerId', 'version'])
+  if (source.version != 1) return invalidResponse('version: expected 1.')
+  if (string(source.providerId) != providerId) return invalidResponse('providerId: does not match the requested provider.')
+  if (!Array.isArray(source.candidates)) return invalidResponse('candidates: expected an array.')
+  const candidates = source.candidates.map((candidate) => accessBinding(candidate, true))
+  if (candidates.some((candidate) => candidate.providerId != providerId))
+    return invalidResponse('candidates[].providerId: does not match the requested provider.')
+  if (new Set(candidates.map((candidate) => candidate.accessBindingId)).size != candidates.length)
+    return invalidResponse('candidates[].accessBindingId: duplicate IDs.')
+  return { candidates, mode: accessMode(source.mode), providerId, version: 1 }
+}
+
+export function connectorAccessCandidatesBatch(value: unknown, providerIds: readonly string[]): ConnectorAccessCandidatesBatch {
+  const source = record(value)
+  exact(source, ['results', 'version'])
+  if (source.version != 1) return invalidResponse('version: expected 1.')
+  if (!Array.isArray(source.results)) return invalidResponse('results: expected an array.')
+  const remaining = new Set(providerIds)
+  const results = source.results.map((entry) => {
+    const item = record(entry)
+    const providerId = string(item.providerId)
+    if (!remaining.delete(providerId)) return invalidResponse('results[].providerId: duplicate or unrequested provider.')
+    if (!Object.hasOwn(item, 'error')) return connectorAccessCandidates(item, providerId)
+    exact(item, ['providerId', 'error'])
+    const error = record(item.error)
+    exact(error, ['code', 'message'])
+    return { providerId, error: { code: string(error.code), message: string(error.message) } }
+  })
+  if (remaining.size != 0) return invalidResponse('results: missing requested providers.')
+  return { results, version: 1 }
+}
+
+export function connection(value: unknown): ConnectorConnection {
+  const source = record(value)
+  requiredFields(source, [
+    ...(Object.hasOwn(source, 'providerAccountId') ? ['providerAccountId'] : []),
+    ...(Object.hasOwn(source, 'alias') ? ['alias'] : []),
+    ...(Object.hasOwn(source, 'builtInAccount') ? ['builtInAccount'] : []),
+    'connectionId',
+    'displayName',
+    'isDefault',
+    'serviceId',
+    'status',
+  ])
+  if (source.builtInAccount !== undefined && typeof source.builtInAccount != 'boolean') return invalidResponse()
+  const status = source.status
+  if (status != 'active' && status != 'disconnected' && status != 'error' && status != 'reauth_required') return invalidResponse()
+  if (typeof source.isDefault != 'boolean') return invalidResponse()
+  return {
+    ...(source.providerAccountId === undefined ? {} : { providerAccountId: string(source.providerAccountId) }),
+    ...(source.alias === undefined ? {} : { alias: string(source.alias) }),
+    ...(source.builtInAccount === undefined ? {} : { builtInAccount: source.builtInAccount }),
+    connectionId: string(source.connectionId),
+    displayName: string(source.displayName),
+    isDefault: source.isDefault,
+    serviceId: string(source.serviceId),
+    status: status as ConnectorConnection['status'],
+  }
+}
+
+function port(value: unknown, input = false): InputPortDefinition {
+  const source = record(value)
+  const description = source.description
+  const hasValue = input && Object.hasOwn(source, 'value')
+  requiredFields(source, ['jsonSchema', 'nullable', ...(description == null ? [] : ['description']), ...(hasValue ? ['value'] : [])])
+  if (description != null && typeof description != 'string') return invalidResponse()
+  if (typeof source.nullable != 'boolean') return invalidResponse()
+  return {
+    ...(description == null ? {} : { description }),
+    jsonSchema: jsonValue(source.jsonSchema),
+    nullable: source.nullable,
+    ...(hasValue ? { value: jsonValue(source.value) } : {}),
+  }
+}
+
+function inputPort(value: unknown): InputPortDefinition {
+  return port(value, true)
+}
+
+function ports<Value>(value: unknown, decode: (value: unknown) => Value): Readonly<Record<string, Value>> {
+  return Object.fromEntries(Object.entries(record(value)).map(([handle, candidate]) => [handle, decode(candidate)]))
+}
+
+export function connectorActionMetadata(value: unknown): ConnectorActionMetadata {
+  const source = record(value)
+  const homepageUrl = source.homepageUrl
+  const icon = source.icon
+  requiredFields(source, [
+    'actionId',
+    ...(Object.hasOwn(source, 'operationType') ? ['operationType'] : []),
+    ...(Object.hasOwn(source, 'inputSchema') ? ['inputSchema'] : []),
+    ...(Object.hasOwn(source, 'outputSchema') ? ['outputSchema'] : []),
+    'authenticated',
+    'description',
+    ...(homepageUrl == null ? [] : ['homepageUrl']),
+    ...(icon == null ? [] : ['icon']),
+    ...('iconSprite' in source ? ['iconSprite'] : []),
+    ...('iconSpritePosition' in source ? ['iconSpritePosition'] : []),
+    'inputs',
+    'name',
+    'outputs',
+    'serviceId',
+    'serviceName',
+  ])
+  if ((homepageUrl != null && typeof homepageUrl != 'string') || (icon != null && typeof icon != 'string')) return invalidResponse()
+  const result: ConnectorActionMetadata = {
+    ...(source.inputSchema === undefined ? {} : { inputSchema: jsonValue(source.inputSchema) }),
+    ...(source.outputSchema === undefined ? {} : { outputSchema: jsonValue(source.outputSchema) }),
+    actionId: string(source.actionId),
+    ...(source.operationType == null ? {} : { operationType: string(source.operationType) }),
+    authenticated: typeof source.authenticated == 'boolean' ? source.authenticated : invalidResponse(),
+    description: typeof source.description == 'string' ? source.description : invalidResponse(),
+    ...(homepageUrl == null ? {} : { homepageUrl }),
+    ...(icon == null ? {} : { icon }),
+    ...providerIconAppearance(source.iconSprite, source.iconSpritePosition),
+    inputs: ports(source.inputs, inputPort),
+    name: string(source.name),
+    outputs: ports(source.outputs, port),
+    serviceId: string(source.serviceId),
+    serviceName: string(source.serviceName),
+  }
+  return result
+}
+
+export function connectorAction(value: unknown): ConnectorAction {
+  const { defaultConnection, ...metadata } = record(value)
+  const action = connectorActionMetadata(metadata)
+  if (defaultConnection == null) return action
+  const preferred = connection(defaultConnection)
+  if (preferred.serviceId != action.serviceId || preferred.status != 'active') return invalidResponse()
+  return { ...action, defaultConnection: preferred }
+}
+
+export function connectorProvider(value: unknown): ConnectorProvider {
+  const source = record(value)
+  const homepageUrl = source.homepageUrl
+  const icon = source.icon
+  if (source.noSetup !== undefined && typeof source.noSetup != 'boolean') return invalidResponse()
+  requiredFields(source, [
+    ...(Object.hasOwn(source, 'noSetup') ? ['noSetup'] : []),
+    'serviceId',
+    'serviceName',
+    ...(homepageUrl == null ? [] : ['homepageUrl']),
+    ...(icon == null ? [] : ['icon']),
+    ...('iconSprite' in source ? ['iconSprite'] : []),
+    ...('iconSpritePosition' in source ? ['iconSpritePosition'] : []),
+  ])
+  if ((homepageUrl != null && typeof homepageUrl != 'string') || (icon != null && typeof icon != 'string')) return invalidResponse()
+  return {
+    ...(homepageUrl == null ? {} : { homepageUrl }),
+    ...(icon == null ? {} : { icon }),
+    ...providerIconAppearance(source.iconSprite, source.iconSpritePosition),
+    serviceId: string(source.serviceId),
+    serviceName: string(source.serviceName),
+    ...(source.noSetup === undefined ? {} : { noSetup: source.noSetup }),
+  }
+}

package/src/control/common/connectorQueries.ts

@@ -0,0 +1,61 @@
+import type { ConnectorAction, ConnectorConnection, ConnectorProvider } from './api.ts'
+
+import { connection, connectorAction, connectorProvider } from './connectorDecoders.ts'
+import { requiredFields, invalidResponse, record, string } from './decoding.ts'
+
+export interface RequestQuery<Value> {
+  readonly path: string
+  readonly decode: (data: unknown) => Value
+}
+
+const scope = (flowId?: string) => (flowId == null ? '' : `?flowId=${encodeURIComponent(flowId)}`)
+
+export function connectorProvidersQuery(flowId?: string, locale?: string): RequestQuery<readonly ConnectorProvider[]> {
+  const parameters = new URLSearchParams({ ...(flowId == null ? {} : { flowId }), ...(locale == null ? {} : { locale }) }).toString()
+  return {
+    path: `/v1/connector/providers${parameters ? `?${parameters}` : ''}`,
+    decode: (value) => {
+      const source = record(value)
+      requiredFields(source, ['providers', 'version'])
+      if (source.version != 1 || !Array.isArray(source.providers)) return invalidResponse()
+      return source.providers.map(connectorProvider)
+    },
+  }
+}
+
+export function connectorActionQuery(actionId: string, flowId?: string, locale?: string): RequestQuery<ConnectorAction> {
+  const parameters = new URLSearchParams({ ...(flowId == null ? {} : { flowId }), ...(locale == null ? {} : { locale }) }).toString()
+  return {
+    path: `/v1/connector/actions/${encodeURIComponent(actionId)}${parameters ? `?${parameters}` : ''}`,
+    decode: (value) => {
+      const source = record(value)
+      requiredFields(source, ['action', 'version'])
+      if (source.version != 1) return invalidResponse()
+      return connectorAction(source.action)
+    },
+  }
+}
+
+export function allConnectorConnectionsQuery(flowId?: string): RequestQuery<readonly ConnectorConnection[]> {
+  return {
+    path: `/v1/connector/connections${scope(flowId)}`,
+    decode: (value) => {
+      const source = record(value)
+      requiredFields(source, ['connections', 'version'])
+      if (source.version != 1 || !Array.isArray(source.connections)) return invalidResponse()
+      return source.connections.map(connection)
+    },
+  }
+}
+
+export function connectorConnectionsQuery(serviceId: string, flowId?: string): RequestQuery<readonly ConnectorConnection[]> {
+  return {
+    path: `/v1/connector/connections/${encodeURIComponent(serviceId)}${scope(flowId)}`,
+    decode: (value) => {
+      const source = record(value)
+      requiredFields(source, ['connections', 'serviceId', 'version'])
+      if (source.version != 1 || string(source.serviceId) != serviceId || !Array.isArray(source.connections)) return invalidResponse()
+      return source.connections.map(connection)
+    },
+  }
+}

package/src/control/common/decoding.ts

@@ -0,0 +1,60 @@
+import type { JsonValue } from '../../flow/common/change.ts'
+
+import { ApiError } from './errors.ts'
+
+export class InvalidResponseError extends ApiError {
+  readonly detail?: string
+
+  constructor(detail?: string) {
+    super(502, 'response.invalid', `The Control API returned an invalid response.${detail == null ? '' : ` ${detail}`}`)
+    this.detail = detail
+  }
+}
+
+export function invalidResponse(detail?: string): never {
+  throw new InvalidResponseError(detail)
+}
+
+export function record(value: unknown): Readonly<Record<string, unknown>> {
+  if (value == null || typeof value != 'object' || Array.isArray(value)) return invalidResponse('Expected an object.')
+  return value as Readonly<Record<string, unknown>>
+}
+
+export function string(value: unknown): string {
+  return typeof value == 'string' && value.length > 0 ? value : invalidResponse('Expected a non-empty string.')
+}
+
+export function requiredFields(value: Readonly<Record<string, unknown>>, keys: readonly string[]): void {
+  const missing = keys.filter((key) => !Object.hasOwn(value, key))
+  if (missing.length > 0) invalidResponse(`Missing fields: ${missing.join(', ')}.`)
+}
+
+export function exact(value: Readonly<Record<string, unknown>>, keys: readonly string[]): void {
+  const actual = Object.keys(value)
+  if (actual.length != keys.length || actual.some((key) => !keys.includes(key))) {
+    const missing = keys.filter((key) => !Object.hasOwn(value, key))
+    const unexpected = actual.filter((key) => !keys.includes(key))
+    invalidResponse(
+      [missing.length > 0 ? `Missing fields: ${missing.join(', ')}.` : '', unexpected.length > 0 ? `Unexpected fields: ${unexpected.join(', ')}.` : '']
+        .filter(Boolean)
+        .join(' '),
+    )
+  }
+}
+
+export function integer(value: unknown): number {
+  return Number.isSafeInteger(value) ? (value as number) : invalidResponse('Expected a safe integer.')
+}
+
+export function jsonValue(value: unknown): JsonValue {
+  if (value === null || typeof value == 'boolean' || typeof value == 'string') return value
+  if (typeof value == 'number' && Number.isFinite(value)) return value
+  if (Array.isArray(value)) return value.map(jsonValue)
+  const source = record(value)
+  return Object.fromEntries(Object.entries(source).map(([key, item]) => [key, jsonValue(item)]))
+}
+
+export function optionalString(value: unknown): string | undefined {
+  if (value == null) return
+  return string(value)
+}

package/src/control/common/draftOperations.ts

@@ -0,0 +1,61 @@
+import type { ChangeOperation, JsonValue, TriggerKeySnapshot, TriggerSchedule } from '../../flow/common/change.ts'
+
+import { z } from 'zod'
+import { changeOperationsSchema } from '../../flow/common/change.ts'
+import { decodeChangeOperation, parseOperation } from '../../flow/common/changeSchema.ts'
+import { checkJsonDepth } from '../../flow/common/json.ts'
+import { createProviderTrigger } from '../../flow/common/nodeChanges.ts'
+import { triggerScheduleSchema } from '../../flow/common/triggerScheduleSchema.ts'
+
+const text = z.string().min(1)
+const json: z.ZodType<JsonValue> = z.json()
+const triggerCreate: z.ZodType<Extract<DraftOperation, { kind: 'graph.trigger.create' }>> = z.strictObject({
+  kind: z.literal('graph.trigger.create'),
+  nodeId: text,
+  key: text,
+  connectionId: text.optional(),
+  name: text.optional(),
+  config: z.record(text, json),
+  schedule: triggerScheduleSchema.readonly().optional(),
+})
+
+export type DraftOperation =
+  | ChangeOperation
+  | {
+      readonly kind: 'graph.trigger.create'
+      readonly nodeId: string
+      readonly key: string
+      readonly connectionId?: string
+      readonly name?: string
+      readonly config: Readonly<Record<string, JsonValue>>
+      readonly schedule?: readonly TriggerSchedule[]
+    }
+
+export function decodeDraftOperations(value: unknown): readonly DraftOperation[] {
+  checkJsonDepth(value)
+  return z
+    .array(z.unknown())
+    .min(1)
+    .parse(value)
+    .map((candidate, index) => {
+      const { kind } = parseOperation(candidate, index, z.object({ kind: text }).parse)
+      return kind == 'graph.trigger.create' ? parseOperation(candidate, index, triggerCreate.parse) : decodeChangeOperation(candidate, index)
+    })
+}
+
+export function draftOperationsSchema(kind?: string): JsonValue {
+  if (kind != null && kind != 'graph.trigger.create') return changeOperationsSchema(kind)
+  const trigger = z.toJSONSchema(triggerCreate)
+  if (kind == 'graph.trigger.create') return trigger as JsonValue
+  const schema = changeOperationsSchema() as Record<string, JsonValue>
+  return { ...schema, items: { anyOf: [schema.items!, trigger as JsonValue] } }
+}
+
+export function resolveDraftOperations(operations: readonly DraftOperation[], definition: (key: string) => TriggerKeySnapshot): readonly ChangeOperation[] {
+  return operations.flatMap((operation) => {
+    if (operation.kind != 'graph.trigger.create') return [operation]
+    const snapshot = definition(operation.key)
+    if (snapshot.type != 'poll' && operation.schedule != null) throw new Error('Only Poll triggers accept a schedule.')
+    return createProviderTrigger(operation.nodeId, snapshot, operation)
+  })
+}

package/src/control/common/errors.ts

@@ -0,0 +1,114 @@
+export const controlErrorCode = {
+  authenticationRequired: 'authentication.required',
+  authorizationDenied: 'authorization.denied',
+  bindingUnresolved: 'binding.unresolved',
+  connectorActionNotFound: 'connector.action-not-found',
+  connectorAccessConflict: 'connector.access-conflict',
+  connectorAccessInvalid: 'connector.access-invalid',
+  connectorAccessRequired: 'connector.access-required',
+  connectorAccessUnsupported: 'connector.access-unsupported',
+  connectorUnconfigured: 'connector.unconfigured',
+  connectorUnavailable: 'connector.unavailable',
+  connectorConsoleUnconfigured: 'connector.console-unconfigured',
+  engineUnavailable: 'engine.unavailable',
+  engineUnsupported: 'engine.unsupported',
+  eventSourceInvalid: 'event-source.invalid',
+  eventSourceIdentityUnavailable: 'event-source.identity-unavailable',
+  eventSourceNotFound: 'event-source.not-found',
+  eventSourceConflict: 'event-source.conflict',
+  flowInvalid: 'flow.invalid',
+  flowRepairRequired: 'flow.repair-required',
+  flowUpgradeRequired: 'flow.upgrade-required',
+  flowNotFound: 'flow.not-found',
+  flowBusy: 'flow.busy',
+  flowConflict: 'flow.conflict',
+  flowPresentationConflict: 'flow.presentation-conflict',
+  flowRevisionConflict: 'flow.revision-conflict',
+  liveConflict: 'live.conflict',
+  liveNotFound: 'live.not-found',
+  pageInvalidCursor: 'page.invalid-cursor',
+  publicationConflict: 'publication.conflict',
+  publicationNotFound: 'publication.not-found',
+  publicationUnsupported: 'publication.unsupported',
+  publishOperationNotFound: 'publication.operation-not-found',
+  routeNotFound: 'route.not-found',
+  runConflict: 'run.conflict',
+  runEventsExpired: 'run.events-expired',
+  runInvalid: 'run.invalid',
+  runNotFound: 'run.not-found',
+  runNotTerminal: 'run.not-terminal',
+  runOverloaded: 'run.overloaded',
+  runWaitNotFound: 'run.wait-not-found',
+  triggerKeyInvalid: 'trigger-key.invalid',
+  triggerKeyNotFound: 'trigger-key.not-found',
+  triggerNotFound: 'trigger.not-found',
+  variableInvalid: 'variable.invalid',
+  variableLimitReached: 'variable.limit-reached',
+  variableNotFound: 'variable.not-found',
+} as const
+
+export type ControlErrorCode = (typeof controlErrorCode)[keyof typeof controlErrorCode]
+
+export const controlErrorMetadata = {
+  [controlErrorCode.eventSourceInvalid]: { status: 400 },
+  [controlErrorCode.eventSourceIdentityUnavailable]: { status: 409 },
+  [controlErrorCode.eventSourceNotFound]: { status: 404 },
+  [controlErrorCode.eventSourceConflict]: { status: 409 },
+  [controlErrorCode.authenticationRequired]: { status: 401 },
+  [controlErrorCode.authorizationDenied]: { status: 403 },
+  [controlErrorCode.bindingUnresolved]: { status: 409 },
+  [controlErrorCode.connectorActionNotFound]: { status: 404 },
+  [controlErrorCode.connectorAccessConflict]: { status: 412 },
+  [controlErrorCode.connectorAccessInvalid]: { status: 409 },
+  [controlErrorCode.connectorAccessRequired]: { status: 409 },
+  [controlErrorCode.connectorAccessUnsupported]: { status: 409 },
+  [controlErrorCode.connectorUnconfigured]: { status: 503 },
+  [controlErrorCode.connectorUnavailable]: { status: 503 },
+  [controlErrorCode.connectorConsoleUnconfigured]: { status: 503 },
+  [controlErrorCode.engineUnavailable]: { status: 503 },
+  [controlErrorCode.engineUnsupported]: { status: 409 },
+  [controlErrorCode.flowInvalid]: { status: 400 },
+  [controlErrorCode.flowRepairRequired]: { status: 409 },
+  [controlErrorCode.flowUpgradeRequired]: { status: 409 },
+  [controlErrorCode.flowNotFound]: { status: 404 },
+  [controlErrorCode.flowBusy]: { status: 409 },
+  [controlErrorCode.flowConflict]: { status: 409 },
+  [controlErrorCode.flowPresentationConflict]: { status: 412 },
+  [controlErrorCode.flowRevisionConflict]: { status: 412 },
+  [controlErrorCode.liveConflict]: { status: 412 },
+  [controlErrorCode.liveNotFound]: { status: 404 },
+  [controlErrorCode.pageInvalidCursor]: { status: 400 },
+  [controlErrorCode.publicationConflict]: { status: 409 },
+  [controlErrorCode.publicationNotFound]: { status: 404 },
+  [controlErrorCode.publicationUnsupported]: { status: 409 },
+  [controlErrorCode.publishOperationNotFound]: { status: 404 },
+  [controlErrorCode.routeNotFound]: { status: 404 },
+  [controlErrorCode.runConflict]: { status: 409 },
+  [controlErrorCode.runEventsExpired]: { status: 410 },
+  [controlErrorCode.runInvalid]: { status: 400 },
+  [controlErrorCode.runNotFound]: { status: 404 },
+  [controlErrorCode.runNotTerminal]: { status: 409 },
+  [controlErrorCode.runOverloaded]: { status: 429 },
+  [controlErrorCode.runWaitNotFound]: { status: 404 },
+  [controlErrorCode.triggerKeyInvalid]: { status: 409 },
+  [controlErrorCode.triggerKeyNotFound]: { status: 404 },
+  [controlErrorCode.triggerNotFound]: { status: 404 },
+  [controlErrorCode.variableInvalid]: { status: 400 },
+  [controlErrorCode.variableLimitReached]: { status: 409 },
+  [controlErrorCode.variableNotFound]: { status: 404 },
+} as const satisfies Record<ControlErrorCode, { readonly status: number }>
+
+export class ApiError extends Error {
+  readonly code: string
+  readonly status: number
+
+  readonly details?: Readonly<Record<string, unknown>>
+
+  constructor(status: number, code: string, message: string, details?: Readonly<Record<string, unknown>>) {
+    super(message)
+    this.code = code
+    this.details = details
+    this.name = 'ApiError'
+    this.status = status
+  }
+}