Types & Interfaces

interface OdysseyEventHandlers {
  onConnected?: (mediaStream: MediaStream) => void;
  onDisconnected?: () => void;
  onStreamStarted?: (streamId: string) => void;
  onStreamEnded?: () => void;
  onInteractAcknowledged?: (prompt: string) => void;
  onStreamError?: (reason: string, message: string) => void;
  onError?: (error: Error, fatal: boolean) => void;
  onStatusChange?: (status: ConnectionStatus, message?: string) => void;
  onBroadcastReady?: (info: BroadcastInfo) => void;
}

type UseOdysseyHandlers = OdysseyEventHandlers;

interface UseOdysseyOptions {
  /** API key for authentication (required) */
  apiKey: string;
  /** Event handlers (optional) */
  handlers?: UseOdysseyHandlers;
}

interface ClientConfig {
  /** API key for authentication (required) */
  apiKey: string;
}

type ConnectionStatus =
  | 'authenticating'  // Authenticating with Odyssey API
  | 'connecting'      // Connecting to streaming server
  | 'reconnecting'    // Reconnecting after disconnect
  | 'connected'       // Connected and ready
  | 'disconnected'    // Disconnected (clean)
  | 'failed';         // Connection failed (fatal)

interface Recording {
  stream_id: string;
  video_url: string | null;
  events_url: string | null;
  thumbnail_url: string | null;
  preview_url: string | null;
  frame_count: number | null;
  duration_seconds: number | null;
}

interface StreamRecordingSummary {
  stream_id: string;
  width: number;
  height: number;
  started_at: string;
  ended_at: string | null;
  duration_seconds: number | null;
}

interface ListStreamRecordingsOptions {
  limit?: number;
  offset?: number;
}

interface StreamRecordingsListResponse {
  recordings: StreamRecordingSummary[];
  total: number;
  limit: number;
  offset: number;
}

type SimulationJobStatus = 'pending' | 'dispatched' | 'processing' | 'completed' | 'failed' | 'cancelled';

interface ScriptEntry {
  timestamp_ms: number;           // When this action occurs (milliseconds from start)
  start?: {                       // Begin a new stream
    prompt: string;
    image?: File | Blob | string; // Optional image for image-to-video
  };
  interact?: {                    // Send an interaction
    prompt: string;
  };
  end?: Record<string, never>;    // End the stream (empty object)
}

interface SimulateOptions {
  /** Single script to run */
  script?: ScriptEntry[];
  /** Batch mode: multiple scripts */
  scripts?: ScriptEntry[][];
  /** URL to script JSON file */
  script_url?: string;
  /** Portrait (true) or landscape (false). Default: true */
  portrait?: boolean;
  /** Skip prompt expansion for this job. Requires the expansion bypass privilege. */
  bypassPromptExpansion?: boolean;
}

interface SimulationStream {
  stream_id: string;
  video_url: string | null;
  events_url: string | null;
  thumbnail_url: string | null;
  preview_url: string | null;
  frame_count: number | null;
  duration_seconds: number | null;
  script_index: number;
}

interface SimulationJob {
  job_id: string;
  status: SimulationJobStatus;
  priority: string;
  created_at: string;
  estimated_wait_minutes: number | null;
}

interface SimulationJobDetail {
  job_id: string;
  status: SimulationJobStatus;
  priority: string;
  created_at: string;
  dispatched_at: string | null;
  started_at: string | null;
  completed_at: string | null;
  error_message: string | null;
  assigned_region: string | null;
  retry_count: number;
  streams: SimulationStream[];
}

interface SimulationJobInfo {
  job_id: string;
  status: SimulationJobStatus;
  priority: string;
  created_at: string;
  completed_at: string | null;
  error_message: string | null;
}

interface ListSimulationsOptions {
  status?: SimulationJobStatus;
  active?: boolean;
  limit?: number;
  offset?: number;
}

interface SimulationJobsList {
  jobs: SimulationJobInfo[];
  total: number;
  limit: number;
  offset: number;
}

interface StreamerCapabilities {
  image_to_video: boolean;
}

interface ClientCredentials {
  sessionId: string;
  signalingUrl: string;
  sessionToken: string;
  expiresIn: number;
  capabilities?: StreamerCapabilities;
}

import { credentialsToDict, credentialsFromDict } from '@odysseyml/odyssey';

// Server-side: mint and serialize
const creds = await server.createClientCredentials();
const dict = credentialsToDict(creds);
// Send dict as JSON to the client

// Client-side: deserialize
const creds = credentialsFromDict(dataFromServer);

interface StartStreamOptions {
 prompt?: string;
 portrait?: boolean;
 image?: File | Blob;
 bypassPromptExpansion?: boolean;
 broadcast?: boolean;
}

interface BroadcastInfo {
 webrtcUrl: string;
 spectatorToken: string;
 hlsUrl: string | null;
}

import { Odyssey } from "@odysseyml/odyssey";

const client = new Odyssey({ apiKey });

await client.connect({
 onBroadcastReady: ({ webrtcUrl, spectatorToken }) => {
   console.log("Share these with spectators:", webrtcUrl, spectatorToken);
 },
});

await client.startStream({
 prompt: "A floating alien temple",
 broadcast: true,
});

const spectator = await Odyssey.connectToStream(
 webrtcUrl,
 spectatorToken
);

videoElement.srcObject = spectator.stream;

spectator.onDisconnect(() => {
 console.log("Broadcast ended");
});

// Main entry point (@odysseyml/odyssey)
export { Odyssey } from './odyssey';
export type { OdysseyEventHandlers, ConnectionStatus, ClientConfig, OdysseyClient } from './types';

// React entry point (@odysseyml/odyssey/react)
export { useOdyssey } from './useOdyssey';
export type { UseOdysseyHandlers, OdysseyClient } from './types';