@marinoscar/platform-web 0.1.0-next.3 → 0.1.0-next.4

package/dist/ai/headless/use-ai-models.js

@@ -0,0 +1,191 @@
+/**
+ * The organisation's AI model catalogue (`/api/admin/ai/models`) — issue
+ * #429, epic #419.
+ *
+ * Fetches one page for the filter it is given and re-fetches whenever that
+ * filter changes (compare by value, so a caller may rebuild the object every
+ * render). A response that arrives after a newer request was sent is DROPPED:
+ * typing in the search box fires several requests, and the last one to be
+ * sent — not the last one to land — is the one on screen.
+ *
+ * ⚠ ENABLING IS OPTIMISTIC. `setEnabled` flips the row at once and rolls it
+ * back if the API refuses (409 `AI_MODEL_DEPRECATED`, 400
+ * `AI_MODEL_UNCLASSIFIED`, or anything else). Resolves `true`/`false`; the refusal lands in `updateError`, worded
+ * from the AI code in `details.reason`.
+ *
+ * `refreshCatalog` enqueues discovery on the job queue and resolves the job
+ * id — the catalogue does not change until that job runs, so the list is not
+ * re-read here.
+ */
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { isPlatformApiError } from '../../core/index.js';
+import { listAiModels, refreshAiModels, updateAiModel } from './client.js';
+import { toAiErrorInfo } from './errors.js';
+import { useIsMounted } from '../internal/use-is-mounted.js';
+import { useAiApi } from './use-ai-api.js';
+/** The AI code an error carries (`details.reason`), or `null`. */
+function aiErrorReason(err) {
+    return toAiErrorInfo(err).code;
+}
+function messageFor(err, fallback) {
+    if (isPlatformApiError(err)) {
+        if (err.status === 403 && !aiErrorReason(err)) {
+            return 'You do not have permission to manage AI models';
+        }
+        return err.message || fallback;
+    }
+    return fallback;
+}
+/** Why a model's enablement was refused, in words an admin can act on. */
+function enableRefusalMessage(err, enabling) {
+    switch (aiErrorReason(err)) {
+        case 'AI_MODEL_DEPRECATED':
+            return 'This model has been withdrawn by the provider and cannot be enabled.';
+        case 'AI_MODEL_UNCLASSIFIED':
+            return 'Classify this model first — edit its capabilities, then enable it.';
+        default:
+            return messageFor(err, enabling ? 'Failed to enable the model' : 'Failed to disable the model');
+    }
+}
+/**
+ * Use AI models.
+ *
+ * @stability experimental
+ */
+export function useAiModels(filter, options = {}) {
+    const api = useAiApi(options.api);
+    const [models, setModels] = useState([]);
+    const [total, setTotal] = useState(0);
+    const [isLoading, setIsLoading] = useState(true);
+    const [error, setError] = useState(null);
+    const [pendingIds, setPendingIds] = useState(new Set());
+    const [updateError, setUpdateError] = useState(null);
+    const [isRefreshing, setIsRefreshing] = useState(false);
+    const [refreshError, setRefreshError] = useState(null);
+    const isMounted = useIsMounted();
+    const requestSeq = useRef(0);
+    // Value identity, so a caller rebuilding the filter object every render
+    // does not refetch every render.
+    const filterKey = JSON.stringify(filter);
+    const fetchModels = useCallback(async () => {
+        const seq = ++requestSeq.current;
+        const isCurrent = () => isMounted() && seq === requestSeq.current;
+        try {
+            setIsLoading(true);
+            setError(null);
+            const response = await listAiModels(api, JSON.parse(filterKey));
+            if (isCurrent()) {
+                setModels(response.items);
+                setTotal(response.total);
+            }
+        }
+        catch (err) {
+            if (isCurrent())
+                setError(messageFor(err, 'Failed to load the model catalogue'));
+        }
+        finally {
+            if (isCurrent())
+                setIsLoading(false);
+        }
+    }, [filterKey, isMounted]);
+    useEffect(() => {
+        void fetchModels();
+    }, [fetchModels]);
+    const markPending = useCallback((id, pending) => {
+        setPendingIds((prev) => {
+            const next = new Set(prev);
+            if (pending)
+                next.add(id);
+            else
+                next.delete(id);
+            return next;
+        });
+    }, []);
+    const replaceModel = useCallback((id, patch) => {
+        setModels((prev) => prev.map((model) => (model.id === id ? patch(model) : model)));
+    }, []);
+    const setEnabled = useCallback(async (model, enabled) => {
+        const previous = model.enabled;
+        setUpdateError(null);
+        markPending(model.id, true);
+        replaceModel(model.id, (row) => ({ ...row, enabled }));
+        try {
+            const updated = await updateAiModel(api, model.id, { enabled });
+            if (isMounted())
+                replaceModel(model.id, () => updated);
+            return true;
+        }
+        catch (err) {
+            if (isMounted()) {
+                replaceModel(model.id, (row) => ({ ...row, enabled: previous }));
+                setUpdateError(enableRefusalMessage(err, enabled));
+            }
+            return false;
+        }
+        finally {
+            if (isMounted())
+                markPending(model.id, false);
+        }
+    }, [isMounted, markPending, replaceModel]);
+    const updateCapabilities = useCallback(async (model, capabilities) => {
+        setUpdateError(null);
+        markPending(model.id, true);
+        try {
+            const updated = await updateAiModel(api, model.id, { capabilities });
+            if (isMounted())
+                replaceModel(model.id, () => updated);
+            return true;
+        }
+        catch (err) {
+            if (isMounted()) {
+                setUpdateError(messageFor(err, 'Failed to save the model capabilities'));
+            }
+            return false;
+        }
+        finally {
+            if (isMounted())
+                markPending(model.id, false);
+        }
+    }, [isMounted, markPending, replaceModel]);
+    const refreshCatalog = useCallback(async (provider) => {
+        try {
+            setIsRefreshing(true);
+            const { jobId } = await refreshAiModels(api, provider);
+            return jobId;
+        }
+        catch (err) {
+            if (isMounted()) {
+                // The server's own message is actionable for AI_DISABLED and
+                // AI_PROVIDER_DISABLED (#888); only a missing key gets web wording.
+                const message = aiErrorReason(err) === 'AI_KEY_REQUIRED'
+                    ? 'This provider has no organization key, so its models cannot be discovered. Save a key on the AI page first.'
+                    : messageFor(err, 'The catalogue refresh could not be queued');
+                setRefreshError((prev) => prev === null ? message : prev.includes(message) ? prev : `${prev} ${message}`);
+            }
+            return null;
+        }
+        finally {
+            if (isMounted())
+                setIsRefreshing(false);
+        }
+    }, [isMounted]);
+    const clearUpdateError = useCallback(() => setUpdateError(null), []);
+    const clearRefreshError = useCallback(() => setRefreshError(null), []);
+    return {
+        models,
+        total,
+        isLoading,
+        error,
+        refetch: fetchModels,
+        pendingIds,
+        updateError,
+        clearUpdateError,
+        setEnabled,
+        updateCapabilities,
+        isRefreshing,
+        refreshError,
+        clearRefreshError,
+        refreshCatalog,
+    };
+}
+//# sourceMappingURL=use-ai-models.js.map

package/dist/ai/headless/use-ai-models.js.map

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

package/dist/ai/headless/use-ai-realtime-session.d.ts

@@ -0,0 +1,185 @@
+/**
+ * One realtime voice session over WebRTC — issue #449, epic #421
+ * (docs/specs/ai-platform.md §2.15).
+ *
+ * THE FLOW. `start()`:
+ *   1. asks for the microphone (`getUserMedia({ audio: true })`) FIRST, so a
+ *      slow permission prompt cannot eat the secret's short connect window;
+ *   2. mints a session (`POST /ai/realtime/sessions`) — the server resolves the
+ *      user's key and trades it for the provider's EPHEMERAL client secret;
+ *   3. builds an `RTCPeerConnection`, adds the mic track, opens the provider's
+ *      `oai-events` data channel and creates an SDP offer;
+ *   4. POSTs the offer straight to the provider's `connectUrl` with
+ *      `Authorization: Bearer <clientSecret>` and applies the SDP answer.
+ * Remote audio arrives on `ontrack` and plays through the `<audio>` element
+ * the caller binds to {@link UseAiRealtimeSessionReturn.audioRef}.
+ *
+ * THE SECRET. `clientSecret` lives in one local variable inside `start()` for
+ * exactly the SDP exchange it exists for. It is never put in state, a ref,
+ * a log line or the DOM. The user's real key never reaches the browser at all.
+ *
+ * TRANSCRIPTS. Both sides are read off the data channel. On open the hook
+ * turns on input transcription with a `session.update`; user lines come from
+ * `conversation.item.input_audio_transcription.delta/.completed`, assistant
+ * lines from `response.output_audio_transcript.delta/.done` (and the beta
+ * `response.audio_transcript.*` names). Lines are keyed by `item_id`, and a
+ * `conversation.item.created/added` reserves a line's place so a user line
+ * whose transcription finishes after the assistant started answering still
+ * reads first.
+ *
+ * CLEANUP. `stop()`, a failure, and unmount all run the same teardown: close
+ * the data channel and the peer connection, stop every mic track, clear the
+ * timer and detach the remote stream. A `stop()` during `start()` is honoured
+ * too: every await is followed by a check that this attempt is still current.
+ */
+import { type RefObject } from 'react';
+import { type AiRealtimeSessionRequest } from './types.js';
+import type { AiHookOptions } from './use-ai-api.js';
+import { type AiErrorInfo } from './errors.js';
+/**
+ * The data channel the provider reads client events from and writes server events to.
+ *
+ * @stability experimental
+ */
+export declare const AI_REALTIME_DATA_CHANNEL = "oai-events";
+/**
+ * The model the provider transcribes the user's speech with.
+ *
+ * @stability experimental
+ */
+export declare const AI_REALTIME_INPUT_TRANSCRIPTION_MODEL = "gpt-4o-mini-transcribe";
+/**
+ * The AI realtime status type.
+ *
+ * @stability experimental
+ */
+export type AiRealtimeStatus = 'idle' | 'starting' | 'connected' | 'ended' | 'error';
+/**
+ * Why a session could not start or stopped. `api` carries the mint's own
+ * AI error (rendered by `AiErrorAlert`); `provider` is an `error` event the
+ * provider sent mid-call, which does not end the session.
+ 
+ *
+ * @stability experimental
+ */
+export type AiRealtimeFailure = {
+    /** Which variant this is (the discriminator). */
+    kind: 'mic-denied';
+} | {
+    /** Which variant this is (the discriminator). */
+    kind: 'no-mic';
+} | {
+    /** Which variant this is (the discriminator). */
+    kind: 'mic-error';
+    /** The message. */
+    message: string;
+} | {
+    /** Which variant this is (the discriminator). */
+    kind: 'unsupported';
+} | {
+    /** Which variant this is (the discriminator). */
+    kind: 'api';
+    /** The error. */
+    error: AiErrorInfo;
+} | {
+    /** Which variant this is (the discriminator). */
+    kind: 'sdp';
+    /** The message. */
+    message: string;
+} | {
+    /** Which variant this is (the discriminator). */
+    kind: 'connection-lost';
+} | {
+    /** Which variant this is (the discriminator). */
+    kind: 'expired';
+} | {
+    /** Which variant this is (the discriminator). */
+    kind: 'provider';
+    /** The message. */
+    message: string;
+};
+/**
+ * The AI realtime transcript line wire shape.
+ *
+ * @stability experimental
+ */
+export interface AiRealtimeTranscriptLine {
+    /** The provider's `item_id` (or a local id when an event carries none). */
+    id: string;
+    /** The role. */
+    role: 'user' | 'assistant';
+    /** The text. */
+    text: string;
+    /** False while deltas are still arriving. */
+    final: boolean;
+}
+/**
+ * What the session runs — never the secret.
+ *
+ * @stability experimental
+ */
+export interface AiRealtimeSessionInfo {
+    /** The provider. */
+    provider: string;
+    /** The model. */
+    model: string;
+    /** The voice. */
+    voice: string;
+}
+/**
+ * The use AI realtime session return wire shape.
+ *
+ * @stability experimental
+ */
+export interface UseAiRealtimeSessionReturn {
+    /** The status. */
+    status: AiRealtimeStatus;
+    /** The failure. */
+    failure: AiRealtimeFailure | null;
+    /** The session. */
+    session: AiRealtimeSessionInfo | null;
+    /** Only lines with text — a reserved, still-empty line is not listed. */
+    transcript: AiRealtimeTranscriptLine[];
+    /** Whether muted. */
+    muted: boolean;
+    /** Whole seconds since the call connected. */
+    elapsedSeconds: number;
+    /** Bind to an `<audio autoPlay>` element: the assistant's voice plays through it. */
+    audioRef: RefObject<HTMLAudioElement | null>;
+    /** The start. */
+    start: (request: AiRealtimeSessionRequest) => Promise<void>;
+    /** The stop. */
+    stop: () => void;
+    /** Whether set muted. */
+    setMuted: (muted: boolean) => void;
+    /** The clear failure. */
+    clearFailure: () => void;
+}
+/**
+ * The use AI realtime session options wire shape.
+ *
+ * @stability experimental
+ */
+export interface UseAiRealtimeSessionOptions extends AiHookOptions {
+    /** Clock, for tests. */
+    now?: () => number;
+}
+/**
+ * `mm:ss` (or `h:mm:ss` past an hour).
+ *
+ * @stability experimental
+ */
+export declare function formatRealtimeElapsed(totalSeconds: number): string;
+/**
+ * Whether this browser can hold a realtime call at all.
+ *
+ * @stability experimental
+ */
+export declare function isRealtimeSupported(): boolean;
+/**
+ * Use AI realtime session.
+ *
+ * @stability experimental
+ */
+export declare function useAiRealtimeSession(options?: UseAiRealtimeSessionOptions): UseAiRealtimeSessionReturn;
+//# sourceMappingURL=use-ai-realtime-session.d.ts.map

package/dist/ai/headless/use-ai-realtime-session.d.ts.map

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