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

package/src/control/common/triggerDecoders.ts

@@ -0,0 +1,175 @@
+import type { TriggerKeySnapshot } from '../../flow/common/change.ts'
+import type {
+  PollTriggerTestResult,
+  TriggerActivity,
+  TriggerActivityKind,
+  TriggerActivityPage,
+  TriggerBinding,
+  TriggerBindingDetail,
+  TriggerKeySummary,
+} from './api.ts'
+
+import { configInputsSchema } from '../../trigger/common/configSchema.ts'
+import { integer, invalidResponse, jsonValue, optionalString, record, string } from './decoding.ts'
+
+export function triggerKeySummary(value: unknown): TriggerKeySummary {
+  const source = record(value)
+  const type = source.type
+  if (type != 'integration' && type != 'poll') return invalidResponse()
+  return {
+    description: typeof source.description == 'string' ? source.description : invalidResponse(),
+    displayName: string(source.displayName),
+    key: string(source.key),
+    name: string(source.name),
+    provider: string(source.provider),
+    type: type as TriggerKeySummary['type'],
+  }
+}
+
+export function triggerKey(value: unknown): TriggerKeySnapshot {
+  const source = record(value)
+  const summary = triggerKeySummary(source)
+  const base = {
+    configInputs: configInputsSchema.parse(source.configInputs),
+    definitionVersion: source.definitionVersion === 2 ? 2 : invalidResponse(),
+    description: summary.description,
+    displayName: summary.displayName,
+    key: summary.key,
+    name: summary.name,
+    outputs: (Array.isArray(source.outputs) ? source.outputs : invalidResponse()).map((entry) => {
+      const port = record(entry)
+      return Object.assign(
+        {
+          handle: string(port.handle),
+          jsonSchema: jsonValue(port.jsonSchema),
+          nullable: typeof port.nullable === 'boolean' ? port.nullable : invalidResponse(),
+        },
+        port.description == null ? {} : { description: string(port.description) },
+      )
+    }),
+    provider: summary.provider,
+  }
+  if (summary.type == 'poll') return { ...base, type: 'poll' }
+  const endpoint = record(source.endpoint)
+  const body = record(endpoint.body)
+  if (!Array.isArray(endpoint.methods) || !Array.isArray(body.formats) || typeof body.allowArray != 'boolean' || typeof body.allowEmpty != 'boolean') {
+    return invalidResponse()
+  }
+  const methods = endpoint.methods.map(string)
+  const formats = body.formats.map(string)
+  const successStatus = integer(endpoint.successStatus)
+  if (
+    methods.some((method) => !['DELETE', 'GET', 'HEAD', 'PATCH', 'POST', 'PUT'].includes(method)) ||
+    formats.some((format) => !['form', 'json', 'multipart', 'text'].includes(format)) ||
+    successStatus < 200 ||
+    successStatus > 299
+  ) {
+    return invalidResponse()
+  }
+  return {
+    ...base,
+    endpoint: {
+      body: {
+        allowArray: body.allowArray,
+        allowEmpty: body.allowEmpty,
+        formats: formats as Extract<TriggerKeySnapshot, { readonly type: 'integration' }>['endpoint']['body']['formats'],
+      },
+      methods: methods as Extract<TriggerKeySnapshot, { readonly type: 'integration' }>['endpoint']['methods'],
+      successStatus,
+    },
+    type: 'integration',
+  }
+}
+
+const triggerKinds: ReadonlySet<TriggerBinding['kind']> = new Set(['error', 'cron', 'integration', 'poll', 'webhook'])
+const triggerHealth: ReadonlySet<TriggerBinding['health']> = new Set(['failed', 'healthy', 'initializing', 'needs_reauth', 'suspended'])
+const triggerActivityKinds: ReadonlySet<TriggerActivityKind> = new Set([
+  'delivery.failed',
+  'health.failed',
+  'health.needs_reauth',
+  'health.recovered',
+  'health.suspended',
+  'operator.paused',
+  'operator.resumed',
+])
+
+export function triggerBinding(value: unknown): TriggerBinding {
+  const source = record(value)
+  const health = source.health
+  const listener = source.listener == null ? undefined : record(source.listener)
+  if (listener != null && listener.health != 'healthy' && listener.health != 'failed' && listener.health != 'needs_reauth') return invalidResponse()
+  const kind = source.kind
+  const runtimeVersion = integer(source.runtimeVersion)
+  if (source.version != 1 || typeof health != 'string' || !triggerHealth.has(health as TriggerBinding['health'])) return invalidResponse()
+  if (typeof kind != 'string' || !triggerKinds.has(kind as TriggerBinding['kind'])) return invalidResponse()
+  if (runtimeVersion <= 0) return invalidResponse()
+  return {
+    ...(source.currentPublicationId == null ? {} : { currentPublicationId: string(source.currentPublicationId) }),
+    ...(source.currentRevisionId == null ? {} : { currentRevisionId: string(source.currentRevisionId) }),
+    ...(source.endpointUrl == null ? {} : { endpointUrl: string(source.endpointUrl) }),
+    ...(listener == null
+      ? {}
+      : {
+          listener: {
+            health: listener.health as NonNullable<TriggerBinding['listener']>['health'],
+            ...(listener.lastErrorCode == null ? {} : { lastErrorCode: string(listener.lastErrorCode) }),
+          },
+        }),
+    flowId: string(source.flowId),
+    health: health as TriggerBinding['health'],
+    kind: kind as TriggerBinding['kind'],
+    ...(source.lastErrorCode == null ? {} : { lastErrorCode: string(source.lastErrorCode) }),
+    runtimeVersion,
+    triggerNodeId: string(source.triggerNodeId),
+    updatedAt: string(source.updatedAt),
+    version: 1,
+  }
+}
+
+export function triggerBindingDetail(value: unknown): TriggerBindingDetail {
+  const source = record(value)
+  if (source.version != 1) return invalidResponse()
+  return { binding: triggerBinding(source.binding), version: 1 }
+}
+
+function triggerActivity(value: unknown): TriggerActivity {
+  const source = record(value)
+  const kind = source.kind
+  if (typeof kind != 'string' || !triggerActivityKinds.has(kind as TriggerActivityKind)) return invalidResponse()
+  const errorCode = optionalString(source.errorCode)
+  const errorMessage = optionalString(source.errorMessage)
+  if (errorMessage != null && errorMessage.length > 512) return invalidResponse()
+  return {
+    activityId: string(source.activityId),
+    createdAt: string(source.createdAt),
+    ...(errorCode == null ? {} : { errorCode }),
+    ...(errorMessage == null ? {} : { errorMessage }),
+    kind: kind as TriggerActivityKind,
+  }
+}
+
+export function triggerActivityPage(value: unknown): TriggerActivityPage {
+  const source = record(value)
+  const nextCursor = optionalString(source.nextCursor)
+  if (source.version != 1 || !Array.isArray(source.activities)) return invalidResponse()
+  return {
+    activities: source.activities.map(triggerActivity),
+    ...(nextCursor == null ? {} : { nextCursor }),
+    version: 1,
+  }
+}
+
+export function pollTriggerTestResult(value: unknown): PollTriggerTestResult {
+  const source = record(value)
+  const filtered = integer(source.filtered)
+  if (source.version != 1 || !Array.isArray(source.events) || typeof source.hasMore != 'boolean' || filtered < 0) return invalidResponse()
+  return {
+    events: source.events.map((event) => {
+      const object = record(event)
+      return Object.fromEntries(Object.entries(object).map(([key, item]) => [key, jsonValue(item)]))
+    }),
+    filtered,
+    hasMore: source.hasMore,
+    version: 1,
+  }
+}

package/src/decision/common/decision.ts

@@ -0,0 +1,168 @@
+import type { InputPort, JsonValue, ManagedTaskDefinition, Port } from '../../flow/common/change.ts'
+
+import { dequal } from 'dequal/lite'
+import { matchesSchema } from '../../flow/common/schema.ts'
+
+export type DecisionQuestion = { readonly name: string; readonly instructions: string } & (
+  | { readonly type: 'noul'; readonly criteria?: { readonly true?: string; readonly false?: string } }
+  | { readonly type: 'choice'; readonly criteria: readonly { readonly name: string; readonly description: string }[] }
+  | { readonly type: 'score'; readonly criteria: readonly string[] }
+)
+export interface DecisionExecutor {
+  readonly kind: 'decision'
+  readonly questions: readonly DecisionQuestion[]
+}
+export interface DecisionIssue {
+  readonly question?: number
+  readonly field: 'questions' | 'name' | 'instructions' | 'criteria' | 'ports'
+  readonly message: string
+}
+
+export const decisionModel = 'typesafe/jev'
+export const decisionLimits = { choice: 255, score: 10 } as const
+
+/** Ordered prefixes are shared by authoring, schemas, validation, and execution. */
+export function limitDecisionQuestion(question: DecisionQuestion): DecisionQuestion {
+  if (question.type === 'noul' || question.criteria.length <= decisionLimits[question.type]) return question
+  if (question.type === 'choice') return { ...question, criteria: question.criteria.slice(0, decisionLimits.choice) }
+  return { ...question, criteria: question.criteria.slice(0, decisionLimits.score) }
+}
+
+export function limitDecisionQuestions(questions: readonly DecisionQuestion[]): readonly DecisionQuestion[] {
+  const limited = questions.map(limitDecisionQuestion)
+  return limited.every((question, i) => question === questions[i]) ? questions : limited
+}
+
+/** Loading an oversized task also updates its previously generated output schemas. */
+export function limitDecisionTask(task: ManagedTaskDefinition): ManagedTaskDefinition {
+  if (task.executor.kind !== 'decision') return task
+  const original = task.executor.questions
+  const questions = limitDecisionQuestions(original)
+  if (questions === original) return task
+  const outputs = task.outputs.map((port) => {
+    if (!('handle' in port)) return port
+    const index = original.findIndex((question) => question.name === port.handle)
+    if (index < 0 || original[index] === questions[index] || !dequal(port.jsonSchema, answerSchema(original[index]!))) return port
+    return { ...port, jsonSchema: decisionAnswerSchema(questions[index]!) }
+  })
+  return { ...task, executor: { ...task.executor, questions }, outputs }
+}
+export const decisionStateSchema: JsonValue = { type: ['string', 'object', 'array'] }
+const probability: JsonValue = { type: 'number', minimum: 0, maximum: 1 }
+export const defaultDecisionQuestion = (name = 'decision1'): DecisionQuestion => ({ name, type: 'noul', instructions: '' })
+
+export function decisionQuestionIssues(questions: readonly DecisionQuestion[]): readonly DecisionIssue[] {
+  questions = limitDecisionQuestions(questions)
+  const issues: DecisionIssue[] = []
+  if (!questions.length) issues.push({ field: 'questions', message: 'Add at least one question.' })
+  questions.forEach((question, index) => {
+    const add = (field: DecisionIssue['field'], message: string) => issues.push({ question: index, field, message })
+    if (!question.name.trim() || question.name === '__proto__' || questions.some((other, i) => i !== index && other.name === question.name))
+      add('name', 'Question names must be non-empty and unique; __proto__ is reserved.')
+    if (!question.instructions.trim()) add('instructions', 'Describe the question to evaluate.')
+    if (question.type === 'choice') {
+      if (!question.criteria.length) add('criteria', 'Provide between 1 and 255 choices.')
+      const names = question.criteria.map((item) => item.name)
+      if (names.some((name) => !name.trim() || name === '__proto__') || new Set(names).size !== names.length)
+        add('criteria', 'Choice names must be non-empty and unique; __proto__ is reserved.')
+    }
+    if (question.type === 'score' && (question.criteria.length < 2 || question.criteria.some((level) => !level.trim())))
+      add('criteria', 'Provide between 2 and 10 non-empty levels, in increasing order.')
+  })
+  return issues
+}
+
+export function decisionAnswerSchema(question: DecisionQuestion): JsonValue {
+  return answerSchema(limitDecisionQuestion(question))
+}
+
+function answerSchema(question: DecisionQuestion): JsonValue {
+  const properties: Record<string, JsonValue> = { type: { const: question.type } }
+  if (question.type === 'noul') properties.noul = probability
+  else {
+    const keys = question.type === 'choice' ? question.criteria.map((item) => item.name) : question.criteria.map((_, index) => String(index))
+    properties.confidence = probability
+    properties.probabilities = {
+      type: 'object',
+      properties: Object.fromEntries(keys.map((key) => [key, probability])),
+      required: keys,
+      additionalProperties: false,
+    }
+    if (question.type === 'choice') properties.choice = { type: 'string', ...(keys.length ? { enum: keys } : {}) }
+    else {
+      properties.score = { type: 'number', minimum: 0, maximum: Math.max(0, keys.length - 1) }
+      properties.legend = {
+        type: 'object',
+        properties: Object.fromEntries(keys.map((key) => [key, { type: 'string' }])),
+        required: keys,
+        additionalProperties: false,
+      }
+    }
+  }
+  return { type: 'object', properties, required: Object.keys(properties) }
+}
+
+export function decisionTask(questions: readonly DecisionQuestion[] = [defaultDecisionQuestion()], name = 'AI Decision'): ManagedTaskDefinition {
+  questions = limitDecisionQuestions(questions)
+  const inputs: InputPort[] = [
+    { handle: 'target', description: 'Text, object, or array to evaluate across all questions.', jsonSchema: decisionStateSchema, nullable: false },
+  ]
+  const outputs: Port[] = questions.map((question) => ({ handle: question.name, jsonSchema: decisionAnswerSchema(question), nullable: false }))
+  return { name, executor: { kind: 'decision', questions }, inputs, outputs }
+}
+
+export function decisionTaskIssues(task: ManagedTaskDefinition): readonly DecisionIssue[] {
+  task = limitDecisionTask(task)
+  if (task.executor.kind !== 'decision') return []
+  const expected = decisionTask(task.executor.questions, task.name)
+  return [
+    ...decisionQuestionIssues(task.executor.questions),
+    ...(!dequal(task.inputs, expected.inputs) || !dequal(task.outputs, expected.outputs)
+      ? [{ field: 'ports' as const, message: 'AI Decision ports must match its questions.' }]
+      : []),
+  ]
+}
+
+export function decisionRequest(questions: readonly DecisionQuestion[], state: JsonValue): JsonValue {
+  questions = limitDecisionQuestions(questions)
+  const issues = decisionQuestionIssues(questions)
+  if (issues.length) throw new TypeError(issues[0]!.message)
+  if (!matchesSchema(state, decisionStateSchema)) throw new TypeError('Decision state must be text, an object, or an array.')
+  return {
+    model: decisionModel,
+    state,
+    questions: Object.fromEntries(
+      questions.map((question) => [
+        question.name,
+        {
+          type: question.type,
+          instructions: question.instructions,
+          ...(question.type === 'choice'
+            ? { criteria: Object.fromEntries(question.criteria.map((item) => [item.name, item.description || null])) }
+            : question.criteria == null
+              ? {}
+              : { criteria: question.criteria }),
+        },
+      ]),
+    ),
+  }
+}
+
+export function decisionAnswers(questions: readonly DecisionQuestion[], response: unknown): Readonly<Record<string, JsonValue>> {
+  questions = limitDecisionQuestions(questions)
+  const source = response as { answers?: unknown } | null
+  const answers = source?.answers
+  if (answers == null || typeof answers !== 'object' || Array.isArray(answers)) throw new TypeError('The model returned no answers.')
+  return Object.fromEntries(
+    questions.map((question) => {
+      const answer = Object.hasOwn(answers, question.name) ? (answers as Record<string, JsonValue>)[question.name] : undefined
+      if (answer === undefined || !matchesSchema(answer, decisionAnswerSchema(question))) throw new TypeError(`Invalid answer for "${question.name}".`)
+      if (question.type !== 'noul') {
+        const distribution = (answer as Record<string, JsonValue>).probabilities as Record<string, number>
+        if (Math.abs(Object.values(distribution).reduce((sum, value) => sum + value, 0) - 1) > 0.0001)
+          throw new TypeError(`Invalid probability distribution for "${question.name}".`)
+      }
+      return [question.name, answer]
+    }),
+  )
+}

package/src/event-source/common/catalog.generated.json

@@ -0,0 +1,65 @@
+[
+  {
+    "key": "feishu_app_bot.on_event",
+    "kind": "feishu",
+    "provider": "feishu_app_bot",
+    "triggerId": "feishu_app_bot.on_event",
+    "maximumBodyBytes": 65536,
+    "applicationIngress": false,
+    "managed": false
+  },
+  {
+    "key": "fireflies.on_meeting_ready",
+    "kind": "fireflies",
+    "provider": "fireflies",
+    "triggerId": "fireflies.on_meeting_ready",
+    "maximumBodyBytes": 65536,
+    "applicationIngress": false,
+    "managed": false
+  },
+  {
+    "key": "intercom.on_conversation_event",
+    "kind": "intercom",
+    "provider": "intercom",
+    "triggerId": "intercom.on_conversation_event",
+    "maximumBodyBytes": 65536,
+    "applicationIngress": true,
+    "managed": false
+  },
+  {
+    "key": "jira.on_issue_event",
+    "kind": "jira",
+    "provider": "jira",
+    "triggerId": "jira.on_issue_event",
+    "maximumBodyBytes": 65536,
+    "applicationIngress": false,
+    "managed": true
+  },
+  {
+    "key": "sentry.on_issue_alert",
+    "kind": "sentry",
+    "provider": "sentry",
+    "triggerId": "sentry.on_issue_alert",
+    "maximumBodyBytes": 65536,
+    "applicationIngress": true,
+    "managed": false
+  },
+  {
+    "key": "slackbot.on_event",
+    "kind": "slack",
+    "provider": "slackbot",
+    "triggerId": "slackbot.on_event",
+    "maximumBodyBytes": 65536,
+    "applicationIngress": true,
+    "managed": false
+  },
+  {
+    "key": "zoom.on_recording_ready",
+    "kind": "zoom",
+    "provider": "zoom",
+    "triggerId": "zoom.on_recording_ready",
+    "maximumBodyBytes": 65536,
+    "applicationIngress": true,
+    "managed": false
+  }
+]

package/src/event-source/common/definition.ts

@@ -0,0 +1,66 @@
+import type { JsonValue } from '../../flow/common/change.ts'
+
+export interface SourceConfiguration {
+  readonly identity: string
+  readonly eventTypes: string[]
+  readonly config: Readonly<Record<string, JsonValue>>
+  readonly secrets: Readonly<Record<string, JsonValue>>
+  readonly state: Readonly<Record<string, JsonValue>>
+}
+export interface SourceEvent {
+  readonly ordering?: { readonly key: string; readonly version: number }
+  readonly id: string
+  readonly type: string
+  readonly payload: Readonly<Record<string, JsonValue>>
+  readonly matches: readonly string[]
+}
+export interface SourceSubscription {
+  readonly key: string
+  readonly config: Readonly<Record<string, JsonValue>>
+}
+export interface EventSourceDefinition {
+  readonly kind: string
+  readonly provider: string
+  readonly triggerId: string
+  readonly maximumBodyBytes: number
+  readonly applicationIngress: boolean
+  readonly managed: boolean
+}
+export type SourceOperation =
+  | { readonly action: 'initialize'; readonly input: Readonly<Record<string, JsonValue>> }
+  | { readonly action: 'update'; readonly source: SourceConfiguration; readonly input: Readonly<Record<string, JsonValue>> }
+  | { readonly action: 'inspect'; readonly source: SourceConfiguration }
+  | { readonly action: 'prepare'; readonly source: SourceConfiguration; readonly config: Readonly<Record<string, JsonValue>>; readonly endpointUrl?: string }
+  | {
+      readonly action: 'receive'
+      readonly source: SourceConfiguration
+      readonly headers: Readonly<Record<string, string>>
+      readonly rawBody: string
+      readonly consumers: readonly { readonly id: string; readonly config: Readonly<Record<string, JsonValue>> }[]
+    }
+
+export class SourceIdentityError extends Error {}
+
+export interface SourceReference {
+  readonly applicationId: string
+  readonly sourceId: string
+}
+export type SourceReferenceOperation = { readonly deploymentId: string } & (
+  | { readonly action: 'route'; readonly applicationId: string; readonly headers: Readonly<Record<string, string>>; readonly rawBody: string }
+  | {
+      readonly action: 'create'
+      readonly requestKey: string
+      readonly input: Readonly<Record<string, JsonValue>>
+    }
+  | { readonly action: 'get'; readonly reference: SourceReference }
+  | { readonly action: 'delete'; readonly reference: SourceReference | { readonly appId?: string; readonly requestKey: string } }
+  | {
+      readonly action: 'update'
+      readonly reference: SourceReference
+      readonly expectedRevision: number
+      readonly input: Readonly<Record<string, JsonValue>>
+    }
+  | { readonly action: 'prepare'; readonly reference: SourceReference; readonly config: Readonly<Record<string, JsonValue>>; readonly endpointUrl?: string }
+  | { readonly action: 'resource'; readonly reference: SourceReference; readonly key: string; readonly active: boolean }
+  | ({ readonly action: 'receive'; readonly reference: SourceReference } & Omit<Extract<SourceOperation, { action: 'receive' }>, 'source' | 'action'>)
+)

package/src/event-source/common/index.ts

@@ -0,0 +1,99 @@
+import type { EventSourceDefinition, SourceConfiguration } from './definition.ts'
+
+import { z } from 'zod'
+import { eventSourceViewSchema } from '../../control/common/eventSources.ts'
+import catalog from './catalog.generated.json' with { type: 'json' }
+import { SourceIdentityError } from './definition.ts'
+
+export type {
+  EventSourceDefinition,
+  SourceConfiguration,
+  SourceEvent,
+  SourceSubscription,
+  SourceOperation,
+  SourceReference,
+  SourceReferenceOperation,
+} from './definition.ts'
+export { SourceIdentityError } from './definition.ts'
+
+export function eventSourceDefinition(kind: string): EventSourceDefinition {
+  for (const entry of catalog) if (entry.kind === kind) return entry
+  throw new SourceIdentityError(`Unknown event source kind: ${kind}`)
+}
+
+const jsonObject = z.record(z.string(), z.json())
+const projectionSchema = z.object({ view: eventSourceViewSchema, ready: z.boolean(), expiresAt: z.number().optional() })
+export const sourceConfigurationSchema = z.object({
+  identity: z.string().min(1),
+  eventTypes: z.array(z.string()),
+  config: jsonObject,
+  secrets: jsonObject,
+  state: jsonObject.refine((state) => projectionSchema.safeParse(state.projection).success, 'Connector source projection is invalid.'),
+})
+
+export function sourceReady(source: SourceConfiguration, now = Date.now()): boolean {
+  const projection = projectionSchema.safeParse(source.state.projection)
+  return projection.success && projection.data.ready && (projection.data.expiresAt == null || projection.data.expiresAt > now)
+}
+
+export function sourceView(source: SourceConfiguration, now = Date.now()): z.infer<typeof eventSourceViewSchema> {
+  if (source.state.projection == null)
+    return {
+      appId: null,
+      manageSubscriptions: null,
+      verificationTokenConfigured: null,
+      encryptKeyConfigured: null,
+      verifiedAt: null,
+      lastError: 'Source details are unavailable. Restore Connector access and refresh to retry.',
+    }
+  const projection = projectionSchema.parse(source.state.projection)
+  const expired = projection.expiresAt != null && projection.expiresAt <= now
+  return {
+    ...projection.view,
+    ...(expired ? { subscriptionStatus: 'error', lastError: 'The source subscription expired. Restore Connector access and retry publication.' } : {}),
+  }
+}
+
+export const sourceResultSchema = z.object({ source: sourceConfigurationSchema })
+export const preparedSourceSchema = sourceResultSchema.extend({ subscriptions: z.array(z.object({ key: z.string(), config: jsonObject })) })
+export const sourceReceiptSchema = z
+  .object({
+    source: sourceConfigurationSchema.optional(),
+    response: z.object({ status: z.number().int().min(200).max(599), body: z.string(), headers: z.record(z.string(), z.string()) }).optional(),
+    event: z
+      .object({
+        id: z.string().min(1),
+        type: z.string().min(1),
+        payload: jsonObject,
+        matches: z.array(z.string()),
+        ordering: z.object({ key: z.string(), version: z.number() }).optional(),
+      })
+      .optional(),
+  })
+  .refine((value) => (value.response == null) !== (value.event == null))
+
+export type SourceResult = z.infer<typeof sourceResultSchema>
+export type PreparedSource = z.infer<typeof preparedSourceSchema>
+export type SourceReceipt = z.infer<typeof sourceReceiptSchema>
+
+export const sourceReferenceSchema = z.object({ applicationId: z.string().min(1), sourceId: z.string().min(1) })
+export const sourceReferenceSnapshotSchema = projectionSchema.extend({
+  reference: sourceReferenceSchema,
+  revision: z.number().int().positive(),
+  eventTypes: z.array(z.string()),
+})
+export const sourceReferenceResultSchema = z.object({ source: sourceReferenceSnapshotSchema })
+export const sourceReferenceDeleteResultSchema = z.object({ deleted: z.literal(true) })
+export const sourceReferenceResourceResultSchema = sourceReferenceResultSchema.extend({ outcome: z.enum(['ready', 'pending']) })
+export const sourceReferenceRouteResultSchema = z.object({
+  references: z.array(sourceReferenceSchema),
+  response: sourceReceiptSchema.shape.response,
+})
+export const preparedSourceReferenceSchema = sourceReferenceResultSchema.extend({ subscriptions: z.array(z.object({ key: z.string() })) })
+export const sourceReferenceReceiptSchema = z
+  .object({
+    ...sourceReceiptSchema.shape,
+    source: sourceReferenceSnapshotSchema.optional(),
+  })
+  .refine((value) => (value.response == null) !== (value.event == null))
+export type SourceReferenceSnapshot = z.infer<typeof sourceReferenceSnapshotSchema>