# PublicManualVideoController

**Kind:** Controller

**Source:** [`atloria-monorepo/apps/api/src/documentation/public-manual-video.controller.ts`](https://github.com/sherkety/atloria/blob/main/atloria-monorepo/apps/api/src/documentation/public-manual-video.controller.ts#L13)

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)