@overshoot/sdk 0.1.0-alpha.0

package/dist/index.js

@@ -0,0 +1,668 @@
+'use strict';
+
+// src/client/errors.ts
+var ApiError = class extends Error {
+  constructor(message, statusCode, requestId, details) {
+    super(message);
+    this.name = "ApiError";
+    this.statusCode = statusCode;
+    this.requestId = requestId;
+    this.details = details;
+  }
+};
+var UnauthorizedError = class extends ApiError {
+  constructor(message, requestId) {
+    super(message, 401, requestId);
+    this.name = "UnauthorizedError";
+  }
+};
+var ValidationError = class extends ApiError {
+  constructor(message, requestId, details) {
+    super(message, 422, requestId, details);
+    this.name = "ValidationError";
+  }
+};
+var NotFoundError = class extends ApiError {
+  constructor(message, requestId) {
+    super(message, 404, requestId);
+    this.name = "NotFoundError";
+  }
+};
+var NetworkError = class extends ApiError {
+  constructor(message, cause) {
+    super(message);
+    this.name = "NetworkError";
+    this.cause = cause;
+  }
+};
+var ServerError = class extends ApiError {
+  constructor(message, requestId, details) {
+    super(message, 500, requestId, details);
+    this.name = "ServerError";
+  }
+};
+
+// src/client/client.ts
+var StreamClient = class {
+  constructor(config) {
+    if (!config.apiKey || typeof config.apiKey !== "string") {
+      throw new Error("apiKey is required and must be a string");
+    }
+    this.baseUrl = config.baseUrl;
+    this.apiKey = config.apiKey;
+  }
+  async request(path, options = {}) {
+    const url = `${this.baseUrl}${path}`;
+    const controller = new AbortController();
+    try {
+      const response = await fetch(url, {
+        ...options,
+        signal: controller.signal,
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${this.apiKey}`,
+          ...options.headers
+        }
+      });
+      if (!response.ok) {
+        const errorData = await response.json().catch(() => ({
+          error: "unknown_error",
+          message: response.statusText
+        }));
+        const message = errorData.message || errorData.error;
+        if (response.status === 401) {
+          throw new UnauthorizedError(
+            message || "Invalid or revoked API key",
+            errorData.request_id
+          );
+        }
+        if (response.status === 422 || response.status === 400) {
+          throw new ValidationError(
+            message,
+            errorData.request_id,
+            errorData.details
+          );
+        }
+        if (response.status === 404) {
+          throw new NotFoundError(message, errorData.request_id);
+        }
+        if (response.status >= 500) {
+          throw new ServerError(
+            message,
+            errorData.request_id,
+            errorData.details
+          );
+        }
+        throw new ApiError(
+          message,
+          response.status,
+          errorData.request_id,
+          errorData.details
+        );
+      }
+      return await response.json();
+    } catch (error) {
+      if (error instanceof ApiError) {
+        throw error;
+      }
+      if (error instanceof Error) {
+        throw new NetworkError(`Network error: ${error.message}`, error);
+      }
+      throw new NetworkError("Unknown network error");
+    }
+  }
+  async createStream(request) {
+    return this.request("/streams", {
+      method: "POST",
+      body: JSON.stringify(request)
+    });
+  }
+  async renewLease(streamId) {
+    return this.request(`/streams/${streamId}/keepalive`, {
+      method: "POST"
+    });
+  }
+  async updatePrompt(streamId, prompt) {
+    return this.request(
+      `/streams/${streamId}/config/prompt`,
+      {
+        method: "PATCH",
+        body: JSON.stringify({ prompt })
+      }
+    );
+  }
+  async submitFeedback(streamId, feedback) {
+    return this.request(`/streams/${streamId}/feedback`, {
+      method: "POST",
+      body: JSON.stringify(feedback)
+    });
+  }
+  async getAllFeedback() {
+    return this.request("/streams/feedback", {
+      method: "GET"
+    });
+  }
+  connectWebSocket(streamId) {
+    const wsUrl = this.baseUrl.replace("http://", "ws://").replace("https://", "wss://");
+    return new WebSocket(`${wsUrl}/ws/streams/${streamId}`);
+  }
+  /**
+   * Health check endpoint (for testing, uses internal port if available)
+   * Note: This endpoint may not be available via the main API
+   */
+  async healthCheck() {
+    const url = `${this.baseUrl}/healthz`;
+    const response = await fetch(url);
+    return response.text();
+  }
+};
+
+// src/client/RealtimeVision.ts
+var DEFAULTS = {
+  BACKEND: "overshoot",
+  MODEL: "Qwen/Qwen3-VL-30B-A3B-Instruct",
+  SOURCE: { type: "camera", cameraFacing: "environment" },
+  SAMPLING_RATIO: 0.1,
+  CLIP_LENGTH_SECONDS: 1,
+  DELAY_SECONDS: 1,
+  FALLBACK_FPS: 30,
+  ICE_SERVERS: [
+    {
+      urls: "turn:34.63.114.235:3478",
+      username: "1768325310:634a30f8-ae52-4a15-9d3f-a56b725dacd9",
+      credential: "H5IEJ1IJrOUzQkVG9lXr8Z4EJGU="
+    }
+  ]
+};
+var CONSTRAINTS = {
+  SAMPLING_RATIO: { min: 0, max: 1 },
+  FPS: { min: 1, max: 120 },
+  CLIP_LENGTH_SECONDS: { min: 0.1, max: 60 },
+  DELAY_SECONDS: { min: 0, max: 60 },
+  RATING: { min: 1, max: 5 }
+};
+var Logger = class {
+  constructor(debugEnabled = false) {
+    this.debugEnabled = debugEnabled;
+  }
+  debug(...args) {
+    if (this.debugEnabled) {
+      console.log("[RealtimeVision Debug]", ...args);
+    }
+  }
+  info(...args) {
+    console.log("[RealtimeVision]", ...args);
+  }
+  warn(...args) {
+    console.warn("[RealtimeVision]", ...args);
+  }
+  error(...args) {
+    console.error("[RealtimeVision]", ...args);
+  }
+};
+var ValidationError2 = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ValidationError";
+  }
+};
+var RealtimeVision = class {
+  constructor(config) {
+    this.mediaStream = null;
+    this.peerConnection = null;
+    this.webSocket = null;
+    this.streamId = null;
+    this.keepaliveInterval = null;
+    this.videoElement = null;
+    this.isRunning = false;
+    this.validateConfig(config);
+    this.config = config;
+    this.logger = new Logger(config.debug ?? false);
+    this.client = new StreamClient({
+      baseUrl: config.apiUrl,
+      apiKey: config.apiKey
+    });
+  }
+  /**
+   * Validate configuration values
+   */
+  validateConfig(config) {
+    if (!config.apiUrl || typeof config.apiUrl !== "string") {
+      throw new ValidationError2("apiUrl is required and must be a string");
+    }
+    if (!config.apiKey || typeof config.apiKey !== "string") {
+      throw new ValidationError2("apiKey is required and must be a string");
+    }
+    if (!config.prompt || typeof config.prompt !== "string") {
+      throw new ValidationError2("prompt is required and must be a string");
+    }
+    if (config.source) {
+      if (config.source.type === "camera") {
+        if (config.source.cameraFacing !== "user" && config.source.cameraFacing !== "environment") {
+          throw new ValidationError2(
+            'cameraFacing must be "user" or "environment"'
+          );
+        }
+      } else if (config.source.type === "video") {
+        if (!(config.source.file instanceof File)) {
+          throw new ValidationError2("video source must provide a File object");
+        }
+      } else {
+        throw new ValidationError2('source.type must be "camera" or "video"');
+      }
+    }
+    if (config.processing?.sampling_ratio !== void 0) {
+      const ratio = config.processing.sampling_ratio;
+      if (ratio < CONSTRAINTS.SAMPLING_RATIO.min || ratio > CONSTRAINTS.SAMPLING_RATIO.max) {
+        throw new ValidationError2(
+          `sampling_ratio must be between ${CONSTRAINTS.SAMPLING_RATIO.min} and ${CONSTRAINTS.SAMPLING_RATIO.max}`
+        );
+      }
+    }
+    if (config.processing?.fps !== void 0) {
+      const fps = config.processing.fps;
+      if (fps < CONSTRAINTS.FPS.min || fps > CONSTRAINTS.FPS.max) {
+        throw new ValidationError2(
+          `fps must be between ${CONSTRAINTS.FPS.min} and ${CONSTRAINTS.FPS.max}`
+        );
+      }
+    }
+    if (config.processing?.clip_length_seconds !== void 0) {
+      const clip = config.processing.clip_length_seconds;
+      if (clip < CONSTRAINTS.CLIP_LENGTH_SECONDS.min || clip > CONSTRAINTS.CLIP_LENGTH_SECONDS.max) {
+        throw new ValidationError2(
+          `clip_length_seconds must be between ${CONSTRAINTS.CLIP_LENGTH_SECONDS.min} and ${CONSTRAINTS.CLIP_LENGTH_SECONDS.max}`
+        );
+      }
+    }
+    if (config.processing?.delay_seconds !== void 0) {
+      const delay = config.processing.delay_seconds;
+      if (delay < CONSTRAINTS.DELAY_SECONDS.min || delay > CONSTRAINTS.DELAY_SECONDS.max) {
+        throw new ValidationError2(
+          `delay_seconds must be between ${CONSTRAINTS.DELAY_SECONDS.min} and ${CONSTRAINTS.DELAY_SECONDS.max}`
+        );
+      }
+    }
+  }
+  /**
+   * Create media stream from the configured source
+   */
+  async createMediaStream(source) {
+    this.logger.debug("Creating media stream from source:", source.type);
+    switch (source.type) {
+      case "camera":
+        return await navigator.mediaDevices.getUserMedia({
+          video: { facingMode: { ideal: source.cameraFacing } },
+          audio: false
+        });
+      case "video":
+        const video = document.createElement("video");
+        video.src = URL.createObjectURL(source.file);
+        video.muted = true;
+        video.loop = true;
+        video.playsInline = true;
+        this.logger.debug("Loading video file:", source.file.name);
+        await new Promise((resolve, reject) => {
+          const timeout = setTimeout(() => {
+            reject(new Error("Video loading timeout after 10 seconds"));
+          }, 1e4);
+          video.onloadedmetadata = () => {
+            clearTimeout(timeout);
+            this.logger.debug("Video metadata loaded");
+            resolve();
+          };
+          video.onerror = (e) => {
+            clearTimeout(timeout);
+            this.logger.error("Video loading error:", e);
+            reject(new Error("Failed to load video file"));
+          };
+          if (video.readyState >= 1) {
+            clearTimeout(timeout);
+            resolve();
+          }
+        });
+        await video.play();
+        this.logger.debug("Video playback started");
+        const stream = video.captureStream();
+        if (!stream) {
+          throw new Error("Failed to capture video stream");
+        }
+        const videoTracks = stream.getVideoTracks();
+        if (videoTracks.length === 0) {
+          throw new Error("Video stream has no video tracks");
+        }
+        this.videoElement = video;
+        return stream;
+      default:
+        throw new Error(`Unknown source type: ${source.type}`);
+    }
+  }
+  /**
+   * Get FPS from media stream
+   */
+  async getStreamFps(stream, source) {
+    if (!stream) {
+      this.logger.warn("Stream is null, using fallback FPS");
+      return DEFAULTS.FALLBACK_FPS;
+    }
+    const videoTracks = stream.getVideoTracks();
+    if (!videoTracks || videoTracks.length === 0) {
+      this.logger.warn("No video tracks found, using fallback FPS");
+      return DEFAULTS.FALLBACK_FPS;
+    }
+    const videoTrack = videoTracks[0];
+    if (!videoTrack) {
+      this.logger.warn("First video track is null, using fallback FPS");
+      return DEFAULTS.FALLBACK_FPS;
+    }
+    if (source.type === "camera") {
+      const settings = videoTrack.getSettings();
+      const fps = settings.frameRate ?? DEFAULTS.FALLBACK_FPS;
+      this.logger.debug("Detected camera FPS:", fps);
+      return fps;
+    }
+    if (source.type === "video" && this.videoElement) {
+      await new Promise((resolve, reject) => {
+        if (this.videoElement.readyState >= 1) {
+          resolve();
+        } else {
+          this.videoElement.onloadedmetadata = () => resolve();
+          this.videoElement.onerror = () => reject(new Error("Failed to load video metadata"));
+        }
+      });
+      this.logger.debug("Using fallback FPS for video file");
+      return DEFAULTS.FALLBACK_FPS;
+    }
+    return DEFAULTS.FALLBACK_FPS;
+  }
+  /**
+   * Get processing configuration with defaults applied
+   */
+  getProcessingConfig(detectedFps) {
+    const userProcessing = this.config.processing || {};
+    return {
+      sampling_ratio: userProcessing.sampling_ratio ?? DEFAULTS.SAMPLING_RATIO,
+      fps: userProcessing.fps ?? detectedFps,
+      clip_length_seconds: userProcessing.clip_length_seconds ?? DEFAULTS.CLIP_LENGTH_SECONDS,
+      delay_seconds: userProcessing.delay_seconds ?? DEFAULTS.DELAY_SECONDS
+    };
+  }
+  /**
+   * Get the effective source configuration
+   */
+  getSource() {
+    return this.config.source ?? DEFAULTS.SOURCE;
+  }
+  /**
+   * Start the vision stream
+   */
+  async start() {
+    if (this.isRunning) {
+      throw new Error("Vision stream already running");
+    }
+    try {
+      const source = this.getSource();
+      this.logger.debug("Starting stream with source type:", source.type);
+      if (source.type === "video") {
+        this.logger.debug("Video file:", {
+          name: source.file.name,
+          size: source.file.size,
+          type: source.file.type
+        });
+        if (!source.file || !(source.file instanceof File)) {
+          throw new Error("Invalid video file");
+        }
+      }
+      this.mediaStream = await this.createMediaStream(source);
+      const videoTrack = this.mediaStream.getVideoTracks()[0];
+      if (!videoTrack) {
+        throw new Error("No video track available");
+      }
+      const detectedFps = await this.getStreamFps(this.mediaStream, source);
+      const iceServers = this.config.iceServers ?? DEFAULTS.ICE_SERVERS;
+      this.logger.debug("Creating peer connection with ICE servers");
+      this.peerConnection = new RTCPeerConnection({ iceServers });
+      this.peerConnection.onicecandidate = (event) => {
+        if (event.candidate) {
+          this.logger.debug("ICE candidate:", {
+            type: event.candidate.type,
+            protocol: event.candidate.protocol
+          });
+        } else {
+          this.logger.debug("ICE gathering complete");
+        }
+      };
+      this.peerConnection.oniceconnectionstatechange = () => {
+        this.logger.debug(
+          "ICE connection state:",
+          this.peerConnection?.iceConnectionState
+        );
+      };
+      this.peerConnection.addTrack(videoTrack, this.mediaStream);
+      const offer = await this.peerConnection.createOffer();
+      await this.peerConnection.setLocalDescription(offer);
+      if (!this.peerConnection.localDescription) {
+        throw new Error("Failed to create local description");
+      }
+      this.logger.debug("Creating stream on server");
+      const response = await this.client.createStream({
+        webrtc: {
+          type: "offer",
+          sdp: this.peerConnection.localDescription.sdp
+        },
+        processing: this.getProcessingConfig(detectedFps),
+        inference: {
+          prompt: this.config.prompt,
+          backend: this.config.backend ?? DEFAULTS.BACKEND,
+          model: this.config.model ?? DEFAULTS.MODEL,
+          output_schema_json: this.config.outputSchema
+        }
+      });
+      this.logger.debug("Backend response received:", {
+        stream_id: response.stream_id,
+        has_turn_servers: !!response.turn_servers
+      });
+      await this.peerConnection.setRemoteDescription(response.webrtc);
+      this.streamId = response.stream_id;
+      this.logger.info("Stream started:", this.streamId);
+      this.setupKeepalive(response.lease?.ttl_seconds);
+      this.setupWebSocket(response.stream_id);
+      this.isRunning = true;
+    } catch (error) {
+      await this.handleFatalError(error);
+      throw error;
+    }
+  }
+  /**
+   * Set up keepalive interval with error handling
+   */
+  setupKeepalive(ttlSeconds) {
+    if (!ttlSeconds) {
+      return;
+    }
+    const intervalMs = ttlSeconds / 2 * 1e3;
+    this.logger.debug("Setting up keepalive with interval:", intervalMs, "ms");
+    this.keepaliveInterval = window.setInterval(async () => {
+      try {
+        if (this.streamId) {
+          await this.client.renewLease(this.streamId);
+          this.logger.debug("Lease renewed");
+        }
+      } catch (error) {
+        this.logger.error("Keepalive failed:", error);
+        const keepaliveError = new Error(
+          `Keepalive failed: ${error instanceof Error ? error.message : String(error)}`
+        );
+        await this.handleFatalError(keepaliveError);
+      }
+    }, intervalMs);
+  }
+  /**
+   * Set up WebSocket connection with error handling
+   */
+  setupWebSocket(streamId) {
+    this.logger.debug("Connecting WebSocket for stream:", streamId);
+    this.webSocket = this.client.connectWebSocket(streamId);
+    this.webSocket.onopen = () => {
+      this.logger.debug("WebSocket connected");
+      if (this.webSocket) {
+        this.webSocket.send(JSON.stringify({ api_key: this.config.apiKey }));
+      }
+    };
+    this.webSocket.onmessage = (event) => {
+      try {
+        const result = JSON.parse(event.data);
+        this.config.onResult(result);
+      } catch (error) {
+        const parseError = new Error(
+          `Failed to parse WebSocket message: ${error instanceof Error ? error.message : String(error)}`
+        );
+        this.handleNonFatalError(parseError);
+      }
+    };
+    this.webSocket.onerror = () => {
+      this.logger.error("WebSocket error occurred");
+      const error = new Error("WebSocket error occurred");
+      this.handleFatalError(error);
+    };
+    this.webSocket.onclose = (event) => {
+      if (this.isRunning) {
+        if (event.code === 1008) {
+          this.logger.error("WebSocket authentication failed");
+          const error = new Error(
+            "WebSocket authentication failed: Invalid or revoked API key"
+          );
+          this.handleFatalError(error);
+        } else {
+          this.logger.warn("WebSocket closed unexpectedly:", event.code);
+          const error = new Error("WebSocket closed unexpectedly");
+          this.handleFatalError(error);
+        }
+      } else {
+        this.logger.debug("WebSocket closed");
+      }
+    };
+  }
+  /**
+   * Handle non-fatal errors (report but don't stop stream)
+   */
+  handleNonFatalError(error) {
+    this.logger.warn("Non-fatal error:", error.message);
+    if (this.config.onError) {
+      this.config.onError(error);
+    }
+  }
+  /**
+   * Handle fatal errors (stop stream and report)
+   */
+  async handleFatalError(error) {
+    this.logger.error("Fatal error:", error);
+    await this.cleanup();
+    this.isRunning = false;
+    const normalizedError = error instanceof Error ? error : new Error(String(error));
+    if (this.config.onError) {
+      this.config.onError(normalizedError);
+    }
+  }
+  /**
+   * Update the prompt/task while stream is running
+   */
+  async updatePrompt(prompt) {
+    if (!this.isRunning || !this.streamId) {
+      throw new Error("Vision stream not running");
+    }
+    if (!prompt || typeof prompt !== "string") {
+      throw new ValidationError2("prompt must be a non-empty string");
+    }
+    this.logger.debug("Updating prompt");
+    await this.client.updatePrompt(this.streamId, prompt);
+    this.logger.info("Prompt updated");
+  }
+  /**
+   * Stop the vision stream and clean up resources
+   */
+  async stop() {
+    this.logger.info("Stopping stream");
+    await this.cleanup();
+    this.isRunning = false;
+  }
+  /**
+   * Submit feedback for the stream
+   */
+  async submitFeedback(feedback) {
+    if (!this.streamId) {
+      throw new Error("No active stream");
+    }
+    if (feedback.rating < CONSTRAINTS.RATING.min || feedback.rating > CONSTRAINTS.RATING.max) {
+      throw new ValidationError2(
+        `rating must be between ${CONSTRAINTS.RATING.min} and ${CONSTRAINTS.RATING.max}`
+      );
+    }
+    if (!feedback.category || typeof feedback.category !== "string") {
+      throw new ValidationError2("category must be a non-empty string");
+    }
+    this.logger.debug("Submitting feedback");
+    await this.client.submitFeedback(this.streamId, {
+      rating: feedback.rating,
+      category: feedback.category,
+      feedback: feedback.feedback ?? ""
+    });
+    this.logger.info("Feedback submitted");
+  }
+  /**
+   * Get the current stream ID
+   */
+  getStreamId() {
+    return this.streamId;
+  }
+  /**
+   * Get the media stream (for displaying video preview)
+   */
+  getMediaStream() {
+    return this.mediaStream;
+  }
+  /**
+   * Check if the stream is running
+   */
+  isActive() {
+    return this.isRunning;
+  }
+  async cleanup() {
+    this.logger.debug("Cleaning up resources");
+    if (this.keepaliveInterval) {
+      window.clearInterval(this.keepaliveInterval);
+      this.keepaliveInterval = null;
+    }
+    if (this.webSocket) {
+      this.webSocket.close();
+      this.webSocket = null;
+    }
+    if (this.peerConnection) {
+      this.peerConnection.close();
+      this.peerConnection = null;
+    }
+    if (this.mediaStream) {
+      this.mediaStream.getTracks().forEach((track) => track.stop());
+      this.mediaStream = null;
+    }
+    if (this.videoElement) {
+      this.videoElement.pause();
+      URL.revokeObjectURL(this.videoElement.src);
+      this.videoElement.remove();
+      this.videoElement = null;
+    }
+    this.streamId = null;
+    this.logger.debug("Cleanup complete");
+  }
+};
+
+exports.ApiError = ApiError;
+exports.NetworkError = NetworkError;
+exports.NotFoundError = NotFoundError;
+exports.RealtimeVision = RealtimeVision;
+exports.ServerError = ServerError;
+exports.StreamClient = StreamClient;
+exports.UnauthorizedError = UnauthorizedError;
+exports.ValidationError = ValidationError;
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map