@kubohiroya/turbowarp-openai-realtime-api 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,133 @@
1
+ import type {RealtimeSessionRequest} from './session-config.js';
2
+
3
+ export type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
4
+
5
+ const LOOPBACK_HOSTNAMES = new Set(['127.0.0.1', 'localhost', '[::1]']);
6
+ const TOKEN_PATTERN = /^[A-Za-z0-9_-]{20,}$/u;
7
+ const CLIENT_SECRET_PATTERN = /^ek_[A-Za-z0-9_-]+$/u;
8
+
9
+ export interface RelaySession {
10
+ endpoint: string;
11
+ token: string;
12
+ expiresAt: number;
13
+ }
14
+
15
+ export interface ClientSecret {
16
+ value: string;
17
+ expiresAt: number;
18
+ model: string;
19
+ }
20
+
21
+ /** Accepts only a plain loopback HTTP origin so the relay token can never leave this machine. */
22
+ export function normalizeRelayEndpoint(endpoint: string): string {
23
+ let url: URL;
24
+ try {
25
+ url = new URL(endpoint.trim());
26
+ } catch {
27
+ throw new TypeError('Relay endpoint must be a valid URL.');
28
+ }
29
+ if (url.protocol !== 'http:' || !LOOPBACK_HOSTNAMES.has(url.hostname)) {
30
+ throw new TypeError('Relay endpoint must use HTTP on a loopback hostname.');
31
+ }
32
+ if (
33
+ url.username.length > 0 ||
34
+ url.password.length > 0 ||
35
+ url.search.length > 0 ||
36
+ url.hash.length > 0 ||
37
+ (url.pathname !== '/' && url.pathname !== '')
38
+ ) {
39
+ throw new TypeError('Relay endpoint must contain only its loopback origin.');
40
+ }
41
+ return url.origin;
42
+ }
43
+
44
+ export async function pairWithRelay(
45
+ endpoint: string,
46
+ code: string,
47
+ fetcher: FetchLike = fetch,
48
+ now: () => number = Date.now
49
+ ): Promise<RelaySession> {
50
+ const origin = normalizeRelayEndpoint(endpoint);
51
+ const trimmed = code.trim();
52
+ if (!/^\d{8}$/u.test(trimmed)) {
53
+ throw new TypeError('Relay pairing code must contain exactly eight digits.');
54
+ }
55
+ const record = requireRecord(
56
+ await requestJson(fetcher, `${origin}/v1/pair`, {
57
+ method: 'POST',
58
+ headers: {'content-type': 'application/json'},
59
+ body: JSON.stringify({code: trimmed}),
60
+ redirect: 'error'
61
+ }),
62
+ 'Relay returned an invalid pairing response.'
63
+ );
64
+ const token = String(record.token ?? '');
65
+ if (!TOKEN_PATTERN.test(token)) throw new Error('Relay returned an invalid pairing token.');
66
+ if (typeof record.expiresAt !== 'number' || !Number.isFinite(record.expiresAt) || record.expiresAt <= now()) {
67
+ throw new Error('Relay returned an invalid session expiration.');
68
+ }
69
+ return {endpoint: origin, token, expiresAt: record.expiresAt};
70
+ }
71
+
72
+ export async function requestClientSecret(
73
+ session: RelaySession,
74
+ request: RealtimeSessionRequest,
75
+ fetcher: FetchLike = fetch,
76
+ now: () => number = Date.now
77
+ ): Promise<ClientSecret> {
78
+ if (session.expiresAt <= now()) {
79
+ throw new Error('Relay session has expired. Pair with the local relay again.');
80
+ }
81
+ const envelope = requireRecord(
82
+ await requestJson(fetcher, `${session.endpoint}/v1/openai/realtime/client-secrets`, {
83
+ method: 'POST',
84
+ headers: {
85
+ 'content-type': 'application/json',
86
+ authorization: `Bearer ${session.token}`
87
+ },
88
+ body: JSON.stringify({session: request}),
89
+ redirect: 'error'
90
+ }),
91
+ 'Relay returned an invalid client secret response.'
92
+ );
93
+ const data = requireRecord(envelope.data, 'Relay returned an invalid client secret response.');
94
+ const value = String(data.value ?? '');
95
+ if (!CLIENT_SECRET_PATTERN.test(value)) throw new Error('Relay returned an invalid client secret.');
96
+ if (typeof data.expiresAt !== 'number' || !Number.isFinite(data.expiresAt) || data.expiresAt <= now()) {
97
+ throw new Error('Relay returned an expired client secret.');
98
+ }
99
+ return {value, expiresAt: data.expiresAt, model: String(data.model ?? '')};
100
+ }
101
+
102
+ async function requestJson(fetcher: FetchLike, url: string, init: RequestInit): Promise<unknown> {
103
+ const response = await fetcher(url, init);
104
+ const text = await response.text();
105
+ let result: unknown = null;
106
+ if (text.length > 0) {
107
+ try {
108
+ result = JSON.parse(text) as unknown;
109
+ } catch {
110
+ throw new Error(`Relay returned a non-JSON response (${response.status}).`);
111
+ }
112
+ }
113
+ if (!response.ok) {
114
+ throw new Error(`Relay request failed (${response.status}): ${errorDetail(result)}`);
115
+ }
116
+ return result;
117
+ }
118
+
119
+ function requireRecord(value: unknown, message: string): Record<string, unknown> {
120
+ if (typeof value !== 'object' || value === null || Array.isArray(value)) throw new Error(message);
121
+ return value as Record<string, unknown>;
122
+ }
123
+
124
+ function errorDetail(value: unknown): string {
125
+ if (typeof value === 'object' && value !== null) {
126
+ const error = (value as Record<string, unknown>).error;
127
+ if (typeof error === 'object' && error !== null) {
128
+ const message = (error as Record<string, unknown>).message;
129
+ if (typeof message === 'string') return message;
130
+ }
131
+ }
132
+ return 'unknown error';
133
+ }
@@ -0,0 +1,71 @@
1
+ import type {FunctionTool} from '@kubohiroya/turbowarp-named-functions/composition';
2
+
3
+ export type OutputMode = 'audio' | 'text';
4
+
5
+ /** Request body sent to the relay's client-secret route (see capability-proxy). */
6
+ export interface RealtimeSessionRequest {
7
+ model?: string;
8
+ instructions?: string;
9
+ voice?: string;
10
+ outputModalities?: [OutputMode];
11
+ tools?: FunctionTool[];
12
+ }
13
+
14
+ export interface SessionSettings {
15
+ /** Empty means the relay's default model. */
16
+ model: string;
17
+ instructions: string;
18
+ voice: string;
19
+ outputMode: OutputMode;
20
+ }
21
+
22
+ export const MAX_INSTRUCTIONS_LENGTH = 16384;
23
+ export const MAX_TOOLS = 32;
24
+ const VOICE_PATTERN = /^[a-z0-9_-]{1,32}$/u;
25
+ const MODEL_PATTERN = /^[A-Za-z0-9._:-]{1,128}$/u;
26
+
27
+ export const SUPPORTED_MODELS = ['gpt-realtime-2.1-mini', 'gpt-realtime-2.1'] as const;
28
+
29
+ export function defaultSessionSettings(): SessionSettings {
30
+ return {model: '', instructions: '', voice: 'marin', outputMode: 'audio'};
31
+ }
32
+
33
+ /** Accepts an empty string (relay default) or a model identifier; the relay decides what is allowed. */
34
+ export function normalizeModel(value: string): string {
35
+ const model = value.trim();
36
+ if (model.length > 0 && !MODEL_PATTERN.test(model)) throw new TypeError('Model must be a model identifier.');
37
+ return model;
38
+ }
39
+
40
+ export function normalizeVoice(value: string): string {
41
+ const voice = value.trim().toLowerCase();
42
+ if (!VOICE_PATTERN.test(voice)) throw new TypeError('Voice must be a lowercase identifier.');
43
+ return voice;
44
+ }
45
+
46
+ export function normalizeInstructions(value: string): string {
47
+ if (value.length > MAX_INSTRUCTIONS_LENGTH) {
48
+ throw new TypeError(`Instructions must be at most ${MAX_INSTRUCTIONS_LENGTH} characters.`);
49
+ }
50
+ return value;
51
+ }
52
+
53
+ export function normalizeOutputMode(value: string): OutputMode {
54
+ if (value === 'audio' || value === 'text') return value;
55
+ throw new TypeError('Output must be audio or text.');
56
+ }
57
+
58
+ export function buildSessionRequest(
59
+ settings: SessionSettings,
60
+ tools: readonly FunctionTool[]
61
+ ): RealtimeSessionRequest {
62
+ if (tools.length > MAX_TOOLS) throw new TypeError(`At most ${MAX_TOOLS} functions can be exported as tools.`);
63
+ const request: RealtimeSessionRequest = {
64
+ voice: settings.voice,
65
+ outputModalities: [settings.outputMode]
66
+ };
67
+ if (settings.model.length > 0) request.model = settings.model;
68
+ if (settings.instructions.length > 0) request.instructions = settings.instructions;
69
+ if (tools.length > 0) request.tools = tools.map((tool) => ({...tool}));
70
+ return request;
71
+ }
@@ -0,0 +1,18 @@
1
+ export type RealtimeEvent = Record<string, unknown> & {type: string};
2
+
3
+ export interface TransportConnectOptions {
4
+ clientSecret: string;
5
+ microphone: boolean;
6
+ onEvent: (event: RealtimeEvent) => void;
7
+ onClose: (reason: string) => void;
8
+ }
9
+
10
+ /**
11
+ * A connection to the Realtime API. WebRTC is the primary implementation; a WebSocket transport can
12
+ * implement the same interface later because both carry the same JSON events.
13
+ */
14
+ export interface RealtimeTransport {
15
+ connect(options: TransportConnectOptions): Promise<void>;
16
+ send(event: RealtimeEvent): void;
17
+ close(): void;
18
+ }
package/src/usage.ts ADDED
@@ -0,0 +1,127 @@
1
+ /**
2
+ * Token usage totals from `response.done` events and an estimated cost.
3
+ *
4
+ * Prices are USD per 1M tokens from the OpenAI pricing page as of 2026-09-18. They are an estimate
5
+ * for learners; the OpenAI dashboard is the source of truth for billing.
6
+ */
7
+
8
+ export interface ModelPrice {
9
+ textInput: number;
10
+ cachedTextInput: number;
11
+ textOutput: number;
12
+ audioInput: number;
13
+ cachedAudioInput: number;
14
+ audioOutput: number;
15
+ }
16
+
17
+ export const MODEL_PRICES: Readonly<Record<string, ModelPrice>> = {
18
+ 'gpt-realtime-2.1': {
19
+ textInput: 4,
20
+ cachedTextInput: 0.4,
21
+ textOutput: 24,
22
+ audioInput: 32,
23
+ cachedAudioInput: 0.4,
24
+ audioOutput: 64
25
+ },
26
+ 'gpt-realtime-2.1-mini': {
27
+ textInput: 0.6,
28
+ cachedTextInput: 0.06,
29
+ textOutput: 2.4,
30
+ audioInput: 10,
31
+ cachedAudioInput: 0.3,
32
+ audioOutput: 20
33
+ }
34
+ };
35
+
36
+ export const PRICES_AS_OF = '2026-09-18';
37
+
38
+ export interface UsageTotals {
39
+ responses: number;
40
+ inputTokens: number;
41
+ outputTokens: number;
42
+ cachedInputTokens: number;
43
+ textInputTokens: number;
44
+ audioInputTokens: number;
45
+ cachedTextInputTokens: number;
46
+ cachedAudioInputTokens: number;
47
+ textOutputTokens: number;
48
+ audioOutputTokens: number;
49
+ estimatedCostUsd: number;
50
+ /** Responses whose model has no known price; their cost is not included. */
51
+ unpricedResponses: number;
52
+ }
53
+
54
+ export function emptyUsage(): UsageTotals {
55
+ return {
56
+ responses: 0,
57
+ inputTokens: 0,
58
+ outputTokens: 0,
59
+ cachedInputTokens: 0,
60
+ textInputTokens: 0,
61
+ audioInputTokens: 0,
62
+ cachedTextInputTokens: 0,
63
+ cachedAudioInputTokens: 0,
64
+ textOutputTokens: 0,
65
+ audioOutputTokens: 0,
66
+ estimatedCostUsd: 0,
67
+ unpricedResponses: 0
68
+ };
69
+ }
70
+
71
+ /** Adds one `response.usage` object to the totals. Unknown or malformed usage counts as zero tokens. */
72
+ export function addUsage(totals: UsageTotals, usage: unknown, model: string): UsageTotals {
73
+ const root = asRecord(usage);
74
+ if (!root) return totals;
75
+ const input = asRecord(root.input_token_details);
76
+ const output = asRecord(root.output_token_details);
77
+ const cachedDetails = asRecord(input?.cached_tokens_details);
78
+
79
+ const textInput = count(input?.text_tokens);
80
+ const audioInput = count(input?.audio_tokens);
81
+ const cached = count(input?.cached_tokens);
82
+ // Without a breakdown, attribute cached tokens to text first: the instructions and tools prefix.
83
+ const cachedText = cachedDetails ? count(cachedDetails.text_tokens) : Math.min(cached, textInput);
84
+ const cachedAudio = cachedDetails ? count(cachedDetails.audio_tokens) : Math.max(0, cached - cachedText);
85
+ const textOutput = count(output?.text_tokens);
86
+ const audioOutput = count(output?.audio_tokens);
87
+
88
+ const next: UsageTotals = {
89
+ responses: totals.responses + 1,
90
+ inputTokens: totals.inputTokens + count(root.input_tokens),
91
+ outputTokens: totals.outputTokens + count(root.output_tokens),
92
+ cachedInputTokens: totals.cachedInputTokens + cached,
93
+ textInputTokens: totals.textInputTokens + textInput,
94
+ audioInputTokens: totals.audioInputTokens + audioInput,
95
+ cachedTextInputTokens: totals.cachedTextInputTokens + cachedText,
96
+ cachedAudioInputTokens: totals.cachedAudioInputTokens + cachedAudio,
97
+ textOutputTokens: totals.textOutputTokens + textOutput,
98
+ audioOutputTokens: totals.audioOutputTokens + audioOutput,
99
+ estimatedCostUsd: totals.estimatedCostUsd,
100
+ unpricedResponses: totals.unpricedResponses
101
+ };
102
+
103
+ const price = MODEL_PRICES[model];
104
+ if (!price) {
105
+ next.unpricedResponses += 1;
106
+ return next;
107
+ }
108
+ next.estimatedCostUsd +=
109
+ (Math.max(0, textInput - cachedText) * price.textInput +
110
+ cachedText * price.cachedTextInput +
111
+ Math.max(0, audioInput - cachedAudio) * price.audioInput +
112
+ cachedAudio * price.cachedAudioInput +
113
+ textOutput * price.textOutput +
114
+ audioOutput * price.audioOutput) /
115
+ 1_000_000;
116
+ return next;
117
+ }
118
+
119
+ function count(value: unknown): number {
120
+ return typeof value === 'number' && Number.isFinite(value) && value > 0 ? Math.floor(value) : 0;
121
+ }
122
+
123
+ function asRecord(value: unknown): Record<string, unknown> | null {
124
+ return typeof value === 'object' && value !== null && !Array.isArray(value)
125
+ ? (value as Record<string, unknown>)
126
+ : null;
127
+ }
@@ -0,0 +1,156 @@
1
+ import type {FetchLike} from './relay-client.js';
2
+ import type {RealtimeEvent, RealtimeTransport, TransportConnectOptions} from './transport.js';
3
+
4
+ export const REALTIME_CALLS_URL = 'https://api.openai.com/v1/realtime/calls';
5
+ export const EVENTS_CHANNEL = 'oai-events';
6
+
7
+ export interface WebRtcDependencies {
8
+ createPeerConnection: () => RTCPeerConnection;
9
+ getUserMedia: (constraints: MediaStreamConstraints) => Promise<MediaStream>;
10
+ createAudioElement: () => HTMLAudioElement;
11
+ fetch: FetchLike;
12
+ channelOpenTimeoutMs?: number;
13
+ }
14
+
15
+ export function browserWebRtcDependencies(): WebRtcDependencies {
16
+ return {
17
+ createPeerConnection: () => new RTCPeerConnection(),
18
+ getUserMedia: (constraints) => navigator.mediaDevices.getUserMedia(constraints),
19
+ createAudioElement: () => {
20
+ const element = document.createElement('audio');
21
+ element.autoplay = true;
22
+ return element;
23
+ },
24
+ fetch: (input, init) => fetch(input, init)
25
+ };
26
+ }
27
+
28
+ /** Browser-to-OpenAI WebRTC session authenticated with an ephemeral client secret. */
29
+ export class WebRtcTransport implements RealtimeTransport {
30
+ private peer: RTCPeerConnection | null = null;
31
+ private channel: RTCDataChannel | null = null;
32
+ private microphone: MediaStream | null = null;
33
+ private audio: HTMLAudioElement | null = null;
34
+ private closed = false;
35
+
36
+ public constructor(private readonly deps: WebRtcDependencies = browserWebRtcDependencies()) {}
37
+
38
+ public async connect(options: TransportConnectOptions): Promise<void> {
39
+ this.closed = false;
40
+ try {
41
+ const peer = this.deps.createPeerConnection();
42
+ this.peer = peer;
43
+ const audio = this.deps.createAudioElement();
44
+ this.audio = audio;
45
+ peer.ontrack = (event) => {
46
+ audio.srcObject = event.streams[0] ?? null;
47
+ };
48
+
49
+ if (options.microphone) {
50
+ const stream = await this.deps.getUserMedia({audio: true});
51
+ this.microphone = stream;
52
+ for (const track of stream.getAudioTracks()) peer.addTrack(track, stream);
53
+ } else {
54
+ peer.addTransceiver('audio', {direction: 'recvonly'});
55
+ }
56
+
57
+ const channel = peer.createDataChannel(EVENTS_CHANNEL);
58
+ this.channel = channel;
59
+ channel.onmessage = (message) => {
60
+ const event = parseEvent(message.data);
61
+ if (event) options.onEvent(event);
62
+ };
63
+ channel.onclose = () => this.handleClose(options, 'The Realtime data channel closed.');
64
+ peer.onconnectionstatechange = () => {
65
+ if (peer.connectionState === 'failed' || peer.connectionState === 'closed') {
66
+ this.handleClose(options, `The Realtime connection ${peer.connectionState}.`);
67
+ }
68
+ };
69
+ const opened = waitForOpen(channel, this.deps.channelOpenTimeoutMs ?? 15_000);
70
+ // Awaited below; this keeps an early failure from surfacing as an unhandled rejection.
71
+ opened.catch(() => undefined);
72
+
73
+ const offer = await peer.createOffer();
74
+ await peer.setLocalDescription(offer);
75
+ const response = await this.deps.fetch(REALTIME_CALLS_URL, {
76
+ method: 'POST',
77
+ body: offer.sdp ?? '',
78
+ headers: {
79
+ authorization: `Bearer ${options.clientSecret}`,
80
+ 'content-type': 'application/sdp'
81
+ },
82
+ redirect: 'error'
83
+ });
84
+ const answer = await response.text();
85
+ if (!response.ok) {
86
+ throw new Error(`Realtime call setup failed (${response.status}).`);
87
+ }
88
+ await peer.setRemoteDescription({type: 'answer', sdp: answer});
89
+ await opened;
90
+ } catch (error) {
91
+ this.close();
92
+ throw error;
93
+ }
94
+ }
95
+
96
+ public send(event: RealtimeEvent): void {
97
+ if (!this.channel || this.channel.readyState !== 'open') {
98
+ throw new Error('Not connected to Realtime.');
99
+ }
100
+ this.channel.send(JSON.stringify(event));
101
+ }
102
+
103
+ public close(): void {
104
+ this.closed = true;
105
+ const channel = this.channel;
106
+ const peer = this.peer;
107
+ this.channel = null;
108
+ this.peer = null;
109
+ if (channel) {
110
+ channel.onmessage = null;
111
+ channel.onclose = null;
112
+ channel.close();
113
+ }
114
+ if (peer) {
115
+ peer.onconnectionstatechange = null;
116
+ peer.ontrack = null;
117
+ peer.close();
118
+ }
119
+ for (const track of this.microphone?.getTracks() ?? []) track.stop();
120
+ this.microphone = null;
121
+ if (this.audio) {
122
+ this.audio.srcObject = null;
123
+ this.audio = null;
124
+ }
125
+ }
126
+
127
+ private handleClose(options: TransportConnectOptions, reason: string): void {
128
+ if (this.closed) return;
129
+ this.close();
130
+ options.onClose(reason);
131
+ }
132
+ }
133
+
134
+ function parseEvent(data: unknown): RealtimeEvent | null {
135
+ if (typeof data !== 'string') return null;
136
+ try {
137
+ const value = JSON.parse(data) as unknown;
138
+ if (typeof value === 'object' && value !== null && typeof (value as {type?: unknown}).type === 'string') {
139
+ return value as RealtimeEvent;
140
+ }
141
+ } catch {
142
+ // Ignore malformed events.
143
+ }
144
+ return null;
145
+ }
146
+
147
+ function waitForOpen(channel: RTCDataChannel, timeoutMs: number): Promise<void> {
148
+ if (channel.readyState === 'open') return Promise.resolve();
149
+ return new Promise((resolve, reject) => {
150
+ const timer = setTimeout(() => reject(new Error('Timed out opening the Realtime data channel.')), timeoutMs);
151
+ channel.addEventListener('open', () => {
152
+ clearTimeout(timer);
153
+ resolve();
154
+ }, {once: true});
155
+ });
156
+ }