@marinoscar/platform-api 0.0.0-stage → 0.1.0-next.4

package/dist/ai/providers/openai/openai-images.mapper.js

@@ -0,0 +1,164 @@
+"use strict";
+// =============================================================================
+// OpenAI images mapper (issue #437, epic #420)
+// =============================================================================
+//
+// AiImageGenerationRequest / AiImageEditRequest <-> `POST /v1/images/generations`
+// and `POST /v1/images/edits`. Pure functions (plus `toFile`, which only wraps
+// bytes); every failure is an `AiError`, never an SDK error.
+//
+// BYTES, NEVER URLS. The port's contract (`media.types.ts`) is bytes + MIME
+// type: a provider-hosted URL expires and is not ours to authorize. The GPT
+// image family always answers `b64_json`; the DALL·E family defaults to a
+// URL, so the mapper pins `response_format: 'b64_json'` for it — and refuses
+// an answer that carries only a URL rather than fetching it.
+//
+// TWO FAMILIES, TWO PARAMETER SETS. `gpt-image-*` (and `chatgpt-image-*`)
+// take `output_format`, `background` and `quality: low|medium|high|auto`, and
+// reject `response_format`. `dall-e-*` take `response_format` and reject the
+// other three (DALL·E 3 names its quality `standard|hd`), so for DALL·E the
+// neutral `quality: 'high'` becomes `hd` and everything the family cannot
+// honour is left out rather than sent to a 400. DALL·E always returns PNG.
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isOpenAiDallE = isOpenAiDallE;
+exports.toOpenAiImageGenerateRequest = toOpenAiImageGenerateRequest;
+exports.toOpenAiImageEditRequest = toOpenAiImageEditRequest;
+exports.fromOpenAiImagesResponse = fromOpenAiImagesResponse;
+const openai_1 = require("openai");
+const ai_error_1 = require("../../core/ai-error");
+const openai_errors_1 = require("./openai-errors");
+const DALL_E = /^dall-e-/;
+const DALL_E_3 = /^dall-e-3(?:-|$)/;
+const FORMAT_MIME = {
+    png: 'image/png',
+    jpeg: 'image/jpeg',
+    webp: 'image/webp',
+};
+const MIME_EXTENSION = {
+    'image/png': 'png',
+    'image/jpeg': 'jpg',
+    'image/webp': 'webp',
+    'image/gif': 'gif',
+};
+/** Whether OpenAI model `modelId` is a DALL·E model (URL-by-default, no output_format). */
+function isOpenAiDallE(modelId) {
+    return DALL_E.test(modelId.trim().toLowerCase());
+}
+/** The fields generate and edit share, shaped for the model's family. */
+function sharedParams(req) {
+    const params = { model: req.model, prompt: req.prompt };
+    if (req.n !== undefined)
+        params.n = req.n;
+    if (req.size !== undefined)
+        params.size = req.size;
+    if (isOpenAiDallE(req.model)) {
+        params.response_format = 'b64_json';
+        if (req.quality === 'high' && DALL_E_3.test(req.model.trim().toLowerCase())) {
+            params.quality = 'hd';
+        }
+    }
+    else {
+        if (req.quality !== undefined)
+            params.quality = req.quality;
+        if (req.background !== undefined)
+            params.background = req.background;
+        if (req.outputFormat !== undefined)
+            params.output_format = req.outputFormat;
+    }
+    return params;
+}
+function escapeHatch(req) {
+    return (req.providerOptions?.[openai_errors_1.OPENAI_PROVIDER_ID] ?? {});
+}
+/** The `/v1/images/generations` body. `providerOptions.openai` merges first; the port's own fields win. */
+function toOpenAiImageGenerateRequest(req) {
+    return { ...escapeHatch(req), ...sharedParams(req), stream: false };
+}
+function fileName(payload, fallback) {
+    if (payload.filename && payload.filename.trim().length > 0)
+        return payload.filename;
+    return `${fallback}.${MIME_EXTENSION[payload.mimeType] ?? 'png'}`;
+}
+/**
+ * The `/v1/images/edits` multipart body. The images (and mask) become SDK
+ * uploads carrying their MIME type, so OpenAI can tell a PNG from a JPEG.
+ */
+async function toOpenAiImageEditRequest(req) {
+    if (!Array.isArray(req.images) || req.images.length === 0) {
+        throw new ai_error_1.AiError('AI_INVALID_REQUEST', 'An image edit needs at least one source image.', {
+            details: { provider: openai_errors_1.OPENAI_PROVIDER_ID },
+        });
+    }
+    const images = await Promise.all(req.images.map((image, index) => (0, openai_1.toFile)(image.data, fileName(image, `image-${index + 1}`), { type: image.mimeType })));
+    // `hd` is DALL·E 3's word, and DALL·E 3 cannot edit: never send it here.
+    const { quality, ...shared } = sharedParams(req);
+    const body = {
+        ...escapeHatch(req),
+        ...shared,
+        ...(quality !== undefined && quality !== 'hd' ? { quality } : {}),
+        // DALL·E 2 edits exactly one image and rejects the array form.
+        image: images.length === 1 && isOpenAiDallE(req.model) ? images[0] : images,
+        stream: false,
+    };
+    if (req.mask) {
+        body.mask = await (0, openai_1.toFile)(req.mask.data, fileName(req.mask, 'mask'), { type: req.mask.mimeType });
+    }
+    return body;
+}
+function malformed(reason, opts) {
+    return new ai_error_1.AiError('AI_PROVIDER_UNAVAILABLE', 'OpenAI returned a malformed images response.', {
+        details: {
+            provider: openai_errors_1.OPENAI_PROVIDER_ID,
+            reason,
+            ...(opts.providerRequestId ? { providerRequestId: opts.providerRequestId } : {}),
+        },
+    });
+}
+/** Token usage, where the GPT image family reports it (DALL·E does not). */
+function imageUsage(usage) {
+    if (!usage)
+        return {};
+    const out = {};
+    if (typeof usage.input_tokens === 'number')
+        out.inputTokens = usage.input_tokens;
+    if (typeof usage.output_tokens === 'number')
+        out.outputTokens = usage.output_tokens;
+    return out;
+}
+/**
+ * The neutral result: one decoded image per `data` entry, each with the MIME
+ * type of the format the provider says it produced (the request's
+ * `outputFormat` when it does not say, PNG when neither does). No images, or
+ * an entry with no `b64_json` (a URL-only answer), is a provider fault.
+ */
+function fromOpenAiImagesResponse(data, opts) {
+    const items = data.data ?? [];
+    if (items.length === 0) {
+        throw malformed('no_images', opts);
+    }
+    const format = data.output_format ?? (isOpenAiDallE(opts.request.model) ? 'png' : opts.request.outputFormat) ?? 'png';
+    const mimeType = FORMAT_MIME[format] ?? 'image/png';
+    const images = items.map((item) => {
+        if (typeof item.b64_json !== 'string' || item.b64_json.length === 0) {
+            throw malformed('missing_b64_json', opts);
+        }
+        const bytes = Buffer.from(item.b64_json, 'base64');
+        if (bytes.length === 0) {
+            throw malformed('empty_image', opts);
+        }
+        return {
+            data: bytes,
+            mimeType,
+            ...(item.revised_prompt ? { revisedPrompt: item.revised_prompt } : {}),
+        };
+    });
+    return {
+        provider: openai_errors_1.OPENAI_PROVIDER_ID,
+        model: opts.request.model,
+        images,
+        usage: imageUsage(data.usage),
+        ...(opts.providerRequestId ? { providerRequestId: opts.providerRequestId } : {}),
+    };
+}
+//# sourceMappingURL=openai-images.mapper.js.map

package/dist/ai/providers/openai/openai-images.mapper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"openai-images.mapper.js","sourceRoot":"","sources":["../../../../src/ai/providers/openai/openai-images.mapper.ts"],"names":[],"mappings":"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"}

package/dist/ai/providers/openai/openai-model-catalog.d.ts

@@ -0,0 +1,36 @@
+import type { AiModelCapabilities } from '../../core/capabilities';
+export interface OpenAiClassifierRule {
+    /** Tested against the full model id. */
+    match: RegExp;
+    /** `null` claims the id as deliberately unclassified. */
+    capabilities: AiModelCapabilities | null;
+}
+/**
+ * Every voice OpenAI's speech endpoint accepts —
+ * `OpenAiProviderAdapter.audio.voices`. The `tts-1` family speaks the first nine only.
+ */
+export declare const OPENAI_SPEECH_VOICES: readonly ["alloy", "ash", "coral", "echo", "fable", "onyx", "nova", "sage", "shimmer", "ballad", "verse", "marin", "cedar"];
+/**
+ * The voices `tts-1` and `tts-1-hd` speak.
+ *
+ * @internal
+ */
+export declare const OPENAI_TTS1_VOICES: ("alloy" | "ash" | "coral" | "echo" | "fable" | "onyx" | "nova" | "sage" | "shimmer" | "ballad" | "verse" | "marin" | "cedar")[];
+/**
+ * Every voice a realtime session accepts —
+ * `OpenAiProviderAdapter.realtime.voices` and the `realtime` classification's `voices` (#449). Not the
+ * speech list: `fable`, `onyx` and `nova` are `/v1/audio/speech` only.
+ * `marin` and `cedar` are the GA `gpt-realtime` voices OpenAI recommends.
+ */
+export declare const OPENAI_REALTIME_VOICES: readonly ["alloy", "ash", "ballad", "coral", "echo", "sage", "shimmer", "verse", "marin", "cedar"];
+/** Ordered; first match wins. See the file header before reordering. */
+export declare const OPENAI_CLASSIFIER_RULES: readonly OpenAiClassifierRule[];
+/**
+ * The capabilities OpenAI model `modelId` is believed to have, or `null` when
+ * this table does not recognise it. Returns a fresh copy each call, so a
+ * caller mutating the result cannot corrupt the table.
+ *
+ * @internal
+ */
+export declare function classifyOpenAiModel(modelId: string, rules?: readonly OpenAiClassifierRule[]): AiModelCapabilities | null;
+//# sourceMappingURL=openai-model-catalog.d.ts.map

package/dist/ai/providers/openai/openai-model-catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openai-model-catalog.d.ts","sourceRoot":"","sources":["../../../../src/ai/providers/openai/openai-model-catalog.ts"],"names":[],"mappings":"AAwBA,OAAO,KAAK,EAAE,mBAAmB,EAAqB,MAAM,yBAAyB,CAAC;AAEtF,MAAM,WAAW,oBAAoB;IACnC,wCAAwC;IACxC,KAAK,EAAE,MAAM,CAAC;IACd,yDAAyD;IACzD,YAAY,EAAE,mBAAmB,GAAG,IAAI,CAAC;CAC1C;AA6ED;;;GAGG;AACH,eAAO,MAAM,oBAAoB,6HAcvB,CAAC;AAEX;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,kIAAmC,CAAC;AAiBnE;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,oGAWzB,CAAC;AAcX,wEAAwE;AACxE,eAAO,MAAM,uBAAuB,EAAE,SAAS,oBAAoB,EAkClE,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,MAAM,EACf,KAAK,GAAE,SAAS,oBAAoB,EAA4B,GAC/D,mBAAmB,GAAG,IAAI,CAU5B"}

package/dist/ai/providers/openai/openai-model-catalog.js

@@ -0,0 +1,209 @@
+"use strict";
+// =============================================================================
+// OpenAI model classifier (issue #426, epic #419)
+// =============================================================================
+//
+// This table is a best-effort default; admins override per model. Update it
+// when OpenAI ships new families.
+//
+// `GET /v1/models` returns ids and nothing about what a model can do, so
+// `classifyModel()` answers from this ordered rule list: FIRST MATCH WINS, and
+// no match means `null` — the catalog (#427) stores the model as
+// `unclassified` and an administrator decides, rather than this file guessing
+// (docs/specs/ai-platform.md §2.17: a wrong guess is worse than "unknown").
+//
+// Dated snapshots (`gpt-4o-2024-08-06`, `o3-mini-2025-01-31`) are kept, not
+// filtered as noise, and classify like their family — every pattern is a
+// prefix match for exactly that reason.
+//
+// A rule may map to `null` on purpose: a family this platform cannot drive
+// through any port yet (Chat-Completions-only audio and search previews,
+// legacy completions models) is claimed explicitly so that a broader rule
+// further down cannot mis-classify it. Specific rules therefore come before
+// general ones — the order IS the logic.
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OPENAI_CLASSIFIER_RULES = exports.OPENAI_REALTIME_VOICES = exports.OPENAI_TTS1_VOICES = exports.OPENAI_SPEECH_VOICES = void 0;
+exports.classifyOpenAiModel = classifyOpenAiModel;
+const GPT5_EFFORTS = ['minimal', 'low', 'medium', 'high'];
+const O_SERIES_EFFORTS = ['low', 'medium', 'high'];
+/** A reasoning model that sees images and files (gpt-5*, o1/o3/o4-mini, codex). */
+function reasoningMultimodal(efforts) {
+    return {
+        capabilities: [
+            'responses',
+            'reasoning',
+            'tools',
+            'hosted_tools',
+            'structured_output',
+            'streaming',
+            'vision_input',
+            'file_input',
+        ],
+        inputModalities: ['text', 'image', 'file'],
+        outputModalities: ['text'],
+        reasoningEfforts: efforts,
+    };
+}
+/** A text-only reasoning model (o1-mini, o3-mini). */
+const REASONING_TEXT = {
+    capabilities: ['responses', 'reasoning', 'tools', 'structured_output', 'streaming'],
+    inputModalities: ['text'],
+    outputModalities: ['text'],
+    reasoningEfforts: O_SERIES_EFFORTS,
+};
+/**
+ * A non-reasoning multimodal chat model (gpt-4o, gpt-4.1, gpt-5-chat). It and
+ * the reasoning multimodal family above carry `hosted_tools` (#442): the
+ * Responses API offers them web search, file search, code interpreter,
+ * image generation and remote MCP. An individual model that lacks one is
+ * refused by OpenAI itself; an administrator can override the chip.
+ */
+const CHAT_MULTIMODAL = {
+    capabilities: ['responses', 'tools', 'hosted_tools', 'structured_output', 'streaming', 'vision_input', 'file_input'],
+    inputModalities: ['text', 'image', 'file'],
+    outputModalities: ['text'],
+};
+/** gpt-4-turbo: vision and tools, but predates strict structured outputs. */
+const CHAT_VISION_LEGACY = {
+    capabilities: ['responses', 'tools', 'streaming', 'vision_input'],
+    inputModalities: ['text', 'image'],
+    outputModalities: ['text'],
+};
+/** gpt-4 / gpt-3.5-turbo: text in, text out, function calling. */
+const CHAT_TEXT_LEGACY = {
+    capabilities: ['responses', 'tools', 'streaming'],
+    inputModalities: ['text'],
+    outputModalities: ['text'],
+};
+const IMAGE_GENERATE_AND_EDIT = {
+    capabilities: ['image_generation', 'image_edit'],
+    inputModalities: ['text', 'image'],
+    outputModalities: ['image'],
+};
+const IMAGE_GENERATE_ONLY = {
+    capabilities: ['image_generation'],
+    inputModalities: ['text'],
+    outputModalities: ['image'],
+};
+const TRANSCRIPTION = {
+    capabilities: ['audio_transcription'],
+    inputModalities: ['audio'],
+    outputModalities: ['text'],
+};
+/**
+ * Every voice OpenAI's speech endpoint accepts —
+ * `OpenAiProviderAdapter.audio.voices`. The `tts-1` family speaks the first nine only.
+ */
+exports.OPENAI_SPEECH_VOICES = [
+    'alloy',
+    'ash',
+    'coral',
+    'echo',
+    'fable',
+    'onyx',
+    'nova',
+    'sage',
+    'shimmer',
+    'ballad',
+    'verse',
+    'marin',
+    'cedar',
+];
+/**
+ * The voices `tts-1` and `tts-1-hd` speak.
+ *
+ * @internal
+ */
+exports.OPENAI_TTS1_VOICES = exports.OPENAI_SPEECH_VOICES.slice(0, 9);
+function speech(voices) {
+    return {
+        capabilities: ['audio_speech'],
+        inputModalities: ['text'],
+        outputModalities: ['audio'],
+        voices: [...voices],
+    };
+}
+const EMBEDDINGS = {
+    capabilities: ['embeddings'],
+    inputModalities: ['text'],
+    outputModalities: ['embedding'],
+};
+/**
+ * Every voice a realtime session accepts —
+ * `OpenAiProviderAdapter.realtime.voices` and the `realtime` classification's `voices` (#449). Not the
+ * speech list: `fable`, `onyx` and `nova` are `/v1/audio/speech` only.
+ * `marin` and `cedar` are the GA `gpt-realtime` voices OpenAI recommends.
+ */
+exports.OPENAI_REALTIME_VOICES = [
+    'alloy',
+    'ash',
+    'ballad',
+    'coral',
+    'echo',
+    'sage',
+    'shimmer',
+    'verse',
+    'marin',
+    'cedar',
+];
+/**
+ * `gpt-realtime*`, `gpt-4o-realtime-preview*` and `gpt-4o-mini-realtime*`:
+ * speech-to-speech over a browser-held session (#449), minted by the
+ * adapter's `realtime` port.
+ */
+const REALTIME = {
+    capabilities: ['realtime'],
+    inputModalities: ['text', 'audio'],
+    outputModalities: ['text', 'audio'],
+    voices: [...exports.OPENAI_REALTIME_VOICES],
+};
+/** Ordered; first match wins. See the file header before reordering. */
+exports.OPENAI_CLASSIFIER_RULES = [
+    // ---- Special-purpose families first: their ids share prefixes with chat models.
+    { match: /realtime/, capabilities: REALTIME },
+    { match: /transcribe|^whisper-/, capabilities: TRANSCRIPTION },
+    { match: /^tts-1(?:-|$)/, capabilities: speech(exports.OPENAI_TTS1_VOICES) },
+    { match: /^tts-|-tts(?:-|$)/, capabilities: speech(exports.OPENAI_SPEECH_VOICES) },
+    { match: /^text-embedding-/, capabilities: EMBEDDINGS },
+    { match: /^dall-e-2(?:-|$)/, capabilities: IMAGE_GENERATE_AND_EDIT },
+    { match: /^dall-e-3(?:-|$)/, capabilities: IMAGE_GENERATE_ONLY },
+    { match: /^(?:chatgpt-|gpt-)image-|-image-/, capabilities: IMAGE_GENERATE_AND_EDIT },
+    // ---- Deliberately unclassified: no port drives these yet.
+    { match: /^gpt-(?:4o-(?:mini-)?)?audio/, capabilities: null },
+    { match: /-search-(?:preview|api)/, capabilities: null },
+    { match: /moderation/, capabilities: null },
+    { match: /^computer-use/, capabilities: null },
+    { match: /^gpt-3\.5-turbo-instruct/, capabilities: null },
+    // ---- GPT-5 family: reasoning, except the `-chat` variants.
+    { match: /^gpt-5(?:\.\d+)?-chat/, capabilities: CHAT_MULTIMODAL },
+    { match: /^gpt-5(?:[.-]|$)/, capabilities: reasoningMultimodal(GPT5_EFFORTS) },
+    // ---- o-series reasoning.
+    { match: /^o[13]-mini(?:-|$)/, capabilities: REASONING_TEXT },
+    { match: /^o\d(?:-|$)/, capabilities: reasoningMultimodal(O_SERIES_EFFORTS) },
+    { match: /^codex-/, capabilities: reasoningMultimodal(O_SERIES_EFFORTS) },
+    // ---- Non-reasoning chat models.
+    { match: /^gpt-4\.1(?:-|$)/, capabilities: CHAT_MULTIMODAL },
+    { match: /^gpt-4o(?:-|$)/, capabilities: CHAT_MULTIMODAL },
+    { match: /^chatgpt-4o-/, capabilities: CHAT_MULTIMODAL },
+    { match: /^gpt-4-turbo|^gpt-4-(?:\d{4}-)?vision/, capabilities: CHAT_VISION_LEGACY },
+    { match: /^gpt-4(?:-|$)/, capabilities: CHAT_TEXT_LEGACY },
+    { match: /^gpt-3\.5-turbo(?:-|$)/, capabilities: CHAT_TEXT_LEGACY },
+];
+/**
+ * The capabilities OpenAI model `modelId` is believed to have, or `null` when
+ * this table does not recognise it. Returns a fresh copy each call, so a
+ * caller mutating the result cannot corrupt the table.
+ *
+ * @internal
+ */
+function classifyOpenAiModel(modelId, rules = exports.OPENAI_CLASSIFIER_RULES) {
+    const id = modelId.trim().toLowerCase();
+    for (const rule of rules) {
+        if (rule.match.test(id)) {
+            return rule.capabilities ? structuredClone(rule.capabilities) : null;
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=openai-model-catalog.js.map

package/dist/ai/providers/openai/openai-model-catalog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"openai-model-catalog.js","sourceRoot":"","sources":["../../../../src/ai/providers/openai/openai-model-catalog.ts"],"names":[],"mappings":"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"}

package/dist/ai/providers/openai/openai-realtime.mapper.d.ts

@@ -0,0 +1,18 @@
+import type { ClientSecretCreateParams, ClientSecretCreateResponse } from 'openai/resources/realtime/client-secrets';
+import { type AiRealtimeSession, type AiRealtimeSessionRequest } from '../../core/types/media.types';
+/** The provider's accepted range for `expires_after.seconds`. */
+export declare const OPENAI_REALTIME_TTL_MIN_SECONDS = 10;
+export declare const OPENAI_REALTIME_TTL_MAX_SECONDS = 7200;
+/** The largest per-response `max_output_tokens` a realtime session accepts (or `inf`). */
+export declare const OPENAI_REALTIME_MAX_OUTPUT_TOKENS = 4096;
+/** The WebRTC SDP endpoint under a base URL. */
+export declare function openAiRealtimeConnectUrl(baseUrl: string | undefined): string;
+/** `AiRealtimeSessionRequest` → the `client_secrets` body. */
+export declare function toOpenAiClientSecretRequest(req: AiRealtimeSessionRequest): ClientSecretCreateParams;
+/** The `client_secrets` answer → `AiRealtimeSession`. */
+export declare function fromOpenAiClientSecretResponse(data: ClientSecretCreateResponse, context: {
+    request: AiRealtimeSessionRequest;
+    baseUrl?: string;
+    providerRequestId?: string | null;
+}): AiRealtimeSession;
+//# sourceMappingURL=openai-realtime.mapper.d.ts.map

package/dist/ai/providers/openai/openai-realtime.mapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openai-realtime.mapper.d.ts","sourceRoot":"","sources":["../../../../src/ai/providers/openai/openai-realtime.mapper.ts"],"names":[],"mappings":"AA6BA,OAAO,KAAK,EACV,wBAAwB,EACxB,0BAA0B,EAC3B,MAAM,0CAA0C,CAAC;AAQlD,OAAO,EAEL,KAAK,iBAAiB,EACtB,KAAK,wBAAwB,EAE9B,MAAM,8BAA8B,CAAC;AAItC,iEAAiE;AACjE,eAAO,MAAM,+BAA+B,KAAK,CAAC;AAClD,eAAO,MAAM,+BAA+B,OAAO,CAAC;AAEpD,0FAA0F;AAC1F,eAAO,MAAM,iCAAiC,OAAO,CAAC;AAEtD,gDAAgD;AAChD,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAE5E;AAED,8DAA8D;AAC9D,wBAAgB,2BAA2B,CAAC,GAAG,EAAE,wBAAwB,GAAG,wBAAwB,CA0CnG;AAED,yDAAyD;AACzD,wBAAgB,8BAA8B,CAC5C,IAAI,EAAE,0BAA0B,EAChC,OAAO,EAAE;IAAE,OAAO,EAAE,wBAAwB,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,GAClG,iBAAiB,CAoCnB"}

package/dist/ai/providers/openai/openai-realtime.mapper.js

@@ -0,0 +1,159 @@
+"use strict";
+// =============================================================================
+// OpenAI realtime mapper (issue #449, epic #421)
+// =============================================================================
+//
+// AiRealtimeSessionRequest <-> `POST /v1/realtime/client_secrets` (the GA
+// Realtime API; the beta `POST /v1/realtime/sessions` is not used). Pure
+// functions; every failure is an `AiError`, never an SDK error.
+//
+// WHAT GOES OUT. `expires_after` is ALWAYS sent (60 seconds by default,
+// `AI_REALTIME_CLIENT_SECRET_TTL_SECONDS`), so the provider's own default,
+// which has changed over time, never decides how long a secret lives. The
+// `session` object is the session's initial configuration: model, voice,
+// instructions, output modalities, turn detection, tools and an output-token
+// cap (at most 4096, the realtime ceiling). `providerOptions.openai` is merged into `session` last, the same
+// escape hatch every other mapper offers.
+//
+// WHAT COMES BACK. `{ value: 'ek_…', expires_at, session }`. `value` is the
+// ephemeral client secret; it becomes `clientSecret` and is otherwise
+// untouched. ⚠ It is a bearer credential: nothing in this file logs it, and
+// `sessionConfig` is rebuilt from named, non-secret fields rather than
+// passed through, so a provider that one day echoes a secret inside
+// `session` cannot leak it through this mapper.
+//
+// THE CONNECT URL is `<baseUrl>/realtime/calls`: the browser POSTs its SDP
+// offer there with `Authorization: Bearer <clientSecret>`. It follows the
+// slot's `baseUrl`, so a deployment behind an OpenAI-compatible gateway
+// sends its browsers to the same place the secret was minted.
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OPENAI_REALTIME_MAX_OUTPUT_TOKENS = exports.OPENAI_REALTIME_TTL_MAX_SECONDS = exports.OPENAI_REALTIME_TTL_MIN_SECONDS = void 0;
+exports.openAiRealtimeConnectUrl = openAiRealtimeConnectUrl;
+exports.toOpenAiClientSecretRequest = toOpenAiClientSecretRequest;
+exports.fromOpenAiClientSecretResponse = fromOpenAiClientSecretResponse;
+const ai_error_1 = require("../../core/ai-error");
+const structured_output_1 = require("../../core/structured-output");
+const media_types_1 = require("../../core/types/media.types");
+const openai_client_factory_1 = require("./openai-client.factory");
+const openai_errors_1 = require("./openai-errors");
+/** The provider's accepted range for `expires_after.seconds`. */
+exports.OPENAI_REALTIME_TTL_MIN_SECONDS = 10;
+exports.OPENAI_REALTIME_TTL_MAX_SECONDS = 7200;
+/** The largest per-response `max_output_tokens` a realtime session accepts (or `inf`). */
+exports.OPENAI_REALTIME_MAX_OUTPUT_TOKENS = 4096;
+/** The WebRTC SDP endpoint under a base URL. */
+function openAiRealtimeConnectUrl(baseUrl) {
+    return `${(baseUrl ?? openai_client_factory_1.OPENAI_DEFAULT_BASE_URL).replace(/\/+$/, '')}/realtime/calls`;
+}
+/** `AiRealtimeSessionRequest` → the `client_secrets` body. */
+function toOpenAiClientSecretRequest(req) {
+    const seconds = req.expiresInSeconds ?? media_types_1.AI_REALTIME_CLIENT_SECRET_TTL_SECONDS;
+    if (!Number.isInteger(seconds) || seconds < exports.OPENAI_REALTIME_TTL_MIN_SECONDS || seconds > exports.OPENAI_REALTIME_TTL_MAX_SECONDS) {
+        throw new ai_error_1.AiError('AI_INVALID_REQUEST', `A realtime client secret lives ${exports.OPENAI_REALTIME_TTL_MIN_SECONDS}-${exports.OPENAI_REALTIME_TTL_MAX_SECONDS} seconds.`, { details: { provider: openai_errors_1.OPENAI_PROVIDER_ID } });
+    }
+    const session = { type: 'realtime', model: req.model };
+    if (req.instructions !== undefined)
+        session.instructions = req.instructions;
+    if (req.modalities !== undefined)
+        session.output_modalities = [...req.modalities];
+    // A deployment cap above the realtime ceiling is simply the ceiling —
+    // sending it as-is would be a 400 for every mint.
+    if (req.maxOutputTokens !== undefined) {
+        session.max_output_tokens = Math.min(req.maxOutputTokens, exports.OPENAI_REALTIME_MAX_OUTPUT_TOKENS);
+    }
+    const audio = {};
+    if (req.voice !== undefined)
+        audio.output = { voice: req.voice };
+    if (req.turnDetection !== undefined)
+        audio.input = { turn_detection: toTurnDetection(req.turnDetection) };
+    if (Object.keys(audio).length > 0)
+        session.audio = audio;
+    if (req.tools?.length) {
+        session.tools = req.tools.map((tool) => ({
+            type: 'function',
+            name: tool.name,
+            description: tool.description,
+            parameters: (0, structured_output_1.toJsonSchema)(tool.parameters),
+        }));
+    }
+    const extra = req.providerOptions?.[openai_errors_1.OPENAI_PROVIDER_ID];
+    return {
+        expires_after: { anchor: 'created_at', seconds },
+        session: (extra ? { ...session, ...extra, type: 'realtime' } : session),
+    };
+}
+/** The `client_secrets` answer → `AiRealtimeSession`. */
+function fromOpenAiClientSecretResponse(data, context) {
+    const { request } = context;
+    if (typeof data?.value !== 'string' || data.value.length === 0 || typeof data.expires_at !== 'number') {
+        throw new ai_error_1.AiError('AI_PROVIDER_UNAVAILABLE', 'OpenAI returned no realtime client secret.', {
+            details: { provider: openai_errors_1.OPENAI_PROVIDER_ID },
+        });
+    }
+    const session = data.session?.type === 'realtime' ? data.session : undefined;
+    const voice = typeof session?.audio?.output?.voice === 'string' ? session.audio.output.voice : request.voice;
+    const modalities = session?.output_modalities ?? request.modalities;
+    const instructions = session?.instructions ?? request.instructions;
+    const maxOutputTokens = typeof session?.max_output_tokens === 'number' ? session.max_output_tokens : request.maxOutputTokens;
+    const turnDetection = request.turnDetection !== undefined ? request.turnDetection : fromTurnDetection(session?.audio?.input?.turn_detection);
+    const sessionConfig = {};
+    if (modalities !== undefined)
+        sessionConfig.modalities = [...modalities];
+    if (instructions !== undefined)
+        sessionConfig.instructions = instructions;
+    if (turnDetection !== undefined)
+        sessionConfig.turnDetection = turnDetection;
+    if (maxOutputTokens !== undefined)
+        sessionConfig.maxOutputTokens = maxOutputTokens;
+    return {
+        ...(session?.id ? { id: session.id } : {}),
+        provider: openai_errors_1.OPENAI_PROVIDER_ID,
+        model: typeof session?.model === 'string' && session.model.length > 0 ? session.model : request.model,
+        clientSecret: data.value,
+        expiresAt: new Date(data.expires_at * 1000),
+        connectUrl: openAiRealtimeConnectUrl(context.baseUrl),
+        ...(voice !== undefined ? { voice } : {}),
+        sessionConfig,
+        ...(context.providerRequestId ? { providerRequestId: context.providerRequestId } : {}),
+    };
+}
+function toTurnDetection(value) {
+    if (value === null)
+        return null;
+    if (value.type === 'semantic_vad') {
+        return { type: 'semantic_vad', ...(value.eagerness !== undefined ? { eagerness: value.eagerness } : {}) };
+    }
+    return {
+        type: 'server_vad',
+        ...(value.threshold !== undefined ? { threshold: value.threshold } : {}),
+        ...(value.prefixPaddingMs !== undefined ? { prefix_padding_ms: value.prefixPaddingMs } : {}),
+        ...(value.silenceDurationMs !== undefined ? { silence_duration_ms: value.silenceDurationMs } : {}),
+    };
+}
+function fromTurnDetection(value) {
+    if (value === null)
+        return null;
+    if (!value || typeof value !== 'object')
+        return undefined;
+    const raw = value;
+    if (raw.type === 'semantic_vad') {
+        const eagerness = raw.eagerness;
+        return {
+            type: 'semantic_vad',
+            ...(eagerness === 'low' || eagerness === 'medium' || eagerness === 'high' || eagerness === 'auto'
+                ? { eagerness }
+                : {}),
+        };
+    }
+    if (raw.type === 'server_vad') {
+        return {
+            type: 'server_vad',
+            ...(typeof raw.threshold === 'number' ? { threshold: raw.threshold } : {}),
+            ...(typeof raw.prefix_padding_ms === 'number' ? { prefixPaddingMs: raw.prefix_padding_ms } : {}),
+            ...(typeof raw.silence_duration_ms === 'number' ? { silenceDurationMs: raw.silence_duration_ms } : {}),
+        };
+    }
+    return undefined;
+}
+//# sourceMappingURL=openai-realtime.mapper.js.map

package/dist/ai/providers/openai/openai-realtime.mapper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"openai-realtime.mapper.js","sourceRoot":"","sources":["../../../../src/ai/providers/openai/openai-realtime.mapper.ts"],"names":[],"mappings":"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"}

package/dist/ai/providers/openai/openai-redirect-guard.d.ts

@@ -0,0 +1,9 @@
+import type { OpenAiFetch } from './openai-client.factory';
+/** The OpenAI-shaped error code a refused redirect surfaces as (in `details.providerCode`). */
+export declare const REDIRECT_REFUSED_CODE = "redirect_refused";
+/**
+ * `fetch` (the injected one, or the platform's) with redirects refused — see
+ * the file header.
+ */
+export declare function noRedirectFetch(fetch?: OpenAiFetch): OpenAiFetch;
+//# sourceMappingURL=openai-redirect-guard.d.ts.map

package/dist/ai/providers/openai/openai-redirect-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openai-redirect-guard.d.ts","sourceRoot":"","sources":["../../../../src/ai/providers/openai/openai-redirect-guard.ts"],"names":[],"mappings":"AA2BA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAE3D,+FAA+F;AAC/F,eAAO,MAAM,qBAAqB,qBAAqB,CAAC;AAMxD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,KAAK,GAAE,WAA+C,GAAG,WAAW,CAyBnG"}