@eyeballs/cms 0.1.0

package/README.md

@@ -0,0 +1,74 @@
+# @eyeballs/cms
+
+Shared Eyeballs CMS API types, client helpers, Next.js revalidation helpers, and API docs for
+starter sites and custom website projects.
+
+## Install In A Website Project
+
+```bash
+npm install @eyeballs/cms
+```
+
+Vercel installs the package during build like any other npm dependency. Keep site-specific secrets
+in the Vercel project environment:
+
+```txt
+EYEBALLS_CMS_URL=https://app.example.com
+EYEBALLS_CMS_TOKEN=eyb_...
+REVALIDATE_SECRET=eyb_reval_...
+```
+
+## Basic Usage
+
+```ts
+import { createEyeballsCms, type CmsVideo } from '@eyeballs/cms';
+
+const cms = createEyeballsCms({
+	baseUrl: process.env.EYEBALLS_CMS_URL!,
+	token: process.env.EYEBALLS_CMS_TOKEN!,
+});
+
+const videos: CmsVideo[] = await cms.videos.list();
+```
+
+## Next.js Revalidation Route
+
+```ts
+// app/api/revalidate/route.ts
+import { createEyeballsRevalidateHandler } from '@eyeballs/cms/next';
+
+export const POST = createEyeballsRevalidateHandler({
+	secret: process.env.REVALIDATE_SECRET,
+});
+```
+
+## Agent Instructions For Starter Sites
+
+Add this to the starter site's `AGENTS.md`:
+
+```md
+Before using the Eyeballs CMS API, read:
+node_modules/@eyeballs/cms/docs/content-api.md
+```
+
+## Publishing
+
+Build locally:
+
+```bash
+npm run cms:build
+```
+
+Preview the npm package contents:
+
+```bash
+npm run cms:pack:dry
+```
+
+Publish after bumping `packages/cms/package.json` version:
+
+```bash
+npm run cms:publish
+```
+
+This package contains no account tokens or site-specific config.

package/dist/client.d.ts

@@ -0,0 +1,33 @@
+import type { CmsContentEntry, CmsRosterProfile, CmsVideo } from './types.js';
+export type EyeballsCmsClientOptions = {
+    baseUrl: string;
+    token: string;
+    fetch?: typeof fetch;
+    defaultRequestInit?: RequestInit;
+};
+export declare class EyeballsCmsError extends Error {
+    status: number;
+    payload: unknown;
+    constructor(message: string, status: number, payload: unknown);
+}
+export declare function createEyeballsCms(options: EyeballsCmsClientOptions): {
+    request: <T>(path: string, init?: RequestInit) => Promise<T>;
+    videos: {
+        list<Fields extends Record<string, unknown> = Record<string, unknown>>(): Promise<CmsVideo<Fields>[]>;
+        get<Fields extends Record<string, unknown> = Record<string, unknown>>(slug: string): Promise<CmsVideo<Fields>>;
+    };
+    roster: {
+        list<Fields extends Record<string, unknown> = Record<string, unknown>>(): Promise<CmsRosterProfile<Fields>[]>;
+        get<Fields extends Record<string, unknown> = Record<string, unknown>>(slug: string): Promise<CmsRosterProfile<Fields>>;
+    };
+    content: {
+        list<Fields extends Record<string, unknown> = Record<string, unknown>>(options?: {
+            type?: string;
+            slug?: string;
+        }): Promise<CmsContentEntry<Fields>[]>;
+        getBySlug<Fields extends Record<string, unknown> = Record<string, unknown>>(slug: string): Promise<CmsContentEntry<Fields>>;
+        getByTypeAndSlug<Fields extends Record<string, unknown> = Record<string, unknown>>(type: string, slug: string): Promise<CmsContentEntry<Fields>>;
+    };
+};
+export type EyeballsCmsClient = ReturnType<typeof createEyeballsCms>;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE9E,MAAM,MAAM,wBAAwB,GAAG;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IACrB,kBAAkB,CAAC,EAAE,WAAW,CAAC;CACjC,CAAC;AAEF,qBAAa,gBAAiB,SAAQ,KAAK;IAC1C,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;gBAEL,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO;CAM7D;AAsBD,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,wBAAwB;cAO3C,CAAC,QAAQ,MAAM,SAAQ,WAAW,KAAQ,OAAO,CAAC,CAAC,CAAC;;aA2B9D,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;YAIvC,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,kCACzC,MAAM;;;aASF,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;YAMvC,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,kCACzC,MAAM;;;aASF,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,sCAAsC;YACtF,IAAI,CAAC,EAAE,MAAM,CAAC;YACd,IAAI,CAAC,EAAE,MAAM,CAAC;SACd;kBASe,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,kCAC/C,MAAM;yBAQZ,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,kCAC/B,MAAM,QAAQ,MAAM;;EAQ9B;AAED,MAAM,MAAM,iBAAiB,GAAG,UAAU,CAAC,OAAO,iBAAiB,CAAC,CAAC"}

package/dist/client.js

@@ -0,0 +1,96 @@
+export class EyeballsCmsError extends Error {
+    status;
+    payload;
+    constructor(message, status, payload) {
+        super(message);
+        this.name = 'EyeballsCmsError';
+        this.status = status;
+        this.payload = payload;
+    }
+}
+function normalizeBaseUrl(baseUrl) {
+    const trimmed = baseUrl.trim().replace(/\/+$/, '');
+    if (!trimmed)
+        throw new Error('Eyeballs CMS baseUrl is required');
+    return trimmed;
+}
+function joinPath(baseUrl, path) {
+    return `${baseUrl}/${path.replace(/^\/+/, '')}`;
+}
+function withQuery(path, params) {
+    const query = new URLSearchParams();
+    for (const [key, value] of Object.entries(params)) {
+        const trimmed = value?.trim();
+        if (trimmed)
+            query.set(key, trimmed);
+    }
+    const queryString = query.toString();
+    return queryString ? `${path}?${queryString}` : path;
+}
+export function createEyeballsCms(options) {
+    const baseUrl = normalizeBaseUrl(options.baseUrl);
+    const token = options.token.trim();
+    if (!token)
+        throw new Error('Eyeballs CMS token is required');
+    const requestFetch = options.fetch ?? fetch;
+    async function request(path, init = {}) {
+        const headers = new Headers(options.defaultRequestInit?.headers);
+        new Headers(init.headers).forEach((value, key) => headers.set(key, value));
+        headers.set('authorization', `Bearer ${token}`);
+        const res = await requestFetch(joinPath(baseUrl, path), {
+            ...options.defaultRequestInit,
+            ...init,
+            headers,
+        });
+        const text = await res.text();
+        const payload = text ? JSON.parse(text) : null;
+        if (!res.ok) {
+            const message = payload && typeof payload === 'object' && 'error' in payload
+                ? String(payload.error)
+                : `Eyeballs CMS request failed: ${res.status}`;
+            throw new EyeballsCmsError(message, res.status, payload);
+        }
+        return payload;
+    }
+    return {
+        request,
+        videos: {
+            async list() {
+                const payload = await request('/api/cms/videos');
+                return payload.videos;
+            },
+            async get(slug) {
+                const payload = await request(`/api/cms/videos/${encodeURIComponent(slug)}`);
+                return payload.video;
+            },
+        },
+        roster: {
+            async list() {
+                const payload = await request('/api/cms/roster');
+                return payload.roster;
+            },
+            async get(slug) {
+                const payload = await request(`/api/cms/roster/${encodeURIComponent(slug)}`);
+                return payload.roster;
+            },
+        },
+        content: {
+            async list(options) {
+                const payload = await request(withQuery('/api/cms/content', {
+                    type: options?.type,
+                    slug: options?.slug,
+                }));
+                return payload.content;
+            },
+            async getBySlug(slug) {
+                const payload = await request(`/api/cms/content/${encodeURIComponent(slug)}`);
+                return payload.content;
+            },
+            async getByTypeAndSlug(type, slug) {
+                const payload = await request(withQuery('/api/cms/content', { type, slug }));
+                return payload.content;
+            },
+        },
+    };
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AASA,MAAM,OAAO,gBAAiB,SAAQ,KAAK;IAC1C,MAAM,CAAS;IACf,OAAO,CAAU;IAEjB,YAAY,OAAe,EAAE,MAAc,EAAE,OAAgB;QAC5D,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;QAC/B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACxB,CAAC;CACD;AAED,SAAS,gBAAgB,CAAC,OAAe;IACxC,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IACnD,IAAI,CAAC,OAAO;QAAE,MAAM,IAAI,KAAK,CAAC,kCAAkC,CAAC,CAAC;IAClE,OAAO,OAAO,CAAC;AAChB,CAAC;AAED,SAAS,QAAQ,CAAC,OAAe,EAAE,IAAY;IAC9C,OAAO,GAAG,OAAO,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,EAAE,CAAC;AACjD,CAAC;AAED,SAAS,SAAS,CAAC,IAAY,EAAE,MAAiD;IACjF,MAAM,KAAK,GAAG,IAAI,eAAe,EAAE,CAAC;IACpC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QACnD,MAAM,OAAO,GAAG,KAAK,EAAE,IAAI,EAAE,CAAC;QAC9B,IAAI,OAAO;YAAE,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;IACtC,CAAC;IACD,MAAM,WAAW,GAAG,KAAK,CAAC,QAAQ,EAAE,CAAC;IACrC,OAAO,WAAW,CAAC,CAAC,CAAC,GAAG,IAAI,IAAI,WAAW,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;AACtD,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,OAAiC;IAClE,MAAM,OAAO,GAAG,gBAAgB,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IAClD,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;IACnC,IAAI,CAAC,KAAK;QAAE,MAAM,IAAI,KAAK,CAAC,gCAAgC,CAAC,CAAC;IAE9D,MAAM,YAAY,GAAG,OAAO,CAAC,KAAK,IAAI,KAAK,CAAC;IAE5C,KAAK,UAAU,OAAO,CAAI,IAAY,EAAE,OAAoB,EAAE;QAC7D,MAAM,OAAO,GAAG,IAAI,OAAO,CAAC,OAAO,CAAC,kBAAkB,EAAE,OAAO,CAAC,CAAC;QACjE,IAAI,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,GAAG,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC,CAAC;QAC3E,OAAO,CAAC,GAAG,CAAC,eAAe,EAAE,UAAU,KAAK,EAAE,CAAC,CAAC;QAEhD,MAAM,GAAG,GAAG,MAAM,YAAY,CAAC,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC,EAAE;YACvD,GAAG,OAAO,CAAC,kBAAkB;YAC7B,GAAG,IAAI;YACP,OAAO;SACP,CAAC,CAAC;QACH,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC;QAC9B,MAAM,OAAO,GAAG,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;QAE/C,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;YACb,MAAM,OAAO,GACZ,OAAO,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,IAAI,OAAO;gBAC3D,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC;gBACvB,CAAC,CAAC,gCAAgC,GAAG,CAAC,MAAM,EAAE,CAAC;YACjD,MAAM,IAAI,gBAAgB,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAC1D,CAAC;QAED,OAAO,OAAY,CAAC;IACrB,CAAC;IAED,OAAO;QACN,OAAO;QACP,MAAM,EAAE;YACP,KAAK,CAAC,IAAI;gBACT,MAAM,OAAO,GAAG,MAAM,OAAO,CAAiC,iBAAiB,CAAC,CAAC;gBACjF,OAAO,OAAO,CAAC,MAAM,CAAC;YACvB,CAAC;YACD,KAAK,CAAC,GAAG,CACR,IAAY;gBAEZ,MAAM,OAAO,GAAG,MAAM,OAAO,CAC5B,mBAAmB,kBAAkB,CAAC,IAAI,CAAC,EAAE,CAC7C,CAAC;gBACF,OAAO,OAAO,CAAC,KAAK,CAAC;YACtB,CAAC;SACD;QACD,MAAM,EAAE;YACP,KAAK,CAAC,IAAI;gBACT,MAAM,OAAO,GAAG,MAAM,OAAO,CAC5B,iBAAiB,CACjB,CAAC;gBACF,OAAO,OAAO,CAAC,MAAM,CAAC;YACvB,CAAC;YACD,KAAK,CAAC,GAAG,CACR,IAAY;gBAEZ,MAAM,OAAO,GAAG,MAAM,OAAO,CAC5B,mBAAmB,kBAAkB,CAAC,IAAI,CAAC,EAAE,CAC7C,CAAC;gBACF,OAAO,OAAO,CAAC,MAAM,CAAC;YACvB,CAAC;SACD;QACD,OAAO,EAAE;YACR,KAAK,CAAC,IAAI,CAAmE,OAG5E;gBACA,MAAM,OAAO,GAAG,MAAM,OAAO,CAC5B,SAAS,CAAC,kBAAkB,EAAE;oBAC7B,IAAI,EAAE,OAAO,EAAE,IAAI;oBACnB,IAAI,EAAE,OAAO,EAAE,IAAI;iBACnB,CAAC,CACF,CAAC;gBACF,OAAO,OAAO,CAAC,OAAO,CAAC;YACxB,CAAC;YACD,KAAK,CAAC,SAAS,CACd,IAAY;gBAEZ,MAAM,OAAO,GAAG,MAAM,OAAO,CAC5B,oBAAoB,kBAAkB,CAAC,IAAI,CAAC,EAAE,CAC9C,CAAC;gBACF,OAAO,OAAO,CAAC,OAAO,CAAC;YACxB,CAAC;YACD,KAAK,CAAC,gBAAgB,CAEpB,IAAY,EAAE,IAAY;gBAC3B,MAAM,OAAO,GAAG,MAAM,OAAO,CAC5B,SAAS,CAAC,kBAAkB,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAC7C,CAAC;gBACF,OAAO,OAAO,CAAC,OAAO,CAAC;YACxB,CAAC;SACD;KACD,CAAC;AACH,CAAC"}

package/dist/helpers.d.ts

@@ -0,0 +1,9 @@
+import type { CmsContentEntry, CmsRosterProfile, CmsVideo } from './types.js';
+export declare function trimSlashes(value: string): string;
+export declare function getContentEntryPath(entry: CmsContentEntry): string | null;
+export declare function getContentTypePath(typeSlug: string): string | null;
+export declare function getRosterProfilePath(profile: Pick<CmsRosterProfile, 'slug' | 'type'>, pathPrefix?: string | null): string | null;
+export declare function getMuxPosterUrl(video: CmsVideo, options?: {
+    time?: number;
+}): string | null;
+//# sourceMappingURL=helpers.d.ts.map

package/dist/helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../src/helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE9E,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,UAExC;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,eAAe,iBAWzD;AAED,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,iBAGlD;AAED,wBAAgB,oBAAoB,CACnC,OAAO,EAAE,IAAI,CAAC,gBAAgB,EAAE,MAAM,GAAG,MAAM,CAAC,EAChD,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,iBAM1B;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,GAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAA;CAAO,iBAO/E"}

package/dist/helpers.js

@@ -0,0 +1,36 @@
+export function trimSlashes(value) {
+    return value.trim().replace(/^\/+|\/+$/g, '');
+}
+export function getContentEntryPath(entry) {
+    if (entry.type?.kind === 'pages') {
+        const websitePath = entry.website_path?.trim();
+        if (!websitePath || websitePath === '/')
+            return '/';
+        return websitePath.startsWith('/') ? websitePath : `/${websitePath}`;
+    }
+    const typeSlug = entry.type?.slug ? trimSlashes(entry.type.slug) : '';
+    const entrySlug = trimSlashes(entry.slug);
+    if (!typeSlug || !entrySlug)
+        return null;
+    return `/${typeSlug}/${entrySlug}`;
+}
+export function getContentTypePath(typeSlug) {
+    const normalized = trimSlashes(typeSlug);
+    return normalized ? `/${normalized}` : null;
+}
+export function getRosterProfilePath(profile, pathPrefix) {
+    const prefix = trimSlashes(pathPrefix || profile.type?.slug || '');
+    const slug = trimSlashes(profile.slug);
+    if (!prefix || !slug)
+        return null;
+    return `/${prefix}/${slug}`;
+}
+export function getMuxPosterUrl(video, options = {}) {
+    const playbackId = video.media.mux_playback_id;
+    if (!playbackId)
+        return video.media.poster_url;
+    const time = options.time ?? video.media.thumbnail_time;
+    const query = typeof time === 'number' && Number.isFinite(time) ? `?time=${time}` : '';
+    return `https://image.mux.com/${playbackId}/thumbnail.jpg${query}`;
+}
+//# sourceMappingURL=helpers.js.map

package/dist/helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.js","sourceRoot":"","sources":["../src/helpers.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,WAAW,CAAC,KAAa;IACxC,OAAO,KAAK,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,YAAY,EAAE,EAAE,CAAC,CAAC;AAC/C,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,KAAsB;IACzD,IAAI,KAAK,CAAC,IAAI,EAAE,IAAI,KAAK,OAAO,EAAE,CAAC;QAClC,MAAM,WAAW,GAAG,KAAK,CAAC,YAAY,EAAE,IAAI,EAAE,CAAC;QAC/C,IAAI,CAAC,WAAW,IAAI,WAAW,KAAK,GAAG;YAAE,OAAO,GAAG,CAAC;QACpD,OAAO,WAAW,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,IAAI,WAAW,EAAE,CAAC;IACtE,CAAC;IAED,MAAM,QAAQ,GAAG,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,WAAW,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IACtE,MAAM,SAAS,GAAG,WAAW,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC1C,IAAI,CAAC,QAAQ,IAAI,CAAC,SAAS;QAAE,OAAO,IAAI,CAAC;IACzC,OAAO,IAAI,QAAQ,IAAI,SAAS,EAAE,CAAC;AACpC,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,QAAgB;IAClD,MAAM,UAAU,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAC;IACzC,OAAO,UAAU,CAAC,CAAC,CAAC,IAAI,UAAU,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;AAC7C,CAAC;AAED,MAAM,UAAU,oBAAoB,CACnC,OAAgD,EAChD,UAA0B;IAE1B,MAAM,MAAM,GAAG,WAAW,CAAC,UAAU,IAAI,OAAO,CAAC,IAAI,EAAE,IAAI,IAAI,EAAE,CAAC,CAAC;IACnE,MAAM,IAAI,GAAG,WAAW,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACvC,IAAI,CAAC,MAAM,IAAI,CAAC,IAAI;QAAE,OAAO,IAAI,CAAC;IAClC,OAAO,IAAI,MAAM,IAAI,IAAI,EAAE,CAAC;AAC7B,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,KAAe,EAAE,UAA6B,EAAE;IAC/E,MAAM,UAAU,GAAG,KAAK,CAAC,KAAK,CAAC,eAAe,CAAC;IAC/C,IAAI,CAAC,UAAU;QAAE,OAAO,KAAK,CAAC,KAAK,CAAC,UAAU,CAAC;IAE/C,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,KAAK,CAAC,KAAK,CAAC,cAAc,CAAC;IACxD,MAAM,KAAK,GAAG,OAAO,IAAI,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IACvF,OAAO,yBAAyB,UAAU,iBAAiB,KAAK,EAAE,CAAC;AACpE,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from './client.js';
+export * from './helpers.js';
+export * from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,4 @@
+export * from './client.js';
+export * from './helpers.js';
+export * from './types.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC"}

package/dist/next.d.ts

@@ -0,0 +1,9 @@
+export type EyeballsRevalidationPayload = {
+    tags?: string[];
+    paths?: string[];
+};
+export type EyeballsRevalidateHandlerOptions = {
+    secret: string | null | undefined;
+};
+export declare function createEyeballsRevalidateHandler(options: EyeballsRevalidateHandlerOptions): (req: Request) => Promise<Response>;
+//# sourceMappingURL=next.d.ts.map

package/dist/next.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"next.d.ts","sourceRoot":"","sources":["../src/next.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,2BAA2B,GAAG;IACzC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,gCAAgC,GAAG;IAC9C,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;CAClC,CAAC;AA6BF,wBAAgB,+BAA+B,CAAC,OAAO,EAAE,gCAAgC,IAG7D,KAAK,OAAO,uBA2BvC"}

package/dist/next.js

@@ -0,0 +1,54 @@
+import { revalidatePath, revalidateTag } from 'next/cache';
+function json(payload, status = 200) {
+    return new Response(JSON.stringify(payload), {
+        status,
+        headers: { 'content-type': 'application/json' },
+    });
+}
+function getHeader(req, name) {
+    return req.headers.get(name)?.trim() || '';
+}
+function normalizePath(path) {
+    if (typeof path !== 'string')
+        return null;
+    const trimmed = path.trim();
+    return trimmed.startsWith('/') ? trimmed : null;
+}
+function normalizeTag(tag) {
+    if (typeof tag !== 'string')
+        return null;
+    const trimmed = tag.trim();
+    return trimmed || null;
+}
+function isString(value) {
+    return typeof value === 'string';
+}
+export function createEyeballsRevalidateHandler(options) {
+    const expectedSecret = options.secret?.trim() || '';
+    return async function POST(req) {
+        if (!expectedSecret) {
+            return json({ ok: false, error: 'Missing revalidation secret' }, 500);
+        }
+        const providedSecret = getHeader(req, 'x-revalidate-secret');
+        if (providedSecret !== expectedSecret) {
+            return json({ ok: false, error: 'Unauthorized' }, 401);
+        }
+        let body = {};
+        try {
+            body = (await req.json());
+        }
+        catch {
+            return json({ ok: false, error: 'Invalid JSON body' }, 400);
+        }
+        const tags = Array.isArray(body.tags) ? body.tags.map(normalizeTag).filter(isString) : [];
+        const paths = Array.isArray(body.paths)
+            ? body.paths.map(normalizePath).filter(isString)
+            : [];
+        for (const tag of tags)
+            revalidateTag(tag, 'max');
+        for (const path of paths)
+            revalidatePath(path, 'page');
+        return json({ ok: true, tags, paths });
+    };
+}
+//# sourceMappingURL=next.js.map

package/dist/next.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"next.js","sourceRoot":"","sources":["../src/next.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,138 @@
+export type CreditEntry = {
+    id: string;
+    role: string;
+    name: string;
+    url: string | null;
+};
+export type ContentFieldType = 'text' | 'textarea' | 'richtext' | 'boolean' | 'image' | 'date' | 'library_work' | 'content_blocks' | 'array';
+export type SimpleContentFieldType = Exclude<ContentFieldType, 'library_work' | 'content_blocks' | 'array'>;
+export type ArrayItemContentFieldType = SimpleContentFieldType | 'library_work';
+export type ContentField = {
+    id: string;
+    type: ContentFieldType;
+    label: string;
+    multiple?: boolean;
+    required?: boolean;
+    itemFields?: ContentField[];
+    itemLabelFieldId?: string;
+    itemSecondaryLabelFieldId?: string;
+};
+export type TextBlock = {
+    id: string;
+    type: 'text';
+    content: string;
+};
+export type ImageBlock = {
+    id: string;
+    type: 'image';
+    src: string;
+    path: string;
+    alt: string;
+    showCaption: boolean;
+};
+export type ButtonBlock = {
+    id: string;
+    type: 'button';
+    text: string;
+    url: string;
+};
+export type ContentBlock = TextBlock | ImageBlock | ButtonBlock;
+export type ContentBlocks = ContentBlock[];
+export type CmsVideoMedia = {
+    mux_playback_id: string | null;
+    poster_url: string | null;
+    thumbnail_time: number | null;
+    mux_blur_placeholder: string | null;
+    mux_blur_aspect_ratio: number | null;
+    loop_start_time: number | null;
+    loop_end_time: number | null;
+    loop_mux_playback_id: string | null;
+    loop_mux_asset_status: string | null;
+    aspect_ratio: number | null;
+    custom_aspect_ratio: number | null;
+    duration_seconds: number | null;
+};
+export type CmsVideoRosterAssignment = {
+    id: string;
+    name: string;
+    url: string | null;
+    roster: {
+        id: string;
+        name: string;
+        slug: string;
+        image_url: string | null;
+        description: string | null;
+        links: unknown;
+    } | null;
+};
+export type CmsVideoRosterGroup = {
+    id: string;
+    name: string;
+    slug: string;
+    assignments: CmsVideoRosterAssignment[];
+};
+export type CmsVideo<Fields extends Record<string, unknown> = Record<string, unknown>> = {
+    id: string;
+    title: string;
+    slug: string;
+    description: string | null;
+    client: string | null;
+    credits: CreditEntry[];
+    tags: string[];
+    roster: CmsVideoRosterGroup[];
+    fields: Fields;
+    field_schema: ContentField[];
+    published_at: string | null;
+    release_date: string | null;
+    media: CmsVideoMedia;
+    created_at: string;
+};
+export type CmsRosterProfile<Fields extends Record<string, unknown> = Record<string, unknown>> = {
+    id: string;
+    name: string;
+    slug: string;
+    image_url: string | null;
+    description: string | null;
+    links: unknown;
+    fields: Fields;
+    status: string;
+    order_index: number;
+    created_at: string;
+    updated_at: string;
+    type: {
+        id: string;
+        name: string;
+        singular_name: string;
+        slug: string;
+        field_schema: ContentField[];
+    } | null;
+    featured_work: CmsVideo[];
+};
+export type CmsContentEntry<Fields extends Record<string, unknown> = Record<string, unknown>> = {
+    id: string;
+    name: string;
+    slug: string;
+    status: 'draft' | 'published' | 'archived';
+    entry_date: string | null;
+    website_path: string | null;
+    meta: {
+        title: string | null;
+        description: string | null;
+        image_url: string | null;
+    };
+    fields: Fields;
+    field_schema: ContentField[];
+    type: {
+        id: string;
+        name: string;
+        slug: string;
+        kind: 'pages' | 'collection';
+    } | null;
+    published_at: string | null;
+    created_at: string;
+    updated_at: string;
+};
+export type EyeballsCmsErrorPayload = {
+    error: string;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/docs/content-api.md

@@ -0,0 +1,530 @@
+# Content API Reference
+
+This is the canonical reference for the Eyeballs CMS/content API used by starter sites,
+website projects, external integrations, and coding agents. Update this file whenever the
+public CMS API response shape, routing behavior, custom field behavior, or website settings
+change.
+
+The API is implemented in the Eyeballs app by `src/app/api/cms/*`. Response shaping lives mostly
+in `src/lib/cmsData.ts`. Field/schema normalization lives in `src/lib/content.ts`. Website preview
+and revalidation URL helpers live in `src/lib/websiteProjectUrl.ts` and
+`src/lib/publicRevalidation.ts`.
+
+## Quick Start
+
+Use Dashboard > Settings > API settings to create a CMS API token. Starter sites normally store:
+
+```bash
+EYEBALLS_CMS_URL=https://app.example.com
+EYEBALLS_CMS_TOKEN=eyb_...
+```
+
+Starter sites should use the shared package when available:
+
+```ts
+import { createEyeballsCms } from '@eyeballs/cms';
+
+const cms = createEyeballsCms({
+	baseUrl: process.env.EYEBALLS_CMS_URL!,
+	token: process.env.EYEBALLS_CMS_TOKEN!,
+});
+```
+
+Every request must include either a bearer token or an `x-api-key` header:
+
+```ts
+async function cmsFetch(path: string) {
+	const res = await fetch(`${process.env.EYEBALLS_CMS_URL}${path}`, {
+		headers: {
+			authorization: `Bearer ${process.env.EYEBALLS_CMS_TOKEN}`,
+		},
+		next: { tags: ['eyeballs-cms'] },
+	});
+
+	if (!res.ok) throw new Error(`CMS request failed: ${res.status}`);
+	return res.json();
+}
+```
+
+## Authentication
+
+Tokens are generated from Dashboard > Settings > API settings and stored hashed in `api_tokens`.
+The raw token is only shown once. Tokens can be sent as:
+
+```http
+Authorization: Bearer eyb_...
+```
+
+or:
+
+```http
+x-api-key: eyb_...
+```
+
+Missing, revoked, or unknown tokens return:
+
+```json
+{ "error": "Missing API token" }
+```
+
+or:
+
+```json
+{ "error": "Invalid API token" }
+```
+
+with HTTP `401`.
+
+## Endpoints
+
+| Endpoint                      | Response                           | Notes                                                                                           |
+| ----------------------------- | ---------------------------------- | ----------------------------------------------------------------------------------------------- |
+| `GET /api/cms/videos`         | `{ "videos": CmsVideo[] }`         | Published library work, newest first.                                                           |
+| `GET /api/cms/videos/{slug}`  | `{ "video": CmsVideo }`            | Published library work by slug.                                                                 |
+| `GET /api/cms/roster`         | `{ "roster": CmsRosterProfile[] }` | Published roster profiles. Empty when the account plan has no creatives access.                 |
+| `GET /api/cms/roster/{slug}`  | `{ "roster": CmsRosterProfile }`   | Published roster profile by slug.                                                               |
+| `GET /api/cms/content`        | `{ "content": CmsContentEntry[] }` | Published collection entries and all pages. Supports `type` and `slug` query params.            |
+| `GET /api/cms/content/{slug}` | `{ "content": CmsContentEntry }`   | Finds by entry slug across content types. Pages are preferred if multiple entries share a slug. |
+
+### Content Query Parameters
+
+`GET /api/cms/content?type=posts`
+
+Returns entries whose content type slug is `posts`.
+
+`GET /api/cms/content?type=posts&slug=my-post`
+
+Returns a single entry when both `type` and `slug` are present.
+
+`GET /api/cms/content?slug=about`
+
+Returns a list of matching entries unless both `type` and `slug` are present. For most website
+detail pages, prefer passing both `type` and `slug`.
+
+## Visibility Rules
+
+Videos only appear when `published_at` is set.
+
+Roster profiles only appear when `status` is `published`. Roster endpoints also depend on the
+account plan having creatives access. Without access, the list endpoint returns an empty list and
+single-profile requests return `404`.
+
+Content collection entries only appear when `status` is `published`.
+
+Page entries are returned regardless of status. Pages are treated as website structure, and their
+field schema is stored on each page entry rather than inherited from the Pages content type.
+
+## Video Shape
+
+`CmsVideo` is returned by video endpoints and by hydrated `library_work` custom fields.
+
+```ts
+type CmsVideo = {
+	id: string;
+	title: string;
+	slug: string;
+	description: string | null;
+	client: string | null;
+	credits: CreditEntry[];
+	tags: string[];
+	roster: VideoCreativeGroup[];
+	fields: Record<string, unknown>;
+	field_schema: ContentField[];
+	published_at: string | null;
+	release_date: string | null;
+	media: {
+		mux_playback_id: string | null;
+		poster_url: string | null;
+		thumbnail_time: number | null;
+		mux_blur_placeholder: string | null;
+		mux_blur_aspect_ratio: number | null;
+		loop_start_time: number | null;
+		loop_end_time: number | null;
+		loop_mux_playback_id: string | null;
+		loop_mux_asset_status: string | null;
+		aspect_ratio: number | null;
+		custom_aspect_ratio: number | null;
+		duration_seconds: number | null;
+	};
+	created_at: string;
+};
+```
+
+`roster` groups the people or roles assigned to a video:
+
+```ts
+type VideoCreativeGroup = {
+	id: string;
+	name: string;
+	slug: string;
+	assignments: Array<{
+		id: string;
+		name: string;
+		url: string | null;
+		roster: {
+			id: string;
+			name: string;
+			slug: string;
+			image_url: string | null;
+			description: string | null;
+			links: unknown;
+		} | null;
+	}>;
+};
+```
+
+## Roster Shape
+
+```ts
+type CmsRosterProfile = {
+	id: string;
+	name: string;
+	slug: string;
+	image_url: string | null;
+	description: string | null;
+	links: unknown;
+	fields: Record<string, unknown>;
+	status: string;
+	order_index: number;
+	created_at: string;
+	updated_at: string;
+	type: {
+		id: string;
+		name: string;
+		singular_name: string;
+		slug: string;
+		field_schema: ContentField[];
+	} | null;
+	featured_work: CmsVideo[];
+};
+```
+
+`featured_work` contains published videos selected for that roster profile.
+
+## Content Entry Shape
+
+```ts
+type CmsContentEntry = {
+	id: string;
+	name: string;
+	slug: string;
+	status: 'draft' | 'published' | 'archived';
+	entry_date: string | null;
+	website_path: string | null;
+	meta: {
+		title: string | null;
+		description: string | null;
+		image_url: string | null;
+	};
+	fields: Record<string, unknown>;
+	field_schema: ContentField[];
+	type: {
+		id: string;
+		name: string;
+		slug: string;
+		kind: 'pages' | 'collection';
+	} | null;
+	published_at: string | null;
+	created_at: string;
+	updated_at: string;
+};
+```
+
+For collection entries, the default website path convention is:
+
+```txt
+/{contentType.slug}/{entry.slug}
+```
+
+For page entries, use `website_path` when it is set. `website_path` should be normalized with a
+leading slash in website projects. The root page normally uses `/`.
+
+## Custom Field Schemas
+
+Custom field schemas are arrays of `ContentField` objects:
+
+```ts
+type ContentField = {
+	id: string;
+	type:
+		| 'text'
+		| 'textarea'
+		| 'richtext'
+		| 'boolean'
+		| 'image'
+		| 'date'
+		| 'library_work'
+		| 'content_blocks'
+		| 'array';
+	label: string;
+	multiple?: boolean;
+	required?: boolean;
+	itemFields?: ContentField[];
+	itemLabelFieldId?: string;
+	itemSecondaryLabelFieldId?: string;
+};
+```
+
+The `id` is the API key used inside `fields`. The `label` is display text in the dashboard.
+Agents and website projects should use field IDs, not labels, when reading API responses.
+
+## Field Naming Rules
+
+When a new custom field is created, its initial `id` is generated from the label with
+`cleanSlug(label)`:
+
+```ts
+function cleanSlug(base: string) {
+	return base
+		.toLowerCase()
+		.trim()
+		.replace(/[^\w\s-]/g, '')
+		.replace(/\s+/g, '-')
+		.replace(/-+/g, '-');
+}
+```
+
+Examples:
+
+| Label           | Field ID        |
+| --------------- | --------------- |
+| `Hero Title`    | `hero-title`    |
+| `Client Quote`  | `client-quote`  |
+| `SEO / Intro`   | `seo-intro`     |
+| `Featured Work` | `featured-work` |
+
+If the generated ID already exists in the same schema, the editor appends a numeric suffix:
+`hero-title`, `hero-title-2`, `hero-title-3`.
+
+After a field exists, renaming the label does not rename the saved field ID. This preserves the
+API contract and existing saved content. When telling an agent about a field setup, include either
+the exact field IDs or enough label context to infer the initial slugged IDs.
+
+Good agent prompt:
+
+```txt
+I created a Posts content type with slug "journal". Its fields are:
+- Hero Image -> hero-image, image
+- Intro Text -> intro-text, richtext
+- Related Work -> related-work, library_work multiple
+
+Use the Content API docs to build /journal and /journal/[slug].
+```
+
+## Field Value Shapes
+
+Values are returned in `entry.fields`, `video.fields`, or `roster.fields` by field ID.
+
+| Field type                            | API value                                        |
+| ------------------------------------- | ------------------------------------------------ | ----- |
+| `text`                                | `string`                                         |
+| `textarea`                            | `string`                                         |
+| `richtext`                            | `string` containing HTML                         |
+| `boolean`                             | `boolean`                                        |
+| `image`                               | image URL string                                 |
+| `date`                                | date string                                      |
+| `library_work` with `multiple: false` | `CmsVideo                                        | null` |
+| `library_work` with multiple/default  | `CmsVideo[]`                                     |
+| `content_blocks`                      | `ContentBlock[]`                                 |
+| `array`                               | array of objects with `_key` plus item field IDs |
+
+`library_work` values are hydrated by the API. Website projects receive full published video
+objects, not raw video IDs. Missing or unpublished referenced videos are omitted from arrays or
+returned as `null` for single-video fields.
+
+Array item fields can use simple fields and single `library_work`. Nested arrays are not allowed.
+
+## Content Blocks
+
+```ts
+type ContentBlock =
+	| {
+			id: string;
+			type: 'text';
+			content: string;
+	  }
+	| {
+			id: string;
+			type: 'image';
+			src: string;
+			path: string;
+			alt: string;
+			showCaption: boolean;
+	  }
+	| {
+			id: string;
+			type: 'button';
+			text: string;
+			url: string;
+	  };
+```
+
+Text block `content` is HTML and should be sanitized or rendered through a trusted rich-text
+renderer in website projects.
+
+## Website Settings And Preview Links
+
+Website preview/view links in the dashboard are driven by the frontend revalidation webhook URL.
+The app derives the website base URL from the saved revalidation URL:
+
+```txt
+https://client-site.com/api/revalidate -> https://client-site.com
+https://client-site.com/custom/api/revalidate -> https://client-site.com/custom
+```
+
+The helper is `getWebsiteProjectBaseUrl(revalidateUrl)`. If no webhook exists or the URL is
+invalid, preview links are not shown.
+
+`FRONTEND_REVALIDATION_URL_OVERRIDE` can override the saved webhook URL for revalidation behavior.
+When the override is present, content edit pages do not derive a preview base URL from the saved
+webhook.
+
+### Page Preview Links
+
+Page entries use `website_path` to build their view URL:
+
+```txt
+baseUrl + website_path
+```
+
+Examples:
+
+| Page name | Entry slug | Website path | View URL path |
+| --------- | ---------- | ------------ | ------------- |
+| Home      | `home`     | `/`          | `/`           |
+| About     | `about`    | `/about`     | `/about`      |
+| Contact   | `contact`  | `/contact`   | `/contact`    |
+
+Only super users can edit page `website_path` and page field schemas.
+
+### Roster Preview Links
+
+Roster profile links use the roster type website route plus the creative slug:
+
+```txt
+/{website_path_prefix || creative_type.slug}/{creative.slug}
+```
+
+Examples:
+
+| Roster type slug | Website profile route | Creative slug | View URL path          |
+| ---------------- | --------------------- | ------------- | ---------------------- |
+| `directors`      | empty                 | `sam-smith`   | `/directors/sam-smith` |
+| `photographers`  | `artists`             | `jane-lee`    | `/artists/jane-lee`    |
+
+Only super users can edit the roster type website profile route.
+
+### Collection Routes
+
+Collection content entries do not currently store a custom `website_path`. Starter sites should
+use:
+
+```txt
+/{contentType.slug}
+/{contentType.slug}/{entry.slug}
+```
+
+If a website project wants friendlier route names, set the content type slug accordingly in the
+dashboard.
+
+## Revalidation
+
+Dashboard > Settings > API settings stores one frontend revalidation webhook per account:
+
+```txt
+revalidate_url: https://client-site.com/api/revalidate
+secret: REVALIDATE_SECRET
+enabled: true
+```
+
+When library, roster, or content changes affect a website, Eyeballs calls the starter site's
+revalidation endpoint with paths and tags. Starter sites should support:
+
+```http
+POST /api/revalidate
+```
+
+with the saved `REVALIDATE_SECRET`.
+
+Content revalidation tags include:
+
+```txt
+content
+content-type:{typeSlug}
+content:{entrySlug}
+```
+
+Roster revalidation tags include:
+
+```txt
+roster-profile:{creativeSlug}
+roster:{typeRouteSlug}
+```
+
+Library work changes can also revalidate work pages, roster profiles, and content entries that
+reference the changed video through `library_work` fields.
+
+## Starter Site Recipes
+
+### List Published Work
+
+```ts
+const { videos } = await cmsFetch('/api/cms/videos');
+```
+
+### Work Detail Page
+
+```ts
+const { video } = await cmsFetch(`/api/cms/videos/${params.slug}`);
+```
+
+### Collection List
+
+```ts
+const { content } = await cmsFetch('/api/cms/content?type=journal');
+```
+
+### Collection Detail
+
+```ts
+const { content: entry } = await cmsFetch(`/api/cms/content?type=journal&slug=${params.slug}`);
+```
+
+### Page By Slug
+
+```ts
+const { content: page } = await cmsFetch('/api/cms/content/home');
+```
+
+For page routing, prefer matching by `website_path` from the content list when the route is not
+the same as the entry slug.
+
+### Roster List And Profile
+
+```ts
+const { roster } = await cmsFetch('/api/cms/roster');
+const { roster: profile } = await cmsFetch(`/api/cms/roster/${params.slug}`);
+```
+
+## Maintenance Checklist
+
+When the API changes, update:
+
+1. `packages/cms/docs/content-api.md`
+2. `packages/cms/src/*` shared types, client helpers, or Next helpers if the contract changed
+3. `/dashboard/settings/api` if token or revalidation settings changed
+4. Any starter template API helper or examples
+5. `AGENTS.md` if agent workflow expectations changed
+
+Check these source files before documenting behavior:
+
+```txt
+src/app/api/cms/*
+src/lib/cmsData.ts
+src/lib/cmsAuth.ts
+src/lib/content.ts
+src/lib/contentFieldValues.ts
+src/lib/contentLibraryWork.ts
+src/lib/websiteProjectUrl.ts
+src/lib/publicRevalidation.ts
+```

package/package.json

@@ -0,0 +1,43 @@
+{
+	"name": "@eyeballs/cms",
+	"version": "0.1.0",
+	"description": "Shared Eyeballs CMS API types, client helpers, and documentation.",
+	"type": "module",
+	"license": "UNLICENSED",
+	"publishConfig": {
+		"access": "public"
+	},
+	"files": [
+		"dist",
+		"docs",
+		"README.md"
+	],
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js"
+		},
+		"./next": {
+			"types": "./dist/next.d.ts",
+			"import": "./dist/next.js"
+		},
+		"./docs/content-api.md": "./docs/content-api.md"
+	},
+	"scripts": {
+		"build": "tsc -p tsconfig.json",
+		"prepack": "npm run build"
+	},
+	"peerDependencies": {
+		"next": ">=15"
+	},
+	"peerDependenciesMeta": {
+		"next": {
+			"optional": true
+		}
+	},
+	"devDependencies": {
+		"typescript": "^6"
+	}
+}