PublicManualVideoController

Kind: Controller

Source: atloria-monorepo/apps/api/src/documentation/public-manual-video.controller.ts

PUBLIC narrated-video surface (D1 distribution) — resolves one video by id for the standalone /embed/video/:id page and iframe embeds. No auth: a video on an already-published, public manual page is public (the service fail-closes on anything else). Cacheable — the payload is immutable CDN urls + overlay data.

PublicManualVideoController exposes the unauthenticated public API surface for narrated manual videos used by the standalone /embed/video/:id page and iframe embeds. It resolves a video only when it belongs to an already-published public manual page, relying on the underlying service to fail closed for private, unpublished, or missing content. Responses are cache-friendly because they contain immutable CDN media URLs and overlay metadata.

Diagram

mermaid
graph LR
  A[Standalone embed page<br/>/embed/video/:id] --> B[PublicManualVideoController]
  C[Iframe embed consumer] --> B
  B --> D[Public manual video service]
  D --> E{Video belongs to<br/>published public page?}
  E -->|Yes| F[Video payload<br/>CDN URLs + overlays]
  E -->|No| G[Not found / access denied]
  F --> H[Cacheable client response]

Usage

ts
// Example: load a public narrated video for an embed page.
// The API returns data only when the video belongs to a published public manual page.

async function loadPublicManualVideo(videoId: string) {
  const response = await fetch(
    `${process.env.NEXT_PUBLIC_API_URL}/public/manual-videos/${videoId}`,
    {
      headers: {
        Accept: 'application/json',
      },
    },
  );

  if (!response.ok) {
    throw new Error(`Unable to load public video: ${response.status}`);
  }

  return response.json();
}

// Use the returned immutable CDN URL and overlay metadata in the video player.
const video = await loadPublicManualVideo('video_123');
console.log(video);

AI Coding Instructions

• Keep this controller unauthenticated; public access must remain constrained by service-level validation that the video belongs to a published public manual page.
• Do not add fallback behavior that exposes videos when publication or page visibility checks fail; missing or non-public content must fail closed.
• Preserve cacheability by returning immutable CDN media URLs and overlay data without user-specific fields.
• Keep embed-page and iframe consumers compatible with the response shape; coordinate payload changes with the standalone /embed/video/:id client.
• Put authorization, publication-state, and ownership checks in the service layer rather than duplicating business logic in the controller.

Relationships

• MODULE_DECLARES → getForEmbed
• DEPENDS_ON → ManualVideoService

Referenced By

• DocumentationModule (MODULE_DECLARES)