Streaming Launcher

A production-ready streaming service launcher using Puppeteer with remote debugging to bypass automation detection and enable Cast functionality.

Features

• 🎥 Cast Support: Full casting capability with Chrome's remote debugging protocol
• 🔐 Credential Management: Secure credential storage for multiple streaming services
• 🚀 TypeScript: Fully typed codebase for better development experience
• ✅ Unit Tests: Jest-based unit testing with mocks
• 🧪 E2E Tests: Playwright-based end-to-end testing
• 📦 Build Pipeline: TypeScript compilation to JavaScript dist folder
• 🔌 Automation Bypass: Uses remote debugging to avoid automation detection by services

Project Structure

├── src/
│   ├── cli.ts                 # Main CLI entry point
│   ├── types/                 # TypeScript type definitions
│   ├── launcher/
│   │   ├── index.ts          # Core launcher functions
│   │   └── chrome-debug.ts   # Chrome remote debugging launcher
│   └── utils/
│       ├── cli.ts            # CLI utilities (readline)
│       ├── file.ts           # File and credential management
│       └── debug.ts          # Chrome debugging utilities
├── tests/
│   ├── unit/                 # Jest unit tests
│   └── e2e/                  # Playwright e2e tests
├── dist/                     # Compiled JavaScript (generated)
├── credentials/              # Credential JSON files (git-ignored)
├── .chrome-profile/          # Persistent Chrome profile (git-ignored)
├── tsconfig.json             # TypeScript configuration
├── jest.config.js            # Jest configuration
├── playwright.config.ts      # Playwright configuration
└── package.json              # Dependencies and scripts

Quick Start

Prerequisites

• Node.js 16+
• Google Chrome installed

Installation

npm install

Build

npm run build

This compiles TypeScript to JavaScript in the dist/ folder.

Running the Launcher

The streaming launcher uses a two-terminal approach:

Terminal 1: Launch Chrome with remote debugging

npm run launch-chrome
# Or in development:
npm run dev:chrome

Terminal 2: Connect and select a service

npm start
# Or in development:
npm run dev

Then follow the prompts to select a streaming service.

Scripts

• npm run build - Compile TypeScript to JavaScript
• npm run clean - Remove dist and coverage directories
• npm start - Run the compiled launcher
• npm run launch-chrome - Launch Chrome with remote debugging (from dist)
• npm run dev - Run launcher in development mode (TypeScript directly)
• npm run dev:chrome - Launch Chrome in development mode
• npm test - Run Jest unit tests
• npm run test:watch - Run tests in watch mode
• npm run test:coverage - Run tests with coverage report
• npm run e2e - Run Playwright e2e tests
• npm run e2e:debug - Run e2e tests in debug mode
• npm run e2e:ui - Run e2e tests with UI
• npm run lint - Type check without emitting JavaScript

Adding Credentials

Create JSON credential files in one of these locations:

1. Recommended: ~/streaming_credentials/ (home directory)
2. Alternative: ./credentials/ (project directory)

The launcher will automatically check both locations and ask you for a custom path if credentials are not found in either location.

Credential File Format

{
  "service": "Netflix",
  "url": "https://www.netflix.com",
  "cookies": [
    {
      "name": "cookie_name",
      "value": "cookie_value",
      "domain": ".netflix.com",
      "path": "/",
      "expires": 1735689600,
      "httpOnly": true,
      "secure": true,
      "sameSite": "Lax"
    }
  ],
  "storage": {
    "key1": "value1",
    "key2": "value2"
  }
}

Setting Up Credentials

Option 1: Home Directory (Recommended)

mkdir -p ~/streaming_credentials
cp Netflix.json ~/streaming_credentials/

Option 2: Project Directory

mkdir -p credentials
cp Netflix.json credentials/

Option 3: Custom Location When you run the launcher, if credentials are not found in default locations, it will ask:

⚠️  No credentials found in default locations:
  - /Users/username/streaming_credentials
  - /path/to/project/credentials

Please enter the path to your credentials folder: /path/to/my/credentials

Just enter the full path (you can use ~ for home directory).

## Testing

### Unit Tests (Jest)

```bash
npm test
npm run test:watch
npm run test:coverage

Tests are located in tests/unit/ and test individual utility functions and modules.

E2E Tests (Playwright)

npx playwright test
npx playwright test --ui
npx playwright test --debug

Tests are located in tests/e2e/ and test the complete launcher workflow.

How It Works

The launcher uses Chrome's remote debugging protocol to avoid automation detection:

1. Chrome Launch: Starts Chrome with --remote-debugging-port=9222
2. Connection: Puppeteer connects via WebSocket to the debugging port
3. Authentication: Loads cookies and localStorage from credentials
4. Navigation: Opens the streaming service URL
5. Cast Ready: Chrome's Cast menu is fully functional

This approach bypasses:

• Automation detection (no webdriver property)
• Google sign-in blocks
• Service-specific automation checks

Development

TypeScript

All source code is written in TypeScript with strict mode enabled. Type definitions are included in the dist folder.

Adding New Modules

1. Create files in src/ with .ts extension
2. Add type definitions in src/types/ if needed
3. Import and use in other modules
4. Run npm run build to compile

Adding Tests

Unit Tests (Jest):

// tests/unit/my-feature.test.ts
describe('My Feature', () => {
  it('should do something', () => {
    expect(true).toBe(true);
  });
});

E2E Tests (Playwright):

// tests/e2e/my-flow.spec.ts
import { test, expect } from '@playwright/test';

test('should complete flow', async ({ page }) => {
  // Your test code
});

Troubleshooting

Chrome not found

• Ensure Chrome is installed and in the default location
• On macOS: /Applications/Google Chrome.app/Contents/MacOS/Google Chrome
• On Linux: Check which google-chrome or which chromium-browser
• On Windows: C:\Program Files\Google\Chrome\Application\chrome.exe

Connection refused

• Make sure npm run launch-chrome is running in another terminal
• Wait 2-3 seconds for Chrome to fully start
• Check that port 9222 is not blocked by firewall

No credentials found

• Create JSON files in the credentials/ directory
• Files must end with .json
• Check the file format matches the example above

Chrome won't connect

# Make sure Chrome is running with debugging
npm run launch-chrome  # or npm run dev:chrome

# Check that port 9222 is available
lsof -i :9222

Build errors

# Check TypeScript errors
npm run lint

# Clean and rebuild
npm run clean && npm run build

Tests failing

# Run with verbose output
npm test -- --verbose

# Run specific test file
npm test -- debug.test.ts

Quick Reference Guide

First Time Setup

git clone <repo>
cd streaming
npm install
npm run build

Running the Application

Development:

# Terminal 1
npm run dev:chrome

# Terminal 2
npm run dev

Production:

# Terminal 1
npm run launch-chrome

# Terminal 2
npm start

Testing

# Run all unit tests
npm test

# Watch mode (re-run on changes)
npm run test:watch

# Coverage report
npm run test:coverage

# E2E tests
npm run e2e

# E2E with debug UI
npm run e2e:debug

Building & Deployment

# Check for type errors
npm run lint

# Build TypeScript to JavaScript
npm run build

# Clean build artifacts
npm run clean

Performance Tips

1. Persist Chrome profile in .chrome-profile/ to avoid re-login
2. Cache credentials in the JSON files
3. Use npm run dev during development (faster than rebuild)
4. Run npm run test:coverage to identify untested code

Environment

• Node.js 16+
• Chrome/Chromium installed

Dependencies

• puppeteer-extra - Browser automation with anti-detection
• typescript - Type-safe JavaScript
• jest - Unit testing framework
• playwright - E2E testing framework

License

See LICENSE file for details.