Frontrow 🎫

A high-performance TypeScript-based ticket availability monitoring system that tracks ticket sales in real-time and sends instant notifications when tickets become available. Built with Bun runtime for optimal performance and modern web technologies for a beautiful user experience.

📋 Table of Contents

• Overview
• Features
• Installation
• Quick Start
• Usage
  • Console Mode
  • Web UI Mode
  • Environment Variables
• API Reference
• Project Structure
• Architecture
• Configuration
• Development
• Troubleshooting
• Requirements
• License
• Author

🎯 Overview

Frontrow is a sophisticated ticket monitoring system designed to help users never miss ticket sales. It continuously monitors ticket availability from ticket vendors (currently supporting Biletix) and provides instant notifications when tickets change status from "Soon" to "On Sale". Additionally, it supports Queue-it tracking to monitor queue positions and wait times for high-demand events.

Key Highlights

• ⚡ Lightning Fast: Built on Bun runtime for exceptional performance
• 🎨 Modern UI: Beautiful web interface with Shoelace design system
• 🛡️ Rate Limit Safe: Intelligent request throttling to prevent IP bans
• 🔔 Multi-Channel Notifications: System notifications and browser alerts
• 📊 Real-Time Statistics: Live performance tracking and status monitoring
• 🎟️ Queue Tracking: Monitor Queue-it queue positions and wait times
• 🔥 Hot Reload: Development mode with automatic file watching
• 📦 Version Tracking: Automatic version generation from git commits

✨ Features

Core Functionality

• 🎫 Real-Time Monitoring: Continuously monitors ticket availability every 1.5 minutes (with ±15% randomization to avoid detection)
• 🔔 Smart Notifications: Instant alerts when tickets change from "Soon" to "On Sale" status
• 📊 Status Tracking: Comprehensive tracking of all performance status changes with detailed statistics
• 🖥️ System Notifications: Native macOS system notifications for ticket availability alerts
• 🌐 Browser Notifications: Web-based notifications for users accessing the web UI
• 🎟️ Queue-it Tracking: Monitor Queue-it queue positions, wait times, and queue status for high-demand events

Rate Limiting & Protection

• 🛡️ Intelligent Rate Limiting: Prevents IP bans with multiple protection mechanisms:
  • Randomized delays between requests (2-5 seconds)
  • Randomized check intervals (±15% variance)
  • Automatic retry with exponential backoff
  • Rate limit detection and handling (429 status codes)
  • Increased check interval (1.5 minutes instead of 1 minute)
  • Connection monitoring and timeout handling

User Interface

• 🎨 Beautiful Modern UI:
  • Built with Shoelace web components
  • Responsive design that works on all devices
  • Colored console output for better readability
  • Real-time status updates
  • Performance statistics dashboard

Developer Experience

• 🔥 Hot Module Reload: Development mode with automatic file watching and reload
• 📦 Version Tracking: Automatic version generation from git commits
• 🔧 TypeScript: Full type safety with strict TypeScript configuration
• 📝 Well-Documented: Comprehensive code documentation and comments

🚀 Installation

Prerequisites

• Bun >= 1.0.0 (Install Bun)
• Node.js >= 18.0.0 (for compatibility, though Bun is the primary runtime)
• Git (for version tracking)

Step-by-Step Installation

1. Clone the repository

   git clone <repository-url>
   cd frontrow

2. Install dependencies

   bun install

   Bun will automatically install all dependencies listed in package.json.

3. Install git hooks (optional but recommended)

   bun run install-hooks

   This installs the pre-push hook that automatically updates the version based on commit messages.

4. Verify installation

   bun --version

🏃 Quick Start

Prerequisites

Before running the application, you need to set up your API cookie:

1. Copy the example environment file:

   cp .env.example .env

2. Edit .env and add your Biletix API cookie (see Environment Variables section for instructions on how to get it)

Console Mode (Fastest Way to Get Started)

# Start monitoring with default event ID (will prompt)
bun start

# Or specify an event ID directly
bun start 5HT02

Web UI Mode

# Production mode
bun run ui

# Development mode with hot reload
bun run dev

Then open your browser and navigate to http://localhost:3000

📖 Usage

Console Mode

Console mode provides a lightweight, terminal-based interface perfect for running in the background or on servers.

Basic Usage

# Interactive mode (prompts for event ID)
bun start

# With event ID argument
bun start <event-id>

Example

bun start 5HT02

Console Output Features:

• 🎨 Colored status indicators
• 📊 Real-time status updates
• 🔔 Notification alerts
• ⏱️ Time until next check
• 📈 Performance statistics

Stopping Console Mode

Press Ctrl+C to stop the monitoring process gracefully.

Web UI Mode

The web UI provides a full-featured dashboard for monitoring ticket availability.

Starting the Server

Production Mode:

bun run ui

Development Mode (with hot reload):

bun run dev

Accessing the UI

1. Start the server using one of the commands above
2. Open your browser
3. Navigate to http://localhost:3000

Web UI Features

• 📊 Real-Time Dashboard: Live updates every 1.5 minutes
• 🎨 Modern Design: Beautiful interface built with Shoelace components
• 🔔 Browser Notifications: Desktop notifications when tickets go on sale
• 🎟️ Queue Tracking: Monitor Queue-it queue positions and wait times
• 📱 Responsive: Works perfectly on desktop, tablet, and mobile devices
• ⚡ Fast: Optimized for performance with minimal latency
• 🔄 Auto-Refresh: Automatic page updates without manual refresh

Using the Web UI

1. Enter an Event ID in the input field
2. Click "Start Monitoring" or press Enter
3. The dashboard will display:
   • Current ticket status
   • Performance statistics
   • Last check timestamp
   • Next check countdown
   • Status history

Queue Tracking (Optional)

The web UI includes Queue-it tracking functionality to monitor queue positions for high-demand events:

1. Configure Queue-it settings in your .env file (see Environment Variables)
2. Start the web UI server
3. Use the "Queue Status" panel in the web interface
4. Click "Start" to begin monitoring queue position and wait times
5. The dashboard displays:
   • Current queue position
   • Estimated wait time
   • Queue status updates
   • Event start time

Environment Variables

You can configure the application using environment variables:

Variable	Description	Default	Required	Example
API_COOKIE	Biletix API cookie for authentication	-	Yes	See setup instructions below
PORT	Server port for web UI mode	3000	No	PORT=8080 bun run ui
NODE_ENV	Environment mode	development	No	NODE_ENV=production bun run ui
QUEUE_CUSTOMER_ID	Queue-it customer ID	-	No*	tmturkiye
QUEUE_EVENT_ID	Queue-it event ID	-	No*	tarkansubat
QUEUE_ID	Queue-it queue UUID	-	No*	af46d858-995c-4be3-8bd0-76ac18d439c8
QUEUE_SESSION_ID	Queue-it session ID (seid)	-	No*	See setup instructions
QUEUE_SETS	Queue-it sets parameter	-	No*	See setup instructions
QUEUE_COOKIES	Queue-it cookies (semicolon-separated)	-	No*	See setup instructions
QUEUE_TARGET_URL	Target URL for queue redirect	-	No*	https://www.biletix.com/etkinlik/5HT02/TURKIYE/tr
QUEUE_LAYOUT_NAME	Queue layout name	-	No*	Black Tarkan
QUEUE_LAYOUT_VERSION	Queue layout version	0	No*	178704974934

* Required only if using Queue-it tracking functionality

Setting Up API_COOKIE (Required)

The API_COOKIE environment variable is required for the application to work. This cookie authenticates requests to the Biletix API.

To get your API cookie:

1. Open https://www.biletix.com in your browser
2. Open Developer Tools (F12 or right-click → Inspect)
3. Go to the Network tab
4. Navigate to an event page or make a request that calls the API
5. Find a request to wbtxapi/api/v1/bxcached/event/getPerformanceList/...
6. Click on the request and go to Headers
7. Copy the value of the Cookie header
8. Paste it into your .env file (see below)

Using .env file (Recommended):

1. Copy the example file:

   cp .env.example .env

2. Edit .env and add your cookie:

   API_COOKIE=BXID=...; SESSIONID=...; QueueITAccepted-...

Note: The .env file is gitignored and will not be committed to version control. Never commit your actual cookie value to the repository.

Setting Other Environment Variables

Unix/Linux/macOS:

PORT=8080 bun run ui

Windows (PowerShell):

$env:PORT=8080; bun run ui

Using .env file: Create a .env file in the project root:

API_COOKIE=your-cookie-value-here
PORT=8080
NODE_ENV=production

Setting Up Queue-it Configuration (Optional)

Queue-it tracking is optional and only needed if you want to monitor queue positions for events that use Queue-it.

To get your Queue-it configuration:

1. Open the Queue-it page in your browser (e.g., https://tmturkiye.queue-it.net/...)
2. Open Developer Tools (F12 or right-click → Inspect)
3. Go to the Network tab
4. Look for requests to /spa-api/queue/.../status
5. Copy the values from the request URL and headers:
   • Queue ID: Found in the URL path (UUID format, e.g., af46d858-995c-4be3-8bd0-76ac18d439c8)
   • Customer ID: Found in the domain (e.g., tmturkiye)
   • Event ID: Found in the URL path (e.g., tarkansubat)
   • Session ID (seid): Found in the query parameters
   • Sets: Found in the query parameters
   • Cookies: Copy the Cookie header from the request

Add to .env file:

QUEUE_CUSTOMER_ID=tmturkiye
QUEUE_EVENT_ID=tarkansubat
QUEUE_ID=af46d858-995c-4be3-8bd0-76ac18d439c8
QUEUE_SESSION_ID=your-session-id-here
QUEUE_SETS=your-sets-value-here
QUEUE_COOKIES=Queue-it-tmturkiye___________tarkansubat=Qid=...&Cid=...; Queue-it-cc3c3169-121e-4c44-9258-7c2d0ca712e3=...
QUEUE_TARGET_URL=https://www.biletix.com/etkinlik/5HT02/TURKIYE/tr
QUEUE_LAYOUT_NAME=Black Tarkan
QUEUE_LAYOUT_VERSION=178704974934

Note: Session ID, Sets, and Cookies values change frequently and may expire. You may need to update them periodically. The server will warn you if these values need to be refreshed.

🔌 API Reference

When running in web UI mode, the following REST API endpoints are available:

Health Check

GET /api/health

Returns the server health status.

Response:

{
  "status": "ok",
  "timestamp": 1706123456789
}

Version Information

GET /api/version

Returns version information including git commit details.

Response:

{
  "version": "1.3.0",
  "commitShort": "a1b2c3d",
  "commitFull": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0",
  "commitCount": 42,
  "branch": "main",
  "buildTime": "2026-01-25T12:34:56.789Z"
}

Check Ticket Status

GET /api/check/<event-id>

Checks the ticket status for a specific event.

Parameters:

• event-id (path parameter): The event ID to check (e.g., 5HT02)

Response:

{
  "data": [
    {
      "performanceId": "12345",
      "performanceCode": "004",
      "performanceName": "Performance Name",
      "performanceDate": "2026-02-15T20:00:00Z",
      "status": "s01_onsale",
      "eventName": "Event Name",
      "venueCity": "Istanbul",
      "venueName": "Venue Name"
    }
  ]
}

Error Response:

{
  "error": "Error message here"
}

Status Codes:

• 200 OK: Successful request
• 400 Bad Request: Invalid event ID
• 404 Not Found: Event not found
• 429 Too Many Requests: Rate limit exceeded
• 500 Internal Server Error: Server error

Queue Configuration

GET /api/queue/config

Returns the Queue-it configuration from environment variables (without sensitive cookies).

Response:

{
  "customerId": "tmturkiye",
  "eventId": "tarkansubat",
  "queueId": "af46d858-995c-4be3-8bd0-76ac18d439c8",
  "sessionId": "session-id-here",
  "sets": "sets-value-here",
  "targetUrl": "https://www.biletix.com/etkinlik/5HT02/TURKIYE/tr",
  "layoutName": "Black Tarkan",
  "layoutVersion": 178704974934,
  "cid": "tr-TR",
  "hasCookies": true
}

Check Queue Status

POST /api/queue/status

Checks the Queue-it queue status for a specific event. This endpoint acts as a proxy to the Queue-it API.

Request Body:

{
  "queueId": "af46d858-995c-4be3-8bd0-76ac18d439c8",
  "customerId": "tmturkiye",
  "eventId": "tarkansubat",
  "cid": "tr-TR",
  "layoutName": "Black Tarkan",
  "sessionId": "session-id-here",
  "sets": "sets-value-here",
  "targetUrl": "https://www.biletix.com/etkinlik/5HT02/TURKIYE/tr",
  "customUrlParams": "",
  "layoutVersion": 178704974934,
  "isClientRedayToRedirect": null,
  "isBeforeOrIdle": true,
  "cookies": {
    "Queue-it-tmturkiye___________tarkansubat": "Qid=...&Cid=...",
    "Queue-it-cc3c3169-121e-4c44-9258-7c2d0ca712e3": "..."
  }
}

Note: All fields are optional if configured via environment variables. The server will use environment variable values as defaults.

Response:

{
  "redirectUrl": "https://www.biletix.com/...",
  "queueId": "af46d858-995c-4be3-8bd0-76ac18d439c8",
  "eventStartTimeUTC": "2026-02-15T20:00:00Z",
  "queueNumber": 1234,
  "queueNumberText": "You are number 1234 in the queue",
  "estimatedWaitTimeSeconds": 300,
  "estimatedWaitTimeMinutes": 5
}

Error Response:

{
  "error": "Queue ID, Customer ID, and Event ID are required",
  "status": 400
}

Status Codes:

• 200 OK: Successful request
• 400 Bad Request: Missing required parameters
• 500 Internal Server Error: Queue API error or server error

📁 Project Structure

frontrow/
├── src/                          # Source code
│   ├── config/                   # Configuration constants
│   │   └── constants.ts          # API URLs, headers, status texts, intervals
│   ├── types/                    # TypeScript type definitions
│   │   └── index.ts              # Performance, ApiResponse, PerformanceStatus types
│   ├── utils/                    # Utility functions
│   │   ├── colors.ts             # ANSI color codes for terminal output
│   │   ├── status.ts             # Status text mapping and badge formatting
│   │   ├── performance.ts        # Performance-related helper functions
│   │   ├── date.ts               # Date formatting utilities
│   │   ├── rateLimiter.ts       # Rate limiting to prevent IP bans
│   │   ├── retry.ts              # Retry logic with exponential backoff
│   │   ├── version.ts            # Version information utilities
│   │   ├── cache.ts              # Caching utilities
│   │   └── connection.ts         # Connection monitoring utilities
│   ├── services/                 # Business logic services
│   │   ├── api.ts                # API fetching logic
│   │   └── crawler.ts            # Main crawler service with status tracking
│   ├── ui/                       # User interface components
│   │   ├── console.ts            # Console output formatting
│   │   └── notifications.ts      # System notifications
│   ├── index.ts                  # Application entry point (console mode)
│   └── server.ts                 # Web server for UI mode
├── public/                       # Web UI assets
│   ├── index.html                # Main HTML file with Shoelace components
│   ├── app.ts                    # Client-side TypeScript
│   └── favicon.svg               # Favicon
├── scripts/                      # Build and utility scripts
│   └── generate-version.ts      # Version generation script
├── .githooks/                    # Git hooks
│   └── pre-push                  # Pre-push hook for version updates
├── .gitignore                    # Git ignore rules
├── package.json                  # Project dependencies and scripts
├── tsconfig.json                 # TypeScript configuration
├── bun.d.ts                      # Bun type definitions
├── LICENSE                       # MIT License
└── README.md                     # This file

Directory Descriptions

• src/config/: Centralized configuration constants including API endpoints, headers, status mappings, and timing intervals
• src/types/: TypeScript type definitions ensuring type safety across the application
• src/utils/: Reusable utility functions for common operations (colors, dates, rate limiting, etc.)
• src/services/: Core business logic including API communication and crawler orchestration
• src/ui/: User interface components for both console and web interfaces
• public/: Static web assets served by the web server
• scripts/: Build and maintenance scripts

🏗️ Architecture

Separation of Concerns

The project follows a clean architecture pattern with clear separation of concerns:

• Types: Centralized type definitions for type safety across the entire application
• Config: All configuration constants in one place for easy maintenance
• Utils: Reusable utility functions that can be used across different modules
• Services: Business logic separated from UI concerns
• UI: Presentation layer for both console and web interfaces

Key Components

FrontrowCrawler

The main service class that orchestrates the crawling process:

• Manages ticket status checking
• Handles status change detection
• Coordinates notifications
• Tracks performance statistics

PerformanceStatusTracker

Tracks performance status changes over time:

• Records status transitions
• Calculates statistics
• Provides historical data

Rate Limiter

Intelligent request throttling system:

• Randomizes delays between requests
• Prevents IP bans
• Handles rate limit responses
• Implements exponential backoff

Retry Logic

Handles transient failures:

• Exponential backoff strategy
• Configurable retry attempts
• Jitter to prevent thundering herd
• Status code-based retry decisions

Data Flow

1. Console Mode:

   User Input → FrontrowCrawler → API Service → Rate Limiter → API
   API Response → Status Tracker → Notification Service → Console Output
   

2. Web UI Mode:

   Browser → Web Server → API Endpoint → API Service → Rate Limiter → API
   API Response → Status Tracker → JSON Response → Browser → UI Update
   

⚙️ Configuration

Timing Configuration

All timing configurations are defined in src/config/constants.ts:

• Check Interval: 90 seconds (1.5 minutes) with ±15% randomization
• Rate Limiter Delays: 2-5 seconds between requests
• Retry Delays: Initial 2 seconds, max 2 minutes with exponential backoff
• Cache TTL: 60 seconds

Status Codes

The application recognizes the following ticket status codes:

Status Code	Description
s01_onsale	On Sale
s02_soldout	Sold Out
s03_soon	Soon
s04_canceled	Canceled
s05_postponed	Postponed
s06_boxoffice	Box Office Only
s12_checkbacklater	Check Back Later
s13_old_over	Past Date
s14_other_channels	Other Channels
s15_other_channel_list_with_boxoffice	Other Purchase
s16_rescheduled	Rescheduled
s17_venue_changed	Venue Changed

API Configuration

• Base URL: https://www.biletix.com
• API Endpoint Pattern: /wbtxapi/api/v1/bxcached/event/getPerformanceList/{eventId}/INTERNET/tr
• Channel: INTERNET
• Language: tr (Turkish)
• Country: TURKIYE

💻 Development

Development Setup

1. Clone and install:

   git clone <repository-url>
   cd frontrow
   bun install

2. Start development server:

   bun run dev

3. Make changes: Edit files in src/ or public/

4. See changes: The server automatically reloads on file changes

Available Scripts

Script	Description
bun start	Run console mode (with automatic version generation)
bun run ui	Run web UI mode in production (with automatic version generation)
bun run dev	Run web UI in development mode with hot reload
bun run version	Generate version.json from git commits
bun run install-hooks	Install git hooks for automatic version updates

Version Management

The project uses automatic version generation based on git commits. The version is generated before starting the application and includes:

• Version Number: From package.json
• Git Commit Hash: Short (7 chars) and full (40 chars)
• Commit Count: Total number of commits
• Branch Name: Current git branch
• Build Timestamp: When the version was generated

The version information is available via:

• Console output when starting the application
• /api/version endpoint in web UI mode
• version.json file (generated automatically)

Git Hooks

The project includes a pre-push hook that automatically updates the version based on commit messages:

• Installation: bun run install-hooks
• Location: .githooks/pre-push
• Function: Runs version generation script before pushing

Code Style

• TypeScript: Strict mode enabled with comprehensive type checking
• Formatting: Follow TypeScript best practices
• Linting: Use TypeScript compiler for type checking
• Documentation: JSDoc comments for public APIs

TypeScript Configuration

The project uses strict TypeScript configuration:

• strict: true - Enables all strict type checking options
• noUncheckedIndexedAccess: true - Prevents unsafe index access
• noImplicitReturns: true - Ensures all code paths return a value
• noUnusedLocals: true - Prevents unused local variables
• exactOptionalPropertyTypes: true - Strict optional property types

🔧 Troubleshooting

Common Issues

Port Already in Use

Problem: Error: Port 3000 is already in use

Solution:

# Use a different port
PORT=8080 bun run ui

# Or find and kill the process using port 3000
lsof -ti:3000 | xargs kill

Bun Not Found

Problem: bun: command not found

Solution:

# Install Bun
curl -fsSL https://bun.sh/install | bash

# Or use npm/npx
npm install -g bun

Version Generation Fails

Problem: Version generation script fails

Solution:

• Ensure you're in a git repository
• Check that git is installed and accessible
• Verify you have at least one commit

Rate Limiting / IP Ban

Problem: Getting 429 errors or IP banned

Solution:

• The application automatically handles rate limiting
• If issues persist, increase delays in src/config/constants.ts
• Consider using a VPN or proxy
• Reduce check frequency

Notifications Not Working

Problem: System notifications not appearing

Solution:

• macOS: Check System Preferences → Notifications → Terminal/Bun
• Browser: Ensure notification permissions are granted
• Check browser console for errors

Web UI Not Loading

Problem: Blank page or errors in browser

Solution:

• Check server logs for errors
• Verify port is correct
• Check browser console for JavaScript errors
• Ensure public/index.html exists
• Try clearing browser cache

Queue Tracking Not Working

Problem: Queue status shows errors or doesn't update

Solution:

• Verify Queue-it configuration in .env file
• Check that QUEUE_CUSTOMER_ID, QUEUE_EVENT_ID, and QUEUE_ID are set
• Ensure QUEUE_SESSION_ID and QUEUE_SETS are current (they expire frequently)
• Verify QUEUE_COOKIES are valid and not expired
• Check server logs for Queue API errors
• Restart the server after updating .env file
• Note: Session ID, Sets, and Cookies may need to be refreshed periodically

Debug Mode

Enable verbose logging by checking console output. The application logs:

• API requests and responses
• Status changes
• Errors and warnings
• Rate limiting events
• Connection issues

Getting Help

If you encounter issues:

1. Check the Troubleshooting section
2. Review server logs and browser console
3. Verify your configuration
4. Check that all dependencies are installed
5. Ensure you're using the correct Bun version

📋 Requirements

Runtime Requirements

• Bun >= 1.0.0

  • Primary runtime environment
  • Provides fast JavaScript/TypeScript execution
  • Installation Guide

• Node.js >= 18.0.0 (optional, for compatibility)

  • Not required if using Bun
  • May be needed for some tooling

System Requirements

• Operating System: macOS, Linux, or Windows
• Memory: Minimum 512MB RAM (recommended 1GB+)
• Network: Internet connection for API access
• Disk Space: ~50MB for installation

Browser Requirements (Web UI)

• Chrome/Edge: Latest 2 versions
• Firefox: Latest 2 versions
• Safari: Latest 2 versions
• Mobile Browsers: iOS Safari, Chrome Mobile

Dependencies

• @shoelace-style/shoelace: ^2.15.1
  • Web component library for UI
  • Automatically loaded via CDN in web UI

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

👤 Author

Erbil Nas

• Email: erbil@erbilnas.com
• GitHub: @erbilnas

---

Made with ❤️ using TypeScript and Bun