@djangocfg/nextjs 2.1.438 → 2.1.440

package/src/og-image/README.md

@@ -1,30 +1,100 @@
 # @djangocfg/nextjs/og-image
 
-Typed URL builder for Django's `django_ogimage` renderer.
+Page metadata + typed OG image builder for Django's `django_ogimage` renderer.
 
 **No Edge Runtime. No `@vercel/og`. No JSX templates.**
 Django renders and caches the PNG — Next.js only builds the URL and injects it into metadata.
 
 ---
 
+## Quick start
+
+One factory per app; pages declare only what's unique. The OG image is chosen by
+a single `og` field (defaults to your static brand image):
+
+```typescript
+// app/_core/metadata.ts — bind the factory once
+import { makeMetadataFactory } from '@djangocfg/nextjs/og-image'
+import { settings } from './settings'
+import { LOCALES } from '@i18n/locales.config'
+
+export const createMetadata = makeMetadataFactory({
+  name: settings.app.name,
+  description: settings.app.description,
+  siteUrl: settings.app.siteUrl,
+  ogImage: settings.app.media.ogimage,     // static brand card (the default)
+  icons: { icon: settings.app.media.favicon },
+  locales: LOCALES,                        // omit for single-locale sites
+})
+
+// any page.tsx
+export const metadata = createMetadata({ title: 'Pricing', path: '/pricing' })
+//                        ↑ static brand image, canonical, hreflang, og, twitter, icons
+```
+
+```typescript
+// content page — render the title onto the OG card
+export const metadata = createMetadata({ title: post.title, path, og: 'dynamic' })
+
+// content page with its own image (a screenshot, cover, …)
+export const metadata = createMetadata({ title: p.name, path, og: { image: p.image, alt: p.name } })
+```
+
+### The `og` axis (`OgSpec`)
+
+A single discriminated union decides what the OG image is — there is exactly one
+way to express each case:
+
+| `og` value | Result |
+|---|---|
+| omitted / `'static'` | the brand image from `config.ogImage` (default) |
+| `'dynamic'` | Django renders the page **title** onto the card |
+| `{ render: { preset, layout, … } }` | dynamic render with explicit params |
+| `{ image, alt? }` | an exact image URL (content screenshot, cover) |
+
+### No backend? Dynamic falls back to static
+
+The `'dynamic'` and `{ render }` cases need a Django renderer. Tell the factory
+where it is — or that there isn't one — via `ogBackend`:
+
+```typescript
+// has a backend → dynamic OG renders against it
+makeMetadataFactory({ ..., ogBackend: 'https://api.example.com' })
+
+// frontend with NO Django backend → og:'dynamic' silently becomes the static
+// brand image, so you never emit a broken /cfg/og/ URL
+makeMetadataFactory({ ..., ogBackend: '' })
+
+// omit → resolve from env (MEDIA_URL → API_URL → SITE_URL)
+makeMetadataFactory({ ... })
+```
+
+So a static-only site can leave `og: 'dynamic'` on content pages without breaking
+anything — set `ogBackend: ''` once and every dynamic spec degrades to static.
+
+---
+
 ## How It Works
 
 ```
-generateMetadata() / withOgImage()
-    ↓
-buildOgUrl(params)          — base64-encodes OGImageParams
+createMetadata({ … , og })   — picks the OG image by the single `og` field
+    ↓  (dynamic cases only)
+buildOgUrl(params)           — base64-encodes OGImageParams
     ↓
-resolveOgPublicBase()       — picks the right base URL from env vars
+resolveOgPublicBase()        — picks the right base URL from env vars
     ↓
 <meta og:image> = "{base}/cfg/og/{b64}/"
 
 Crawler/browser hits that URL
     ↓
-Django OGImageRenderView    — decodes params, renders PNG via PicTex
+Django OGImageRenderView     — decodes params, renders PNG via PicTex
     ↓
 FileResponse (cached in MEDIA_ROOT/ogimage/<sharded>/<key>.png)
 ```
 
+Static / `{ image }` cases skip Django entirely — the URL points straight at the
+given image.
+
 ---
 
 ## URL Resolution
@@ -66,45 +136,71 @@ NEXT_PUBLIC_MEDIA_URL=https://cdn.example.com
 
 ## API
 
-### `buildOgUrl(params)`
+### Recommended
 
-Builds the raw OG image URL string. Useful when you need the URL directly.
+#### `makeMetadataFactory(config) → (page) => Metadata`
 
-```typescript
-import { buildOgUrl } from '@djangocfg/nextjs/og-image'
+Binds a `SiteMetaConfig` once and returns a per-page factory. This is the single
+recommended entry point.
 
-const url = buildOgUrl({ title: 'Hello', preset: 'DARK_BLUE' })
-// → "https://api.example.com/cfg/og/eyJ0aXRsZSI6Ikhlb.../"
+```typescript
+const createMetadata = makeMetadataFactory(config)
+export const metadata = createMetadata({ title: 'About', path: '/about' })
 ```
 
-### `createOgMetadata(params)`
+**`SiteMetaConfig`**
 
-Returns a Next.js `Metadata` fragment with `openGraph.images` and `twitter.images`.
+| Field | Type | Notes |
+|---|---|---|
+| `name` | `string` | brand name (titles, siteName, alt) |
+| `description` | `string` | default description |
+| `siteUrl` | `string` | absolute origin, e.g. `https://example.com` |
+| `ogImage` | `string` | static brand OG image URL |
+| `ogBackend?` | `string` | Django origin for the dynamic renderer (see below) |
+| `icons?` | `Metadata['icons']` | favicon / apple-touch |
+| `locales?` | `readonly string[]` | for hreflang; omit for single-locale |
+| `defaultLocale?` | `string` | x-default locale (defaults `en` / first) |
+
+**`PageMeta`**
+
+| Field | Type | Notes |
+|---|---|---|
+| `title?` | `string` | falls back to `config.name` |
+| `description?` | `string` | falls back to `config.description` |
+| `keywords?` | `string[]` | |
+| `locale?` | `string` | canonical + `openGraph.locale` |
+| `path?` | `string` | path without locale prefix, `''` for home |
+| `og?` | `OgSpec` | the OG image axis (see table above) |
+| `extra?` | `Metadata` | escape hatch merged last (robots, authors, title-template, …) |
 
-```typescript
-import { createOgMetadata } from '@djangocfg/nextjs/og-image'
+#### `createMetadata(config, page)`
 
-export async function generateMetadata() {
-  return createOgMetadata({ title: 'Page', preset: 'DARK_BLUE' })
-}
-// → { openGraph: { images: [{ url, width: 1200, height: 630 }] }, twitter: { ... } }
-```
+The un-curried form `makeMetadataFactory` wraps. Use when you don't want a bound factory.
 
-### `withOgImage(metadata, params)`
+### Low-level (escape hatches)
 
-Merges OG image into an existing `Metadata` object. Auto-extracts `title` from metadata if not in params.
+Most pages never need these — they're the primitives the factory is built on.
 
-```typescript
-import { withOgImage } from '@djangocfg/nextjs/og-image'
+#### `buildOgUrl(params)`
 
-export async function generateMetadata(): Promise<Metadata> {
-  return withOgImage(
-    { title: 'Product Page', description: 'Buy now' },
-    { preset: 'DARK_BLUE', layout: 'HERO' }
-  )
-}
+Raw OG image URL string for the dynamic renderer.
+
+```typescript
+const url = buildOgUrl({ title: 'Hello', preset: 'DARK_BLUE' })
+// → "https://api.example.com/cfg/og/eyJ0aXRsZSI6Ikhlb.../"
 ```
 
+#### `createOgMetadata(params)` · `withOgImage(metadata, params)`
+
+`createOgMetadata` returns a `{ openGraph, twitter }` image fragment for the
+dynamic renderer; `withOgImage` merges that fragment into an existing `Metadata`
+(auto-extracting `title`). Both are for manual metadata assembly outside the factory.
+
+#### `resolveOgImage(spec, staticUrl, fallbackTitle)`
+
+The single decision point that turns an `OgSpec` into an image fragment — exported
+for advanced custom factories.
+
 ---
 
 ## OGImageParams

package/src/og-image/index.ts

@@ -1,6 +1,11 @@
-export type { OGImageParams, OGPreset, OGLayout } from './types'
-export { buildOgUrl } from './url'
-export { createOgMetadata, withOgImage } from './metadata'
-export type { WithOgImageOptions } from './metadata'
+// ── Recommended API ──────────────────────────────────────────────────────────
+// Bind the factory once per app, then call it from each page.
 export { createMetadata, makeMetadataFactory } from './metadata-factory'
 export type { SiteMetaConfig, PageMeta } from './metadata-factory'
+
+// ── Types ────────────────────────────────────────────────────────────────────
+export type { OGImageParams, OGPreset, OGLayout, OgSpec } from './types'
+
+// ── Low-level primitives (escape hatches) ────────────────────────────────────
+export { buildOgUrl } from './url'
+export { createOgMetadata, withOgImage, resolveOgImage, extractTitle } from './metadata'

package/src/og-image/metadata-factory.ts

@@ -1,6 +1,6 @@
 import type { Metadata } from 'next'
-import type { OGImageParams } from './types'
-import { withOgImage, type WithOgImageOptions } from './metadata'
+import type { OgSpec } from './types'
+import { resolveOgImage } from './metadata'
 
 /**
  * Site-wide identity the metadata factory needs. Config-agnostic on purpose —
@@ -16,34 +16,48 @@ export interface SiteMetaConfig {
   siteUrl: string
   /** Ready-made static brand OG image URL (absolute or root-relative). */
   ogImage: string
+  /**
+   * Django origin that serves the dynamic OG renderer (`/cfg/og/`), e.g.
+   * "https://api.example.com". Required for `og: 'dynamic'` / `{ render }`.
+   *
+   * - set    → dynamic OG images render against this origin
+   * - `''`   → no backend: dynamic specs fall back to the static brand image
+   *            (use this for a frontend with no Django, so no broken URLs)
+   * - omit   → fall back to env vars (MEDIA_URL → API_URL → SITE_URL)
+   */
+  ogBackend?: string
   /** Optional favicon / apple-touch icons forwarded to Metadata.icons. */
   icons?: Metadata['icons']
-  /** Locales for hreflang alternates (first is treated as x-default if no enDefault). */
+  /** Locales for hreflang alternates. Omit for single-locale sites. */
   locales?: readonly string[]
   /** Locale used for x-default hreflang (defaults to "en" or first locale). */
   defaultLocale?: string
 }
 
-/** Per-page inputs. Everything is optional except what makes the page unique. */
+/**
+ * Per-page inputs. Only `title` is really worth setting per page; everything
+ * else falls back to the site config.
+ */
 export interface PageMeta {
-  /** Page title (without the brand suffix — the template adds it). */
+  /** Page title (without the brand suffix). Falls back to the site name. */
   title?: string
   /** Page description; falls back to the site description. */
   description?: string
   keywords?: string[]
   /** Current locale, used for canonical + openGraph.locale + alternates. */
   locale?: string
-  /** Path without locale prefix, e.g. "/skills". '' for home. Drives alternates. */
+  /** Path without locale prefix, e.g. "/skills". '' for home. */
   path?: string
   /**
-   * OG image control, forwarded to `withOgImage`:
-   * - omitted        → static brand image (`config.ogImage`) — the safe default
-   * - `true`         → dynamic render from the page title
-   * - OGImageParams  → dynamic render with explicit preset/layout/colors
-   * - `false`        → no image (inherit whatever the layout set)
-   * - string         → explicit image URL
+   * What the OG image should be. Defaults to `'static'` (the brand image).
+   * - `'static'`          brand image from config (default)
+   * - `'dynamic'`         render the page title onto the card
+   * - `{ render: {...} }` render with explicit preset/layout/colors
+   * - `{ image, alt? }`   an exact image URL (e.g. a content screenshot)
    */
-  og?: boolean | string | Omit<OGImageParams, 'title'>
+  og?: OgSpec
+  /** Escape hatch: extra Metadata fields merged last (robots, authors, etc.). */
+  extra?: Metadata
 }
 
 function buildAlternates(
@@ -52,26 +66,25 @@ function buildAlternates(
   locale: string
 ): Metadata['alternates'] {
   if (!config.locales?.length) {
-    return { canonical: `${config.siteUrl}/${locale}${path}` }
+    return { canonical: `${config.siteUrl}/${path}`.replace(/\/+$/, '') || config.siteUrl }
   }
   const languages: Record<string, string> = {}
   for (const loc of config.locales) {
     languages[loc] = `${config.siteUrl}/${loc}${path}`
   }
-  const xDefault = config.defaultLocale ?? (config.locales.includes('en') ? 'en' : config.locales[0])
+  const xDefault =
+    config.defaultLocale ?? (config.locales.includes('en') ? 'en' : config.locales[0])
   languages['x-default'] = `${config.siteUrl}/${xDefault}${path}`
   return { canonical: `${config.siteUrl}/${locale}${path}`, languages }
 }
 
 /**
- * Builds a complete Next.js `Metadata` object from a one-time site config plus
- * per-page inputs — title-template, description, openGraph, twitter, canonical
- * + hreflang alternates, and icons — so pages only declare what's unique.
+ * Builds a complete Next.js `Metadata` from a one-time site config plus per-page
+ * inputs — title-template, description, openGraph, twitter, canonical + hreflang,
+ * icons, and the OG image — so pages only declare what's unique.
  *
- * OG image defaults to the static brand image (`config.ogImage`); opt into the
- * dynamic renderer per page with `og: true` / `og: { preset: 'DARK_BLUE' }`.
- *
- * Bind the config once in your app, then call the bound fn from each page:
+ * The OG image is chosen by the single `og` field (defaults to the static brand
+ * image). There is exactly one way to do each thing.
  *
  *   // app/_core/metadata.ts
  *   export const createMetadata = makeMetadataFactory({
@@ -83,16 +96,25 @@ function buildAlternates(
  *     locales: LOCALES,
  *   })
  *
- *   // any page.tsx
- *   export const metadata = createMetadata({ title: 'Skills', path: '/skills' })
+ *   // landing page — static brand image (default)
+ *   export const metadata = createMetadata({ title: 'Pricing', path: '/pricing' })
+ *   // content page — title rendered onto the card
+ *   export const metadata = createMetadata({ title: post.title, path, og: 'dynamic' })
+ *   // content page with its own image
+ *   export const metadata = createMetadata({ title: p.name, og: { image: p.image } })
  */
 export function createMetadata(config: SiteMetaConfig, page: PageMeta = {}): Metadata {
   const title = page.title ?? config.name
   const description = page.description ?? config.description
   const locale = page.locale ?? config.defaultLocale ?? 'en'
   const path = page.path ?? ''
+  const ogUrl = config.locales?.length
+    ? `${config.siteUrl}/${locale}${path}`
+    : `${config.siteUrl}${path}`
+
+  const ogImage = resolveOgImage(page.og ?? 'static', config.ogImage, title, config.ogBackend)
 
-  const base: Metadata = {
+  const metadata: Metadata = {
     title,
     description,
     keywords: page.keywords,
@@ -100,41 +122,34 @@ export function createMetadata(config: SiteMetaConfig, page: PageMeta = {}): Met
     openGraph: {
       type: 'website',
       locale,
-      url: `${config.siteUrl}/${locale}${path}`,
+      url: ogUrl,
       siteName: config.name,
       title,
       description,
+      ...ogImage.openGraph,
     },
     twitter: {
-      card: 'summary_large_image',
       title,
       description,
+      ...ogImage.twitter,
     },
     icons: config.icons,
   }
 
-  // Resolve the `og` shorthand into withOgImage options.
-  let ogOptions: WithOgImageOptions
-  if (page.og === undefined || page.og === false) {
-    // Default & explicit-off both map to the static brand image. (false on the
-    // factory means "don't render dynamic" — but we still want a brand image,
-    // so we point at the static one. Use og:false at the page only if you've
-    // set images elsewhere; here static is the friendly default.)
-    ogOptions = { image: config.ogImage }
-  } else if (page.og === true) {
-    ogOptions = {} // dynamic, title auto-extracted
-  } else if (typeof page.og === 'string') {
-    ogOptions = { image: page.og }
-  } else {
-    ogOptions = page.og // OGImageParams → dynamic with overrides
+  if (!page.extra) return metadata
+  // Shallow-merge the escape hatch, but deep-merge the nested og/twitter so the
+  // image we just set isn't clobbered by a partial `extra.openGraph`.
+  return {
+    ...metadata,
+    ...page.extra,
+    openGraph: { ...metadata.openGraph, ...page.extra.openGraph },
+    twitter: { ...metadata.twitter, ...page.extra.twitter },
   }
-
-  return withOgImage(base, ogOptions)
 }
 
 /**
  * Curries `createMetadata` with a fixed site config so pages call a zero-config
- * factory. See the docstring on `createMetadata` for the usage pattern.
+ * factory. This is the single recommended entry point for app metadata.
  */
 export function makeMetadataFactory(config: SiteMetaConfig) {
   return (page: PageMeta = {}): Metadata => createMetadata(config, page)

package/src/og-image/metadata.ts

@@ -1,109 +1,100 @@
 import type { Metadata } from 'next'
-import type { OGImageParams } from './types'
+import type { OGImageParams, OgSpec } from './types'
 import { buildOgUrl } from './url'
 
+const OG_WIDTH = 1200
+const OG_HEIGHT = 630
+
+/** A Next.js OG image entry. */
+function imageEntry(url: string, alt: string) {
+  return { url, width: OG_WIDTH, height: OG_HEIGHT, alt }
+}
+
 /**
- * Creates Next.js Metadata fragment with og:image and twitter:image
- * pointing to Django's django_ogimage renderer.
- *
- * Usage in generateMetadata():
- *   return createOgMetadata({ title: 'Page', preset: 'DARK_BLUE' })
+ * Builds the og/twitter image fragment for a given image URL — the one place
+ * that knows the shape Next.js expects. Both static URLs and the dynamic
+ * renderer funnel through here, so there's a single source of truth.
  */
-export function createOgMetadata(params: OGImageParams): Metadata {
-  const url = buildOgUrl(params)
-  const image = { url, width: 1200, height: 630, alt: params.title }
+function ogImageFragment(url: string, alt: string): Pick<Metadata, 'openGraph' | 'twitter'> {
   return {
-    openGraph: {
-      images: [image],
-    },
-    twitter: {
-      card: 'summary_large_image',
-      images: [url],
-    },
+    openGraph: { images: [imageEntry(url, alt)] },
+    twitter: { card: 'summary_large_image', images: [url] },
   }
 }
 
 /**
- * Options for `withOgImage`. Extends the dynamic-renderer params with an
- * `image` opt-out so a page can keep its own (static) OG image instead of the
- * dynamically-rendered one.
+ * Metadata fragment whose OG image is rendered by Django's django_ogimage
+ * endpoint (/cfg/og/). Low-level — most callers use `createMetadata`'s `og`
+ * field instead.
  */
-export type WithOgImageOptions = Omit<OGImageParams, 'title'> & {
-  title?: string
-  /**
-   * Controls the OG image source:
-   * - omitted / `true` → dynamic render via Django's /cfg/og/ (default)
-   * - `false`          → don't touch images; the page/layout's own og:image
-   *                      is preserved (use for a ready-made static brand image)
-   * - `string`         → use this exact URL as a static og/twitter image
-   */
-  image?: boolean | string
+export function createOgMetadata(params: OGImageParams): Metadata {
+  return ogImageFragment(buildOgUrl(params), params.title)
+}
+
+/** Extract a plain title string from Next.js's title shapes. */
+export function extractTitle(metadata: Metadata): string {
+  const t = metadata.title
+  if (!t) return ''
+  if (typeof t === 'string') return t
+  if (typeof t === 'object' && 'absolute' in t) return (t as { absolute: string }).absolute
+  if (typeof t === 'object' && 'default' in t) return (t as { default: string }).default
+  return ''
 }
 
 /**
- * Merges og:image metadata into an existing Metadata object.
+ * Resolves an `OgSpec` against a base Metadata into a concrete og/twitter image
+ * fragment. `staticUrl` is the site's brand image, used for the `'static'` case.
  *
- * Usage:
- *   // dynamic (default)
- *   return withOgImage({ title: 'Page', description: '...' }, { preset: 'DARK_BLUE' })
- *   // keep the page's own static image
- *   return withOgImage(meta, { preset: 'DARK_BLUE', image: false })
- *   // explicit static image
- *   return withOgImage(meta, { image: '/static/ogimage.png' })
+ * `backend` is the Django origin that serves the dynamic renderer. The dynamic
+ * cases (`'dynamic'`, `{ render }`) require it: when it's `undefined`/empty —
+ * e.g. a frontend with no Django backend — they **fall back to the static brand
+ * image** instead of emitting a broken `/cfg/og/` URL. (`undefined` still lets
+ * `buildOgUrl` fall back to env vars; pass `''` to force the static fallback.)
+ *
+ * This is the single decision point for "what is the OG image" — no other code
+ * branches on the spec.
  */
-export function withOgImage(
-  metadata: Metadata,
-  params: WithOgImageOptions = {}
-): Metadata {
-  const { image, ...ogParams } = params
+export function resolveOgImage(
+  spec: OgSpec,
+  staticUrl: string,
+  fallbackTitle: string,
+  backend?: string
+): Pick<Metadata, 'openGraph' | 'twitter'> {
+  const canRenderDynamic = backend === undefined || backend !== ''
 
-  // Opt-out: leave the incoming metadata's images untouched.
-  if (image === false) {
-    return metadata
+  if (spec === 'static') {
+    return ogImageFragment(staticUrl, fallbackTitle)
   }
-
-  // Explicit static URL: set og/twitter images without hitting the renderer.
-  if (typeof image === 'string') {
-    return {
-      ...metadata,
-      openGraph: {
-        ...metadata.openGraph,
-        images: [{ url: image, width: 1200, height: 630, alt: extractTitle(metadata) }],
-      },
-      twitter: {
-        card: 'summary_large_image',
-        ...metadata.twitter,
-        images: [image],
-      },
-    }
+  if (spec === 'dynamic') {
+    return canRenderDynamic
+      ? ogImageFragment(buildOgUrl({ title: fallbackTitle }, backend), fallbackTitle)
+      : ogImageFragment(staticUrl, fallbackTitle)
   }
-
-  // Default: dynamic render. Auto-extract title; params.title overrides.
-  const resolvedParams: OGImageParams = {
-    title: extractTitle(metadata),
-    ...ogParams,
+  if ('image' in spec) {
+    return ogImageFragment(spec.image, spec.alt ?? fallbackTitle)
   }
+  // { render: {...} } — dynamic with explicit params; title defaults to page title.
+  const title = spec.render.title ?? fallbackTitle
+  return canRenderDynamic
+    ? ogImageFragment(buildOgUrl({ ...spec.render, title }, backend), title)
+    : ogImageFragment(staticUrl, title)
+}
 
-  const ogMeta = createOgMetadata(resolvedParams)
-
+/**
+ * Merges OG image metadata (dynamic render) into existing Metadata. Kept for
+ * low-level/manual use; `createMetadata` is the recommended entry point.
+ *
+ *   return withOgImage({ title: 'Page' }, { preset: 'DARK_BLUE' })
+ */
+export function withOgImage(
+  metadata: Metadata,
+  params: Omit<OGImageParams, 'title'> & { title?: string } = {}
+): Metadata {
+  const title = params.title ?? extractTitle(metadata)
+  const frag = createOgMetadata({ ...params, title })
   return {
     ...metadata,
-    openGraph: {
-      ...metadata.openGraph,
-      ...ogMeta.openGraph,
-    },
-    twitter: {
-      ...metadata.twitter,
-      ...ogMeta.twitter,
-    },
+    openGraph: { ...metadata.openGraph, ...frag.openGraph },
+    twitter: { ...metadata.twitter, ...frag.twitter },
   }
 }
-
-function extractTitle(metadata: Metadata): string {
-  const t = metadata.title
-  if (!t) return ''
-  if (typeof t === 'string') return t
-  if (typeof t === 'object' && 'absolute' in t) return (t as { absolute: string }).absolute
-  if (typeof t === 'object' && 'default' in t) return (t as { default: string }).default
-  return ''
-}

package/src/og-image/types.ts

@@ -11,6 +11,21 @@ export type OGPreset =
 
 export type OGLayout = 'DEFAULT' | 'HERO' | 'ARTICLE' | 'MINIMAL'
 
+/**
+ * Per-page OG image intent — the single axis that decides what the OG image is.
+ * A discriminated union so every case is explicit and type-checked:
+ *
+ *   'static'              brand image from site config (the default)
+ *   'dynamic'             render the page title onto the OG card
+ *   { render: {...} }     render with explicit preset/layout/colors
+ *   { image, alt? }       an exact image URL (e.g. a content screenshot)
+ */
+export type OgSpec =
+  | 'static'
+  | 'dynamic'
+  | { render: Omit<OGImageParams, 'title'> & { title?: string } }
+  | { image: string; alt?: string }
+
 /** Mirrors Django OGImageParams exactly */
 export interface OGImageParams {
   title: string

package/src/og-image/url.ts

@@ -50,9 +50,13 @@ function cleanParams(params: OGImageParams): Record<string, unknown> {
  * django_ogimage endpoint: /cfg/og/<base64params>/
  *
  * The URL is suitable for use in og:image and twitter:image meta tags.
+ *
+ * @param base Optional explicit backend origin (e.g. "https://api.example.com").
+ *   When omitted, it's resolved from env (MEDIA_URL → API_URL → SITE_URL → '').
+ *   Pass the `ogBackend` from your site config to avoid relying on env.
  */
-export function buildOgUrl(params: OGImageParams): string {
+export function buildOgUrl(params: OGImageParams, base?: string): string {
   const b64 = encodeBase64(JSON.stringify(cleanParams(params)))
-  const base = resolveOgPublicBase()
-  return `${base}/cfg/og/${b64}/`
+  const origin = (base ?? resolveOgPublicBase()).replace(/\/$/, '')
+  return `${origin}/cfg/og/${b64}/`
 }