feat: add livestream REST endpoints

.devcontainer.json

@@ -4,11 +4,11 @@
 	"name": "Open Home Foundation - API",
 	"image": "mcr.microsoft.com/devcontainers/typescript-node:24-bookworm",
 	"forwardPorts": [
-		443
+		3000
 	],
 	"portsAttributes": {
-		"443": {
-			"label": "HTTPS server"
+		"3000": {
+			"label": "web-api (HTTP)"
 		}
 	},
 	"customizations": {
@@ -31,4 +31,4 @@
 	},
 	"postCreateCommand": "pnpm install",
 	"remoteUser": "node"
-}
+}

.env.example

@@ -0,0 +1,18 @@
+# YouTube Data API v3 key (https://console.cloud.google.com/apis/credentials)
+YOUTUBE_API_KEY=
+
+# Publicly reachable base URL of this service, used as the WebSub callback
+# target for YouTube push notifications (e.g. https://api.openhomefoundation.org).
+# Leave blank in local dev without a public tunnel; status will still update via
+# the periodic reconcile.
+PUBLIC_BASE_URL=
+
+# Shared secret for verifying WebSub push payloads (HMAC signature). Required
+# for push notifications: without it the service skips subscriptions and the
+# /pubsub webhook rejects all incoming notifications (403). Generate one with
+# `openssl rand -hex 32`.
+PUBSUB_SECRET=
+
+# Optional token echoed by the hub during subscription verification.
+# If set, /pubsub GET requires hub.verify_token to match this value.
+PUBSUB_VERIFY_TOKEN=

.gitignore

@@ -2,3 +2,4 @@ node_modules/
 dist/
 *.log
 .DS_Store
+.env

package.json

@@ -10,6 +10,7 @@
   },
   "dependencies": {
     "@nestjs/common": "^11.1.19",
+    "@nestjs/config": "^4.0.4",
     "@nestjs/core": "^11.1.19",
     "@nestjs/platform-express": "^11.1.19",
     "@nestjs/platform-socket.io": "^11.1.19",

src/app.module.ts

@@ -1,11 +1,17 @@
 import { Module } from '@nestjs/common';
+import { ConfigModule } from '@nestjs/config';
 import { AppController } from './app.controller';
 import { AppGateway } from './app.gateway';
 import { HealthModule } from './health';
 import { getVersionInfo } from './health/version';
+import { LivestreamModule } from './livestream';
 
 @Module({
-  imports: [HealthModule.register({ version: getVersionInfo() })],
+  imports: [
+    ConfigModule.forRoot({ isGlobal: true }),
+    HealthModule.register({ version: getVersionInfo() }),
+    LivestreamModule,
+  ],
   controllers: [AppController],
   providers: [AppGateway],
 })

src/livestream/index.ts

@@ -0,0 +1,4 @@
+export * from './livestream.channels';
+export * from './livestream.module';
+export * from './livestream.service';
+export * from './pubsub.service';

src/livestream/livestream.channels.ts

@@ -0,0 +1,36 @@
+export interface Channel {
+  /** URL-safe identifier used in the API path, e.g. "home-assistant". */
+  slug: string;
+  /** Human-friendly display name. */
+  name: string;
+  /** YouTube handle without the leading "@". */
+  handle: string;
+}
+
+/**
+ * Open Home Foundation project channels tracked for livestreams.
+ * Add a new project by appending an entry here — no other code changes needed.
+ */
+export const CHANNELS: readonly Channel[] = [
+  { slug: 'home-assistant', name: 'Home Assistant', handle: 'home_assistant' },
+  { slug: 'esphome', name: 'ESPHome', handle: 'esphomeio' },
+  {
+    slug: 'open-home-foundation',
+    name: 'Open Home Foundation',
+    handle: 'OpenHomeFndn',
+  },
+  {
+    slug: 'music-assistant',
+    name: 'Music Assistant',
+    handle: 'musicassistantio',
+  },
+];
+
+/**
+ * Canonical YouTube channel RSS feed URL, used both as the discovery source and
+ * as the WebSub (PubSubHubbub) subscription topic — keep a single form so the
+ * two code paths cannot drift. This is the URL documented for the hub topic:
+ * https://developers.google.com/youtube/v3/guides/push_notifications
+ */
+export const feedUrl = (channelId: string): string =>
+  `https://www.youtube.com/feeds/videos.xml?channel_id=${channelId}`;

src/livestream/livestream.controller.ts

@@ -0,0 +1,18 @@
+import { Controller, Get, Param } from '@nestjs/common';
+
+import { LivestreamInfo, LivestreamService } from './livestream.service';
+
+@Controller('livestream')
+export class LivestreamController {
+  constructor(private readonly livestream: LivestreamService) {}
+
+  @Get()
+  getAll(): LivestreamInfo[] {
+    return this.livestream.getAll();
+  }
+
+  @Get(':slug')
+  getStatus(@Param('slug') slug: string): LivestreamInfo {
+    return this.livestream.getStatus(slug);
+  }
+}

src/livestream/livestream.module.ts

@@ -0,0 +1,12 @@
+import { Module } from '@nestjs/common';
+
+import { LivestreamController } from './livestream.controller';
+import { LivestreamService } from './livestream.service';
+import { PubSubController } from './pubsub.controller';
+import { PubSubService } from './pubsub.service';
+
+@Module({
+  controllers: [LivestreamController, PubSubController],
+  providers: [LivestreamService, PubSubService],
+})
+export class LivestreamModule {}