@c15t/nextjs 2.2.0 → 3.0.0-alpha.0

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

@@ -0,0 +1,416 @@
+---
+title: Fetching reference
+description: Reference for Next.js consent URLs, manifest resolution, request
+  geography and offline configuration.
+group: frameworks
+---
+
+## URL configuration
+
+`defineConsentConfig` from `c15t/next` declares the URLs shared by
+`resolveConsent` and `ConsentRoot`. For help choosing a setup, start with
+[data fetching](../data-fetching.md).
+Requires Next.js 15 or 16 (`next ^15.0.0 || ^16.0.0`).
+
+| Property      | Behavior                                                                                                                                            |
+| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `backendURL`  | Required backend base URL. Consent submissions go to `/subjects` under this URL. Without `manifestURL`, server prefetch calls its `/init` endpoint. |
+| `manifestURL` | Optional URL that serves the policy manifest. Setting it enables manifest resolution.                                                               |
+| `initURL`     | Optional browser initialization endpoint. With the local manifest handler, this resolves policy using the browser request's geography.              |
+
+The current API does not derive `manifestURL` or `initURL` from `backendURL`,
+and declaring URLs does not create routes. Values can be absolute HTTP or
+HTTPS URLs or paths beginning with `/`. Server helpers resolve relative paths
+against the incoming request's host.
+
+`defineConsentConfig` validates at call time and throws a `TypeError` when the
+argument is not an object, when `backendURL` is missing, or when any URL is
+neither an absolute `http(s)` URL nor a `/`-relative path. Protocol-relative
+`//consent.example.com` and bare `api/c15t` are rejected because the server
+helpers would resolve them against the request host and reach an unintended
+origin. The returned object is frozen. When `initURL` is set without
+`manifestURL` and `NODE_ENV` is not `production`, it logs a `console.warn`:
+browser initialization would use the init route, but server prefetch would
+still call backend `/init` on every request. Set `manifestURL` so both sides
+resolve the cached manifest.
+
+### Why are the URLs separate?
+
+`backendURL` usually points to Inth, while the manifest and local init routes
+belong to your Next.js application. Appending `/manifest` to the Inth URL would
+select Inth's endpoint, not create or select your app's cached manifest route.
+Using `/api/c15t` as the backend prefix through an optional rewrite does not
+change the config defaults.
+
+The manifest **handler** does derive its upstream `/manifest` URL from its
+backend URL. That server-side default is separate from `defineConsentConfig`,
+which keeps the URLs you pass to it and does not choose a fetching mode for you.
+
+### Do I need the local init route?
+
+No. The router guides use server prefetch and one manifest route. Successful
+prefetch supplies the initial policy directly to the browser.
+
+Add a local init route when browser initialization needs your host's location
+headers or you want to keep manifest resolution on the server. It resolves the
+cached manifest in your app instead of calling the backend's `/init`.
+
+Add `initURL: '/api/c15t/init'` to your existing `defineConsentConfig` value,
+keeping `backendURL` and `manifestURL`. Then add the handler for your router.
+It reads the same absolute upstream backend environment variable as your
+manifest handler.
+
+```ts title="app/api/c15t/init/route.ts"
+export { GET } from 'c15t/next/api';
+```
+
+For Pages Router, use this file instead:
+
+```ts title="pages/api/c15t/init.ts"
+import { createPagesApiHandlers } from 'c15t/next/pages';
+
+export default createPagesApiHandlers().init;
+```
+
+Without `initURL`, browser initialization resolves the manifest locally. It
+uses location supplied by prefetch or your application, but cannot read your
+host's geographic headers itself. See [geography and privacy signals](#geography-and-privacy-signals).
+
+### Transport combinations
+
+| Consent config                         | Server prefetch                           | Browser initialization                                                         |
+| -------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------ |
+| `backendURL`, `manifestURL`, `initURL` | Resolves the manifest with request inputs | Calls `initURL`, whose local handler resolves the manifest with request inputs |
+| `backendURL`, `manifestURL`            | Resolves the manifest with request inputs | Loads the manifest resolver lazily in the browser                              |
+| `backendURL` only                      | Calls backend `/init`                     | Calls backend `/init`                                                          |
+| `backendURL`, `initURL`                | Calls backend `/init`                     | Calls `initURL`                                                                |
+| Explicit `options.mode: offline()`     | No hosted prefetch                        | Resolves bundled local rules                                                   |
+
+Hosted combinations submit choices to `${backendURL}/subjects`. Offline mode
+uses browser persistence only. A prepared server result can satisfy the first
+browser initialization; the browser column describes what happens when
+initialization is needed, including recovery after prefetch fails.
+
+Setting only `initURL` does not enable server manifest resolution. Keep
+`manifestURL` when both server and browser requests should resolve the cached
+manifest.
+
+### Switch to regular backend init
+
+Remove `manifestURL` and `initURL` from `c15t.config.ts`. The
+[browser initialization guide](../client-side.md#configure-one-backend-url)
+has a complete backend-only configuration. For server rendering, keep the
+prefetch and boundary wiring from your router guide. Prefetch will call backend
+`/init` per request.
+
+Remove unused local manifest and init handlers. If you use an optional backend
+rewrite, removing the local init handler lets that request reach the backend
+through the rewrite. See [optimization](../optimization.md)
+for rewrite configuration.
+
+## Server helper options
+
+`resolveConsent` is the one server helper. `c15t/next/server` exports it for
+the App Router, where the default request context reads `next/headers` and
+calls `await connection()` from `next/server` before reading the clock.
+`c15t/next/pages` exports the same function for the Pages Router, taking the
+Node `req` instead. Both entries accept the options in this section; the
+Pages Router entry replaces only the `request` adapter.
+
+What `resolveConsent` does depends on whether it has a backend to reach. With
+`config` or `backendURL`, it resolves policy from the manifest or backend
+`/init` and returns the visitor's `ConsentState`. Without either, it makes no
+network request and returns cookie- and header-only state; see
+[cookie-only state](#cookie-only-state).
+
+### resolveConsent options
+
+| Option           | Default              | Behavior                                                                                                                                                                                                                   |
+| ---------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `backendURL`     | `config.backendURL`  | Backend base URL. An explicit value overrides `config.backendURL`. Without a manifest source, `resolveConsent` calls `${backendURL}/init`. Omit both `backendURL` and `config` for cookie-only state.                      |
+| `config`         | none                 | A `defineConsentConfig` result supplying `backendURL` and `manifestURL`. Explicit options on this bag win over its fields. `initURL` is not read.                                                                          |
+| `manifestURL`    | `config.manifestURL` | Manifest route URL. When set, server prefetch resolves policy from the manifest and does not call backend `/init`.                                                                                                         |
+| `manifest`       | none                 | Inline manifest object used instead of fetching `manifestURL`. Any `manifestURL` is still resolved first, so a relative one needs a request host.                                                                          |
+| `fetch`          | `globalThis.fetch`   | Fetch implementation for the backend `/init` or manifest request. Wrap it in Next.js fetch caching only in manifest mode; the `/init` call carries visitor cookies and returns per-visitor state, so keep it uncached.     |
+| `forwardHeaders` | `[]`                 | Request header names copied onto the outgoing call. Backend `/init` also forwards `x-forwarded-for` and `user-agent` automatically; manifest requests forward only this list. Headers absent from the request are skipped. |
+| `onError`        | none                 | Receives the failure from the backend or manifest request. When omitted, failures are logged with `console.warn` only when `NODE_ENV` is not `production`.                                                                 |
+| `now`            | `Date.now()`         | Clock used to validate stored records and stamped into the result.                                                                                                                                                         |
+| `cookieName`     | `c15t`               | Cookie holding persisted consent. Must match the client `storageConfig.storageKey`.                                                                                                                                        |
+| `country`        | header detection     | Overrides the country read from request headers.                                                                                                                                                                           |
+| `language`       | header detection     | Overrides the language read from `accept-language`.                                                                                                                                                                        |
+| `request`        | `next/headers`       | Request context adapter with `cookies()` and `headers()`. The default only works in the App Router.                                                                                                                        |
+
+`resolveConsent` throws when the request adapter's `headers()` or `cookies()`
+rejects (the default adapter rejects outside a request scope), and when your
+`onError` callback throws. Thrown URL resolution, network and policy
+resolution errors are handled: they return the same baseline state as the
+cookie-only call, with stored records, geography, language and GPC from the
+request but no resolved policy. The page still renders and the browser initializes
+consent on mount. Non-2xx responses from backend `/init` are failures too, so
+a `500` renders the baseline rather than throwing. A successful response whose
+body reports `policyResolution.status: 'failed'`, for example an unsupported
+policy contract, is different: that failed resolution is kept as the prepared
+state, the browser does not re-initialize on mount, and the consent UI stays
+hidden until the cause is fixed.
+
+Absolute `http(s)` URLs are used as given. A `/`-relative `backendURL` or
+`manifestURL` is resolved from the request: the scheme comes from
+`x-forwarded-proto` and defaults to `https`; the host comes from
+`x-forwarded-host`, then `host`, then the `referer` host. When no host is available, `resolveConsent` reports the error
+and returns the baseline state. Those headers decide where the server sends
+the request, so behind a proxy the edge must overwrite `x-forwarded-host` and
+`x-forwarded-proto` rather than pass client values through; otherwise a client
+can point server prefetch at a host of its choosing. When you cannot guarantee
+that, use absolute URLs. Use `https` for any production `backendURL`: the
+`/init` call forwards the visitor's cookies, which plain HTTP exposes on the
+path; keep `http` for local development only.
+
+Forwarded headers differ by path. The backend `/init` call carries the
+request cookies, `x-forwarded-for`, `user-agent`, any `forwardHeaders`, and
+derived `x-c15t-country`, `x-c15t-region`, `accept-language` and `sec-gpc`
+headers; it is sent with `cache: 'no-store'` and `credentials: 'include'`.
+The manifest request carries only the headers named in `forwardHeaders`.
+Cookies, the client IP and the user agent are not added automatically, because
+the manifest is public policy data, but an explicit entry is forwarded
+verbatim: a `forwardHeaders` list that names `cookie`, `x-forwarded-for` or
+`user-agent` sends them to the manifest host too, so do not reuse a list meant
+for the backend path. Cookies are still read locally on both paths to restore
+records.
+
+An inline `manifest` is never refreshed. The manifest transport returns the
+object as given instead of fetching it, so the snapshot is the source of truth
+for that request rather than a cache seed. A stale snapshot resolves stale
+policy until the application ships a new one. One request can still happen:
+when the inline manifest has `iab.enabled: true` with an `iab.gvl` reference
+and the matched rule uses the `iab` model, the transport fetches the Global
+Vendor List with the `fetch` option, and a blocked network there also falls
+back to the baseline. `backendURL` is still required because choices post to
+`${backendURL}/subjects`.
+
+`onError` replaces the default logging entirely. Without it, production
+deployments render the baseline silently; pass `onError` to report failures to
+your monitoring. `cookieName` must match the client `storageKey` for stored
+choices to be restored at all: with a mismatch the server supplies empty
+records, the provider treats them as prepared and skips browser hydration, so
+the visitor's existing choice stays ignored for the whole mount, not only at
+first paint.
+
+### Cookie-only state
+
+Call `resolveConsent` with no `config` and no `backendURL` when rendering
+needs the visitor's stored records but not a resolved policy. It makes no
+network request. It reads the request and returns a JSON-serializable
+`ConsentState` with `initialRecords`, `initialPrivacySignals.gpc`, `now` and,
+when any value was detected, `initialOverrides` with `country`, `region` and
+`language`. It does not set cookies and does not cache across requests. Only
+these options apply:
+
+| Option       | Default          | Behavior                                                                                            |
+| ------------ | ---------------- | --------------------------------------------------------------------------------------------------- |
+| `now`        | `Date.now()`     | Clock used to validate stored records and stamped into the result.                                  |
+| `cookieName` | `c15t`           | Cookie holding persisted consent. Must match the client `storageConfig.storageKey`.                 |
+| `country`    | header detection | Overrides the country read from request headers.                                                    |
+| `language`   | header detection | Overrides the language read from `accept-language`.                                                 |
+| `request`    | `next/headers`   | Request context adapter with `cookies()` and `headers()`. The default only works in the App Router. |
+
+The cookie header is read from `headers().get('cookie')` first and from
+`request.cookies()` only when that header is absent. Country and region come
+from the headers listed in [geography and privacy signals](#geography-and-privacy-signals).
+
+### Types
+
+| Type                         | Exported from                                      | What it names                                                                        |
+| ---------------------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------ |
+| `ConsentState`               | `c15t/next`, `c15t/next/server`, `c15t/next/pages` | The value `resolveConsent` returns and `ConsentRoot` takes as `state`                |
+| `ResolveConsentOptions`      | `c15t/next/server`                                 | The App Router options bag                                                           |
+| `ConsentRequestOptions`      | `c15t/next/server`                                 | The request-reading subset: `now`, `cookieName`, `country`, `language`, `request`    |
+| `PagesResolveConsentOptions` | `c15t/next/pages`                                  | `ResolveConsentOptions` with `req` in place of `request`                             |
+| `ConsentRootProps`           | `c15t/next`                                        | Props of `ConsentRoot`; `ConsentRootProps['state']` also accepts the pending promise |
+| `ConsentConfig`              | `c15t/next`, `c15t/next/server`, `c15t/next/pages` | The frozen `defineConsentConfig` result passed as `config`                           |
+
+### Pages Router differences
+
+`c15t/next/pages` exports `resolveConsent` with the Node request in place of
+the `request` adapter. `resolveConsent({ req, ...options })` accepts every
+option in the App Router table except `request`; `req` is the request from
+`getServerSideProps` or an API route. Omitting `config` and `backendURL`
+returns cookie-only state here too. The result is JSON-compatible, but fields
+that were not detected are `undefined` (for example
+`initialPrivacySignals.gpc` without a `sec-gpc` header), and
+`getServerSideProps` rejects `undefined` values in development. Round-trip the
+result through `JSON.parse(JSON.stringify(result))` before returning it as a
+prop, as `examples/nextjs/pages/pages-router.tsx` does.
+
+`createPagesRequestContext(req)` builds the `request` adapter itself. Headers
+are converted to Web `Headers`, and cookies are read from the `cookie` header.
+Use it when calling the `c15t/next/server` helper from a custom server or
+test harness where `next/headers` is unavailable:
+
+```ts title="server/consent.ts"
+import { resolveConsent } from 'c15t/next/server';
+import { createPagesRequestContext } from 'c15t/next/pages';
+import { consentConfig } from '../c15t.config';
+import type { IncomingMessage } from 'node:http';
+
+export function resolveRequestConsent(req: IncomingMessage) {
+  return resolveConsent({
+    config: consentConfig,
+    request: createPagesRequestContext(req),
+  });
+}
+```
+
+## Route handler options
+
+### createNextConsentRouteHandlers options
+
+`createNextConsentRouteHandlers(optionsOrConfig)` from `c15t/next/api` returns
+`GET` for the init route and `manifestGET` for the manifest route. The
+ready-made `GET` and `manifestGET` exports from the same module are created
+with no options, so they read only environment variables.
+
+| Option                      | Default / env                                           | Behavior                                                                                                                                                                                                                                                                                          |
+| --------------------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `backendURL`                | `C15T_BACKEND_URL`, then `NEXT_PUBLIC_C15T_BACKEND_URL` | Backend base URL. The manifest route fetches `${backendURL}/manifest`. Not read when `manifestURL` is set.                                                                                                                                                                                        |
+| `manifestURL`               | `C15T_MANIFEST_URL`                                     | Full upstream manifest URL. Takes precedence over `backendURL` plus `/manifest`.                                                                                                                                                                                                                  |
+| `manifestRevalidateSeconds` | `300`; env `C15T_MANIFEST_REVALIDATE_SECONDS`           | Next.js Data Cache revalidation for the manifest fetch. `false` disables it; the env value `'false'` also disables it. The env value is read with `parseInt`, so `60seconds` becomes `60` and `1e2` becomes `1`; values without a leading number or below `0` fall back to the default.           |
+| `fetch`                     | `globalThis.fetch`                                      | Fetch implementation for the manifest and Global Vendor List requests.                                                                                                                                                                                                                            |
+| `onBackgroundRevalidate`    | none                                                    | Receives the promise of a background manifest refresh started by a request, so a host can keep it alive with `after` from `next/server` or a platform `waitUntil`. Called inside the handler; the promise never rejects. See [Optimization](../optimization.md#configure-manifest-cache-refresh). |
+| `fetchGvl`                  | built-in cached fetcher                                 | Loads the Global Vendor List for IAB policies. Called only under the conditions described in this section.                                                                                                                                                                                        |
+
+An explicit option wins over its environment variable, and a manifest URL from
+either source wins over `backendURL`. URLs are resolved per request, so a
+missing or invalid value fails the request rather than the build: with neither
+`backendURL` nor `manifestURL` configured the handler throws
+`@c15t/nextjs/api: configure C15T_BACKEND_URL or C15T_MANIFEST_URL.`. A
+`/`-relative value is resolved against the incoming request's host and
+forwarded headers, which points the handler at your own app and lets a client
+that controls `x-forwarded-host` choose the upstream. Keep upstream URLs
+absolute so the manifest route neither fetches itself nor an attacker's host.
+
+Passing a `defineConsentConfig` result uses only its `backendURL`. Its
+`manifestURL` and `initURL` name the routes these handlers serve, so
+forwarding them would make the manifest route fetch itself. The same rule
+applies when the config's `backendURL` is a same-origin rewrite prefix: pass
+the absolute upstream URL instead, as described in
+[optimization](../optimization.md).
+
+`GET` resolves the cached manifest with the request's geography, language and
+GPC headers and responds with `cache-control: private, no-store` and
+`x-c15t-policy-contract: 1`. When the request carries an
+`x-c15t-policy-contract` header with a different value, the response keeps the
+translations and UI data but sets `policyResolution` to `status: 'failed'`
+with `reason: 'unsupported-contract'` and removes `policySnapshotToken` and
+`gvl`. Requests without the header are treated as compatible.
+
+`manifestGET` forwards the upstream `cache-control` header, or
+`public, s-maxage=300, stale-while-revalidate=86400` when the upstream omits
+it, plus `etag` when present and an `age` computed from the in-process cache.
+It adds `content-type: application/json`, `x-c15t-policy-contract: 1` and
+`x-c15t-next-revalidate`, whose value is the upstream `s-maxage` when present,
+`300` when the upstream sends no `cache-control` at all (the default header is
+substituted before `s-maxage` is read), and otherwise the configured
+revalidation interval. A `language` query
+parameter on the manifest route is passed to the upstream manifest request.
+
+`fetchGvl` runs inside `GET` only when the manifest has `iab.enabled: true`,
+the manifest includes an `iab.gvl` reference, and the resolved policy matched
+with `model: 'iab'`. It receives the reference, the `fetch` option, and the
+language taken from the first segment of the resolved translations language
+(`en` when empty). The default fetcher caches the vendor list in process.
+A fetched list becomes a `gvlReference` and a small banner summary in the
+serialized payload. A `null` result keeps IAB unavailable. With
+`config.initURL`, the browser reads the list from that same-origin handler;
+otherwise it uses the manifest's public list URL. See
+[server-rendered vendor data](https://c15t.com/docs/frameworks/javascript/iab/overview#server-rendered-vendor-data)
+for loading and caching behavior.
+
+`createPagesApiHandlers(options)` from `c15t/next/pages` accepts the same
+options or a `defineConsentConfig` result and returns `{ init, manifest }`:
+`init` wraps `GET` and `manifest` wraps `manifestGET`, each taking the Node
+`req` and `res` of a `pages/api` route. Because a `pages/api` default export
+receives every method, requests other than `GET` and `HEAD` are answered with
+`405` and an `allow: GET` header before the wrapped handler runs.
+
+## Manifest request resolution
+
+The [App Router](../app-router.md) and
+[Pages Router](../pages-router.md) manifest setups use this flow:
+
+1. The app's manifest handler fetches the absolute backend's `/manifest`
+   endpoint and caches public policy data.
+2. `resolveConsent({ config: consentConfig })` reads the manifest route,
+   resolves policy with the current request's inputs and restores valid consent
+   cookies.
+3. `ConsentRoot` receives that result as `state` and the URL configuration
+   as `config`. Hydration preserves the resolved state.
+4. If browser initialization is needed, it resolves the manifest locally. An
+   optional `initURL` moves this resolution to the app server.
+5. Browser choices post to `${backendURL}/subjects`.
+
+A warm policy cache avoids backend `/init` during request resolution. The app
+may still read its manifest route, cold caches fetch upstream data, and choices
+still reach the backend. IAB policies can also require a Global Vendor List
+fetch. See [manifest caching](../optimization.md) for cache
+settings, and [server rendering](../server-side.md) for awaiting
+or streaming prefetch results.
+
+## Geography and privacy signals
+
+Server manifest resolution reads location headers from the hosting platform.
+It recognizes country headers such as `cf-ipcountry` and
+`x-vercel-ip-country`, and region headers such as `cf-region-code` and
+`x-vercel-ip-country-region`. The application overrides `x-c15t-country` and
+`x-c15t-region` take precedence. Only trusted infrastructure should supply
+location overrides in production.
+
+Request helpers also read language and GPC. Missing location stays unknown;
+the resolver does not infer country from the Next.js server's IP. Test unknown
+country and region against your configured policy rules.
+
+Browser manifest resolution uses location overrides from prefetch or your
+application. A browser-only entry without those inputs uses unknown location.
+The [optional init route](#do-i-need-the-local-init-route) reads geographic
+headers on the server and keeps resolver code and translations out of browser
+initialization.
+
+## Offline configuration
+
+Not recommended for production environments. Use offline mode for local
+development, tests or demos that do not need backend records.
+
+Omit hosted prefetch and select the offline factory in a Client Component.
+Keep your existing banner, dialog and preferences link as children of this
+root:
+
+```tsx title="app/offline-consent.tsx"
+'use client';
+
+import type { ReactNode } from 'react';
+import { ConsentRoot, offline } from 'c15t/next';
+
+const mode = offline();
+
+export function OfflineConsent({ children }: { children: ReactNode }) {
+  return (
+    <ConsentRoot state={{}} options={{ mode }}>
+      {children}
+    </ConsentRoot>
+  );
+}
+```
+
+The default local policy pack handles missing geography; offline mode does not
+perform IP lookup. Supply `policyRules` to replace that pack when your local
+policy needs different behavior. Browser persistence stores choices, but this
+setup has no backend record service. See
+[transport choices](../../../guides/data-fetching.md) for the tradeoffs.
+
+### Authenticated hosted vendor lists
+
+When hosted `resolveConsent()` forwards cookies or additional request headers,
+or uses a custom `fetch`, it retains the fetched vendor list in server state.
+The browser cannot replay a private server fetch. This fallback preserves consent
+loading and vendor filtering without copying credentials into the page. Its
+payload size is unchanged from inline GVL loading. For compact pages with private
+upstreams, expose the public list through a same-origin manifest init handler.