# `@beyonk/content-delivery`

Utilities for generating CDN URLs for images, videos, and other assets served through Beyonk's content delivery infrastructure.

## Installation

```bash
pnpm add @beyonk/content-delivery
```

## Usage

### ESM

```js
import {
  getCdnUrl,
  getAssetUrl,
  getThumbnailUrl,
  getVideoEmbedUrl,
  getVideoUrl,
  generateSocialImageUrl
} from '@beyonk/content-delivery'
```

### CommonJS

```js
const {
  getCdnUrl,
  getAssetUrl,
  getThumbnailUrl,
  getVideoEmbedUrl,
  getVideoUrl,
  generateSocialImageUrl
} = require('@beyonk/content-delivery')
```

### Mime Type Utilities

The mime type utilities are available as a separate entry point:

```js
// ESM
import { extension, mimeType, getDeliveryType, types } from '@beyonk/content-delivery/lib/mime-type'

// CommonJS
const { extension, mimeType, getDeliveryType, types } = require('@beyonk/content-delivery/lib/mime-type')
```

## API

### getCdnUrl(cdnUrl, metadata, options)

Generates a CDN URL for an image or other file. `cdnUrl` is the Bunny pull zone (`URLs.cdn`, e.g. `https://cdn.example.com`).

Media metadata comes in two formats:

- **Current** - `{ path, mimeType }`, no `id`. The file is stored in Bunny at `path` and resized with query params, e.g. `https://cdn.example.com/avatars/image_abc.png?width=128`. All new uploads use this format.
- **Legacy** - `{ path, id, type }`. Media from before the move to Bunny, served through adaptive-delivery at `/api/v2/i/beyonk/{p|q}/{size}/{path}/{id}.{ext}`. Kept only so old records still render.

`options` are the Bunny image params to send (`width`, `height`, `format`, `quality`, `variant`), plus `environmentName` (`'prod'` or `'qa'`, used for legacy media - pass it for any stored media). Only the given params are sent, so without `format` the source format is kept (e.g. transparent PNGs stay transparent). With no params, the original file is returned.

```js
const metadata = { path: 'avatars/image_abc.png', mimeType: 'image/png' }

getCdnUrl('https://cdn.example.com', metadata, { width: 128 })                  // ?width=128
getCdnUrl('https://cdn.example.com', metadata, { width: 650, format: 'jpeg' })  // ?width=650&format=jpeg
getCdnUrl('https://cdn.example.com', metadata, { variant: 'google-wallet-square' })
```

Legacy media can't take params, so the closest adaptive-delivery size is picked from `width`: up to 128 `tiny`, up to 450 `card`, up to 650 `small`, otherwise `large`.

### getAssetUrl(environmentName, metadata)

Generates a direct asset URL bypassing the CDN transformation layer.

```js
const metadata = { path: 'documents', id: 'doc123', type: 'application/pdf' }
const url = getAssetUrl('prod', metadata)
```

### getThumbnailUrl(metadata, env, params)

Generates a thumbnail URL. Videos get their Bunny Stream thumbnail, non-image files (PDF, docx, ...) get the placeholder `defaults/thumbnail.jpeg`, and images go through `getCdnUrl` with the given params.

```js
const env = {
  ENVIRONMENT_NAME: 'prod',
  IMAGE_BASE_URL: 'https://cdn.example.com',
  VIDEO_BASE_URL: 'https://video.example.com/'
}
const url = getThumbnailUrl({ path: 'avatars/image_abc.png', mimeType: 'image/png' }, env, { width: 450, format: 'jpeg' })
```

### getVideoEmbedUrl(video, options)

Generates a [Bunny Stream](https://docs.bunny.net/stream/embedding) embed URL, suitable for use in an `<iframe>`.

```js
const url = getVideoEmbedUrl({ bunny: { libraryId: '12345', videoId: 'video123' } }, { autoplay: false, loop: true })
```

The following options are always applied (defaulting to `true`): `autoplay`, `loop`, `muted`, `preload`, `responsive`.

The following options are only appended when explicitly provided: `captions`, `t`, `chromecast`, `disableAirplay`, `disableIosPlayer`, `showHeatmap`, `playsinline`, `showSpeed`, `rememberPosition`, `compactControls`.

See the [Bunny embedding docs](https://docs.bunny.net/stream/embedding) for the full list of supported parameters.

### ~~getVideoUrl(libraryId, video, options)~~ (deprecated)

> **Deprecated:** use [`getVideoEmbedUrl`](#getvideoembedurlvideo-options) instead.

Generates an embeddable video URL.

```js
const url = getVideoUrl('12345', { bunny: { libraryId: '12345', videoId: 'video123' } }, { autoplay: false, loop: true })
```

### generateSocialImageUrl(cdnUrl, environmentName, type, id, isPortal)

Generates a social sharing image URL.

```js
const url = generateSocialImageUrl('https://cdn.example.com', 'prod', 'experience', 'abc123', false)
```