@c15t/nextjs 2.2.1 → 3.0.0-alpha.1

package/dist-types/api.d.ts

@@ -0,0 +1,88 @@
+import type { ConsentManifest, ConsentManifestGVLReference, GlobalVendorList } from '@c15t/schema/types';
+import type { ConsentConfig } from './config';
+type NextFetchInit = RequestInit & {
+    next?: {
+        revalidate?: number | false;
+        tags?: string[];
+    };
+};
+export interface NextConsentManifestHandlersOptions {
+    /**
+     * Backend base URL that serves `/manifest`.
+     * Defaults to `C15T_BACKEND_URL` or `NEXT_PUBLIC_C15T_BACKEND_URL`.
+     */
+    backendURL?: string;
+    /**
+     * Full manifest URL. Overrides `backendURL + "/manifest"`.
+     * Defaults to `C15T_MANIFEST_URL`.
+     */
+    manifestURL?: string;
+    /**
+     * Next.js Data Cache lifetime for the manifest fetch.
+     * Defaults to the backend manifest route's default `s-maxage` of 300s.
+     */
+    manifestRevalidateSeconds?: number | false;
+    fetch?: typeof globalThis.fetch;
+    /**
+     * Receives the promise of a background manifest revalidation started by
+     * a request, so the host can keep it alive past the response on runtimes
+     * that stop detached work once a response is sent. Called inside the
+     * handler, so `after` from `next/server` (Next 15.1 and later; 15.0
+     * exposes it as `unstable_after`) can be used directly. The promise
+     * never rejects. Not called when the manifest is fresh or the request
+     * itself waits on the upstream.
+     *
+     * @example
+     * ```ts
+     * import { after } from 'next/server';
+     *
+     * createNextConsentRouteHandlers({
+     *   ...consentConfig,
+     *   onBackgroundRevalidate: (refresh) => after(() => refresh),
+     * });
+     * ```
+     */
+    onBackgroundRevalidate?: (revalidation: Promise<void>) => void;
+    fetchGvl?: (input: {
+        reference: ConsentManifestGVLReference;
+        language: string;
+        fetch: typeof globalThis.fetch;
+    }) => Promise<GlobalVendorList | null>;
+}
+export interface ManifestFetchResult {
+    manifest: ConsentManifest;
+    cacheControl: string;
+    etag?: string;
+    revalidate: number | false;
+    status: number;
+}
+export declare const getSMaxAge: (cacheControl: string | null) => number | undefined;
+export declare const createManifestFetchInit: (options?: NextConsentManifestHandlersOptions) => NextFetchInit;
+export declare const fetchCachedManifest: (request: Request, options?: NextConsentManifestHandlersOptions, language?: string | null) => Promise<ManifestFetchResult & {
+    age: number;
+}>;
+/**
+ * Build the App Router route handlers for the consent routes.
+ *
+ * @param options - Handler options, or a `defineConsentConfig` result. From a
+ * config only `backendURL` is used: its `manifestURL` and `initURL` are the
+ * routes these handlers serve.
+ * @returns `GET` for the init route and `manifestGET` for the manifest route.
+ * @example
+ * ```ts
+ * // app/api/consent/manifest/route.ts
+ * import { createNextConsentRouteHandlers } from '@c15t/nextjs/api';
+ * import { consentConfig } from '@/consent.config';
+ *
+ * export const { manifestGET: GET } =
+ *   createNextConsentRouteHandlers(consentConfig);
+ * ```
+ */
+export declare const createNextConsentRouteHandlers: (optionsOrConfig?: NextConsentManifestHandlersOptions | ConsentConfig) => {
+    GET(request: Request): Promise<Response>;
+    manifestGET(request: Request): Promise<Response>;
+};
+export type { ConsentConfig } from './config';
+export { defineConsentConfig } from './config';
+export declare const GET: (request: Request) => Promise<Response>;
+export declare const manifestGET: (request: Request) => Promise<Response>;

package/dist-types/config.d.ts

@@ -0,0 +1,110 @@
+/**
+ * `defineConsentConfig` — the URLs a Next.js consent setup needs, declared
+ * once and shared by the route handlers, `resolveConsent`, and the client
+ * `ConsentRoot`.
+ *
+ * Plain data with no `next` imports, so the same module is safe to import
+ * from a route file, a Server Component, and a `'use client'` file.
+ */
+/**
+ * URLs shared by every side of a Next.js consent setup.
+ */
+export interface ConsentConfig {
+    /**
+     * Backend base URL; `/subjects` writes and, without a manifest, `/init`
+     * reads go here.
+     */
+    backendURL: string;
+    /**
+     * Same-origin route that serves the cached manifest (from
+     * `createNextConsentRouteHandlers`). Enables manifest mode.
+     */
+    manifestURL?: string;
+    /**
+     * Same-origin route that resolves init from the cached manifest with the
+     * request's geo (the handlers' `GET`). Enables geo in the browser without
+     * a backend `/init` call.
+     */
+    initURL?: string;
+}
+/**
+ * Declare the consent URLs once and hand the result to every side of the
+ * setup: `createNextConsentRouteHandlers` (route file), `resolveConsent`
+ * (Server Component or `getServerSideProps`), and `ConsentRoot` (client).
+ * Each reads the fields it needs, so the URLs are never repeated.
+ *
+ * The returned object is frozen plain data: no `next` imports, safe to
+ * import from a `'use client'` file, and serializable as a Server Component
+ * prop.
+ *
+ * @param config - Backend base URL plus the optional same-origin routes.
+ * @returns The validated, frozen config.
+ * @throws {TypeError} When `backendURL` is missing, or any URL is neither an
+ * absolute `http(s)` URL nor a `/`-relative path.
+ * @example
+ * Manifest mode with browser geo, in three files.
+ *
+ * ```ts
+ * // consent.config.ts
+ * import { defineConsentConfig } from '@c15t/nextjs';
+ *
+ * export const consentConfig = defineConsentConfig({
+ *   backendURL: 'https://consent.example.com',
+ *   // Same-origin routes served by the handlers below.
+ *   manifestURL: '/api/consent/manifest',
+ *   initURL: '/api/consent/init',
+ * });
+ * ```
+ *
+ * ```ts
+ * // app/api/consent/manifest/route.ts
+ * import { createNextConsentRouteHandlers } from '@c15t/nextjs/api';
+ * import { consentConfig } from '@/consent.config';
+ *
+ * export const { manifestGET: GET } =
+ *   createNextConsentRouteHandlers(consentConfig);
+ * ```
+ *
+ * ```ts
+ * // app/api/consent/init/route.ts
+ * import { createNextConsentRouteHandlers } from '@c15t/nextjs/api';
+ * import { consentConfig } from '@/consent.config';
+ *
+ * export const { GET } = createNextConsentRouteHandlers(consentConfig);
+ * ```
+ *
+ * ```tsx
+ * // app/layout.tsx
+ * import { ConsentRoot } from '@c15t/nextjs';
+ * import { resolveConsent } from '@c15t/nextjs/server';
+ * import { consentConfig } from '@/consent.config';
+ *
+ * export default async function RootLayout({ children }) {
+ *   const state = await resolveConsent({ config: consentConfig });
+ *   return (
+ *     <html>
+ *       <body>
+ *         <ConsentRoot state={state} config={consentConfig}>
+ *           {children}
+ *         </ConsentRoot>
+ *       </body>
+ *     </html>
+ *   );
+ * }
+ * ```
+ *
+ * With `initURL` set, the browser fetches init from the same-origin
+ * `GET` handler, which resolves the cached manifest with the request's
+ * geo headers, so the visitor's country is known without a backend
+ * `/init` call. Consent saves still post to `${backendURL}/subjects`.
+ * Drop `initURL` to resolve init in the browser from `manifestURL`
+ * (no geo), or drop both for hosted mode against `${backendURL}/init`.
+ */
+export declare const defineConsentConfig: (config: ConsentConfig) => ConsentConfig;
+/**
+ * Whether a value came from {@link defineConsentConfig}. The brand is an
+ * enumerable symbol, so it survives object spread.
+ *
+ * @internal
+ */
+export declare const isConsentConfig: (value: unknown) => value is ConsentConfig;

package/dist-types/devtools.d.ts

@@ -0,0 +1 @@
+export * from '@c15t/react/devtools';

package/dist-types/headers.d.ts

@@ -0,0 +1,4 @@
+import type { ConsentRequestHeaderInputs, ResolveInitFromManifestInputs } from '@c15t/schema/types';
+/** Normalized request values used to resolve consent policy. */
+export type ConsentRequestInputs = ConsentRequestHeaderInputs & ResolveInitFromManifestInputs;
+export { CONSENT_REQUEST_HEADER_NAMES, COUNTRY_HEADERS, consentInputsToOverrides, extractConsentRequestInputs, parseGlobalPrivacyControl, REGION_HEADERS, } from '@c15t/schema/types';

package/dist-types/index.d.ts

@@ -1,14 +1,32 @@
 /**
- * Main entry point for the C15T Next.js integration package.
- * Re-exports all necessary components, hooks, and utilities from the React package
- * and middleware for seamless integration with Next.js applications.
+ * `@c15t/nextjs` Next.js App Router adapter.
  *
- * @packageDocumentation
- * @see {@link @c15t/react} for React components and hooks
- * @see {@link ./middleware} for Next.js middleware integration
+ * Pattern:
+ *   // app/layout.tsx (Server Component)
+ *   import { resolveConsent } from '@c15t/nextjs/server';
+ *   import { ConsentRoot } from '@c15t/nextjs';
+ *
+ *   export default async function RootLayout({ children }) {
+ *     const state = await resolveConsent();
+ *     return (
+ *       <html>
+ *         <body>
+ *           <ConsentRoot state={state}>{children}</ConsentRoot>
+ *         </body>
+ *       </html>
+ *     );
+ *   }
+ *
+ *   // any client component
+ *   import { useConsent } from '@c15t/react';
+ *   const allowed = useConsent('marketing');
+ *
+ * Server helpers return serializable data and avoid module-level runtime
+ * caches, keeping requests isolated under Fluid Compute.
  */
 export * from '@c15t/react';
-export { buildPrefetchScript, type PrefetchOptions } from 'c15t';
-export { C15tPrefetch } from './libs/browser-initial-data';
-export { fetchInitialData } from './libs/initial-data';
-export type { C15tPrefetchProps, ConsentManagerProps, FetchInitialDataOptions, InitialDataPromise, } from './types';
+export type { ConsentRootProps } from './root';
+export { ConsentRoot } from './root';
+export type { ConsentState } from './types';
+export type { ConsentConfig } from './config';
+export { defineConsentConfig } from './config';

package/dist-types/middleware.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `@c15t/nextjs/middleware` keeps the Next 15 name for the proxy helper.
+ *
+ * Next 16 renamed `middleware.ts` to `proxy.ts`; the implementation lives in
+ * `@c15t/nextjs/proxy` and this entry re-exports it under the old name.
+ */
+import { c15tProxy } from './proxy';
+export type { C15tProxyOptions as C15tMiddlewareOptions } from './proxy';
+/**
+ * Alias of `c15tProxy` from `@c15t/nextjs/proxy` for `middleware.ts` files.
+ *
+ * Both names stay supported. Prefer `c15tProxy` in new code, and switch to it
+ * when you rename `middleware.ts` to `proxy.ts` on Next 16.
+ */
+export declare const c15tMiddleware: typeof c15tProxy;

package/dist-types/node-bridge.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Bridges Node's `http` request and response objects to the Web `Request`,
+ * `Response`, and `Headers` types the server helpers and route handlers
+ * speak. Typed structurally so the public `@c15t/nextjs/pages` surface does
+ * not depend on `@types/node`.
+ */
+/**
+ * Node-style incoming headers: lowercase names, arrays for repeated headers.
+ * `IncomingHttpHeaders` from `node:http` satisfies this shape.
+ */
+export type NodeIncomingHeaders = Record<string, string | string[] | undefined>;
+/**
+ * The part of a Node `IncomingMessage` the server helpers read.
+ */
+export interface NodeRequestLike {
+    headers: NodeIncomingHeaders;
+}
+/**
+ * The part of a Node `IncomingMessage` the API bridge reads. `NextApiRequest`
+ * and the `req` of `getServerSideProps` both satisfy it.
+ */
+export interface NodeApiRequestLike extends NodeRequestLike {
+    /**
+     * Body already parsed by Next's API route `bodyParser`. Left undefined when
+     * the route disables the parser, in which case the raw stream is read.
+     */
+    body?: unknown;
+    method?: string;
+    url?: string;
+    [Symbol.asyncIterator]?: () => AsyncIterator<Uint8Array | string>;
+}
+/**
+ * The part of a Node `ServerResponse` the API bridge writes to.
+ * `NextApiResponse` satisfies it.
+ */
+export interface NodeApiResponseLike {
+    statusCode: number;
+    setHeader: (name: string, value: string | string[]) => unknown;
+    write: (chunk: Uint8Array) => unknown;
+    end: (chunk?: Uint8Array) => unknown;
+}
+/**
+ * Converts Node-style incoming headers to a Web `Headers` instance.
+ * Repeated headers are joined with `, `; undefined entries are skipped.
+ */
+export declare const toWebHeaders: (headers: NodeIncomingHeaders) => Headers;
+/**
+ * Converts a Node `IncomingMessage` into a Web `Request`. The URL is rebuilt
+ * from `x-forwarded-proto`, `x-forwarded-host`/`host`, and `req.url`, the
+ * same inputs the route handlers use to resolve a relative backend URL.
+ */
+export declare const toWebRequest: (req: NodeApiRequestLike) => Promise<Request>;
+/**
+ * Writes a Web `Response` to a Node `ServerResponse`: status, headers
+ * (`set-cookie` as separate values), then the body streamed chunk by chunk.
+ */
+export declare const writeWebResponse: (response: Response, res: NodeApiResponseLike) => Promise<void>;

package/dist-types/pages.d.ts

@@ -0,0 +1,88 @@
+/**
+ * `@c15t/nextjs/pages` — Pages Router entry.
+ *
+ * `@c15t/nextjs/server` reads the request through `next/headers`, which only
+ * exists in the App Router, and `@c15t/nextjs/api` ships App Router route
+ * handlers (Web `Request` in, `Response` out). These wrappers take the Node
+ * `req`/`res` that `getServerSideProps` and API routes receive instead.
+ *
+ * @example
+ * ```ts
+ * // pages/index.tsx
+ * import { resolveConsent } from '@c15t/nextjs/pages';
+ *
+ * export const getServerSideProps = async ({ req }) => ({
+ * 	props: { state: await resolveConsent({ backendURL: '/api/c15t', req }) },
+ * });
+ * ```
+ */
+import type { NextConsentManifestHandlersOptions } from './api';
+import type { ConsentConfig } from './config';
+import type { NodeApiRequestLike, NodeApiResponseLike, NodeRequestLike } from './node-bridge';
+import type { ConsentState, KernelConfig, NextRequestContext, ResolveConsentOptions } from './server';
+export type { NodeApiRequestLike, NodeApiResponseLike, NodeIncomingHeaders, NodeRequestLike, } from './node-bridge';
+export type { ConsentConfig, ConsentState, KernelConfig, NextConsentManifestHandlersOptions, NextRequestContext, };
+export { defineConsentConfig } from './config';
+/**
+ * `resolveConsent` options with the Node request in place of the `request`
+ * adapter, which this entry derives from `req`.
+ */
+export type PagesResolveConsentOptions = Omit<ResolveConsentOptions, 'request'> & {
+    /**
+     * The `req` from `getServerSideProps` or an API route.
+     */
+    req: NodeRequestLike;
+};
+/**
+ * Builds the `request` adapter the server helpers expect from a Node
+ * request. Headers convert to Web `Headers`; cookies come from the `cookie`
+ * header.
+ *
+ * @param req - `req` from `getServerSideProps` or an API route
+ * @returns A `NextRequestContext` for `@c15t/nextjs/server`
+ */
+export declare const createPagesRequestContext: (req: NodeRequestLike) => NextRequestContext;
+/**
+ * Resolve the visitor's consent state in `getServerSideProps`. Same
+ * behaviour as `resolveConsent` from `@c15t/nextjs/server`, reading cookies
+ * and geo headers from `req` instead of `next/headers`: without a backend
+ * URL it returns the request-only state, with one it also folds in the
+ * backend or manifest init. The result is plain JSON, so return it as a
+ * prop and hand it to `ConsentRoot`.
+ *
+ * @param options - Backend URL or a `defineConsentConfig` result, the Node
+ * `req`, and the server helper options
+ * @returns The visitor's JSON-serializable `ConsentState`
+ * @example
+ * ```ts
+ * export const getServerSideProps = async ({ req }) => ({
+ * 	props: { state: await resolveConsent({ config: consentConfig, req }) },
+ * });
+ * ```
+ */
+export declare const resolveConsent: (options: PagesResolveConsentOptions) => Promise<ConsentState>;
+/**
+ * A Pages Router API route handler: Node `req` in, Node `res` written.
+ */
+export type PagesApiHandler = (req: NodeApiRequestLike, res: NodeApiResponseLike) => Promise<void>;
+/**
+ * Pages Router API route handlers for the consent routes. Wraps
+ * `createNextConsentRouteHandlers` from `@c15t/nextjs/api` so each handler
+ * takes the Node `req`/`res` of a `pages/api` route.
+ *
+ * @param options - Same options as `createNextConsentRouteHandlers`, or a
+ * `defineConsentConfig` result
+ * @returns `init` for `GET /init` and `manifest` for `GET /manifest`
+ *
+ * @example
+ * ```ts
+ * // pages/api/consent/manifest.ts
+ * import { createPagesApiHandlers } from '@c15t/nextjs/pages';
+ *
+ * export default createPagesApiHandlers({ backendURL: '/api/c15t' }).manifest;
+ * ```
+ */
+export declare const createPagesApiHandlers: (options?: NextConsentManifestHandlersOptions | ConsentConfig) => {
+    init: PagesApiHandler;
+    manifest: PagesApiHandler;
+};

package/dist-types/proxy.d.ts

@@ -0,0 +1,34 @@
+import { NextResponse } from 'next/server.js';
+import type { NextRequest } from 'next/server.js';
+export interface C15tProxyOptions {
+    /**
+     * Also persist normalized geo into cookies for runtimes that do not keep
+     * middleware request headers visible to RSC.
+     */
+    cookie?: boolean | {
+        countryName?: string;
+        regionName?: string;
+    };
+}
+/**
+ * Creates a `NextResponse.next()` that forwards normalized consent headers.
+ *
+ * Use from `proxy.ts` (Next 16) or `middleware.ts` (Next 15) when the
+ * deployment platform exposes geo to the proxy but strips it before Server
+ * Components or Route Handlers. `@c15t/nextjs/middleware` exports the same
+ * function as `c15tMiddleware`.
+ *
+ * @example
+ * ```ts
+ * // proxy.ts
+ * import { c15tProxy } from '@c15t/nextjs/proxy';
+ * import type { NextRequest } from 'next/server';
+ *
+ * export const proxy = (request: NextRequest) => c15tProxy(request);
+ * ```
+ *
+ * @param request - The incoming Next.js request.
+ * @param options - Header and cookie forwarding options.
+ * @returns A response that forwards normalized consent headers.
+ */
+export declare const c15tProxy: (request: NextRequest, options?: C15tProxyOptions) => NextResponse;

package/dist-types/root.d.ts

@@ -0,0 +1,92 @@
+import type { Script } from '@c15t/core/modules/script-loader';
+import type { ProviderTransportFactory } from '@c15t/react';
+import type { UseNetworkBlockerOptions, UsePersistenceOptions, UseScriptLoaderOptions } from '@c15t/react/module-hooks';
+import type { ConsentProviderOptions } from '@c15t/react/provider';
+import type { ReactNode } from 'react';
+import type { ConsentConfig } from './config';
+import type { ConsentState } from './types';
+export interface ConsentRootProps {
+    /**
+     * The visitor's resolved consent state, produced server-side by
+     * `resolveConsent()` from `@c15t/nextjs/server`. Serializable JSON; a
+     * promise is fine, the provider awaits it.
+     */
+    state: ConsentState | Promise<ConsentState>;
+    /**
+     * Backend base URL (e.g. `/api/c15t` or `https://consent.example.com`).
+     * When provided, the provider uses hosted mode and auto-runs init.
+     * Overrides `config.backendURL`.
+     */
+    backendURL?: string;
+    /**
+     * A `defineConsentConfig` result. Picks the transport when
+     * `options.mode` is not set:
+     *
+     * - `initURL` set: hosted mode with init fetched from that same-origin
+     *   route (the handlers' `GET`, which resolves the cached manifest with
+     *   the request's geo) and saves posted to `${backendURL}/subjects`.
+     * - Otherwise `manifestURL` set: the manifest transport, resolving init
+     *   in the browser from that route. The resolver loads on first init so
+     *   it stays out of the initial bundle.
+     * - Otherwise: hosted mode against `backendURL`.
+     */
+    config?: ConsentConfig;
+    /**
+     * Script tags to manage with the script-loader module.
+     */
+    scripts?: Script[];
+    /**
+     * Remove configured browser data for initially denied categories after policy
+     * resolution and when consent is later revoked.
+     * Initial-only: remount ConsentRoot to replace the cleanup configuration.
+     */
+    clearOnRevocation?: ConsentProviderOptions['clearOnRevocation'];
+    /**
+     * Script-loader options.
+     */
+    scriptLoader?: UseScriptLoaderOptions;
+    /**
+     * Network-blocker configuration.
+     */
+    networkBlocker?: UseNetworkBlockerOptions | false;
+    /**
+     * Enable client-side persistence. Defaults to true.
+     */
+    persistence?: boolean | UsePersistenceOptions;
+    /**
+     * Additional React provider options.
+     */
+    options?: Omit<ConsentProviderOptions, 'mode' | 'clearOnRevocation' | 'networkBlocker' | 'persistence' | 'prefetch' | 'scriptLoader' | 'scripts' | '__debugPkg'> & {
+        mode?: ProviderTransportFactory;
+    };
+    children: ReactNode;
+}
+/**
+ * Mounts the consent provider for a Next.js app. Render it once, near the
+ * top of the tree, with the `state` a Server Component resolved through
+ * `resolveConsent()`.
+ *
+ * @example
+ * ```tsx
+ * // app/layout.tsx
+ * import { ConsentRoot } from '@c15t/nextjs';
+ * import { resolveConsent } from '@c15t/nextjs/server';
+ * import { consentConfig } from '@/consent.config';
+ *
+ * export default function RootLayout({ children }) {
+ *   return (
+ *     <html>
+ *       <body>
+ *         <ConsentRoot
+ *           state={resolveConsent({ config: consentConfig })}
+ *           config={consentConfig}
+ *         >
+ *           {children}
+ *         </ConsentRoot>
+ *       </body>
+ *     </html>
+ *   );
+ * }
+ * ```
+ */
+export declare const ConsentRoot: ({ state, backendURL, config, scripts, scriptLoader, clearOnRevocation, networkBlocker, persistence, options, children, }: ConsentRootProps) => import("react").JSX.Element;