feat(openai): introducing KnownRealtimeResponse

plugins/openai/src/realtime/api_proto.ts

@@ -2,6 +2,8 @@
 //
 // SPDX-License-Identifier: Apache-2.0
 
+import { ExtractStrict } from "../utility-types";
+
 export const SAMPLE_RATE = 24000;
 export const NUM_CHANNELS = 1;
 export const IN_FRAME_SIZE = 2400; // 100ms
@@ -27,13 +29,13 @@ export type InputTranscriptionModel = 'whisper-1' | string; // Open-ended, for f
 export type Modality = 'text' | 'audio';
 export type ToolChoice = 'auto' | 'none' | 'required' | string;
 export type State = 'initializing' | 'listening' | 'thinking' | 'speaking' | string;
-export type ResponseStatus =
+export type KnownResponseStatus =
   | 'in_progress'
   | 'completed'
   | 'incomplete'
   | 'cancelled'
-  | 'failed'
-  | string;
+  | 'failed';
+export type ResponseStatus = KnownResponseStatus | string;
 export type ClientEventType =
   | 'session.update'
   | 'input_audio_buffer.append'
@@ -200,22 +202,28 @@ export interface ConversationResource {
   object: 'realtime.conversation';
 }
 
+export interface IncompleteResponseStatusDetails {
+  type: ExtractStrict<KnownResponseStatus, 'incomplete'>;
+  reason: 'max_output_tokens' | 'content_filter' | string;
+}
+
+export interface FailedResponseStatusDetails {
+  type: ExtractStrict<KnownResponseStatus, 'failed'>;
+  error?: {
+    code: 'server_error' | 'rate_limit_exceeded' | string;
+    message: string;
+  };
+}
+
+export interface CancelledResponseStatusDetails {
+  type: ExtractStrict<KnownResponseStatus, 'cancelled'>;
+  reason: 'turn_detected' | 'client_cancelled' | string;
+}
+
 export type ResponseStatusDetails =
-  | {
-      type: 'incomplete';
-      reason: 'max_output_tokens' | 'content_filter' | string;
-    }
-  | {
-      type: 'failed';
-      error?: {
-        code: 'server_error' | 'rate_limit_exceeded' | string;
-        message: string;
-      };
-    }
-  | {
-      type: 'cancelled';
-      reason: 'turn_detected' | 'client_cancelled' | string;
-    };
+  | IncompleteResponseStatusDetails
+  | FailedResponseStatusDetails
+  | CancelledResponseStatusDetails;
 
 export interface ModelUsage {
   total_tokens: number;

plugins/openai/src/realtime/realtime_model.ts

@@ -34,7 +34,7 @@ interface ModelOptions {
   apiVersion?: string;
 }
 
-export interface RealtimeResponse {
+interface RealtimeResponseBase {
   id: string;
   status: api_proto.ResponseStatus;
   statusDetails: api_proto.ResponseStatusDetails | null;
@@ -45,6 +45,30 @@ export interface RealtimeResponse {
   firstTokenTimestamp?: number;
 }
 
+interface KnownRealtimeResponseBase<T extends api_proto.ResponseStatusDetails>
+  extends RealtimeResponseBase {
+  status: T['type'];
+  statusDetails: T;
+}
+
+export interface UnknownRealtimeResponse extends RealtimeResponseBase {
+  status: string;
+  statusDetails: null;
+}
+
+export type IncompleteRealtimeResponse =
+  KnownRealtimeResponseBase<api_proto.IncompleteResponseStatusDetails>;
+export type FailedRealtimeResponse =
+  KnownRealtimeResponseBase<api_proto.FailedResponseStatusDetails>;
+export type CancelledRealtimeResponse =
+  KnownRealtimeResponseBase<api_proto.CancelledResponseStatusDetails>;
+export type KnownRealtimeResponse =
+  | IncompleteRealtimeResponse
+  | FailedRealtimeResponse
+  | CancelledRealtimeResponse;
+
+export type RealtimeResponse = KnownRealtimeResponse | UnknownRealtimeResponse;
+
 export interface RealtimeOutput {
   responseId: string;
   itemId: string;

plugins/openai/src/utility-types.ts

@@ -0,0 +1 @@
+export type ExtractStrict<T, U extends T> = T extends U ? T : never;