Webinars & On-Demand Recording Hub

The public webinar system lives at /webinars and /webinars/[slug]. It covers the full lifecycle: upcoming registration, live join, and — for past webinars — an email-gated on-demand recording hub with a premium Mux-first player.

Architecture at a glance#

MongoDB (webinars collection)
       │  edited via apps/workspace /webinars module
       ▼
lib/services/webinar.service.ts
       │  public projections strip server-only secrets
       ▼
app/webinars/              →  directory listing
app/webinars/[slug]/       →  public detail page
app/webinars/[slug]/join   →  live join hub   (token-gated, status = live/upcoming)
app/webinars/[slug]/watch  →  recording hub   (token-gated, status = past)

Two separate gated hubs exist — one for joining a live event, one for watching a recording — both following the same token-validation pattern.

Data model#

Webinar type — types/webinar.ts#

Key fields relevant to the recording flow:

PublicWebinar — the client-safe projection#

PublicWebinar is a strict Omit of Webinar that drops every server-only secret before the type ever reaches a component or API response:

// types/webinar.ts
export type PublicWebinar = Omit<
  Webinar,
  "status" | "created_by" | "live_webinar_link" | "recording_download_url"
> & { status: WebinarStatus };

recording_download_url is intentionally co-omitted with live_webinar_link. The raw Zoom URL must never appear in page HTML, client props, or any public API response.

Zod schema — lib/schemas/webinar.ts#

recording_download_url: z
  .string()
  .url("Must be a valid URL")
  .nullable()
  .optional()
  .or(z.literal("")),

Mirrors the live_webinar_link validator exactly. Empty string is normalized to null in the admin form's pre-save step.

Service projections — lib/services/webinar.service.ts#

Public queries exclude recording_download_url (and live_webinar_link) at the projection level — never filtered client-side.

Gating model: public teaser vs. gated hub#

For past webinars the detail page (/webinars/[slug]) shows a teaser — a thumbnail with play affordance, or the YouTube embed if present (retained for SEO value). The full recording, HD download, and premium player are only accessible from the gated watch hub.

/webinars/[slug]          ← public (teaser + "Get the recording" form)
/webinars/[slug]/watch    ← gated  (full recording hub, requires token)

Visitors who have not requested the recording see the teaser and the form. There is no way to reach WatchHubView without a valid token issued via the request flow.

On-demand request flow#

A visitor submits the "Get the recording" form on the detail page. This is the full path from form submission to the gated hub.

Visitor on /webinars/[slug]  (status === "past")
  │  submits "Get the recording" form
  │  fields: full_name, email, company (+ optional phone, country_code, tracking)
  ▼
POST /api/webinars/[slug]/recording/request
  │
  │  1. Validate webinar exists AND computed status === "past"  → 400 if not past
  │  2. create-or-reuse webinar_registrations row:
  │       • getRegistrationByWebinarAndEmail(webinar_id, email)
  │         → if found: reuse existing token  (no duplicate row, no duplicate email)
  │         → if not:   createRegistration({ ..., registration_source: "recording" })
  │  3. silent subscription upsert:
  │       upsertConfirmedSubscription({
  │         email, full_name, company,
  │         source: "webinar_recording", source_slug: slug
  │       })
  │       → "already subscribed" is swallowed silently, never surfaced to user
  │  4. send "Your recording is ready" email (buildRecordingReadyEmail)
  │       → primary CTA: "Watch the recording →"  (watchUrl)
  │       → secondary:   "View webinar details →"  (webinarUrl)
  │       → includes unsubscribe footer
  │  5. return { success: true, mode: "new" | "returning", watchUrl }
  ▼
Email delivers tokenized link  →  /webinars/[slug]/watch?t=<unsubscribe_token>
  ▼
Gated watch hub (see below)

Key behaviors:

• Returning requesters get their existing token reused — no duplicate row, no duplicate email. mode: "returning" in the response signals this.
• Subscription is a non-blocking side effect. Errors from upsertConfirmedSubscription never fail the request.
• The JSON response includes watchUrl so the client can offer "Open your recording now" immediately; the emailed link remains the canonical, durable path.
• If the webinar status is not "past", the endpoint returns 400 — the live registration route (/api/webinars/register) continues to handle upcoming/live events and already correctly rejects past webinars.

Email template — lib/email/webinar-emails.ts#

buildRecordingReadyEmail({ name, webinarTitle, watchUrl, webinarUrl, unsubscribeUrl })

Follows the dark-theme inline-CSS pattern of buildRegistrationConfirmationEmail. Primary CTA button links to watchUrl; a secondary text link points to webinarUrl. Unsubscribe footer included on every send.

Gated watch hub — /webinars/[slug]/watch?t=<token>#

A force-dynamic server component that mirrors the live join hub pattern (app/webinars/[slug]/join/page.tsx).

Token validation sequence#

Every page load runs the following checks in order. Any failure redirects to the recovery gate.

1. token present in query string?
      No  →  recovery gate (missing_token)

2. getRegistrationByToken(token)
      null  →  recovery gate (invalid_token)

3. registration.webinar_slug === slug?
      No  →  recovery gate (wrong_webinar)

4. getWebinarBySlugWithPrivate(slug)
      null  →  recovery gate (webinar_not_found)

5. computed status === "past"?
      draft / upcoming / live  →  redirect to /webinars/[slug]  (recording not yet available)
      cancelled                →  recovery gate (cancelled)
      past                     →  proceed ✓

6. render WatchHubView with:
     • webinar (PublicWebinar fields only — no recording_download_url)
     • registrant name + email
     • hasDownload: boolean  (true if recording_download_url is non-empty)
     • downloadUrl: "/api/webinars/[slug]/recording/download?t=<token>"
     • token (for client-side re-use)

The raw recording_download_url is never passed to the client. The server component computes a boolean hasDownload and constructs the proxy URL; the client never sees the Zoom link.

Recovery gate — /webinars/[slug]/watch/invalid#

Mirrors join/invalid. Renders a friendly message and offers a re-request form that posts to POST /api/webinars/[slug]/recording/request. The page never reveals the recording source or the registrant's identity to an unverified visitor.

WatchHubView layout#

┌──────────────────────────────────────────────────────────┐
│  Matters.AI logo              Watching as <name> · verified │
├──────────────────────────────────────────────────────────┤
│        ╭┄┄ ambient glow (Mux/direct only) ┄┄╮              │
│   ┌────────────────────────────────────────────────┐       │
│   │            HERO PLAYER  (Mux | iframe)          │       │
│   │  ⏯ ──────●──────  00:12 / 47:30  [cinema][PiP][⛶] │   │
│   └────────────────────────────────────────────────┘       │
│   Source:  ● Mux (HD)   ○ YouTube    ○ Twitch   ○ X        │
│            [ ⬇ Download HD ]  ·  Also on: LinkedIn event ↗  │
├──────────────────────────────────────────────────────────┤
│  <title> · why-attend · what-you'll-learn · agenda · speakers  │
└──────────────────────────────────────────────────────────┘

Source switcher — tab priority order#

The available tab list is built from whichever fields are present on the webinar record:

The default active tab is always the first available, preferring Mux. If only YouTube is present, YouTube is the hero and ambient light is automatically disabled (iframe tabs block cross-origin pixel reads).

Hero player — Mux tab#

Reuses VideoPlayerWithAutoPiP / MuxPlayerOfficial:

• Native Picture-in-Picture + auto-PiP when the player scrolls out of view
• Native fullscreen
• Poster and scrub storyboard auto-derived from mux_playback_id
• Custom overlay layer: cinema toggle + ambient light toggle

View modes#

Cinema and PiP are only available on the Mux tab. Iframe tabs (YouTube, Twitch, X) support native fullscreen only.

Ambient light (Mux / direct video only)#

A <canvas> element sits behind the player. On each animation frame (throttled), it samples the playing <video> element's pixels (downscaled), blurs and scales the result to produce a color bloom behind the player frame.

• Driven by requestAnimationFrame, paused when the video is paused or off-screen
• Respects prefers-reduced-motion
• Automatically disabled for all iframe tabs (cross-origin pixel reads are blocked by the browser)
• The Mux player's underlying <video> element is accessed via the player ref / mediaElement property from @mux/mux-player-react. Degrades gracefully if unavailable (ambient light silently off; everything else works normally)

Proxied HD download — GET /api/webinars/[slug]/recording/download?t=<token>#

The "Download HD" button on the watch hub hits this endpoint. It re-validates the token on every request and 307-redirects to the Zoom URL. The raw URL is never in the page HTML.

1. getRegistrationByToken(t)
      null, or registration.webinar_slug !== slug  →  403

2. getWebinarBySlugWithPrivate(slug)
      null, or status !== "past"  →  403

3. recording_download_url empty / null  →  403

4. success  →  307 redirect to recording_download_url
               (Zoom serves the bytes directly)

All failure paths return 403 — never 404. This prevents existence leaks: a caller with a bad token cannot determine whether a download URL exists.

The 307 redirect is the default. There is a clear extension point to switch to a full streaming proxy (server-side fetch of the Zoom file, piped through the response) if hiding the Zoom domain becomes a requirement — the interface is identical to callers.

Public detail page changes — app/webinars/[slug]/client-page.tsx#

For past webinars the page no longer renders the full recording ungated. Instead it shows:

1. Teaser — the webinar thumbnail with a play affordance, or the YouTube embed if youtube_url is set (YouTube embed is kept for SEO value even in gated mode).
2. "Get the recording" form — the existing SubscribeForm past variant, now posting to POST /api/webinars/[slug]/recording/request instead of the old register route.
3. Success copy — "Check your email — we just sent your private link to the recording."

The old live registration route (app/api/webinars/register/route.ts) is unchanged and continues to reject past webinars with 400. The recording path is a separate endpoint with different semantics.

Security model#

Admin how-to: setting up a recording on a past webinar#

After a webinar has ended, the recording becomes available in two steps in the workspace webinar form:

1. Set the video source (mux_playback_id or youtube_url)#

In the workspace webinar edit page, under Video / Playback:

• Mux Playback ID — the ID from your Mux dashboard (e.g. abcXYZ123). Drives the premium player with ambient light, cinema mode, PiP, and scrub storyboard.
• YouTube URL — a standard https://www.youtube.com/watch?v=... or embed URL. Used as fallback if no Mux ID is set, and retained on the public detail page for SEO.

You can set both — Mux will be the default tab in the watch hub, YouTube will be the second.

2. Set the HD download link (recording_download_url)#

In the workspace webinar edit page, under Publish Settings (grouped with the existing video/link fields), fill in Recording download (HD):

• Paste the Zoom cloud-recording direct-download URL here.
• Leave blank to hide the "Download HD" button on the watch hub entirely.
• The field accepts any valid URL; empty string is normalized to null on save.
• This field is server-only — it never appears in the browser source of the public site.

3. Publish / save#

Save the form. The recording hub is now live. Any visitor who submits the "Get the recording" form on the detail page will receive an email with a tokenized link to /webinars/[slug]/watch?t=<token>.

Key files#

Public website (root Next.js app)#

Shared services and utilities#

Workspace admin#

Reuse inventory#

Related#

• Public Website Overview — where webinars fit in the public surface
• Videos Module — the /videos gallery (different surface; Mux playback pattern reference)
• Security Model — server-only secrets policy