Sync project files

DOCUMENTATION/API.md

@@ -0,0 +1,94 @@
+# API Reference
+
+All endpoints are relative to the server root (e.g. `http://localhost:5000`).
+
+---
+
+## `GET /api/stream/:source/:id`
+
+Returns a JSON array of available streams for a given match.
+
+**URL parameters**  
+- `source` – source name (`admin`, `echo`, `golf`, etc.)  
+- `id` – match slug (e.g. `ppv-brooklyn-nets-vs-milwaukee-bucks`)
+
+**Example request**  
+```
+GET /api/stream/admin/ppv-brooklyn-nets-vs-milwaukee-bucks
+```
+
+**Example response**
+```json
+[
+  {
+    "id": "ppv-brooklyn-nets-vs-milwaukee-bucks",
+    "streamNo": 1,
+    "language": "English - ESPN+",
+    "hd": true,
+    "streamUrl": "http://localhost:5000/api/m3u8-proxy?url=https%3A%2F%2Flb14.strmd.st%2Fsecure%2F...%2Fplaylist.m3u8",
+    "source": "admin",
+    "viewers": 14
+  }
+]
+```
+
+**Fields**  
+| Field      | Type    | Description |
+|------------|---------|-------------|
+| `id`       | string  | Match identifier |
+| `streamNo` | number  | Stream number (used internally) |
+| `language` | string  | Human‑readable label |
+| `hd`       | boolean | Whether the stream is high‑definition |
+| `streamUrl`| string  | **Proxied** playlist URL – use this for playback |
+| `source`   | string  | Source name |
+| `viewers`  | number  | Approximate viewer count (may be `0`) |
+
+> The endpoint may also accept a full watch URL or embed URL if your router supports it.
+
+---
+
+## `GET /api/m3u8-proxy`
+
+Serves the HLS playlist or a segment.  
+The server automatically detects whether the response is a playlist or a segment and handles it accordingly.
+
+**Query parameters**  
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `url`     | ✅       | The upstream HLS URL (playlist or segment). |
+| `referer` | ❌       | Override the `Referer` header sent to upstream. If omitted, `EMBED_DOMAIN` is used. |
+
+**Behaviour**  
+- If the upstream response is an M3U8 playlist (contains `#EXTM3U`), it rewrites all media URLs and `URI` attributes to point back to `/api/m3u8-proxy`.
+- If the response is an MPEG‑TS segment, it strips the PNG wrapper (if present) and returns raw TS data.
+
+**Response headers**  
+- `Content-Type: application/vnd.apple.mpegurl` or `video/mp2t`  
+- `Access-Control-Allow-Origin: *`  
+- `Cache-Control: no-cache`
+
+**Example**  
+```
+GET /api/m3u8-proxy?url=https://lb14.strmd.st/secure/.../playlist.m3u8&referer=https://embed.st/
+```
+
+---
+
+## `GET /api/segment-proxy` *(if mounted separately)*
+
+Some implementations separate segment proxying from playlist proxying.  
+This endpoint behaves exactly like `/api/m3u8-proxy` but is dedicated to segments and always returns `video/mp2t`.
+
+**Same query parameters as above.**
+
+---
+
+## Error Responses
+
+All endpoints return appropriate HTTP status codes:
+
+- `400` – Missing required parameter.
+- `502` – Upstream fetch failed (non‑2xx status, network error, or invalid response).
+- `500` – Internal server error (e.g., resolver failure).
+
+Error responses are plain text with a descriptive message.

DOCUMENTATION/README.md

@@ -0,0 +1,34 @@
+# HLS Stream Proxy Server
+
+A Node.js server that resolves and proxies HLS streams from **streamed.pk / embed.st** (and **golf** embeds) so they can be played in any browser or media player without referer or CORS issues.
+
+## Features
+
+- Resolves `admin`/`echo` streams using the embed.st handshake.
+- Resolves `golf` streams via a third‑party embed chain.
+- Proxies HLS playlists and segments with correct `Referer`/`Origin` headers.
+- Rewrites M3U8 playlists so all segments and keys go through the proxy.
+- Strips PNG wrappers from segments (tiktokcdn).
+- Works with `hls.js`, VLC, MPV, and any HLS‑compatible player.
+
+## Quick Start
+
+```bash
+git clone https://github.com/vyla-entertainment/live-api
+npm install
+npm start
+```
+
+Then open `http://localhost:5000` (or your deployed URL).
+
+## Documentation
+
+- [API Reference](./API.md)
+- [Architecture Overview](./ARCHITECTURE.md)
+- [Setup & Configuration](./SETUP.md)
+- [Deployment (incl. Hugging Face Spaces)](./DEPLOYMENT.md)
+- [Debugging](./DEBUGGING.md)
+
+## License
+
+For study and research only. See the original [streamed-pk-hls-stream-resolver](https://github.com/sharoon7171/streamed-pk-hls-stream-resolver) disclaimer.

DOCUMENTATION/SETUP.md

@@ -0,0 +1,24 @@
+# Setup & Configuration
+
+## Prerequisites
+
+- **Node.js** ≥ 22 (ES modules support).
+- **curl** installed and available in `PATH` (required for proxying).
+
+## Installation
+
+1. Clone the repository:
+```bash
+   git clone https://github.com/vyla-entertainment/live-api
+   cd live-api
+```
+
+2. Install dependencies:
+```bash
+   npm install
+ ```
+
+3. Start the server:
+```bash
+   npm start
+```