feat(api): define v1 control-plane contract

2026-07-16 10:58:05 +08:00
parent aa3c3f9803
commit a86970d33b
14 changed files with 3234 additions and 4 deletions
@@ -0,0 +1,52 @@
+import type { PageEnvelope, PageQuery } from './instances.js';
+
+export const AUDIT_OUTCOMES = ['succeeded', 'failed', 'partially-succeeded', 'denied'] as const;
+export type AuditOutcome = (typeof AUDIT_OUTCOMES)[number];
+
+export interface RedactedParameterSummaryItem {
+  readonly fieldId: string;
+  readonly displayValue: string;
+  readonly redacted: boolean;
+}
+
+export interface AuditEvent {
+  readonly id: string;
+  readonly occurredAt: string;
+  readonly actorId: string;
+  readonly action: string;
+  readonly outcome: AuditOutcome;
+  readonly requestId: string;
+  readonly instanceId?: string;
+  readonly jobId?: string;
+  readonly itemId?: string;
+  readonly attemptId?: string;
+  readonly preparationId?: string;
+  readonly parameterSummary?: readonly RedactedParameterSummaryItem[];
+}
+export interface AuditFilters {
+  readonly actorId?: string;
+  readonly instanceId?: string;
+  readonly jobId?: string;
+  readonly operationId?: string;
+  readonly outcome?: AuditOutcome;
+  readonly occurredFrom?: string;
+  readonly occurredTo?: string;
+  readonly requestId?: string;
+}
+export type AuditPageQuery = PageQuery<'occurredAt' | 'action' | 'outcome'> & AuditFilters;
+export type AuditPage = PageEnvelope<AuditEvent>;
+
+export const EVENT_KINDS = ['instance', 'job', 'item', 'attempt', 'audit'] as const;
+export type EventKind = (typeof EVENT_KINDS)[number];
+interface EventBase<Kind extends EventKind> {
+  readonly kind: Kind;
+  readonly id: string;
+  readonly occurredAt: string;
+  readonly requestId: string;
+}
+export type EventEnvelope =
+  | (EventBase<'instance'> & { readonly instanceId: string })
+  | (EventBase<'job'> & { readonly jobId: string })
+  | (EventBase<'item'> & { readonly jobId: string; readonly itemId: string })
+  | (EventBase<'attempt'> & { readonly jobId: string; readonly attemptId: string })
+  | (EventBase<'audit'> & { readonly auditEventId: string });