@overshoot/sdk 0.1.0-alpha.0

package/dist/index.d.ts

@@ -0,0 +1,302 @@
+type StreamSource = {
+    type: "camera";
+    cameraFacing: "user" | "environment";
+} | {
+    type: "video";
+    file: File;
+};
+type WebRtcOffer = {
+    type: "offer";
+    sdp: string;
+};
+type WebRtcAnswer = {
+    type: "answer";
+    sdp: string;
+};
+type StreamProcessingConfig = {
+    sampling_ratio: number;
+    fps: number;
+    clip_length_seconds?: number;
+    delay_seconds?: number;
+};
+type StreamInferenceConfig = {
+    prompt: string;
+    backend: "gemini" | "overshoot";
+    model: string;
+    output_schema_json?: Record<string, any>;
+};
+type StreamClientMeta = {
+    request_id?: string;
+};
+type StreamCreateRequest = {
+    webrtc: WebRtcOffer;
+    processing: StreamProcessingConfig;
+    inference: StreamInferenceConfig;
+    client?: StreamClientMeta;
+};
+type StreamCreateResponse = {
+    stream_id: string;
+    webrtc: WebRtcAnswer;
+    lease?: {
+        ttl_seconds: number;
+    };
+    turn_servers?: RTCIceServer[];
+};
+type StreamInferenceResult = {
+    id: string;
+    stream_id: string;
+    model_backend: "gemini" | "overshoot";
+    model_name: string;
+    prompt: string;
+    result: string;
+    inference_latency_ms: number;
+    total_latency_ms: number;
+    ok: boolean;
+    error: string | null;
+};
+type StreamConfigResponse = {
+    id: string;
+    stream_id: string;
+    prompt: string;
+    backend: "gemini" | "overshoot";
+    model: string;
+    output_schema_json?: Record<string, any>;
+    created_at?: string;
+    updated_at?: string;
+};
+type FeedbackCreateRequest = {
+    rating: number;
+    category: string;
+    feedback?: string;
+};
+type FeedbackResponse = {
+    id: string;
+    stream_id: string;
+    rating: number;
+    category: string;
+    feedback: string;
+    created_at?: string;
+    updated_at?: string;
+};
+type KeepaliveResponse = {
+    status: "ok";
+    stream_id: string;
+    ttl_seconds: number;
+};
+type StatusResponse = {
+    status: "ok";
+};
+type ErrorResponse = {
+    error: string;
+    message?: string;
+    request_id?: string;
+    details?: any;
+};
+
+type ClientConfig = {
+    baseUrl: string;
+    apiKey: string;
+};
+declare class StreamClient {
+    private baseUrl;
+    private apiKey;
+    constructor(config: ClientConfig);
+    private request;
+    createStream(request: StreamCreateRequest): Promise<StreamCreateResponse>;
+    renewLease(streamId: string): Promise<KeepaliveResponse>;
+    updatePrompt(streamId: string, prompt: string): Promise<StreamConfigResponse>;
+    submitFeedback(streamId: string, feedback: FeedbackCreateRequest): Promise<StatusResponse>;
+    getAllFeedback(): Promise<FeedbackResponse[]>;
+    connectWebSocket(streamId: string): WebSocket;
+    /**
+     * Health check endpoint (for testing, uses internal port if available)
+     * Note: This endpoint may not be available via the main API
+     */
+    healthCheck(): Promise<string>;
+}
+
+interface RealtimeVisionConfig {
+    /**
+     * Base URL for the API (e.g., "https://api.example.com")
+     */
+    apiUrl: string;
+    /**
+     * API key for authentication
+     * Required for all API requests
+     */
+    apiKey: string;
+    /**
+     * The prompt/task to run on window segments of the stream.
+     * This runs continuously (at a defined window interval).
+     *
+     * Examples:
+     * - "Read any visible text"
+     * - "Detect objects and return as JSON array"
+     * - "Describe facial expression"
+     */
+    prompt: string;
+    /**
+     * Video source configuration
+     * Defaults to camera with environment facing if not specified
+     */
+    source?: StreamSource;
+    /**
+     * Model backend to use
+     */
+    backend?: "gemini" | "overshoot";
+    /**
+     * Model name to use for inference
+     */
+    model?: string;
+    /**
+     * Optional JSON schema for structured output
+     */
+    outputSchema?: Record<string, any>;
+    /**
+     * Called when a new inference result arrives (~1 per second)
+     */
+    onResult: (result: StreamInferenceResult) => void;
+    /**
+     * Called when an error occurs
+     */
+    onError?: (error: Error) => void;
+    /**
+     * Custom processing configuration
+     * All fields are optional and will use defaults if not provided
+     */
+    processing?: {
+        /**
+         * Sampling ratio (0-1). Controls what fraction of frames are processed.
+         */
+        sampling_ratio?: number;
+        /**
+         * Frames per second (1-120)
+         */
+        fps?: number;
+        /**
+         * Clip length in seconds (0.1-60)
+         */
+        clip_length_seconds?: number;
+        /**
+         * Delay in seconds (0-60)
+         */
+        delay_seconds?: number;
+    };
+    /**
+     * ICE servers for WebRTC connection
+     * If not provided, uses default TURN servers
+     */
+    iceServers?: RTCIceServer[];
+    /**
+     * Enable debug logging
+     * @default false
+     */
+    debug?: boolean;
+}
+declare class RealtimeVision {
+    private config;
+    private client;
+    private logger;
+    private mediaStream;
+    private peerConnection;
+    private webSocket;
+    private streamId;
+    private keepaliveInterval;
+    private videoElement;
+    private isRunning;
+    constructor(config: RealtimeVisionConfig);
+    /**
+     * Validate configuration values
+     */
+    private validateConfig;
+    /**
+     * Create media stream from the configured source
+     */
+    private createMediaStream;
+    /**
+     * Get FPS from media stream
+     */
+    private getStreamFps;
+    /**
+     * Get processing configuration with defaults applied
+     */
+    private getProcessingConfig;
+    /**
+     * Get the effective source configuration
+     */
+    private getSource;
+    /**
+     * Start the vision stream
+     */
+    start(): Promise<void>;
+    /**
+     * Set up keepalive interval with error handling
+     */
+    private setupKeepalive;
+    /**
+     * Set up WebSocket connection with error handling
+     */
+    private setupWebSocket;
+    /**
+     * Handle non-fatal errors (report but don't stop stream)
+     */
+    private handleNonFatalError;
+    /**
+     * Handle fatal errors (stop stream and report)
+     */
+    private handleFatalError;
+    /**
+     * Update the prompt/task while stream is running
+     */
+    updatePrompt(prompt: string): Promise<void>;
+    /**
+     * Stop the vision stream and clean up resources
+     */
+    stop(): Promise<void>;
+    /**
+     * Submit feedback for the stream
+     */
+    submitFeedback(feedback: {
+        rating: number;
+        category: string;
+        feedback?: string;
+    }): Promise<void>;
+    /**
+     * Get the current stream ID
+     */
+    getStreamId(): string | null;
+    /**
+     * Get the media stream (for displaying video preview)
+     */
+    getMediaStream(): MediaStream | null;
+    /**
+     * Check if the stream is running
+     */
+    isActive(): boolean;
+    private cleanup;
+}
+
+declare class ApiError extends Error {
+    readonly statusCode?: number;
+    readonly requestId?: string;
+    readonly details?: any;
+    constructor(message: string, statusCode?: number, requestId?: string, details?: any);
+}
+declare class UnauthorizedError extends ApiError {
+    constructor(message: string, requestId?: string);
+}
+declare class ValidationError extends ApiError {
+    constructor(message: string, requestId?: string, details?: any);
+}
+declare class NotFoundError extends ApiError {
+    constructor(message: string, requestId?: string);
+}
+declare class NetworkError extends ApiError {
+    readonly cause?: Error;
+    constructor(message: string, cause?: Error);
+}
+declare class ServerError extends ApiError {
+    constructor(message: string, requestId?: string, details?: any);
+}
+
+export { ApiError, type ErrorResponse, type FeedbackCreateRequest, type FeedbackResponse, type KeepaliveResponse, NetworkError, NotFoundError, RealtimeVision, type RealtimeVisionConfig, ServerError, type StatusResponse, StreamClient, type StreamClientMeta, type StreamConfigResponse, type StreamCreateRequest, type StreamCreateResponse, type StreamInferenceConfig, type StreamInferenceResult, type StreamProcessingConfig, type StreamSource, UnauthorizedError, ValidationError, type WebRtcAnswer, type WebRtcOffer };