XStream

A TypeScript library for interacting with XStream APIs. This library provides a simple interface for accessing IPTV services that implement the XStream API protocol.

Installation

npm install xstream-helper
# or
yarn add xstream-helper
# or
pnpm add xstream-helper

Usage

import { XtreamAPI, MediaType } from 'xstream-helper';

// Initialize the client
const client = new XtreamAPI({
  username: 'your_username',
  password: 'your_password',
  baseUrl: 'http://your-provider.com'
});

// Authenticate with the service
const auth = await client.authenticate();

// Get live TV streams
const liveStreams = await client.getLiveStreams();

// Generate a streaming URL
const streamUrl = client.getMediaUrl(MediaType.LIVE, 'stream_id');

API Documentation

Initialization

The XtreamAPI class requires credentials for initialization:

interface XtreamCredentials {
    username: string;
    password: string;
    baseUrl: string;
}

Available Methods

Authentication

• authenticate(): Authenticates with the service and returns user and server information

  const auth = await client.authenticate();
  // Returns Promise<XtreamAuthResponse>

Live TV

• getLiveCategories(): Retrieves all available live stream categories

  // Returns Promise<XtreamCategory[]>
  // where XtreamCategory = {
  //   category_id: string;
  //   category_name: string;
  //   parent_id: number;
  // }

• getLiveStreams(): Retrieves all available live streams

  // Returns Promise<XtreamStream[]>
  // where XtreamStream = {
  //   stream_id: number;
  //   name: string;
  //   title: string;
  //   stream_icon: string;
  //   category_id: string;
  //   added: string;
  //   rating: string;
  //   rating_5based: number;
  // }

Video on Demand (VOD)

• getVodCategories(): Retrieves all available VOD categories

  // Returns Promise<XtreamCategory[]>

• getVodStreams(): Retrieves all available VOD streams

  // Returns Promise<XtreamVodStream[]>
  // Extends XtreamStream with additional properties:
  // stream_type, container_extension, duration, plot,
  // cast, director, genre, release_date, youtube_trailer

TV Series

• getSeriesCategories(): Retrieves all available series categories

  // Returns Promise<XtreamCategory[]>

• getSeriesList(): Retrieves all available series

  // Returns Promise<XtreamSeriesInfo[]>
  // Extends XtreamStream with additional properties:
  // series_id, cover, plot, cast, director, genre,
  // release_date, last_modified, episodes

Stream URLs

• getMediaUrl(mediaType: MediaType, streamId: string | number, container?: string): Generates streaming URLs

  // Returns string
  // For live streams (default container is 'ts')
  const liveUrl = client.getMediaUrl(MediaType.LIVE, '123');
    
  // For movies with specific container
  const movieUrl = client.getMediaUrl(MediaType.MOVIE, '456', 'mp4');

Media Types

The library supports different types of media streams:

enum MediaType {
    LIVE = 'live',
    MOVIE = 'movie',
    SERIES = 'series'
}

Error Handling

All API methods throw errors for failed requests. It's recommended to use try-catch blocks:

try {
    const streams = await client.getLiveStreams();
} catch (error) {
    console.error('Failed to fetch streams:', error);
}

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

License

MIT