@absolutejs/voice 0.0.1

package/dist/voice/src/svelte/createVoiceStream.d.ts

@@ -0,0 +1,14 @@
+import type { VoiceConnectionOptions } from '../types';
+export declare const createVoiceStream: <TResult = unknown>(path: string, options?: VoiceConnectionOptions) => {
+    close(): void;
+    endTurn(): void;
+    readonly error: string | null;
+    readonly isConnected: boolean;
+    readonly partial: string;
+    readonly sessionId: string;
+    readonly status: "idle" | import("..").VoiceSessionStatus;
+    readonly turns: import("..").VoiceTurnRecord<TResult>[];
+    readonly assistantTexts: string[];
+    sendAudio(audio: Uint8Array | ArrayBuffer): void;
+    subscribe(subscriber: () => void): () => void;
+};

package/dist/voice/src/svelte/index.d.ts

@@ -0,0 +1 @@
+export { createVoiceStream } from './createVoiceStream';

package/dist/voice/src/turnDetection.d.ts

@@ -0,0 +1,3 @@
+import type { Transcript } from './types';
+export declare const DEFAULT_SILENCE_MS = 700;
+export declare const buildTurnText: (transcripts: Transcript[], partialText: string) => string;

package/dist/voice/src/types.d.ts

@@ -0,0 +1,318 @@
+import type { SessionStore } from '@absolutejs/absolute';
+export type AudioFormat = {
+    container: 'raw';
+    encoding: 'pcm_s16le';
+    sampleRateHz: number;
+    channels: 1 | 2;
+};
+export type AudioChunk = ArrayBuffer | ArrayBufferView;
+export type Transcript = {
+    id: string;
+    text: string;
+    isFinal: boolean;
+    confidence?: number;
+    language?: string;
+    startedAtMs?: number;
+    endedAtMs?: number;
+    vendor?: string;
+};
+export type VoicePartialEvent = {
+    type: 'partial';
+    transcript: Transcript;
+    receivedAt: number;
+};
+export type VoiceFinalEvent = {
+    type: 'final';
+    transcript: Transcript;
+    receivedAt: number;
+};
+export type VoiceEndOfTurnEvent = {
+    type: 'endOfTurn';
+    reason: 'vendor' | 'silence' | 'manual';
+    receivedAt: number;
+};
+export type VoiceErrorEvent = {
+    type: 'error';
+    error: Error;
+    recoverable: boolean;
+    code?: string;
+};
+export type VoiceCloseEvent = {
+    type: 'close';
+    code?: number;
+    reason?: string;
+    recoverable?: boolean;
+};
+export type STTSessionEventMap = {
+    partial: VoicePartialEvent;
+    final: VoiceFinalEvent;
+    endOfTurn: VoiceEndOfTurnEvent;
+    error: VoiceErrorEvent;
+    close: VoiceCloseEvent;
+};
+export type STTAdapterSession = {
+    on: <K extends keyof STTSessionEventMap>(event: K, handler: (payload: STTSessionEventMap[K]) => void | Promise<void>) => () => void;
+    send: (audio: AudioChunk) => Promise<void>;
+    close: (reason?: string) => Promise<void>;
+};
+export type STTAdapterOpenOptions = {
+    sessionId: string;
+    format: AudioFormat;
+    signal?: AbortSignal;
+};
+export type STTAdapter<TOptions extends STTAdapterOpenOptions = STTAdapterOpenOptions> = {
+    kind: 'stt';
+    open: (options: TOptions) => Promise<STTAdapterSession> | STTAdapterSession;
+};
+export type TTSAudioEvent = {
+    type: 'audio';
+    chunk: AudioChunk;
+    format: AudioFormat;
+    receivedAt: number;
+};
+export type TTSSessionEventMap = {
+    audio: TTSAudioEvent;
+    error: VoiceErrorEvent;
+    close: VoiceCloseEvent;
+};
+export type TTSAdapterSession = {
+    on: <K extends keyof TTSSessionEventMap>(event: K, handler: (payload: TTSSessionEventMap[K]) => void | Promise<void>) => () => void;
+    send: (text: string) => Promise<void>;
+    close: (reason?: string) => Promise<void>;
+};
+export type TTSAdapterOpenOptions = {
+    sessionId: string;
+    signal?: AbortSignal;
+};
+export type TTSAdapter<TOptions extends TTSAdapterOpenOptions = TTSAdapterOpenOptions> = {
+    kind: 'tts';
+    open: (options: TOptions) => Promise<TTSAdapterSession> | TTSAdapterSession;
+};
+export type RealtimeSessionEventMap = STTSessionEventMap & {
+    audio: TTSAudioEvent;
+};
+export type RealtimeAdapterSession = {
+    on: <K extends keyof RealtimeSessionEventMap>(event: K, handler: (payload: RealtimeSessionEventMap[K]) => void | Promise<void>) => () => void;
+    send: (input: AudioChunk | string) => Promise<void>;
+    close: (reason?: string) => Promise<void>;
+};
+export type RealtimeAdapterOpenOptions = {
+    sessionId: string;
+    format: AudioFormat;
+    signal?: AbortSignal;
+};
+export type RealtimeAdapter<TOptions extends RealtimeAdapterOpenOptions = RealtimeAdapterOpenOptions> = {
+    kind: 'realtime';
+    open: (options: TOptions) => Promise<RealtimeAdapterSession> | RealtimeAdapterSession;
+};
+export type VoiceSessionStatus = 'active' | 'reconnecting' | 'completed' | 'failed';
+export type VoiceTurnRecord<TResult = unknown> = {
+    id: string;
+    text: string;
+    transcripts: Transcript[];
+    assistantText?: string;
+    committedAt: number;
+    result?: TResult;
+};
+export type VoiceSessionRecord<TMeta = Record<string, never>, TResult = unknown> = {
+    id: string;
+    createdAt: number;
+    lastActivityAt?: number;
+    status: VoiceSessionStatus;
+    transcripts: Transcript[];
+    currentTurn: {
+        transcripts: Transcript[];
+        partialText: string;
+        finalText: string;
+        lastAudioAt?: number;
+    };
+    turns: VoiceTurnRecord<TResult>[];
+    committedTurnIds: string[];
+    reconnect: {
+        attempts: number;
+        lastDisconnectAt?: number;
+    };
+    metadata?: TMeta;
+};
+export type VoiceSessionSummary = {
+    id: string;
+    createdAt: number;
+    lastActivityAt?: number;
+    status: VoiceSessionStatus;
+    turnCount: number;
+};
+export type VoiceSessionStore<TSession extends VoiceSessionRecord = VoiceSessionRecord> = SessionStore<TSession, VoiceSessionSummary>;
+export type VoiceLogger = {
+    debug?: (message: string, meta?: Record<string, unknown>) => void;
+    info?: (message: string, meta?: Record<string, unknown>) => void;
+    warn?: (message: string, meta?: Record<string, unknown>) => void;
+    error?: (message: string, meta?: Record<string, unknown>) => void;
+};
+export type VoiceReconnectConfig = {
+    strategy?: 'resume-last-turn' | 'restart' | 'fail';
+    timeout?: number;
+    maxAttempts?: number;
+};
+export type VoiceSocket = {
+    send: (data: string | Uint8Array | ArrayBuffer) => void | Promise<void>;
+    close: (code?: number, reason?: string) => void | Promise<void>;
+};
+export type VoiceSessionHandle<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown> = {
+    id: string;
+    connect: (socket: VoiceSocket) => Promise<void>;
+    receiveAudio: (audio: AudioChunk) => Promise<void>;
+    commitTurn: (reason?: VoiceEndOfTurnEvent['reason']) => Promise<void>;
+    disconnect: (event?: VoiceCloseEvent) => Promise<void>;
+    complete: (result?: TResult) => Promise<void>;
+    fail: (error: unknown) => Promise<void>;
+    close: (reason?: string) => Promise<void>;
+    snapshot: () => Promise<TSession>;
+};
+export type VoiceRouteResult<TResult = unknown> = {
+    complete?: boolean;
+    result?: TResult;
+    assistantText?: string;
+};
+export type VoiceRouteConfig<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown> = {
+    onSession?: (input: {
+        context: TContext;
+        session: TSession;
+        api: VoiceSessionHandle<TContext, TSession, TResult>;
+    }) => Promise<void> | void;
+    onTurn: (input: {
+        context: TContext;
+        session: TSession;
+        turn: VoiceTurnRecord<TResult>;
+        api: VoiceSessionHandle<TContext, TSession, TResult>;
+    }) => Promise<VoiceRouteResult<TResult> | void> | VoiceRouteResult<TResult> | void;
+    onComplete: (input: {
+        context: TContext;
+        session: TSession;
+        api: VoiceSessionHandle<TContext, TSession, TResult>;
+    }) => Promise<void> | void;
+    onError?: (input: {
+        context: TContext;
+        sessionId: string;
+        session?: TSession;
+        error: unknown;
+        api?: VoiceSessionHandle<TContext, TSession, TResult>;
+    }) => Promise<void> | void;
+};
+export type VoicePluginConfig<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown> = {
+    path: string;
+    stt: STTAdapter;
+    tts?: TTSAdapter;
+    session: VoiceSessionStore<TSession>;
+    reconnect?: VoiceReconnectConfig;
+    turnDetection?: {
+        silenceMs?: number;
+    };
+    logger?: VoiceLogger;
+} & VoiceRouteConfig<TContext, TSession, TResult>;
+export type CreateVoiceSessionOptions<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown> = {
+    id: string;
+    context: TContext;
+    socket: VoiceSocket;
+    stt: STTAdapter;
+    store: VoiceSessionStore<TSession>;
+    reconnect: Required<VoiceReconnectConfig>;
+    turnDetection: {
+        silenceMs: number;
+    };
+    route: VoiceRouteConfig<TContext, TSession, TResult>;
+    logger?: VoiceLogger;
+};
+export type CreateVoiceSession = <TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown>(options: CreateVoiceSessionOptions<TContext, TSession, TResult>) => VoiceSessionHandle<TContext, TSession, TResult>;
+export type VoiceClientStartMessage = {
+    type: 'start';
+    sessionId?: string;
+};
+export type VoiceClientEndTurnMessage = {
+    type: 'end_turn';
+};
+export type VoiceClientCloseMessage = {
+    type: 'close';
+    reason?: string;
+};
+export type VoiceClientPingMessage = {
+    type: 'ping';
+};
+export type VoiceClientMessage = VoiceClientStartMessage | VoiceClientEndTurnMessage | VoiceClientCloseMessage | VoiceClientPingMessage;
+export type VoiceServerSessionMessage = {
+    type: 'session';
+    sessionId: string;
+    status: VoiceSessionStatus;
+};
+export type VoiceServerPartialMessage = {
+    type: 'partial';
+    transcript: Transcript;
+};
+export type VoiceServerFinalMessage = {
+    type: 'final';
+    transcript: Transcript;
+};
+export type VoiceServerTurnMessage<TResult = unknown> = {
+    type: 'turn';
+    turn: VoiceTurnRecord<TResult>;
+};
+export type VoiceServerAssistantMessage = {
+    type: 'assistant';
+    text: string;
+    turnId?: string;
+};
+export type VoiceServerCompleteMessage = {
+    type: 'complete';
+    sessionId: string;
+};
+export type VoiceServerErrorMessage = {
+    type: 'error';
+    message: string;
+    recoverable?: boolean;
+};
+export type VoiceServerPongMessage = {
+    type: 'pong';
+};
+export type VoiceServerMessage<TResult = unknown> = VoiceServerSessionMessage | VoiceServerPartialMessage | VoiceServerFinalMessage | VoiceServerTurnMessage<TResult> | VoiceServerAssistantMessage | VoiceServerCompleteMessage | VoiceServerErrorMessage | VoiceServerPongMessage;
+export type VoiceConnectionOptions = {
+    protocols?: string[];
+    reconnect?: boolean;
+    maxReconnectAttempts?: number;
+    pingInterval?: number;
+    sessionId?: string;
+};
+export type VoiceStreamState<TResult = unknown> = {
+    sessionId: string | null;
+    status: VoiceSessionStatus | 'idle';
+    partial: string;
+    turns: VoiceTurnRecord<TResult>[];
+    assistantTexts: string[];
+    error: string | null;
+    isConnected: boolean;
+};
+export type VoiceStoreAction<TResult = unknown> = {
+    type: 'session';
+    sessionId: string;
+    status: VoiceSessionStatus;
+} | {
+    type: 'partial';
+    transcript: Transcript;
+} | {
+    type: 'final';
+    transcript: Transcript;
+} | {
+    type: 'turn';
+    turn: VoiceTurnRecord<TResult>;
+} | {
+    type: 'assistant';
+    text: string;
+} | {
+    type: 'complete';
+    sessionId: string;
+} | {
+    type: 'error';
+    message: string;
+} | {
+    type: 'connected';
+} | {
+    type: 'disconnected';
+};

package/dist/voice/src/vue/index.d.ts

@@ -0,0 +1 @@
+export { useVoiceStream } from './useVoiceStream';

package/dist/voice/src/vue/useVoiceStream.d.ts

@@ -0,0 +1,13 @@
+import type { VoiceConnectionOptions, VoiceTurnRecord } from '../types';
+export declare const useVoiceStream: <TResult = unknown>(path: string, options?: VoiceConnectionOptions) => {
+    assistantTexts: import("vue").ShallowRef<string[], string[]>;
+    close: () => void;
+    endTurn: () => void;
+    error: import("vue").Ref<string | null, string | null>;
+    isConnected: import("vue").Ref<boolean, boolean>;
+    partial: import("vue").Ref<string, string>;
+    sendAudio: (audio: Uint8Array | ArrayBuffer) => void;
+    sessionId: import("vue").Ref<string, string>;
+    status: import("vue").Ref<"idle" | import("..").VoiceSessionStatus, "idle" | import("..").VoiceSessionStatus>;
+    turns: import("vue").ShallowRef<VoiceTurnRecord<TResult>[], VoiceTurnRecord<TResult>[]>;
+};