API Reference

API Reference

This document provides detailed information about the APIs used in Let's Stream V2.0.

Authentication API

User Management

Sign Up

interface SignUpParams {
  email: string;
  password: string;
}

interface SignUpResponse {
  user: User;
  token: string;
}

Sign In

interface SignInParams {
  email: string;
  password: string;
}

interface SignInResponse {
  user: User;
  token: string;
}

Social Authentication

interface SocialAuthParams {
  provider: 'google';
}

interface SocialAuthResponse {
  user: User;
  token: string;
  provider: string;
}

Media API

Movies

Get Popular Movies

interface MovieParams {
  page?: number;
  language?: string;
}

interface MovieResponse {
  results: Movie[];
  page: number;
  total_pages: number;
  total_results: number;
}

Search Movies

interface SearchParams {
  query: string;
  page?: number;
  include_adult?: boolean;
  language?: string;
}

TV Shows

Get Popular Shows

interface TVParams {
  page?: number;
  language?: string;
}

interface TVResponse {
  results: TVShow[];
  page: number;
  total_pages: number;
  total_results: number;
}

Sports

Get Live Matches

interface LiveMatchesParams {
  sport?: string;
  league?: string;
  limit?: number;
}

interface LiveMatchesResponse {
  matches: SportMatch[];
  total: number;
}

User Data API

Watch History

Add to History

interface WatchHistoryEntry {
  user_id: string;
  media_id: string;
  media_type: 'movie' | 'tv';
  progress: number;
  timestamp: number;
}

Get History

interface GetHistoryParams {
  user_id: string;
  limit?: number;
  offset?: number;
}

interface GetHistoryResponse {
  history: WatchHistoryEntry[];
  total: number;
}

User Preferences

Update Preferences

interface UserPreferences {
  user_id: string;
  theme?: string;
  accentColor?: string;
  isWatchHistoryEnabled: boolean;
  notifications: {
    enabled: boolean;
    types: string[];
  };
}

Firestore Collections

Collection: userPreferences

interface UserPreferencesDoc {
  user_id: string;
  isWatchHistoryEnabled: boolean;
  accentColor: string;
  created_at: Timestamp;
  updated_at: Timestamp;
}

Collection: watchHistory

interface WatchHistoryDoc {
  user_id: string;
  media_id: string;
  media_type: 'movie' | 'tv';
  title: string;
  poster_path: string;
  watched_at: Timestamp;
  progress: number;
}

Error Handling

Error Codes

enum ErrorCode {
  INVALID_CREDENTIALS = 'auth/invalid-credentials',
  USER_NOT_FOUND = 'auth/user-not-found',
  EMAIL_IN_USE = 'auth/email-already-in-use',
  WEAK_PASSWORD = 'auth/weak-password',
  NETWORK_ERROR = 'network/error',
  API_ERROR = 'api/error',
  RATE_LIMIT = 'api/rate-limit',
}

Error Responses

interface ErrorResponse {
  code: ErrorCode;
  message: string;
  details?: any;
}

Rate Limiting

Configuration

interface RateLimitConfig {
  maxRequests: number;
  timeWindow: number;
  errorCode: ErrorCode;
}

const defaultConfig: RateLimitConfig = {
  maxRequests: 100,
  timeWindow: 60000,
  errorCode: ErrorCode.RATE_LIMIT,
};

WebSocket Events

User Events

interface UserEvent {
  type: 'presence' | 'status' | 'preferences';
  user_id: string;
  data: any;
  timestamp: number;
}

Media Events

interface MediaEvent {
  type: 'play' | 'pause' | 'seek' | 'end';
  media_id: string;
  user_id: string;
  timestamp: number;
  data: {
    progress?: number;
    position?: number;
  };
}

PWA Events

Service Worker

interface ServiceWorkerEvent {
  type: 'install' | 'activate' | 'update' | 'error';
  timestamp: number;
  details?: any;
}

Push Notifications

interface PushNotification {
  title: string;
  body: string;
  icon?: string;
  data?: {
    url?: string;
    action?: string;
    [key: string]: any;
  };
}

Authentication Flow

Token Management

interface AuthToken {
  access_token: string;
  refresh_token: string;
  expires_in: number;
  user_id: string;
}

Session Management

interface Session {
  user: User;
  tokens: AuthToken;
  created_at: number;
  expires_at: number;
}

Example Usage

Authentication

const auth = new Auth();

// Sign up
const user = await auth.signUp({
  email: 'user@example.com',
  password: 'password123'
});

// Sign in
const session = await auth.signIn({
  email: 'user@example.com',
  password: 'password123'
});

// Google sign in
const googleUser = await auth.socialAuth({
  provider: 'google'
});

Media Operations

const media = new MediaAPI();

// Get popular movies
const movies = await media.getPopular({
  page: 1,
  language: 'en'
});

// Search content
const results = await media.search({
  query: 'matrix',
  include_adult: false
});

// Get live sports
const matches = await media.getLiveMatches({
  sport: 'football',
  limit: 10
});

User Operations

const userAPI = new UserAPI();

// Update preferences
await userAPI.updatePreferences({
  user_id: 'user123',
  accentColor: '#ff0000',
  isWatchHistoryEnabled: true
});

// Get watch history
const history = await userAPI.getHistory({
  user_id: 'user123',
  limit: 20
});