feat: add example environment files for api, app, processing, and sdk

.gitignore

@@ -18,6 +18,8 @@ yarn-error.log*
 
 # env files
 .env*
+# ...but keep the committed templates
+!.env.example
 
 # vercel
 .vercel

api/.env.example

@@ -0,0 +1,44 @@
+# ──────────────────────────────────────────────────────────────────────────────
+# api/ — NestJS backend environment
+#
+# Copy this file to `.env` and adjust the values for your local setup:
+#   cp api/.env.example api/.env
+#
+# Every value below is safe for LOCAL DEVELOPMENT ONLY. Never commit a real
+# secret, and never reuse these example secrets in staging or production.
+# ──────────────────────────────────────────────────────────────────────────────
+
+# Port the HTTP/WebSocket server listens on.
+PORT=3001
+
+# Runtime mode: development | production | test
+NODE_ENV=development
+
+# PostgreSQL connection string. Must match the database loaded via
+# `psql -d xstreamroll_dev -f database/schema.sql`.
+DATABASE_URL=postgresql://postgres:postgres@localhost:5432/xstreamroll_dev
+
+# Secret used to sign and verify JWT access tokens. REQUIRED.
+# Generate your own — do NOT use this placeholder outside local dev:
+#   openssl rand -hex 32
+# or, without openssl:
+#   node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
+JWT_SECRET=replace-with-a-generated-secret-openssl-rand-hex-32
+
+# API key clients present to authenticate against the streaming endpoints.
+# REQUIRED. Generate your own for local dev:
+#   openssl rand -hex 24
+STREAM_API_KEY=replace-with-a-generated-stream-api-key
+
+# Allowed CORS origin for browser requests (the app dev server).
+CORS_ORIGIN=http://localhost:3000
+
+# Rate limiting (express-throttler). Window in milliseconds and max requests
+# per window per client.
+THROTTLE_TTL=60000
+THROTTLE_LIMIT=100
+
+# Dev-only convenience: allow roles to be supplied via request headers so auth
+# flows can be exercised locally without minting tokens. Production deployments
+# MUST set this to 0 to disable the fallback.
+ALLOW_HEADER_ROLES=1

app/.env.example

@@ -0,0 +1,23 @@
+# ──────────────────────────────────────────────────────────────────────────────
+# app/ — Next.js frontend environment
+#
+# Copy this file to `.env` and adjust the values for your local setup:
+#   cp app/.env.example app/.env
+#
+# NOTE: variables prefixed with `NEXT_PUBLIC_` are inlined into the client
+# bundle and are therefore PUBLIC. Never put secrets behind a NEXT_PUBLIC_ name.
+# All values below are safe for local development only.
+# ──────────────────────────────────────────────────────────────────────────────
+
+# Base URL of the API service, used by client-side data fetching.
+# Defaults to http://localhost:3001 when unset.
+NEXT_PUBLIC_API_URL=http://localhost:3001
+
+# Base URL of the API used during server-side rendering / data fetching.
+# Falls back to NEXT_PUBLIC_API_URL, then to http://localhost:3001.
+API_URL=http://localhost:3001
+
+# Base URL of the public viewer used to build embed snippet iframe URLs.
+# The generated iframe src is `<NEXT_PUBLIC_VIEWER_URL>/embed/<publicId>`.
+# Defaults to https://xstreamroll.example.com when unset.
+NEXT_PUBLIC_VIEWER_URL=http://localhost:3000

xstreamroll-processing/.env.example

@@ -0,0 +1,23 @@
+# ──────────────────────────────────────────────────────────────────────────────
+# xstreamroll-processing/ — Stream-processing worker environment
+#
+# Copy this file to `.env` and adjust the values for your local setup:
+#   cp xstreamroll-processing/.env.example xstreamroll-processing/.env
+#
+# The worker polls the API over HTTP for pending events and posts processed
+# results back — it does not connect to the database or a message broker
+# directly. All values below are safe for local development only.
+# ──────────────────────────────────────────────────────────────────────────────
+
+# Base URL of the API service the worker pulls events from and posts results to.
+# Must be a valid URL. Defaults to http://localhost:3001 when unset.
+API_URL=http://localhost:3001
+
+# Runtime mode: development | production | test
+NODE_ENV=development
+
+# How often (in milliseconds) the worker polls the API for pending events.
+POLL_INTERVAL_MS=5000
+
+# Maximum number of stream sessions processed concurrently. Defaults to 32.
+MAX_CONCURRENT_SESSIONS=32

xstreamroll-sdk/.env.example

@@ -0,0 +1,22 @@
+# ──────────────────────────────────────────────────────────────────────────────
+# xstreamroll-sdk/ — Client SDK environment
+#
+# Copy this file to `.env` and adjust the values for your local setup:
+#   cp xstreamroll-sdk/.env.example xstreamroll-sdk/.env
+#
+# The SDK itself is configured at runtime through the `StreamingClient`
+# constructor (`baseUrl` / `env`), so it reads NO environment variables on its
+# own. The variables below exist purely as a convenience for running local
+# examples, scratch scripts, and integration checks against your own API.
+# All values are safe for local development only.
+# ──────────────────────────────────────────────────────────────────────────────
+
+# Base URL of the API the SDK should talk to in local examples/scripts.
+# Pass this to `new StreamingClient({ baseUrl: process.env.SDK_BASE_URL })`.
+SDK_BASE_URL=http://localhost:3001
+
+# Credentials for a local development user, handy when exercising the auth
+# helpers (`client.login(...)`) from an example script. These are NOT real
+# accounts — create your own local user via the API and replace these.
+SDK_DEV_EMAIL=dev@localhost
+SDK_DEV_PASSWORD=replace-with-your-local-dev-password