@sonordev/agency-site-kit 0.3.1 → 0.4.1

package/dist/portfolio/server.cjs

@@ -1,155 +1,67 @@
 'use strict';
 
-var chunk633UMQQH_cjs = require('../chunk-633UMQQH.cjs');
-var chunkEE75WRCM_cjs = require('../chunk-EE75WRCM.cjs');
+var chunk7ZHRMWJU_cjs = require('../chunk-7ZHRMWJU.cjs');
 var chunkFCKDJ4MJ_cjs = require('../chunk-FCKDJ4MJ.cjs');
+require('../chunk-HQGAX2LI.cjs');
+require('../chunk-XOWSXZYW.cjs');
 
-// src/portfolio/server.ts
-var LOG_PREFIX = "[@sonordev/agency-site-kit/portfolio]";
-function portfolioGet(path) {
-  return chunkEE75WRCM_cjs.apiFetch(path, { method: "GET", tags: [chunkFCKDJ4MJ_cjs.PORTFOLIO_CACHE_TAG] });
-}
-function buildQuery(params) {
-  const entries = Object.entries(params).filter(
-    (entry) => entry[1] != null
-  );
-  if (entries.length === 0) return "";
-  const qs = new URLSearchParams(
-    entries.map(([k, v]) => [k, String(v)])
-  ).toString();
-  return `?${qs}`;
-}
-async function getPortfolioItems(options) {
-  const fallback = { items: [], total: 0, limit: 0, offset: 0 };
-  const query = buildQuery({
-    category: options?.category,
-    featured: options?.featured,
-    limit: options?.limit,
-    offset: options?.offset
-  });
-  const data = await portfolioGet(
-    `/api/public/portfolio/items${query}`
-  );
-  if (!data) {
-    console.warn(`${LOG_PREFIX} Failed to fetch portfolio items.`);
-    return fallback;
-  }
-  return data;
-}
-async function getPortfolioItem(slug) {
-  if (!slug) {
-    console.warn(`${LOG_PREFIX} getPortfolioItem called with empty slug.`);
-    return null;
-  }
-  const data = await portfolioGet(
-    `/api/public/portfolio/items/${encodeURIComponent(slug)}`
-  );
-  if (!data || !data.found || !data.item) {
-    console.warn(`${LOG_PREFIX} Portfolio item not found for slug: "${slug}".`);
-    return null;
-  }
-  const { item } = data;
-  return {
-    id: item.id,
-    slug: item.slug,
-    title: item.title,
-    subtitle: item.subtitle,
-    category: item.category,
-    services: item.services,
-    description: item.description,
-    hero_image: item.hero_image,
-    hero_image_alt: item.hero_image_alt,
-    live_url: item.live_url,
-    project_id: item.project_id ?? null,
-    kpis: item.kpis,
-    details: item.details,
-    seo: item.seo,
-    featured: item.featured,
-    order: item.order,
-    published_at: item.published_at,
-    hero_screenshots: item.hero_screenshots,
-    baseline_metrics: item.baseline_metrics,
-    current_metrics: item.current_metrics,
-    metrics_last_refreshed_at: item.metrics_last_refreshed_at,
-    // Sanitized HERE because this is the last genuinely-server-side hop:
-    // PortfolioPage compiles to a client component (tsup 'use client'
-    // banner), so raw client-site paths in sections would serialize into
-    // the RSC payload and get crawled against the agency site (GSC 404s).
-    sections: chunk633UMQQH_cjs.sanitizePortfolioSections(item.sections ?? []),
-    metricsDelta: item.metricsDelta ?? []
-  };
-}
-async function getPortfolioCategories() {
-  const data = await portfolioGet("/api/public/portfolio/categories");
-  if (!data) {
-    console.warn(`${LOG_PREFIX} Failed to fetch portfolio categories.`);
-    return [];
-  }
-  return data;
-}
-async function getPortfolioBrandConfig() {
-  const fallback = {
-    primary: "#6366f1",
-    secondary: "#8b5cf6",
-    background: "#0a0a0f",
-    backgroundElevated: "#12121a",
-    surface: "#1a1a2e",
-    surfaceHover: "#22223a",
-    surfaceBorder: "#2a2a3e",
-    textPrimary: "#f0f0f5",
-    textSecondary: "#a0a0b5",
-    textTertiary: "#6b6b80",
-    fontHeading: "Inter, system-ui, sans-serif",
-    fontBody: "Inter, system-ui, sans-serif"
-  };
-  const data = await portfolioGet(
-    "/api/public/portfolio/config"
-  );
-  if (!data || !data.brand) {
-    console.warn(`${LOG_PREFIX} Failed to fetch brand config, using defaults.`);
-    return fallback;
-  }
-  return data.brand;
-}
-async function generatePortfolioMetadata(slug) {
-  const item = await getPortfolioItem(slug);
-  if (!item) {
-    return {};
-  }
-  const seo = item.seo;
-  const title = seo?.metaTitle || item.title;
-  const description = seo?.metaDescription || item.description;
-  const keywords = seo?.keywords ?? [];
-  const ogImages = [];
-  if (item.hero_image) {
-    ogImages.push(item.hero_image);
-  }
-  return {
-    title,
-    description,
-    keywords: keywords.length > 0 ? keywords : void 0,
-    openGraph: {
-      title,
-      description,
-      images: ogImages.length > 0 ? ogImages : void 0,
-      type: "article"
-    }
-  };
-}
-async function generatePortfolioStaticParams() {
-  const data = await getPortfolioItems({ limit: 500, offset: 0 });
-  return data.items.map((item) => ({ slug: item.slug }));
-}
 
+
+Object.defineProperty(exports, "PortfolioApiError", {
+  enumerable: true,
+  get: function () { return chunk7ZHRMWJU_cjs.PortfolioApiError; }
+});
+Object.defineProperty(exports, "PortfolioContractError", {
+  enumerable: true,
+  get: function () { return chunk7ZHRMWJU_cjs.PortfolioContractError; }
+});
+Object.defineProperty(exports, "assertPortfolioItemShape", {
+  enumerable: true,
+  get: function () { return chunk7ZHRMWJU_cjs.assertPortfolioItemShape; }
+});
+Object.defineProperty(exports, "generatePortfolioCategoryStaticParams", {
+  enumerable: true,
+  get: function () { return chunk7ZHRMWJU_cjs.generatePortfolioCategoryStaticParams; }
+});
+Object.defineProperty(exports, "generatePortfolioIndexMetadata", {
+  enumerable: true,
+  get: function () { return chunk7ZHRMWJU_cjs.generatePortfolioIndexMetadata; }
+});
+Object.defineProperty(exports, "generatePortfolioMetadata", {
+  enumerable: true,
+  get: function () { return chunk7ZHRMWJU_cjs.generatePortfolioMetadata; }
+});
+Object.defineProperty(exports, "generatePortfolioSitemapEntries", {
+  enumerable: true,
+  get: function () { return chunk7ZHRMWJU_cjs.generatePortfolioSitemapEntries; }
+});
+Object.defineProperty(exports, "generatePortfolioStaticParams", {
+  enumerable: true,
+  get: function () { return chunk7ZHRMWJU_cjs.generatePortfolioStaticParams; }
+});
+Object.defineProperty(exports, "getPortfolioBrandConfig", {
+  enumerable: true,
+  get: function () { return chunk7ZHRMWJU_cjs.getPortfolioBrandConfig; }
+});
+Object.defineProperty(exports, "getPortfolioCategories", {
+  enumerable: true,
+  get: function () { return chunk7ZHRMWJU_cjs.getPortfolioCategories; }
+});
+Object.defineProperty(exports, "getPortfolioItem", {
+  enumerable: true,
+  get: function () { return chunk7ZHRMWJU_cjs.getPortfolioItem; }
+});
+Object.defineProperty(exports, "getPortfolioItems", {
+  enumerable: true,
+  get: function () { return chunk7ZHRMWJU_cjs.getPortfolioItems; }
+});
+Object.defineProperty(exports, "slugifyCategory", {
+  enumerable: true,
+  get: function () { return chunk7ZHRMWJU_cjs.slugifyCategory; }
+});
 Object.defineProperty(exports, "PORTFOLIO_CACHE_TAG", {
   enumerable: true,
   get: function () { return chunkFCKDJ4MJ_cjs.PORTFOLIO_CACHE_TAG; }
 });
-exports.generatePortfolioMetadata = generatePortfolioMetadata;
-exports.generatePortfolioStaticParams = generatePortfolioStaticParams;
-exports.getPortfolioBrandConfig = getPortfolioBrandConfig;
-exports.getPortfolioCategories = getPortfolioCategories;
-exports.getPortfolioItem = getPortfolioItem;
-exports.getPortfolioItems = getPortfolioItems;
 //# sourceMappingURL=server.cjs.map
 //# sourceMappingURL=server.cjs.map

package/dist/portfolio/server.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/portfolio/server.ts"],"names":["apiFetch","PORTFOLIO_CACHE_TAG","sanitizePortfolioSections"],"mappings":"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","file":"server.cjs","sourcesContent":["/**\n * @sonordev/agency-site-kit — Portfolio server-side data fetching\n *\n * RSC (React Server Component) data layer for portfolio pages.\n * All functions are async and designed for use in Next.js App Router\n * server components, generateMetadata(), and generateStaticParams().\n *\n * This file is server-only — no 'use client' directive.\n */\n\nimport { apiFetch } from '../shared/api';\nimport { PORTFOLIO_CACHE_TAG } from '../shared/cache';\nimport { sanitizePortfolioSections } from './sanitize';\nimport type {\n  BrandConfig,\n  MetricsDelta,\n  PortfolioConfigResponse,\n  PortfolioItemFull,\n  PortfolioListResponse,\n  PortfolioSeoData,\n  PortfolioSection,\n} from '../types';\n\nconst LOG_PREFIX = '[@sonordev/agency-site-kit/portfolio]';\n\n// Re-export so consumers and route handlers can reference the same tag.\nexport { PORTFOLIO_CACHE_TAG } from '../shared/cache';\n\n/**\n * GET against the public portfolio API with the shared portfolio cache tag,\n * so the Portal's revalidation webhook can invalidate every portfolio fetch\n * (list, detail, categories, config, sitemap data) via one revalidateTag.\n */\nfunction portfolioGet<T>(path: string): Promise<T | null> {\n  return apiFetch<T>(path, { method: 'GET', tags: [PORTFOLIO_CACHE_TAG] });\n}\n\n// ---------------------------------------------------------------------------\n// Internal helpers\n// ---------------------------------------------------------------------------\n\n/**\n * Builds a query string from an object, omitting undefined/null values.\n */\nfunction buildQuery(params: Record<string, string | number | boolean | undefined | null>): string {\n  const entries = Object.entries(params).filter(\n    (entry): entry is [string, string | number | boolean] => entry[1] != null,\n  );\n  if (entries.length === 0) return '';\n  const qs = new URLSearchParams(\n    entries.map(([k, v]) => [k, String(v)]),\n  ).toString();\n  return `?${qs}`;\n}\n\n// ---------------------------------------------------------------------------\n// Public API — List items\n// ---------------------------------------------------------------------------\n\n/**\n * Fetches published portfolio items from the public API.\n * Cached via Next.js ISR (revalidate: 3600).\n */\nexport async function getPortfolioItems(options?: {\n  category?: string;\n  featured?: boolean;\n  limit?: number;\n  offset?: number;\n}): Promise<PortfolioListResponse> {\n  const fallback: PortfolioListResponse = { items: [], total: 0, limit: 0, offset: 0 };\n\n  const query = buildQuery({\n    category: options?.category,\n    featured: options?.featured,\n    limit: options?.limit,\n    offset: options?.offset,\n  });\n\n  const data = await portfolioGet<PortfolioListResponse>(\n    `/api/public/portfolio/items${query}`,\n  );\n\n  if (!data) {\n    console.warn(`${LOG_PREFIX} Failed to fetch portfolio items.`);\n    return fallback;\n  }\n\n  return data;\n}\n\n// ---------------------------------------------------------------------------\n// Public API — Single item\n// ---------------------------------------------------------------------------\n\n/** Shape returned by the single-item API endpoint. */\ninterface PortfolioItemApiResponse {\n  found: boolean;\n  item: {\n    id: string;\n    slug: string;\n    title: string;\n    subtitle: string;\n    category: string;\n    services: string[];\n    description: string;\n    hero_image: string;\n    hero_image_alt: string;\n    live_url: string | null;\n    project_id: string | null;\n    kpis: PortfolioItemFull['kpis'];\n    details: PortfolioItemFull['details'];\n    seo: PortfolioItemFull['seo'];\n    featured: boolean;\n    order?: number;\n    published_at: string | null;\n    hero_screenshots: PortfolioItemFull['hero_screenshots'];\n    baseline_metrics: PortfolioItemFull['baseline_metrics'];\n    current_metrics: PortfolioItemFull['current_metrics'];\n    metrics_last_refreshed_at: string | null;\n    sections: PortfolioSection[];\n    metricsDelta: MetricsDelta[];\n  };\n}\n\n/**\n * Fetches a single portfolio item by slug, including full Sanity sections\n * and live metrics delta. This is the main data function for portfolio detail pages.\n *\n * Returns null when the item is not found or the API call fails.\n */\nexport async function getPortfolioItem(slug: string): Promise<PortfolioItemFull | null> {\n  if (!slug) {\n    console.warn(`${LOG_PREFIX} getPortfolioItem called with empty slug.`);\n    return null;\n  }\n\n  const data = await portfolioGet<PortfolioItemApiResponse>(\n    `/api/public/portfolio/items/${encodeURIComponent(slug)}`,\n  );\n\n  if (!data || !data.found || !data.item) {\n    console.warn(`${LOG_PREFIX} Portfolio item not found for slug: \"${slug}\".`);\n    return null;\n  }\n\n  // Map the API response to the PortfolioItemFull type\n  const { item } = data;\n  return {\n    id: item.id,\n    slug: item.slug,\n    title: item.title,\n    subtitle: item.subtitle,\n    category: item.category,\n    services: item.services,\n    description: item.description,\n    hero_image: item.hero_image,\n    hero_image_alt: item.hero_image_alt,\n    live_url: item.live_url,\n    project_id: item.project_id ?? null,\n    kpis: item.kpis,\n    details: item.details,\n    seo: item.seo,\n    featured: item.featured,\n    order: item.order,\n    published_at: item.published_at,\n    hero_screenshots: item.hero_screenshots,\n    baseline_metrics: item.baseline_metrics,\n    current_metrics: item.current_metrics,\n    metrics_last_refreshed_at: item.metrics_last_refreshed_at,\n    // Sanitized HERE because this is the last genuinely-server-side hop:\n    // PortfolioPage compiles to a client component (tsup 'use client'\n    // banner), so raw client-site paths in sections would serialize into\n    // the RSC payload and get crawled against the agency site (GSC 404s).\n    sections: sanitizePortfolioSections(item.sections ?? []),\n    metricsDelta: item.metricsDelta ?? [],\n  };\n}\n\n// ---------------------------------------------------------------------------\n// Public API — Categories\n// ---------------------------------------------------------------------------\n\n/**\n * Fetches available portfolio categories.\n * Returns an empty array on failure.\n */\nexport async function getPortfolioCategories(): Promise<string[]> {\n  const data = await portfolioGet<string[]>('/api/public/portfolio/categories');\n\n  if (!data) {\n    console.warn(`${LOG_PREFIX} Failed to fetch portfolio categories.`);\n    return [];\n  }\n\n  return data;\n}\n\n// ---------------------------------------------------------------------------\n// Public API — Brand config\n// ---------------------------------------------------------------------------\n\n/**\n * Fetches brand configuration for the agency (colors, fonts, logo).\n * Returns sensible defaults when the API call fails.\n */\nexport async function getPortfolioBrandConfig(): Promise<BrandConfig> {\n  const fallback: BrandConfig = {\n    primary: '#6366f1',\n    secondary: '#8b5cf6',\n    background: '#0a0a0f',\n    backgroundElevated: '#12121a',\n    surface: '#1a1a2e',\n    surfaceHover: '#22223a',\n    surfaceBorder: '#2a2a3e',\n    textPrimary: '#f0f0f5',\n    textSecondary: '#a0a0b5',\n    textTertiary: '#6b6b80',\n    fontHeading: 'Inter, system-ui, sans-serif',\n    fontBody: 'Inter, system-ui, sans-serif',\n  };\n\n  const data = await portfolioGet<PortfolioConfigResponse>(\n    '/api/public/portfolio/config',\n  );\n\n  if (!data || !data.brand) {\n    console.warn(`${LOG_PREFIX} Failed to fetch brand config, using defaults.`);\n    return fallback;\n  }\n\n  return data.brand;\n}\n\n// ---------------------------------------------------------------------------\n// Next.js Metadata helper\n// ---------------------------------------------------------------------------\n\n/**\n * Generates Next.js Metadata for a portfolio item page.\n * For use in generateMetadata() in the App Router.\n *\n * Returns an empty object when the item cannot be found, which is safe\n * to spread into the metadata return value.\n */\nexport async function generatePortfolioMetadata(slug: string): Promise<{\n  title?: string;\n  description?: string;\n  keywords?: string[];\n  openGraph?: {\n    title?: string;\n    description?: string;\n    images?: string[];\n    type?: string;\n  };\n}> {\n  const item = await getPortfolioItem(slug);\n\n  if (!item) {\n    return {};\n  }\n\n  // Prefer dedicated SEO data if available, fall back to item fields\n  const seo: PortfolioSeoData | null = item.seo;\n  const title = seo?.metaTitle || item.title;\n  const description = seo?.metaDescription || item.description;\n  const keywords = seo?.keywords ?? [];\n\n  // Collect OG images: prefer SEO og image, then hero image\n  const ogImages: string[] = [];\n  if (item.hero_image) {\n    ogImages.push(item.hero_image);\n  }\n\n  return {\n    title,\n    description,\n    keywords: keywords.length > 0 ? keywords : undefined,\n    openGraph: {\n      title,\n      description,\n      images: ogImages.length > 0 ? ogImages : undefined,\n      type: 'article',\n    },\n  };\n}\n\n// ---------------------------------------------------------------------------\n// Next.js Static Params helper\n// ---------------------------------------------------------------------------\n\n/**\n * Generates static params for portfolio pages.\n * For use in generateStaticParams() in the App Router.\n *\n * Fetches all published portfolio items and returns their slugs.\n */\nexport async function generatePortfolioStaticParams(): Promise<Array<{ slug: string }>> {\n  // Fetch a large batch to cover all published items\n  const data = await getPortfolioItems({ limit: 500, offset: 0 });\n\n  return data.items.map((item) => ({ slug: item.slug }));\n}\n"]}
+{"version":3,"sources":[],"names":[],"mappings":"","file":"server.cjs"}

package/dist/portfolio/server.d.cts

@@ -1,4 +1,4 @@
-import { B as BrandConfig, P as PortfolioItemFull, a as PortfolioListResponse } from '../types-DL4t_Cfa.cjs';
+import { P as PortfolioItemFull, a as PortfolioSection, M as MetricsDelta, B as BrandConfig, b as PortfolioListResponse } from '../types-0tVPy4pU.cjs';
 export { P as PORTFOLIO_CACHE_TAG } from '../cache-CE_ujDK4.cjs';
 
 /**
@@ -11,9 +11,48 @@ export { P as PORTFOLIO_CACHE_TAG } from '../cache-CE_ujDK4.cjs';
  * This file is server-only — no 'use client' directive.
  */
 
+/**
+ * Error contract (single source of truth for portfolio content fetching):
+ *
+ * - "Not found" is a DATA answer: the API returns 200 with `found: false`,
+ *   and `getPortfolioItem` returns null. Consumers map null → notFound().
+ * - Infrastructure failure (network error, 5xx, rate-limit exhaustion,
+ *   missing SONOR_API_KEY) THROWS PortfolioApiError. It must never be
+ *   conflated with "not found": treating an outage as a 404 turns indexed
+ *   /work URLs into real 404s during ISR regeneration (the GSC 404-flood
+ *   class of incident). A thrown error makes Next.js keep serving the last
+ *   good page during background revalidation, and fails builds loudly
+ *   instead of silently generating an empty portfolio.
+ *
+ * The one exception is getPortfolioBrandConfig, which degrades to default
+ * branding on failure — cosmetic fallback is safe; content fallback is not.
+ */
+declare class PortfolioApiError extends Error {
+    readonly path: string;
+    constructor(path: string, message?: string);
+}
+/**
+ * A 200 response whose body violates the expected shape. Thrown before any
+ * mapping so drift between the API and this package surfaces as a loud,
+ * named error instead of `undefined` text on live pages.
+ */
+declare class PortfolioContractError extends PortfolioApiError {
+    readonly field: string;
+    constructor(path: string, field: string, detail: string);
+}
+/**
+ * Minimal runtime shape check for the single-item response. Deliberately
+ * lenient about unknown extra fields (the API may grow) and strict about
+ * the fields this package renders from.
+ */
+declare function assertPortfolioItemShape(item: unknown, path: string): asserts item is PortfolioItemApiResponse['item'];
 /**
  * Fetches published portfolio items from the public API.
  * Cached via Next.js ISR (revalidate: 3600).
+ *
+ * An empty portfolio is `{ items: [] }` from a healthy API. Infrastructure
+ * failure throws PortfolioApiError (see the error contract above) — it never
+ * silently renders an empty portfolio or an empty sitemap.
  */
 declare function getPortfolioItems(options?: {
     category?: string;
@@ -21,29 +60,65 @@ declare function getPortfolioItems(options?: {
     limit?: number;
     offset?: number;
 }): Promise<PortfolioListResponse>;
+/** Shape returned by the single-item API endpoint. */
+interface PortfolioItemApiResponse {
+    found: boolean;
+    item: {
+        id: string;
+        slug: string;
+        title: string;
+        subtitle: string;
+        category: string;
+        services: string[];
+        description: string;
+        hero_image: string;
+        hero_image_alt: string;
+        live_url: string | null;
+        project_id: string | null;
+        kpis: PortfolioItemFull['kpis'];
+        details: PortfolioItemFull['details'];
+        seo: PortfolioItemFull['seo'];
+        featured: boolean;
+        order?: number;
+        published_at: string | null;
+        hero_screenshots: PortfolioItemFull['hero_screenshots'];
+        baseline_metrics: PortfolioItemFull['baseline_metrics'];
+        current_metrics: PortfolioItemFull['current_metrics'];
+        metrics_last_refreshed_at: string | null;
+        sections: PortfolioSection[];
+        metricsDelta: MetricsDelta[];
+        sectionsOrdered?: boolean;
+    };
+}
 /**
  * Fetches a single portfolio item by slug, including full Sanity sections
  * and live metrics delta. This is the main data function for portfolio detail pages.
  *
- * Returns null when the item is not found or the API call fails.
+ * Returns null ONLY when the item genuinely does not exist (API answered
+ * `found: false`) — safe to map to notFound(). Infrastructure failures throw
+ * PortfolioApiError instead, so an API outage during ISR regeneration keeps
+ * serving the last good page rather than minting a real 404.
  */
 declare function getPortfolioItem(slug: string): Promise<PortfolioItemFull | null>;
 /**
  * Fetches available portfolio categories.
- * Returns an empty array on failure.
+ * Infrastructure failure throws PortfolioApiError (see error contract).
  */
 declare function getPortfolioCategories(): Promise<string[]>;
 /**
  * Fetches brand configuration for the agency (colors, fonts, logo).
- * Returns sensible defaults when the API call fails.
+ * Returns sensible defaults when the API call fails — the ONE deliberate
+ * exception to the throw-on-failure contract: brand config is cosmetic, and
+ * an API blip must not take down the whole layout that wraps every page.
  */
 declare function getPortfolioBrandConfig(): Promise<BrandConfig>;
 /**
  * Generates Next.js Metadata for a portfolio item page.
  * For use in generateMetadata() in the App Router.
  *
- * Returns an empty object when the item cannot be found, which is safe
- * to spread into the metadata return value.
+ * Returns an empty object when the item does not exist (safe to spread into
+ * the metadata return value); infrastructure failures throw so a build never
+ * silently ships pages with missing metadata.
  */
 declare function generatePortfolioMetadata(slug: string): Promise<{
     title?: string;
@@ -61,9 +136,84 @@ declare function generatePortfolioMetadata(slug: string): Promise<{
  * For use in generateStaticParams() in the App Router.
  *
  * Fetches all published portfolio items and returns their slugs.
+ * Infrastructure failure throws, failing the build loudly instead of
+ * silently building a site with zero portfolio pages.
  */
 declare function generatePortfolioStaticParams(): Promise<Array<{
     slug: string;
 }>>;
+/**
+ * URL slug for a category display value ("Web Development" → "web-development").
+ * Single source of truth for category URLs — PortfolioIndex resolves slugs
+ * back to the original values by matching against getPortfolioCategories().
+ */
+declare function slugifyCategory(category: string): string;
+/**
+ * Static params for the category filter routes.
+ * For use in app/work/category/[category]/page.tsx:
+ *
+ * ```ts
+ * export async function generateStaticParams() {
+ *   return generatePortfolioCategoryStaticParams();
+ * }
+ * ```
+ */
+declare function generatePortfolioCategoryStaticParams(): Promise<Array<{
+    category: string;
+}>>;
+/**
+ * Metadata for index + category + paginated portfolio routes: a stable
+ * title/canonical so filtered and paginated variants don't compete in
+ * search. Spread into generateMetadata()'s return value.
+ */
+declare function generatePortfolioIndexMetadata(options: {
+    /** Site origin (e.g. "https://youragency.com"). */
+    baseUrl: string;
+    /** Route prefix. Defaults to "/work". */
+    basePath?: string;
+    /** Active category SLUG (from the route param), if any. */
+    category?: string | null;
+    /** 1-based page number. */
+    page?: number;
+    /** Title base, e.g. "Our Work". Category/page qualifiers are appended. */
+    titleBase?: string;
+}): Promise<{
+    title: string;
+    alternates: {
+        canonical: string;
+    };
+}>;
+/** One entry in the shape Next.js expects from app/sitemap.(js|ts). */
+interface PortfolioSitemapEntry {
+    url: string;
+    lastModified?: string;
+    changeFrequency?: 'always' | 'hourly' | 'daily' | 'weekly' | 'monthly' | 'yearly' | 'never';
+    priority?: number;
+}
+/**
+ * Builds sitemap entries for every published portfolio item, in the shape
+ * Next.js `app/sitemap.(js|ts)` expects — spread the result into the array
+ * you return:
+ *
+ * ```ts
+ * const portfolio = await generatePortfolioSitemapEntries({
+ *   baseUrl: 'https://youragency.com',
+ * });
+ * return [...staticEntries, ...portfolio];
+ * ```
+ *
+ * `lastModified` prefers the metrics refresh timestamp (case studies change
+ * when their live metrics update) and falls back to the publish date.
+ * Infrastructure failure throws — a sitemap silently missing every case
+ * study is how portfolio URLs fall out of the index.
+ */
+declare function generatePortfolioSitemapEntries(options: {
+    /** Site origin, no trailing slash needed (e.g. "https://youragency.com"). */
+    baseUrl: string;
+    /** Route prefix for case studies. Defaults to "/work". */
+    basePath?: string;
+    changeFrequency?: PortfolioSitemapEntry['changeFrequency'];
+    priority?: number;
+}): Promise<PortfolioSitemapEntry[]>;
 
-export { generatePortfolioMetadata, generatePortfolioStaticParams, getPortfolioBrandConfig, getPortfolioCategories, getPortfolioItem, getPortfolioItems };
+export { PortfolioApiError, PortfolioContractError, type PortfolioSitemapEntry, assertPortfolioItemShape, generatePortfolioCategoryStaticParams, generatePortfolioIndexMetadata, generatePortfolioMetadata, generatePortfolioSitemapEntries, generatePortfolioStaticParams, getPortfolioBrandConfig, getPortfolioCategories, getPortfolioItem, getPortfolioItems, slugifyCategory };

package/dist/portfolio/server.d.ts

@@ -1,4 +1,4 @@
-import { B as BrandConfig, P as PortfolioItemFull, a as PortfolioListResponse } from '../types-DL4t_Cfa.js';
+import { P as PortfolioItemFull, a as PortfolioSection, M as MetricsDelta, B as BrandConfig, b as PortfolioListResponse } from '../types-0tVPy4pU.js';
 export { P as PORTFOLIO_CACHE_TAG } from '../cache-CE_ujDK4.js';
 
 /**
@@ -11,9 +11,48 @@ export { P as PORTFOLIO_CACHE_TAG } from '../cache-CE_ujDK4.js';
  * This file is server-only — no 'use client' directive.
  */
 
+/**
+ * Error contract (single source of truth for portfolio content fetching):
+ *
+ * - "Not found" is a DATA answer: the API returns 200 with `found: false`,
+ *   and `getPortfolioItem` returns null. Consumers map null → notFound().
+ * - Infrastructure failure (network error, 5xx, rate-limit exhaustion,
+ *   missing SONOR_API_KEY) THROWS PortfolioApiError. It must never be
+ *   conflated with "not found": treating an outage as a 404 turns indexed
+ *   /work URLs into real 404s during ISR regeneration (the GSC 404-flood
+ *   class of incident). A thrown error makes Next.js keep serving the last
+ *   good page during background revalidation, and fails builds loudly
+ *   instead of silently generating an empty portfolio.
+ *
+ * The one exception is getPortfolioBrandConfig, which degrades to default
+ * branding on failure — cosmetic fallback is safe; content fallback is not.
+ */
+declare class PortfolioApiError extends Error {
+    readonly path: string;
+    constructor(path: string, message?: string);
+}
+/**
+ * A 200 response whose body violates the expected shape. Thrown before any
+ * mapping so drift between the API and this package surfaces as a loud,
+ * named error instead of `undefined` text on live pages.
+ */
+declare class PortfolioContractError extends PortfolioApiError {
+    readonly field: string;
+    constructor(path: string, field: string, detail: string);
+}
+/**
+ * Minimal runtime shape check for the single-item response. Deliberately
+ * lenient about unknown extra fields (the API may grow) and strict about
+ * the fields this package renders from.
+ */
+declare function assertPortfolioItemShape(item: unknown, path: string): asserts item is PortfolioItemApiResponse['item'];
 /**
  * Fetches published portfolio items from the public API.
  * Cached via Next.js ISR (revalidate: 3600).
+ *
+ * An empty portfolio is `{ items: [] }` from a healthy API. Infrastructure
+ * failure throws PortfolioApiError (see the error contract above) — it never
+ * silently renders an empty portfolio or an empty sitemap.
  */
 declare function getPortfolioItems(options?: {
     category?: string;
@@ -21,29 +60,65 @@ declare function getPortfolioItems(options?: {
     limit?: number;
     offset?: number;
 }): Promise<PortfolioListResponse>;
+/** Shape returned by the single-item API endpoint. */
+interface PortfolioItemApiResponse {
+    found: boolean;
+    item: {
+        id: string;
+        slug: string;
+        title: string;
+        subtitle: string;
+        category: string;
+        services: string[];
+        description: string;
+        hero_image: string;
+        hero_image_alt: string;
+        live_url: string | null;
+        project_id: string | null;
+        kpis: PortfolioItemFull['kpis'];
+        details: PortfolioItemFull['details'];
+        seo: PortfolioItemFull['seo'];
+        featured: boolean;
+        order?: number;
+        published_at: string | null;
+        hero_screenshots: PortfolioItemFull['hero_screenshots'];
+        baseline_metrics: PortfolioItemFull['baseline_metrics'];
+        current_metrics: PortfolioItemFull['current_metrics'];
+        metrics_last_refreshed_at: string | null;
+        sections: PortfolioSection[];
+        metricsDelta: MetricsDelta[];
+        sectionsOrdered?: boolean;
+    };
+}
 /**
  * Fetches a single portfolio item by slug, including full Sanity sections
  * and live metrics delta. This is the main data function for portfolio detail pages.
  *
- * Returns null when the item is not found or the API call fails.
+ * Returns null ONLY when the item genuinely does not exist (API answered
+ * `found: false`) — safe to map to notFound(). Infrastructure failures throw
+ * PortfolioApiError instead, so an API outage during ISR regeneration keeps
+ * serving the last good page rather than minting a real 404.
  */
 declare function getPortfolioItem(slug: string): Promise<PortfolioItemFull | null>;
 /**
  * Fetches available portfolio categories.
- * Returns an empty array on failure.
+ * Infrastructure failure throws PortfolioApiError (see error contract).
  */
 declare function getPortfolioCategories(): Promise<string[]>;
 /**
  * Fetches brand configuration for the agency (colors, fonts, logo).
- * Returns sensible defaults when the API call fails.
+ * Returns sensible defaults when the API call fails — the ONE deliberate
+ * exception to the throw-on-failure contract: brand config is cosmetic, and
+ * an API blip must not take down the whole layout that wraps every page.
  */
 declare function getPortfolioBrandConfig(): Promise<BrandConfig>;
 /**
  * Generates Next.js Metadata for a portfolio item page.
  * For use in generateMetadata() in the App Router.
  *
- * Returns an empty object when the item cannot be found, which is safe
- * to spread into the metadata return value.
+ * Returns an empty object when the item does not exist (safe to spread into
+ * the metadata return value); infrastructure failures throw so a build never
+ * silently ships pages with missing metadata.
  */
 declare function generatePortfolioMetadata(slug: string): Promise<{
     title?: string;
@@ -61,9 +136,84 @@ declare function generatePortfolioMetadata(slug: string): Promise<{
  * For use in generateStaticParams() in the App Router.
  *
  * Fetches all published portfolio items and returns their slugs.
+ * Infrastructure failure throws, failing the build loudly instead of
+ * silently building a site with zero portfolio pages.
  */
 declare function generatePortfolioStaticParams(): Promise<Array<{
     slug: string;
 }>>;
+/**
+ * URL slug for a category display value ("Web Development" → "web-development").
+ * Single source of truth for category URLs — PortfolioIndex resolves slugs
+ * back to the original values by matching against getPortfolioCategories().
+ */
+declare function slugifyCategory(category: string): string;
+/**
+ * Static params for the category filter routes.
+ * For use in app/work/category/[category]/page.tsx:
+ *
+ * ```ts
+ * export async function generateStaticParams() {
+ *   return generatePortfolioCategoryStaticParams();
+ * }
+ * ```
+ */
+declare function generatePortfolioCategoryStaticParams(): Promise<Array<{
+    category: string;
+}>>;
+/**
+ * Metadata for index + category + paginated portfolio routes: a stable
+ * title/canonical so filtered and paginated variants don't compete in
+ * search. Spread into generateMetadata()'s return value.
+ */
+declare function generatePortfolioIndexMetadata(options: {
+    /** Site origin (e.g. "https://youragency.com"). */
+    baseUrl: string;
+    /** Route prefix. Defaults to "/work". */
+    basePath?: string;
+    /** Active category SLUG (from the route param), if any. */
+    category?: string | null;
+    /** 1-based page number. */
+    page?: number;
+    /** Title base, e.g. "Our Work". Category/page qualifiers are appended. */
+    titleBase?: string;
+}): Promise<{
+    title: string;
+    alternates: {
+        canonical: string;
+    };
+}>;
+/** One entry in the shape Next.js expects from app/sitemap.(js|ts). */
+interface PortfolioSitemapEntry {
+    url: string;
+    lastModified?: string;
+    changeFrequency?: 'always' | 'hourly' | 'daily' | 'weekly' | 'monthly' | 'yearly' | 'never';
+    priority?: number;
+}
+/**
+ * Builds sitemap entries for every published portfolio item, in the shape
+ * Next.js `app/sitemap.(js|ts)` expects — spread the result into the array
+ * you return:
+ *
+ * ```ts
+ * const portfolio = await generatePortfolioSitemapEntries({
+ *   baseUrl: 'https://youragency.com',
+ * });
+ * return [...staticEntries, ...portfolio];
+ * ```
+ *
+ * `lastModified` prefers the metrics refresh timestamp (case studies change
+ * when their live metrics update) and falls back to the publish date.
+ * Infrastructure failure throws — a sitemap silently missing every case
+ * study is how portfolio URLs fall out of the index.
+ */
+declare function generatePortfolioSitemapEntries(options: {
+    /** Site origin, no trailing slash needed (e.g. "https://youragency.com"). */
+    baseUrl: string;
+    /** Route prefix for case studies. Defaults to "/work". */
+    basePath?: string;
+    changeFrequency?: PortfolioSitemapEntry['changeFrequency'];
+    priority?: number;
+}): Promise<PortfolioSitemapEntry[]>;
 
-export { generatePortfolioMetadata, generatePortfolioStaticParams, getPortfolioBrandConfig, getPortfolioCategories, getPortfolioItem, getPortfolioItems };
+export { PortfolioApiError, PortfolioContractError, type PortfolioSitemapEntry, assertPortfolioItemShape, generatePortfolioCategoryStaticParams, generatePortfolioIndexMetadata, generatePortfolioMetadata, generatePortfolioSitemapEntries, generatePortfolioStaticParams, getPortfolioBrandConfig, getPortfolioCategories, getPortfolioItem, getPortfolioItems, slugifyCategory };