@content-hq/client

Client helpers for published Lowerfold content.

import { createContentClient } from "@content-hq/client";

export const content = createContentClient({
  endpoint: process.env.CONTENT_HQ_API_URL!,
  siteKey: "discover-beaujolais",
  token: process.env.CONTENT_HQ_READ_TOKEN,
});

const articles = await content.listArticles({ locale: "en" });

Native client previews

The HTTP client can load a private draft with the same article shape used by published pages. A media route can therefore render its normal article template when the final URL contains a preview query parameter.

const preview = await content.getClientPreview(searchParams.preview);

if (preview.article.path !== pathname) {
  notFound();
}

return <ArticlePage article={preview.article} />;

Approval and change requests use the same token:

await content.approveClientPreview(token);
await content.requestClientPreviewChanges(token, message);

Sponsored previews also expose the order context needed during review:

console.log(preview.orderReference);
console.log(preview.requestedLinks);

requestedLinks only carries the ordered anchor and destination URL. Consumer sites own the review UI, translations, and article-specific rendering.

Preview pages must be rendered dynamically, must not be cached, and must send robots: { index: false, follow: false }. Never put the token in analytics, logs, canonical URLs, Open Graph URLs, or outbound referrers.

@content-hq/client does not depend on the Lowerfold monorepo at runtime. Consumer apps should install it from npm so they do not need SSH access to the private Lowerfold repository during Vercel builds.

When CONTENT_HQ_READ_TOKEN is set on the admin app, pass the same token to the client. If the admin token is empty, read endpoints stay open for local development.

Direct database client

Consumer sites that render on the server can also read from Neon directly through the stable published_articles_v1 SQL view. The package does not install a database driver; pass a query function from the driver already used by the site.

import { createDatabaseContentClient } from "@content-hq/client";
import { Pool } from "pg";

const pool = new Pool({
  connectionString: process.env.CONTENT_HQ_DATABASE_URL,
});

export const content = createDatabaseContentClient({
  query: (text, values) => pool.query(text, values),
  siteKey: "discover-beaujolais",
});

const articles = await content.listArticles({ locale: "en" });

Use a read-only database user for consumer sites. Breaking SQL contract changes must create a new view, for example published_articles_v2, instead of changing published_articles_v1 in place.

Next.js revalidation

Next.js App Router sites can expose a shared Lowerfold revalidation endpoint:

// app/api/revalidate/route.ts
import { createContentHqRevalidateHandler } from "@content-hq/client/next";

export const POST = createContentHqRevalidateHandler({
  siteKey: "discover-beaujolais",
});

The helper reads CONTENT_HQ_REVALIDATE_SECRET by default and validates the x-content-hq-revalidate-secret header sent by Lowerfold.

Release checklist

Consumer sites should depend on a pinned npm version, not on a local file: dependency or a private git URL. When the client contract changes:

1. Update packages/client/package.json version.
2. Run pnpm --filter @content-hq/client build.
3. Run cd packages/client && npm publish --access public.
4. Commit the client sources, dist/, and package metadata changes.
5. Push the Lowerfold branch.
6. Repin each consumer site to the new npm version and run pnpm install.

Example:

pnpm --filter @content-hq/client build
cd packages/client && npm publish --access public
git add packages/client pnpm-lock.yaml
git commit -m "Publish client v0.2.1"
git push origin main

Consumer dependency format:

"@content-hq/client": "0.2.1"

The package is intentionally public and unlicensed. It contains only typed client helpers and no Lowerfold secrets. Access control stays on the consumer site through read-only database URLs or API tokens.