@discoverworthy/assets 0.1.0

package/README.md

@@ -0,0 +1,210 @@
+# @discoverworthy/assets
+
+Framework-agnostic image references for DiscoverWorthy Managed Assets. Rotate, optimize, and manage your images from the dashboard — on any framework, without a rebuild.
+
+## The Three-Tier Model
+
+**Tier 0 — Bare URL** (works everywhere)
+```
+https://app.discoverworthy.com/img/{siteId}/{imageKey}
+```
+Paste this into an `<img src>`, CSS `url()`, email, RSS, or anywhere. Rotation and transforms happen at the resolver — no SDK needed.
+
+**Tier 1 — `urlFor()` helper** (any JS/TS framework)
+```js
+import { urlFor, configure } from '@discoverworthy/assets';
+configure({ siteId: 'my-site' });
+const src = urlFor('hero-key', { width: 640 });
+```
+Use in Astro frontmatter, Svelte templates, Vue bindings, Next.js, or anywhere you generate URLs.
+
+**Tier 2 — Framework components** (optional polish)
+```tsx
+import { DwImage } from '@discoverworthy/assets/react';
+<DwImage asset="hero-key" alt="Team" />
+```
+Per-framework components (React/Next first; others as demand appears) add responsive srcSet, lazy loading, blur-up, and fallback handling.
+
+**Rule:** rotation and transforms are a property of **Tier 0** — the resolver, not the SDK. So even if you install nothing and just paste a URL, your images rotate from the dashboard. Tiers 1 and 2 only add developer ergonomics.
+
+## Install
+
+```bash
+npm install @discoverworthy/assets
+```
+
+## Quick Start
+
+### React / Next.js
+
+```tsx
+import { configure, DwImage } from '@discoverworthy/assets';
+
+// Configure once at app startup
+configure({ siteId: 'my-site-123' });
+
+export default function Hero() {
+  return (
+    <DwImage
+      asset="hero-key"
+      alt="Team in the workshop"
+      width={1024}
+      sizes="(max-width: 768px) 100vw, 50vw"
+    />
+  );
+}
+```
+
+### Astro
+
+```astro
+---
+import { configure, urlFor } from '@discoverworthy/assets';
+
+configure({ siteId: 'my-site-123' });
+
+const heroSrc = urlFor('hero-key', { width: 1024 });
+---
+
+<img src={heroSrc} alt="Team in the workshop" />
+```
+
+### Svelte
+
+```svelte
+<script>
+  import { configure, urlFor } from '@discoverworthy/assets';
+
+  configure({ siteId: 'my-site-123' });
+
+  const heroSrc = urlFor('hero-key', { width: 1024 });
+</script>
+
+<img src={heroSrc} alt="Team in the workshop" />
+```
+
+### Vue
+
+```vue
+<template>
+  <img :src="heroSrc" alt="Team in the workshop" />
+</template>
+
+<script setup>
+import { configure, urlFor } from '@discoverworthy/assets';
+
+configure({ siteId: 'my-site-123' });
+const heroSrc = urlFor('hero-key', { width: 1024 });
+</script>
+```
+
+### Plain HTML / WordPress
+
+No install needed. Just use the Tier 0 URL:
+
+```html
+<img src="https://app.discoverworthy.com/img/my-site-123/hero-key" alt="Team in the workshop" />
+```
+
+Image rotation, variant sizing, and all transforms work the same way. They're properties of the resolver, not the SDK.
+
+## API
+
+### `configure(opts)`
+
+Set the default site ID and/or host once at startup. All subsequent `urlFor()` calls use these defaults unless overridden.
+
+```js
+configure({ siteId: 'my-site-123' });
+// Now urlFor('image-key') works without passing siteId.
+
+configure({ siteId: 'my-site', host: 'https://dev.discoverworthy.com' });
+// Override the host (useful for dev/staging).
+```
+
+**Options:**
+- `siteId` (string) — The site ID for this deployment. Required (either here or on every `urlFor()` call).
+- `host` (string, default: `https://app.discoverworthy.com`) — Base URL for the image resolver.
+
+### `urlFor(assetId, opts)`
+
+Generate a URL for a managed DiscoverWorthy asset.
+
+```js
+urlFor('hero-key');                              // Base URL
+urlFor('hero-key', { width: 640 });              // With width variant
+urlFor('hero-key', { width: 1024, siteId: 'other-site' }); // Override siteId
+```
+
+**Parameters:**
+- `assetId` (string, required) — The image key from `dw_adopt_image` or the dashboard.
+- `opts.width` (number) — Requested width. The resolver produces WebP variants at `320`, `640`, `1024`, `1600`. Other values are passed through; the resolver will ignore unknown widths.
+- `opts.siteId` (string) — Override the configured site ID.
+- `opts.host` (string) — Override the configured host.
+
+**Returns:** A string URL like `https://app.discoverworthy.com/img/my-site/hero-key?w=640`.
+
+### `ALLOWED_WIDTHS`
+
+Exported array of allowed image widths: `[320, 640, 1024, 1600]`. Use this to build responsive srcSet or media-query logic.
+
+```js
+import { ALLOWED_WIDTHS, urlFor } from '@discoverworthy/assets';
+
+const srcSet = ALLOWED_WIDTHS.map(w => 
+  `${urlFor('hero-key', { width: w })} ${w}w`
+).join(', ');
+```
+
+### `<DwImage>` (React/Next)
+
+A pre-built component that handles responsive images, lazy loading, and fallbacks.
+
+```tsx
+import { DwImage } from '@discoverworthy/assets/react';
+
+<DwImage
+  asset="hero-key"
+  alt="Team in the workshop"
+  width={1024}
+  sizes="(max-width: 768px) 100vw, 50vw"
+  fallback="/images/placeholder.jpg"
+  lazy={true}
+/>
+```
+
+**Props:**
+- `asset` (string, required) — Image key.
+- `alt` (string, required) — Alt text for accessibility.
+- `width` (number) — Requested width for the `src` attribute. The component auto-builds a srcSet with all allowed widths.
+- `sizes` (string) — CSS media queries for responsive sizing.
+- `fallback` (string) — URL to use if the managed asset fails to load.
+- `lazy` (boolean, default: `true`) — Use lazy loading.
+- `siteId` (string) — Override the configured site ID.
+- `host` (string) — Override the configured host.
+- All standard `<img>` attributes (`className`, `style`, `onLoad`, etc.) are passed through.
+
+## Transforms & Rotation
+
+The resolver (`/img/{siteId}/{imageKey}`) handles all image transforms:
+
+- **Width variants** — Add `?w=320|640|1024|1600` to produce responsive WebP variants
+- **Rotation** — Configure a rotation policy in the dashboard (round-robin, weighted, scheduled) and images automatically cycle on the schedule you set
+- **Fallback** — If no rotation is configured, the resolver uses the original source URL
+
+All transforms work at **Tier 0** — even if you paste a bare URL with no SDK, your images rotate and resize.
+
+## Why This Matters
+
+Managed Assets closes the gap between copy-pipeline sites (where the dashboard controls every image) and owned sites (where you build in your own repo). You get:
+
+- **Zero-rebuild image swaps** — Change hero images from the dashboard without deploying new code
+- **Rotation & A/B testing** — Cycle seasonal variants, A/B test images, or weight favored variants
+- **Framework-agnostic** — Works on Next, Astro, Svelte, Vue, Hugo, plain HTML, WordPress, or anything else
+- **Optional adoption** — Use Tier 0 (bare URL) for any site; Tier 1/2 are just ergonomics
+
+## More Information
+
+- [DiscoverWorthy docs](https://discoverworthy.com)
+- GitHub: [discover-worthy/saas](https://github.com/discover-worthy/saas)
+- License: MIT

package/index.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Options for configuring the global asset resolver.
+ */
+export interface ConfigureOptions {
+  /**
+   * Site ID for this host/deployment. Used by urlFor() if not overridden.
+   */
+  siteId?: string;
+  /**
+   * Base URL for the image resolver (default: https://app.discoverworthy.com).
+   * Usually not needed unless pointing at a different environment.
+   */
+  host?: string;
+}
+
+/**
+ * Options for building an asset URL.
+ */
+export interface UrlForOptions {
+  /**
+   * Requested width (320, 640, 1024, or 1600).
+   * The resolver produces a WebP variant at this width.
+   * See ALLOWED_WIDTHS for accepted values.
+   */
+  width?: number;
+  /**
+   * Override the configured siteId for this call.
+   */
+  siteId?: string;
+  /**
+   * Override the configured host for this call.
+   */
+  host?: string;
+}
+
+/**
+ * Configure the default site ID and/or host for urlFor() calls.
+ * Call this once at startup to avoid passing siteId on every invocation.
+ *
+ * @example
+ * configure({ siteId: 'my-site-123' });
+ * // Then urlFor('image-key') works without passing siteId.
+ *
+ * @param opts - Configuration options
+ */
+export function configure(opts?: ConfigureOptions): void;
+
+/**
+ * Allowed image widths supported by the resolver.
+ * Use these to build srcset attributes or responsive image logic.
+ * The resolver produces a WebP variant for each width.
+ */
+export const ALLOWED_WIDTHS: number[];
+
+/**
+ * Generate a URL for a managed DiscoverWorthy asset.
+ *
+ * The URL points to the resolver at /img/{siteId}/{assetId}, which:
+ * - Rotates images based on policy (if configured on the dashboard)
+ * - Produces WebP variants at ?w=320|640|1024|1600
+ * - Falls back to replacement_url or source_url if no rotation is set
+ *
+ * Call configure({ siteId }) once at startup, or pass siteId in opts to override.
+ *
+ * @example
+ * // After configure({ siteId: 'my-site' }):
+ * urlFor('hero-key')                        // → https://app.discoverworthy.com/img/my-site/hero-key
+ * urlFor('hero-key', { width: 640 })        // → https://app.discoverworthy.com/img/my-site/hero-key?w=640
+ *
+ * @example
+ * // Or pass siteId directly:
+ * urlFor('hero-key', { siteId: 'other-site', width: 1024 })
+ *
+ * @param assetId - The image key returned by dw_adopt_image or manually assigned
+ * @param opts - Options
+ * @returns The resolver URL
+ * @throws If assetId is missing or siteId is not configured
+ */
+export function urlFor(assetId: string, opts?: UrlForOptions): string;

package/index.js

@@ -0,0 +1,71 @@
+const DEFAULT_HOST = 'https://app.discoverworthy.com';
+let _config = { siteId: null, host: DEFAULT_HOST };
+
+/**
+ * Configure the default site ID and/or host for urlFor() calls.
+ * Call this once at startup to avoid passing siteId on every invocation.
+ *
+ * @example
+ * configure({ siteId: 'my-site-123' });
+ * // Then urlFor('image-key') works without passing siteId.
+ *
+ * @param {Object} opts - Configuration options
+ * @param {string} [opts.siteId] - The site ID for this host/deployment
+ * @param {string} [opts.host] - Base URL for the image resolver (default: https://app.discoverworthy.com)
+ */
+export function configure(opts = {}) {
+  if (opts.siteId !== undefined) _config.siteId = opts.siteId;
+  if (opts.host !== undefined) _config.host = opts.host || DEFAULT_HOST;
+}
+
+/**
+ * Allowed image widths supported by the resolver.
+ * Use these to build srcset attributes or responsive image logic.
+ * The resolver produces a WebP variant for each width.
+ *
+ * @type {number[]}
+ */
+export const ALLOWED_WIDTHS = [320, 640, 1024, 1600];
+
+/**
+ * Generate a URL for a managed DiscoverWorthy asset.
+ *
+ * The URL points to the resolver at /img/{siteId}/{assetId}, which:
+ * - Rotates images based on policy (if configured on the dashboard)
+ * - Produces WebP variants at ?w=320|640|1024|1600
+ * - Falls back to replacement_url or source_url if no rotation is set
+ *
+ * Call configure({ siteId }) once at startup, or pass siteId in opts to override.
+ *
+ * @example
+ * // After configure({ siteId: 'my-site' }):
+ * urlFor('hero-key')                        // → https://app.discoverworthy.com/img/my-site/hero-key
+ * urlFor('hero-key', { width: 640 })        // → https://app.discoverworthy.com/img/my-site/hero-key?w=640
+ *
+ * @example
+ * // Or pass siteId directly:
+ * urlFor('hero-key', { siteId: 'other-site', width: 1024 })
+ *
+ * @param {string} assetId - The image key returned by dw_adopt_image or manually assigned
+ * @param {Object} [opts] - Options
+ * @param {number} [opts.width] - Requested width (320, 640, 1024, or 1600) — resolver produces WebP
+ * @param {string} [opts.siteId] - Override the configured siteId for this call
+ * @param {string} [opts.host] - Override the configured host for this call
+ * @returns {string} The resolver URL
+ * @throws {Error} If assetId is missing or siteId is not configured
+ */
+export function urlFor(assetId, opts = {}) {
+  if (!assetId || typeof assetId !== 'string') {
+    throw new Error('urlFor: assetId (the image key) is required');
+  }
+  const siteId = opts.siteId || _config.siteId;
+  if (!siteId) {
+    throw new Error('urlFor: no siteId — call configure({ siteId }) once at startup, or pass { siteId } here');
+  }
+  const host = (opts.host || _config.host || DEFAULT_HOST).replace(/\/+$/, '');
+  let url = `${host}/img/${encodeURIComponent(siteId)}/${encodeURIComponent(assetId)}`;
+  if (opts.width != null) {
+    url += `?w=${encodeURIComponent(String(opts.width))}`;
+  }
+  return url;
+}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@discoverworthy/assets",
+  "version": "0.1.0",
+  "description": "Framework-agnostic image references for DiscoverWorthy Managed Assets — urlFor() plus optional per-framework components.",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    },
+    "./react": {
+      "types": "./react.d.ts",
+      "default": "./react.js"
+    },
+    "./server": {
+      "types": "./server.d.ts",
+      "default": "./server.js"
+    }
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "react.js",
+    "react.d.ts",
+    "server.js",
+    "server.d.ts",
+    "README.md"
+  ],
+  "keywords": [
+    "discoverworthy",
+    "assets",
+    "images",
+    "managed-assets",
+    "managed-copy",
+    "headless-cms",
+    "collections",
+    "image-optimization",
+    "next",
+    "react",
+    "astro",
+    "svelte",
+    "vue"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/discover-worthy/saas"
+  },
+  "license": "MIT",
+  "author": "DiscoverWorthy",
+  "engines": {
+    "node": ">=18"
+  },
+  "peerDependencies": {
+    "react": ">=17"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "sideEffects": false
+}

package/react.d.ts

@@ -0,0 +1,122 @@
+import { FC, ImgHTMLAttributes, HTMLAttributes, ReactNode, ElementType } from 'react';
+
+/**
+ * Props for the DwImage React component.
+ * Extends standard HTML img attributes but removes src/srcSet (managed by the component).
+ */
+export interface DwImageProps extends Omit<ImgHTMLAttributes<HTMLImageElement>, 'src' | 'srcSet'> {
+  /**
+   * The image key from dw_adopt_image or manually assigned in the dashboard.
+   */
+  asset: string;
+
+  /**
+   * Alt text for accessibility. Required.
+   */
+  alt: string;
+
+  /**
+   * Requested width for the src attribute (320, 640, 1024, or 1600).
+   * The component automatically builds a srcSet with all allowed widths.
+   */
+  width?: number;
+
+  /**
+   * CSS media queries for responsive sizing.
+   * Passed directly to the <img> sizes attribute.
+   */
+  sizes?: string;
+
+  /**
+   * URL to use if the managed asset fails to load.
+   * The src and srcSet are replaced once on error (idempotent).
+   */
+  fallback?: string;
+
+  /**
+   * Whether to use lazy loading (default: true).
+   * Set to false for above-the-fold images.
+   */
+  lazy?: boolean;
+
+  /**
+   * Override the configured siteId for this component.
+   */
+  siteId?: string;
+
+  /**
+   * Override the configured host for this component.
+   */
+  host?: string;
+}
+
+/**
+ * A React component that renders an optimized <img> for a DiscoverWorthy managed asset.
+ *
+ * Automatically builds:
+ * - src: the resolver URL at the optionally specified width
+ * - srcSet: all allowed widths (320w, 640w, 1024w, 1600w) for responsive loading
+ * - loading: 'lazy' by default (can be overridden with the lazy prop or rest attributes)
+ * - decoding: 'async'
+ *
+ * Supports an optional fallback URL: if the image fails to load, the src switches
+ * to the fallback (once per render).
+ *
+ * @example
+ * // Configure once at app startup:
+ * import { configure } from '@discoverworthy/assets';
+ * configure({ siteId: 'my-site' });
+ *
+ * // Then use the component:
+ * <DwImage asset="hero-key" alt="Team in the workshop" />
+ *
+ * @example
+ * // With responsive widths and sizes:
+ * <DwImage
+ *   asset="hero-key"
+ *   alt="Team in the workshop"
+ *   width={1024}
+ *   sizes="(max-width: 768px) 100vw, 50vw"
+ * />
+ *
+ * @example
+ * // With a fallback for when the managed asset isn't ready yet:
+ * <DwImage
+ *   asset="hero-key"
+ *   alt="Team in the workshop"
+ *   fallback="/images/hero.jpg"
+ * />
+ */
+export const DwImage: FC<DwImageProps>;
+
+/**
+ * Props for the DwText managed-copy component.
+ */
+export interface DwTextProps extends HTMLAttributes<HTMLElement> {
+  /**
+   * The copy key from dw_adopt_copy. Rendered as the `data-dw-copy` attribute;
+   * the deploy-finalize pipeline overlays the managed value onto this element.
+   */
+  id: string;
+
+  /**
+   * The element/tag to render (e.g. 'h1', 'p', 'span', 'button'). Defaults to 'span'.
+   */
+  as?: ElementType;
+
+  /**
+   * The default text — kept inline as the SEO / no-JS fallback until a managed
+   * override exists.
+   */
+  children?: ReactNode;
+}
+
+/**
+ * A React component for a DiscoverWorthy managed-copy string — the text sibling
+ * of DwImage. Renders `<as data-dw-copy={id}>{children}</as>`; the managed value
+ * is injected server-side at deploy time, so the default stays in the markup.
+ *
+ * @example
+ * <DwText id="hero_headline" as="h1">Plumbing you can trust</DwText>
+ */
+export const DwText: FC<DwTextProps>;

package/react.js

@@ -0,0 +1,108 @@
+import { createElement } from 'react';
+import { urlFor, ALLOWED_WIDTHS } from './index.js';
+
+/**
+ * A React component that renders an optimized <img> for a DiscoverWorthy managed asset.
+ *
+ * Automatically builds:
+ * - src: the resolver URL at the optionally specified width
+ * - srcSet: all allowed widths (320w, 640w, 1024w, 1600w) for responsive loading
+ * - loading: 'lazy' by default (can be overridden with the lazy prop or rest attributes)
+ * - decoding: 'async'
+ *
+ * Supports an optional fallback URL: if the image fails to load, the src switches
+ * to the fallback (once per render).
+ *
+ * @param {Object} props - Component props
+ * @param {string} props.asset - The image key from dw_adopt_image
+ * @param {string} props.alt - Alt text for accessibility (required)
+ * @param {number} [props.width] - Requested width for the src attribute (320, 640, 1024, 1600)
+ * @param {string} [props.sizes] - CSS media queries for responsive sizing
+ * @param {string} [props.fallback] - URL to use if the image fails to load
+ * @param {boolean} [props.lazy=true] - Whether to use lazy loading (default: true)
+ * @param {string} [props.siteId] - Override the configured siteId
+ * @param {string} [props.host] - Override the configured host
+ * @param {...any} rest - Other <img> attributes (className, style, onLoad, etc.)
+ * @returns {JSX.Element} An <img> element
+ *
+ * @example
+ * // Configure once at app startup:
+ * configure({ siteId: 'my-site' });
+ *
+ * // Then use the component:
+ * <DwImage asset="hero-key" alt="Team in the workshop" />
+ *
+ * @example
+ * // With responsive widths and sizes:
+ * <DwImage
+ *   asset="hero-key"
+ *   alt="Team in the workshop"
+ *   width={1024}
+ *   sizes="(max-width: 768px) 100vw, 50vw"
+ * />
+ *
+ * @example
+ * // With a fallback for when the managed asset isn't ready yet:
+ * <DwImage
+ *   asset="hero-key"
+ *   alt="Team in the workshop"
+ *   fallback="/images/hero.jpg"
+ * />
+ */
+export function DwImage({
+  asset,
+  alt,
+  width,
+  sizes,
+  fallback,
+  lazy = true,
+  siteId,
+  host,
+  ...rest
+}) {
+  const src = urlFor(asset, { width, siteId, host });
+
+  const srcSet = ALLOWED_WIDTHS.map((w) => {
+    const url = urlFor(asset, { width: w, siteId, host });
+    return `${url} ${w}w`;
+  }).join(', ');
+
+  const handleError = (event) => {
+    if (fallback && event.currentTarget.src !== fallback) {
+      event.currentTarget.src = fallback;
+      event.currentTarget.srcSet = '';
+    }
+  };
+
+  return createElement('img', {
+    src,
+    srcSet,
+    alt,
+    sizes,
+    loading: lazy ? 'lazy' : 'eager',
+    decoding: 'async',
+    onError: fallback ? handleError : undefined,
+    ...rest,
+  });
+}
+
+/**
+ * A React component for a DiscoverWorthy managed-copy string (the text sibling
+ * of DwImage). Renders an element carrying `data-dw-copy="<id>"` with the given
+ * children as the default/fallback text. The deploy-finalize pipeline overlays
+ * the managed value onto this element server-side, so the default stays in the
+ * markup for SEO and no-JS — there's no client-side fetch.
+ *
+ * @param {Object} props
+ * @param {string} props.id - The copy key from dw_adopt_copy (goes in data-dw-copy)
+ * @param {string} [props.as='span'] - The element/tag to render (e.g. 'h1', 'p', 'button')
+ * @param {React.ReactNode} props.children - The default text, kept inline as the fallback
+ * @param {...any} rest - Other attributes (className, style, etc.)
+ * @returns {JSX.Element}
+ *
+ * @example
+ * <DwText id="hero_headline" as="h1">Plumbing you can trust</DwText>
+ */
+export function DwText({ id, as = 'span', children, ...rest }) {
+  return createElement(as, { 'data-dw-copy': id, ...rest }, children);
+}

package/server.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Server-side helpers for DiscoverWorthy Managed Collections.
+ * Build-time only — uses the workspace token (a secret). Never import in client code.
+ */
+
+export interface CollectionFetchOptions {
+  /** Workspace token. Defaults to process.env.DISCOVERWORTHY_DEPLOY_TOKEN. */
+  token?: string;
+  /** Override the API host. Defaults to https://app.discoverworthy.com. */
+  host?: string;
+}
+
+export interface CollectionField {
+  name: string;
+  type: 'text' | 'textarea' | 'number' | 'boolean' | 'date' | 'url' | 'image';
+  label: string;
+  required?: boolean;
+}
+
+export interface CollectionItem {
+  _id: string;
+  _order: number;
+  [field: string]: unknown;
+}
+
+export interface FetchCollectionResult {
+  collection: { slug: string; label: string; fields: CollectionField[] };
+  items: CollectionItem[];
+}
+
+export interface ListCollectionsResult {
+  collections: Array<{
+    slug: string;
+    label: string;
+    description: string | null;
+    fields: CollectionField[];
+  }>;
+}
+
+/**
+ * Fetch a collection's published items at build time.
+ * @param slug The collection slug (from dw_define_collection).
+ */
+export function fetchCollection(slug: string, opts?: CollectionFetchOptions): Promise<FetchCollectionResult>;
+
+/** List every collection (slug + label + field schema) for the workspace. */
+export function listCollections(opts?: CollectionFetchOptions): Promise<ListCollectionsResult>;

package/server.js

@@ -0,0 +1,63 @@
+/**
+ * Server-side helpers for DiscoverWorthy Managed Collections (the headless-CMS
+ * content API). Build-time only — these use the workspace token, which is a
+ * SECRET. Never import this from client/browser code.
+ */
+
+const DEFAULT_HOST = 'https://app.discoverworthy.com';
+
+function resolveToken(opts) {
+  if (opts && opts.token) return opts.token;
+  if (typeof process !== 'undefined' && process.env && process.env.DISCOVERWORTHY_DEPLOY_TOKEN) {
+    return process.env.DISCOVERWORTHY_DEPLOY_TOKEN;
+  }
+  return null;
+}
+
+function resolveHost(opts) {
+  return ((opts && opts.host) || DEFAULT_HOST).replace(/\/+$/, '');
+}
+
+/**
+ * Fetch a collection's published items at build time.
+ * @param {string} slug - The collection slug (from dw_define_collection).
+ * @param {{ token?: string, host?: string }} [opts] - token defaults to
+ *   process.env.DISCOVERWORTHY_DEPLOY_TOKEN.
+ * @returns {Promise<{ collection: { slug: string, label: string, fields: any[] }, items: Array<Record<string, any>> }>}
+ */
+export async function fetchCollection(slug, opts = {}) {
+  if (!slug || typeof slug !== 'string') {
+    throw new Error('fetchCollection: slug is required');
+  }
+  const token = resolveToken(opts);
+  if (!token) {
+    throw new Error('fetchCollection: no workspace token — pass { token } or set DISCOVERWORTHY_DEPLOY_TOKEN (server-side only)');
+  }
+  const host = resolveHost(opts);
+  const url = `${host}/api/v1/hosting/content/collections/${encodeURIComponent(slug)}`;
+  const res = await fetch(url, { headers: { Authorization: `Bearer ${token}` } });
+  if (!res.ok) {
+    throw new Error(`fetchCollection(${slug}) failed: ${res.status}`);
+  }
+  return res.json();
+}
+
+/**
+ * List every collection (slug + label + field schema) for the workspace.
+ * @param {{ token?: string, host?: string }} [opts]
+ * @returns {Promise<{ collections: Array<{ slug: string, label: string, description: string | null, fields: any[] }> }>}
+ */
+export async function listCollections(opts = {}) {
+  const token = resolveToken(opts);
+  if (!token) {
+    throw new Error('listCollections: no workspace token — pass { token } or set DISCOVERWORTHY_DEPLOY_TOKEN (server-side only)');
+  }
+  const host = resolveHost(opts);
+  const res = await fetch(`${host}/api/v1/hosting/content/collections`, {
+    headers: { Authorization: `Bearer ${token}` },
+  });
+  if (!res.ok) {
+    throw new Error(`listCollections failed: ${res.status}`);
+  }
+  return res.json();
+}