@c15t/nextjs 2.2.1 → 3.0.0-alpha.0

package/docs/frameworks/next/data-fetching.md

@@ -0,0 +1,74 @@
+---
+title: Data fetching
+description: Choose cached manifests for a Next.js server, backend
+  initialization for a simpler setup, or offline mode for local development.
+group: frameworks
+---
+
+## Cached manifests
+
+Recommended for Next.js deployments with a server.
+
+A manifest contains public policy configuration, such as the rules used to
+decide which consent permissions apply. Your Next.js server caches this data
+and resolves consent separately for each visitor. Reusing the manifest avoids
+asking the backend to resolve policy on every request.
+
+```text
+          Inth policy
+               ↓
+    Next.js manifest cache
+               ↓
+Request → Consent decision
+
+Choices → Inth records
+```
+
+Policy data is shared through the cache. Each visitor's decision uses their
+location, privacy signals and saved choices. Consent submissions still go to
+Inth.
+
+Follow the [App Router](./app-router.md) or
+[Pages Router](./pages-router.md) setup. Both configure the
+manifest route explicitly. A `backendURL` alone does
+not enable manifests.
+
+You can prepare consent during server rendering or initialize it in the browser.
+See [rendering choices](./server-side.md).
+
+## Backend initialization
+
+Use regular backend `/init` when you want fewer configuration steps, or when
+[exporting a static site](./static-export.md) that cannot run
+Next.js API routes.
+
+c15t asks the backend to resolve consent when initialization is needed. This
+requires only `backendURL` in your consent configuration, with no local manifest
+or init handlers. Inth still manages policy and stores consent records.
+
+Start with [client-side initialization](./client-side.md) for
+a complete setup. You can also use backend initialization with server prefetch,
+as shown in the router guides.
+
+## Offline mode
+
+Not recommended for production environments.
+
+Use offline mode for local development, tests or demos that do not need backend
+records. It resolves bundled policy rules and keeps choices in browser storage.
+It makes no consent backend requests and does not look up the visitor's location.
+
+See the [offline configuration example](./api-reference/data-fetching.md#offline-configuration).
+
+## Hosting and further configuration
+
+We recommend Inth to manage your backend. A
+[self-hosted backend](https://c15t.com/docs/self-host/quickstart) supports both manifests and
+regular initialization, but you operate its database, policies and availability.
+Hosting is a separate choice from how your application fetches consent data.
+
+For optional same-origin rewrites and cache settings, see
+[Optimization](./optimization.md). Use the
+[fetching reference](./api-reference/data-fetching.md) for exact
+URL behavior and location headers, or
+[Troubleshooting](./troubleshooting.md) if consent fails to initialize.

package/docs/frameworks/next/geography-headers.md

@@ -0,0 +1,251 @@
+---
+title: Forward geography headers
+description: Use c15tProxy in Next.js proxy.ts or middleware.ts so Server
+  Components and Route Handlers receive the visitor's country and region.
+group: frameworks
+---
+
+## When do I need the proxy?
+
+Add `c15tProxy` when your hosting platform exposes the visitor's location to
+Next.js middleware or proxy but strips those headers before Server Components
+and Route Handlers run. Without them, `resolveConsent`, the awaited
+server helpers and the optional local `/api/c15t/init` handler see an unknown
+location and apply your unknown-location policy rule for every visitor.
+
+c15t reads location from the platform headers listed in
+[Which headers are read?](#which-headers-are-read): Cloudflare (`cf-ipcountry`,
+`cf-region-code`), Vercel (`x-vercel-ip-country`,
+`x-vercel-ip-country-region`), the `x-amz-cf-ipcountry` header some
+CloudFront setups add, and generic
+proxy headers (`x-country-code`, `x-country`, `x-region-code`). c15t does not
+keep a list of which hosts strip them. Check your deployment: log
+`(await headers()).get('x-vercel-ip-country')` or the equivalent for your host
+inside a Server Component. If the value is present, you do not need the proxy.
+If it is missing while the same header is present in `proxy.ts`, add the proxy.
+
+The proxy copies the incoming request headers, resolves country, region and
+Global Privacy Control from them, and forwards the result on the request as
+`x-c15t-country`, `x-c15t-region` and `sec-gpc`. Those application override
+headers have the highest precedence, so Server Components and Route Handlers
+read the same values the proxy saw. When no location header is present, the
+proxy sets nothing and the location stays unknown.
+
+The proxy runs on Next.js `^15.0.0 || ^16.0.0`. It does not apply to a
+[static export](./static-export.md), which has no server.
+
+## Add the proxy (Next.js 16)
+
+Create `proxy.ts` at the project root, or in `src/` if your app lives there:
+
+```ts title="proxy.ts"
+import { c15tProxy } from 'c15t/next/proxy';
+import type { NextRequest } from 'next/server';
+
+export function proxy(request: NextRequest) {
+  return c15tProxy(request);
+}
+
+export const config = {
+  matcher: ['/((?!_next/static|_next/image|favicon.ico).*)'],
+};
+```
+
+`c15tProxy` returns `NextResponse.next()` with the forwarded request headers.
+If you already have a proxy, call `c15tProxy(request)` where you would
+otherwise return `NextResponse.next()`, and set any response headers or
+cookies on the returned response.
+
+`config.matcher` must cover every page that renders `ConsentRoot`,
+because `resolveConsent` and the awaited helpers run during those page
+requests. It must also cover `/api/c15t/:path*` if you serve the optional local
+init route and want it to resolve policy with the visitor's location. The
+manifest route serves public policy data and does not need location.
+
+## Add the middleware (Next.js 15)
+
+On Next.js 15 the file is `middleware.ts` and the export is `middleware`:
+
+```ts title="middleware.ts"
+import { c15tMiddleware } from 'c15t/next/middleware';
+import type { NextRequest } from 'next/server';
+
+export function middleware(request: NextRequest) {
+  return c15tMiddleware(request);
+}
+
+export const config = {
+  matcher: ['/((?!_next/static|_next/image|favicon.ico).*)'],
+};
+```
+
+`c15tMiddleware` is the same function as `c15tProxy` under the Next.js 15
+name. Both imports stay supported on both Next.js versions. When you upgrade to
+Next.js 16 and rename `middleware.ts` to `proxy.ts`, switch the import to
+`c15tProxy` from `c15t/next/proxy` at the same time. The options type is
+exported as `C15tMiddlewareOptions` and `C15tProxyOptions` respectively.
+
+## Persist geography in cookies
+
+Pass `cookie: true` to also write the resolved location into cookies. Use this
+on runtimes where the forwarded request headers do not reach React Server
+Components, so that your own server code can read the location on later
+requests. The proxy writes the cookie on the response, and `cookies()` reads
+the incoming request, so the first visit still resolves as unknown and the
+first request after a location change still sees the previous value:
+
+```ts title="proxy.ts"
+import { c15tProxy } from 'c15t/next/proxy';
+import type { NextRequest } from 'next/server';
+
+export function proxy(request: NextRequest) {
+  return c15tProxy(request, { cookie: true });
+}
+```
+
+The default cookie names are `c15t-country` and `c15t-region`. Both are set
+with `httpOnly: true`, `sameSite: 'lax'` and `path: '/'`, so browser scripts
+cannot read them. Pass an object to rename them:
+
+```ts title="proxy.ts (partial)"
+c15tProxy(request, {
+  cookie: { countryName: 'geo-country', regionName: 'geo-region' },
+});
+```
+
+A cookie is written only when the matching header resolved a value. The
+proxy never clears a stale cookie, so a visitor whose location header
+disappears keeps the previous cookie until it is cleared or the session cookie
+expires.
+
+The c15t server helpers read request headers, not these cookies. To use the
+cookie, read it where you call `resolveConsent` and pass it as the
+`country` override:
+
+```tsx title="app/layout.tsx (partial)"
+import type { ReactNode } from 'react';
+import { cookies } from 'next/headers';
+import { resolveConsent } from 'c15t/next/server';
+import { consentConfig } from '../c15t.config';
+import { Consent } from '../components/consent';
+
+async function ResolvedConsent({ children }: { children: ReactNode }) {
+  const country = (await cookies()).get('c15t-country')?.value;
+  const state = await resolveConsent({
+    config: consentConfig,
+    country,
+  });
+  return <Consent state={state}>{children}</Consent>;
+}
+```
+
+This is the `ResolvedConsent` component from the
+[App Router guide](./app-router.md); keep it inside the
+`Suspense` boundary shown there.
+
+`resolveConsent` accepts `country` and `language` overrides. It has no
+`region` override in the current API, so the region cookie is available only to
+your own code.
+
+The cookie comes back in the client-controlled `Cookie` header. `HttpOnly`
+stops page scripts from reading it; it does not stop a visitor from sending
+`c15t-country=<value>` and, through the `country` override, choosing a less
+restrictive rule for themselves. Deleting the incoming cookie is not an
+option here, because `cookies()` reads that same request and `c15tProxy` only
+sets the cookie on the response. Use this fallback only when the edge that
+terminates all traffic overwrites the incoming `c15t-country` and
+`c15t-region` cookies with its own trusted geography on every request, or
+when your code signs the value and verifies the signature before passing it
+as `country`. Where you can do neither, keep the cookie out of policy
+resolution and use it only for non-policy code such as display defaults.
+
+## Which headers are read?
+
+`c15tProxy` and the server helpers use the same extraction from
+`@c15t/schema`. Within each group, the first header with a value wins:
+
+| Input                  | Headers, highest precedence first                                                                            | Source                                                 |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------ |
+| Country                | `x-c15t-country`, `cf-ipcountry`, `x-vercel-ip-country`, `x-amz-cf-ipcountry`, `x-country-code`, `x-country` | c15t override, Cloudflare, Vercel, CloudFront, generic |
+| Region                 | `x-c15t-region`, `cf-region-code`, `x-vercel-ip-country-region`, `x-region-code`                             | c15t override, Cloudflare, Vercel, generic             |
+| Global Privacy Control | `x-c15t-gpc`, `sec-gpc`                                                                                      | c15t override, browser signal                          |
+| Language               | `accept-language`                                                                                            | browser                                                |
+
+CloudFront's own geolocation headers, `CloudFront-Viewer-Country` and
+`CloudFront-Viewer-Country-Region`, are not in this list. Forward them to the
+origin with an origin request policy, then map them in `proxy.ts` before
+calling `c15tProxy`. An origin request policy forwards headers but cannot
+rename them. A CloudFront Function can also read geography headers when a
+cache policy or origin request policy exposes them to the function, as shown
+in [AWS's viewer-request example](https://github.com/aws-samples/amazon-cloudfront-functions/tree/main/redirect-based-on-country).
+
+Clear every country and region input c15t recognizes before mapping the
+trusted CloudFront values:
+
+```ts title="proxy.ts"
+import { c15tProxy } from 'c15t/next/proxy';
+import { NextRequest } from 'next/server';
+
+export function proxy(request: NextRequest) {
+  const headers = new Headers(request.headers);
+  for (const name of [
+    'x-c15t-country',
+    'cf-ipcountry',
+    'x-vercel-ip-country',
+    'x-amz-cf-ipcountry',
+    'x-country-code',
+    'x-country',
+    'x-c15t-region',
+    'cf-region-code',
+    'x-vercel-ip-country-region',
+    'x-region-code',
+  ]) {
+    headers.delete(name);
+  }
+  const country = headers.get('cloudfront-viewer-country');
+  const region = headers.get('cloudfront-viewer-country-region');
+  if (country) headers.set('x-c15t-country', country);
+  if (region) headers.set('x-c15t-region', region);
+  return c15tProxy(new NextRequest(request, { headers }));
+}
+```
+
+The `delete` calls drop client-supplied overrides and fallback geography
+headers. When CloudFront omits a country or region, that value stays unknown
+instead of falling through to a header supplied by the visitor.
+
+GPC values are meaningful only as `1` or `0`; any other value is treated as
+absent. The proxy writes the normalized result to `sec-gpc`, so an incoming
+`x-c15t-gpc: 1` reaches Server Components as `sec-gpc: 1`. Browsers refuse to
+let scripts set `Sec-*` request headers, which is why the `x-c15t-gpc` override
+exists for the browser's own init request.
+
+Only trusted infrastructure may set `x-c15t-country`, `x-c15t-region` or
+`x-c15t-gpc` in production, because they always win. A client that sends them
+chooses its own policy rule, and `c15tProxy` forwards a client-supplied value
+over the platform header rather than stripping it. The edge that terminates all
+traffic must therefore delete incoming `x-c15t-*` headers before anything sets
+them, in every deployment. Blocking direct origin access with a firewall or
+platform origin protection is an additional control that keeps requests on that
+edge; it does not replace the stripping, because a forwarded client header
+still passes through the protected path.
+
+## Verify
+
+Deploy with the proxy and load the site from two locations with different
+configured policy rules, for example through a VPN or your host's geo testing
+tools. After server prefetch resolves, the rendered consent policy must match
+each location: an opt-in region shows the banner with optional categories denied, while a region
+configured for notice-only or no notice renders accordingly. Confirm the values
+by logging `(await headers()).get('x-c15t-country')` in a Server Component;
+it should equal the platform header seen in the proxy.
+
+Remove the proxy temporarily and reload. If both locations now resolve the
+unknown-location rule, your platform strips location headers before Server
+Components and the proxy is required. If they still resolve correctly, your
+platform already passes the headers through and the proxy is optional.
+
+With the local init route in the matcher, request `/api/c15t/init` from each
+location and confirm its `policyResolution` reflects the location. If you use
+`cookie: true`, check the response for `Set-Cookie: c15t-country=...` with
+`HttpOnly` and `SameSite=Lax`.

package/docs/frameworks/next/headless.md

@@ -1,192 +1,102 @@
 ---
-title: Headless Mode
-description: Build fully custom consent UI using only hooks - no pre-built
-  components required.
+title: Headless
+description: Build a custom consent banner in Next.js with the
+  c15t/next/headless hooks inside your existing ConsentRoot.
 group: frameworks
 ---
-c15t's headless mode means using the hooks (`useConsentManager`, `useTranslations`, etc.) without any pre-built UI components. This gives you complete control over the consent experience.
-
-Before you go headless, walk the customization ladder in order:
-
-1. **Pre-built components** - Use provider options, component props, tokens, slots, and `theme.consentActions`
-2. **Compound components** - Rearrange c15t primitives when the markup order must change
-3. **`noStyle`** - Keep c15t structure but replace its styling
-4. **Headless** - Use only hooks and build the entire UI yourself
-
-## When to Go Headless
-
-Go headless when:
-
-* Your design system requires complete control over markup
-* You need a consent flow that doesn't fit the banner/dialog pattern
-* You want to embed consent choices inline rather than as overlays
-
-Use a lower-power tool instead when:
-
-* The component structure works but the styling doesn't -> use tokens, slots, or `noStyle`
-* You only need to rearrange existing c15t parts -> use compound components
-* You want to change copy -> use `ConsentManagerProvider.options.i18n`
-* You only need to restyle stock actions -> use `theme.consentActions`
-
-> ⚠️ **Warning:**
-> Headless mode is not the first answer for pure theming. If you are still trying to debug why a banner footer color did not change, stay in the styling system and verify the token-to-component mapping before you rebuild the UI.
-
-> ℹ️ **Info:**
-> Need a policy-aware implementation guide? See Building Headless Components.
-
-## Full Example: Custom Consent Banner
-
-```tsx
-import { useConsentManager, useTranslations } from '@c15t/nextjs';
-
-function CustomConsentBanner() {
-  const {
-    activeUI,
-    consents,
-    consentCategories,
-    consentTypes,
-    saveConsents,
-    setSelectedConsent,
-    selectedConsents,
-  } = useConsentManager();
-  const translations = useTranslations();
-
-  if (activeUI !== 'banner') return null;
-
-  const displayedTypes = consentTypes.filter(
-    (t) => consentCategories.includes(t.name) && t.display
-  );
-
-  return (
-    <div className="fixed bottom-0 inset-x-0 bg-white border-t p-6 shadow-lg z-50">
-      <h2 className="text-lg font-semibold">
-        {translations.cookieBanner.title}
-      </h2>
-      <p className="text-sm text-gray-600 mt-1">
-        {translations.cookieBanner.description}
-      </p>
-
-      <div className="mt-4 space-y-3">
-        {displayedTypes.map((type) => (
-          <label key={type.name} className="flex items-center gap-3">
-            <input
-              type="checkbox"
-              checked={selectedConsents[type.name] ?? consents[type.name] ?? false}
-              disabled={type.disabled}
-              onChange={(e) => setSelectedConsent(type.name, e.target.checked)}
-            />
-            <div>
-              <span className="font-medium">
-                {translations.consentTypes[type.name]?.title ?? type.name}
-              </span>
-              <p className="text-xs text-gray-500">{type.description}</p>
-            </div>
-          </label>
-        ))}
-      </div>
-
-      <div className="mt-4 flex gap-3">
-        <button
-          onClick={() => saveConsents('necessary')}
-          className="px-4 py-2 border rounded"
-        >
-          {translations.common.rejectAll}
-        </button>
-        <button
-          onClick={() => saveConsents('custom')}
-          className="px-4 py-2 border rounded"
-        >
-          {translations.common.save}
-        </button>
-        <button
-          onClick={() => saveConsents('all')}
-          className="px-4 py-2 bg-blue-600 text-white rounded"
-        >
-          {translations.common.acceptAll}
-        </button>
-      </div>
-    </div>
-  );
-}
-```
 
-## Usage with Provider
-
-The headless UI still needs a `ConsentManagerProvider`:
-
-```tsx
-import { type ReactNode } from 'react';
-import { ConsentManagerProvider } from '@c15t/nextjs';
-
-export function ConsentManager({ children }: { children: ReactNode }) {
-  return (
-    <ConsentManagerProvider
-      options={{
-        mode: 'hosted',
-        backendURL: '/api/c15t',
-        consentCategories: ['necessary', 'measurement', 'marketing'],
-      }}
-    >
-      <CustomConsentBanner />
-      {children}
-    </ConsentManagerProvider>
-  );
+## When to go headless
+
+The pre-built banner and dialog cover most designs through props, slots, and
+the stylesheet. Go headless when your markup has to be something else
+entirely: a design system component, a native sheet, or a layout the compound
+parts cannot express.
+
+Headless code owns the rendered controls, so it also owns the compliance
+outcome. The hooks hand you the actions a policy requires, the rights it must
+keep reachable, and diagnostics when your presentation drops one. Render from
+those lists rather than from a fixed set of buttons, and a site that later adds
+a notice region keeps working without a code change.
+
+Check for a policy before rendering your own surfaces. `useModel()` from
+`c15t/next` returns `null` while no rule has resolved and `'none'` under a rule
+that owes no consent UI, and the pre-built surfaces render nothing in that
+state.
+
+## Minimal example
+
+The headless hooks read the runtime from the `ConsentRoot` set up in your
+[App Router](./app-router.md) or
+[Pages Router](./pages-router.md) guide, so they only run in a
+Client Component. Render this component inside that existing root in place
+of the stock banner. Keep the dialog and persistent preferences control.
+
+```tsx title="components/consent-banner.tsx"
+'use client';
+
+import { useHeadlessConsentUI, useTranslations } from 'c15t/next/headless';
+
+const ACTION_LABELS = {
+	accept: 'acceptAll',
+	reject: 'rejectAll',
+	customize: 'customize',
+	dismiss: 'acknowledge',
+	save: 'save',
+} as const;
+
+export function Banner() {
+	const { banner, performAction, openDialog } = useHeadlessConsentUI();
+	const { common, rights } = useTranslations();
+
+	if (!banner.isVisible) {
+		return null;
+	}
+
+	return (
+		<section role="region" aria-label="Privacy">
+			{banner.preferenceControls.map((right) => (
+				<button key={right} type="button" onClick={openDialog}>
+					{right === 'opt-out' ? rights?.optOut : rights?.preferences}
+				</button>
+			))}
+			{banner.actionGroups.map((group) => (
+				<div key={group.join('-')}>
+					{group.map((action) => (
+						<button
+							key={action}
+							type="button"
+							data-primary={banner.primaryActions.includes(action) || undefined}
+							onClick={() => performAction(action)}
+						>
+							{common[ACTION_LABELS[action]]}
+						</button>
+					))}
+				</div>
+			))}
+		</section>
+	);
 }
 ```
 
-## Custom Dialog
-
-Build a custom consent dialog for detailed category management:
-
-```tsx
-import { useConsentManager, useTranslations } from '@c15t/nextjs';
-
-function CustomConsentDialog() {
-  const {
-    activeUI,
-    setActiveUI,
-    consentTypes,
-    consentCategories,
-    selectedConsents,
-    consents,
-    setSelectedConsent,
-    saveConsents,
-    has,
-  } = useConsentManager();
-  const translations = useTranslations();
-
-  if (activeUI !== 'dialog') return null;
-
-  return (
-    <div className="fixed inset-0 z-50 flex items-center justify-center">
-      <div className="absolute inset-0 bg-black/50" onClick={() => setActiveUI('none')} />
-      <div className="relative bg-white rounded-xl p-6 max-w-md w-full">
-        <h2 className="text-lg font-semibold">{translations.consentManagerDialog.title}</h2>
-
-        {consentTypes
-          .filter((t) => consentCategories.includes(t.name))
-          .map((type) => (
-            <div key={type.name} className="flex items-center justify-between py-3 border-b">
-              <div>
-                <p className="font-medium">{translations.consentTypes[type.name]?.title}</p>
-                <p className="text-sm text-gray-500">{type.description}</p>
-              </div>
-              <input
-                type="checkbox"
-                checked={selectedConsents[type.name] ?? consents[type.name] ?? false}
-                disabled={type.disabled}
-                onChange={(e) => setSelectedConsent(type.name, e.target.checked)}
-              />
-            </div>
-          ))}
-
-        <div className="mt-4 flex justify-end gap-2">
-          <button onClick={() => saveConsents('necessary')}>Reject</button>
-          <button onClick={() => saveConsents('custom')}>Save</button>
-          <button onClick={() => saveConsents('all')}>Accept All</button>
-        </div>
-      </div>
-    </div>
-  );
-}
-```
+`banner.actionGroups` is the resolved layout: reject and accept share a group
+at equal prominence, and the rest follow. `banner.orderedActions` is the same
+list flattened. Under a notice the only action is `dismiss`, and
+`banner.preferenceControls` recommends additional buttons for opening
+preferences. Under a notice it contains `opt-out`, which selects the
+"Do not sell or share my data" label. The example renders that button and
+an "OK" button. Both controls keep their own command: opening
+preferences and dismissing the notice.
+
+The list is a rendering helper. It does not establish that your UI implements
+all policy rights. Provide disclosure and persistent preferences access.
+
+`performAction` saves all categories for `accept`, none for `reject`, the
+current draft for `save`, records a dismissal for `dismiss`, and opens the
+preference center for `customize`. `banner.diagnostics` reports when a host
+layout drops a required action or gives equivalent actions different
+prominence. Review each diagnostic when configuring custom presentation.
+
+`banner.variant`, `banner.position`, and `banner.blocking` carry the resolved
+shape from `presentation.prompt`, so a headless surface can follow the same
+bar, widget, or wall choice the pre-built banner would make, and can trap
+focus and lock scroll exactly when `blocking` is true.