@c15t/react 3.0.0-alpha.1 → 3.0.0-alpha.10

package/docs/guides/data-fetching.md

@@ -1,163 +0,0 @@
----
-title: Data fetching and transports
-description: Choose cached manifests, backend init or offline policy resolution,
-  and understand where consent records are saved.
-group: guides
----
-
-## Start with Inth and a cached manifest
-
-Use Inth for managed policy and consent records. For a Next.js application with
-a server, use a cached manifest to resolve policy in your application. Route
-browser consent traffic directly to Inth, or optionally use a Next.js rewrite
-to keep those requests on your app's origin. Follow the
-[Next.js manifest setup](https://c15t.com/docs/frameworks/next/data-fetching).
-
-Backend ownership and data fetching are separate decisions. Inth manages the
-backend for you. A [self-hosted backend](https://c15t.com/docs/self-host/quickstart) uses the same
-protocol while you operate its database, policies and availability. A static
-site can still call Inth. Only `offline()` deliberately removes consent backend
-requests and stores choices locally.
-
-| Fetching path                  | Where policy resolves                                                                 | Where choices are submitted | Choose it when                                                                                         |
-| ------------------------------ | ------------------------------------------------------------------------------------- | --------------------------- | ------------------------------------------------------------------------------------------------------ |
-| Cached manifest on your server | Your application resolves public policy data with each request's location and signals | Inth or your c15t backend   | Your host has a runtime server and you want to reuse policy data across requests                       |
-| Regular backend `/init`        | The consent backend                                                                   | The same backend            | You want the fewest moving parts, need backend-owned request resolution, or have no application server |
-| Manifest in the browser        | The browser, using supplied or unknown location                                       | Inth or your c15t backend   | You deliberately want client resolution and have planned geography, bundle size and policy refresh     |
-| Offline                        | The browser or local runtime, using bundled rules                                     | No backend submission       | Local development and tests. Not recommended for production environments.                              |
-| Custom transport               | Your implementation                                                                   | Your implementation         | An existing service cannot use the c15t backend protocol                                               |
-
-## What is a consent manifest?
-
-A manifest is a versioned policy document served by `GET /manifest`. It contains
-policy rules, translation configuration and related consent configuration. It
-is public configuration, not a visitor's saved choices. A resolver combines the
-manifest with country, region, language and privacy signals to produce an init
-result for one visitor.
-
-Reusing the public document avoids asking the consent backend to resolve policy
-for every application request. Cache misses and revalidation still fetch the
-manifest, and consent writes still need the backend. Measure the deployed
-request path before promising a latency improvement.
-
-Do not put secrets, visitor identifiers or consent records into a manifest.
-Keep personalized init responses out of shared caches. Changing a policy also
-requires a refresh strategy for cached or build-time manifests.
-
-## What does regular `/init` do?
-
-`hosted({ url })` uses `${url}/init` for initialization and `${url}/subjects` for
-consent submissions. The name `hosted` describes the transport protocol; the URL
-can belong to Inth or your own c15t backend.
-
-```ts title="src/consent-mode.ts"
-import { hosted } from 'c15t';
-
-export function createConsentMode(backendURL: string) {
-  return hosted({ url: backendURL });
-}
-```
-
-Pass the factory to your adapter's `mode` option. For request rendering, use the
-adapter's server helper and forward its prepared result to the browser. For
-static output, initialize in the browser with a reachable external URL.
-
-A regular backend `/init` request lets the backend resolve the visitor context.
-A same-origin URL named `/api/c15t/init` can instead resolve from a cached
-manifest in your application. The URL name alone does not tell you which path
-runs.
-
-## How do transports and proxies differ?
-
-A transport implements initialization, saving and optional record operations.
-A proxy changes where HTTP requests travel. It does not change the policy
-resolver or make personalized responses safe to cache.
-
-For a same-origin init route that resolves a manifest, the hosted transport can
-separate policy reads and record writes. With a backend rewrite mounted at
-`/api/c15t`, a client mode can use:
-
-```ts title="src/consent-mode.ts"
-import { hosted } from 'c15t';
-
-export const mode = hosted({
-  url: '/api/c15t',
-  initURL: '/api/c15t/init',
-  assertDecisionInputs: true,
-});
-```
-
-The route must return the c15t init response contract. `assertDecisionInputs`
-binds saves to the resolved policy when init did not return a signed policy
-snapshot token. The backend can then reject a stale policy decision. Next.js
-sets this option for you when `ConsentRoot` receives a `config` with
-`initURL`.
-
-The init route resolves policy; the backend rewrite forwards `/api/c15t/subjects`
-and other record endpoints. Configure both if you choose this optional proxy
-variant. The
-[Next.js rewrite recipe](https://c15t.com/docs/frameworks/next/optimization#keep-browser-consent-requests-on-your-origin)
-shows the configuration. A direct absolute backend URL works
-without a rewrite.
-
-This optional optimization keeps c15t requests on the app's origin and avoids a separate browser DNS lookup
-and TLS connection to the consent backend. The app server still connects to
-the upstream backend for manifest refreshes and consent writes. Vendor scripts
-and vendor requests keep their own origins.
-
-Set the absolute upstream endpoint through `C15T_BACKEND_URL` in Next.js server
-configuration. The endpoint URL is public connection information, not a secret.
-The browser uses `/api/c15t` without needing the upstream URL. A static export
-cannot serve a Next.js route or rewrite at runtime; use the absolute Inth URL or
-a proxy provided by the static host instead.
-
-## When should I use offline mode?
-
-Not recommended for production environments. Use Inth or a self-hosted backend
-for production policy and consent records.
-
-`offline()` resolves bundled policy rules without an init request and acknowledges
-saves locally. The runtime's persistence module stores the choice in browser
-storage. There is no backend audit history, cross-device record service or IP
-geolocation supplied by this transport.
-
-Use your adapter's offline factory so its translations and provider context are
-included. This React and Next.js example replaces the hosted mode in an existing
-client provider:
-
-```ts title="src/consent-mode.ts"
-import { offline } from 'c15t/react';
-
-export const mode = offline();
-```
-
-With no `policyRules`, the current offline transport uses the recommended rule
-pack. Supplying `policyRules` replaces that pack. Unknown country and region are
-real resolution inputs; offline mode does not discover a visitor's location.
-Use [policy rules](https://c15t.com/docs/frameworks/next/concepts/policy-presets) to understand
-matching and defaults, and test the missing-location case.
-
-Offline mode is an explicit architecture choice, not an automatic fallback for
-a failed Inth request. If hosted initialization fails before a policy resolves,
-optional permissions remain denied and the stock prompt stays hidden. Observe
-initialization failures instead of silently changing policy sources.
-
-## Can I provide my own transport?
-
-`custom(transport)` accepts a `KernelTransport` with the v3 `init` and `save`
-contract. It does not accept v2 endpoint handlers such as `setConsent`. Keep
-policy resolution, record acknowledgments and failure behavior consistent with
-the kernel contract. Prefer a built-in transport when your backend supports it.
-
-## Verify the selected path
-
-Inspect browser and server requests separately. A server manifest fetch will
-not appear in the browser's Network panel. On a warm manifest path, check that
-page requests do not call the backend `/init`, a visitor's choice still reaches
-the backend's `/subjects`, and policy changes become visible after the configured
-refresh. In the recommended Next.js setup, the browser should call only
-`/api/c15t` paths for consent HTTP traffic; inspect server logs to verify their
-upstream destinations.
-
-Test different locations, missing location headers, GPC, returning choices and
-backend failure. See [verification](./verify-consent.md).

package/docs/guides/deployment-modes.md

@@ -1,63 +0,0 @@
----
-title: Choose a deployment mode
-description: Choose who runs your consent backend, then select manifest, init or
-  offline resolution for your deployment.
-group: guides
----
-
-## Use Inth for managed policy and records
-
-Start with [Inth](https://inth.com) unless you need to operate the consent
-service yourself or deliberately need only local browser records. Configure
-policy rules and trusted origins in the project, then use its exact backend
-endpoint in your framework setup.
-
-| Backend ownership         | Policy source                                          | Record storage                           | Use when                                                                  |
-| ------------------------- | ------------------------------------------------------ | ---------------------------------------- | ------------------------------------------------------------------------- |
-| Inth hosted service       | Centrally managed policy through a manifest or `/init` | Browser records plus backend submissions | You want managed policy and consent records                               |
-| Self-hosted c15t          | Your backend's manifest or `/init`                     | Browser records plus your database       | You need to operate the service and its infrastructure                    |
-| Browser-only offline mode | Bundled `policyRules`                                  | Browser persistence                      | Local development and tests. Not recommended for production environments. |
-
-Hosted and self-hosted c15t use the same transport protocol. Switching who runs
-the backend does not require switching from manifests to `/init`.
-
-## Choose data fetching separately
-
-For Next.js deployments with a runtime server, use the
-[manifest setup](https://c15t.com/docs/frameworks/next/data-fetching). It reuses public policy data
-in your application while consent writes still go to Inth. Regular backend
-`/init` is available when you want backend-owned request resolution or a simpler
-browser setup. See [data fetching and transports](./data-fetching.md) for
-the comparison, including custom transports and offline mode.
-
-## Match initialization to your application output
-
-| Application output | Initial state             | Required setup                                              |
-| ------------------ | ------------------------- | ----------------------------------------------------------- |
-| Request SSR        | Prepared for this visitor | Adapter request helper and matching client configuration    |
-| Static HTML or SPA | Resolved in the browser   | Reachable external URLs or deliberately bundled local rules |
-
-Request SSR can include the visitor's prompt in the initial HTML. Pass the
-prepared records and policy resolution through to hydration. Do not convert
-effective permissions into new stored choices.
-
-Static HTML is shared across visitors. It cannot contain a choice resolved from
-each visitor's cookies or geography at build time. A static site can still use
-Inth through browser requests. A same-origin `/api/c15t` URL only works if a
-service actually serves it; a Next.js static export does not run API routes.
-
-A manifest contains reusable public policy data. A resolved init response and
-personalized consent HTML belong to a request. Do not give them the same shared
-cache treatment.
-
-## Handle initialization and storage failures
-
-While no policy resolves, optional permissions stay denied and the stock
-consent UI stays hidden. No banner can mean pending or failed initialization.
-It does not mean permission to load analytics. Observe errors before changing
-presentation, and do not silently switch to offline policy after a hosted
-request fails.
-
-Browser storage can also be unavailable. A working in-memory interaction does
-not prove the choice survives reload. Use
-[verification](./verify-consent.md) to test the actual deployment.

package/docs/integrations/clear-on-revocation.md

@@ -1,167 +0,0 @@
----
-title: Clear on revocation
-description: Remove configured first-party cookies and Web Storage keys when
-  their consent category is denied.
-group: integrations
----
-
-## Configure cleanup
-
-Add `clearOnRevocation` to your provider or runtime options. Declare only the
-data owned by each optional category:
-
-```ts
-import { hosted, type ClearOnRevocationConfig } from 'c15t';
-import { createConsentRuntime } from 'c15t/runtime';
-
-const clearOnRevocation = {
-	measurement: {
-		cookies: ['_ga', '_ga_*'],
-		localStorage: ['analytics:*'],
-	},
-	marketing: {
-		cookies: ['_fbp'],
-		sessionStorage: ['campaign-id'],
-	},
-} satisfies ClearOnRevocationConfig;
-
-const runtime = createConsentRuntime({
-	mode: hosted({ url: '/api/c15t' }),
-	clearOnRevocation,
-});
-
-// Start in the browser after mount. The endpoint must serve your c15t backend.
-runtime.start();
-
-// Call runtime.dispose() when the app no longer needs consent management.
-```
-
-For React, pass the same configuration through `ConsentProvider.options`:
-
-```tsx
-import type { ReactNode } from 'react';
-import { ConsentProvider, hosted } from 'c15t/react';
-
-const mode = hosted({ url: '/api/c15t' });
-
-export function Consent({ children }: { children: ReactNode }) {
-	return (
-		<ConsentProvider
-			options={{
-				mode,
-				clearOnRevocation: {
-					measurement: { cookies: ['_ga', '_ga_*'] },
-				},
-			}}
-		>
-			{children}
-		</ConsentProvider>
-	);
-}
-```
-
-The same option is available in Next.js and TanStack Start `ConsentRoot` props, Vue and
-Nuxt configuration, Svelte providers, and Astro integration options. Solid and
-other headless integrations can use `createConsentRuntime` as shown above.
-Every adapter uses the same cleanup module.
-
-Omitting `clearOnRevocation` leaves cleanup disabled. The provider option is
-initial-only. Remount the provider to replace its cleanup configuration. For
-a shared runtime, configure the runtime owner rather than a borrowing provider.
-
-## Matching names and cookie scopes
-
-Use an exact string or a nonempty prefix followed by `*`. `_ga_*` matches
-`_ga_ABC123`; it does not match `_ga`. Regular expressions, wildcards in other
-positions, and a bare `*` are unsupported. Web Storage keys may contain spaces,
-Unicode, and punctuation. Cookie names use their raw spelling, without URL
-decoding.
-
-Cookies can share a name while having different domains or paths. Cleanup
-tries the current host and its parent domains, and the current path and its
-ancestors. To target a specific scope, use an object:
-
-```ts
-const clearOnRevocation = {
-	measurement: {
-		cookies: [
-			{ name: 'analytics-id', domain: 'example.com', path: '/' },
-			{ name: 'checkout-metrics', domain: '', path: '/checkout' },
-			{ name: 'partitioned-metrics', partitioned: true },
-		],
-	},
-};
-```
-
-An empty `domain` means host-only. Explicit domains and paths replace the
-automatic attempts for that field. Exact names can be deleted at a configured
-path even when the current page cannot read that cookie. Prefix matching can
-only discover cookie names visible to the current page, so use an exact name
-for a cookie on another path.
-
-Partitioned cookies require `partitioned: true`; ordinary targets remove
-unpartitioned cookies. Cookie deletion preserves the browser's `__Secure-`
-and `__Host-` prefix requirements. c15t protects its own consent, notice,
-privacy, pending-save, and IAB consent records in cookies and localStorage,
-including configured custom storage keys, even if your patterns match them.
-c15t does not store consent in sessionStorage, so targeted entries there are
-removed even when their names match consent storage keys.
-
-## When cleanup runs
-
-The runtime attaches cleanup after persistence and the script loader. Cleanup
-waits while the policy is pending. On the first settled snapshot, it removes
-configured data for every denied category. This includes a new opt-in visitor
-who has not made a choice and a returning visitor whose permission expired.
-
-After that first pass, cleanup runs when a category changes from allowed to
-denied. Saving a refusal, expiry, a policy change, Global Privacy Control,
-or synchronized records can cause that transition. Under an opt-out policy,
-an expired grant that remains effectively allowed does not trigger deletion.
-The `necessary` category cannot be configured for cleanup.
-
-Cleanup keeps waiting if a failed initial request leaves the policy pending.
-If a previously settled policy falls back to denial after an initialization
-failure, cleanup removes its configured data. A later successful retry cannot
-restore deleted data.
-
-Runtime construction, server rendering, draft checkbox edits, opening the
-dialog, and disposal do not clear data. Cleanup does not poll storage or repeat
-on unrelated UI updates.
-
-## Use an existing kernel
-
-For a manually assembled integration, attach the module in the browser after
-persistence hydration and script-loader setup:
-
-```ts
-import { createClearOnRevocation } from 'c15t/modules/clear-on-revocation';
-
-const cleanup = createClearOnRevocation({
-	kernel,
-	config: { measurement: { cookies: ['_ga', '_ga_*'] } },
-	storageConfig,
-});
-
-// Stop observing consent when this integration is torn down.
-cleanup.dispose();
-```
-
-Here `kernel` is your existing consent kernel. Pass the same `storageConfig`
-used by persistence so cleanup protects custom record keys. Attaching the
-module can immediately clear denied categories if the policy is already
-settled. Do not also attach it when your provider or runtime owns cleanup.
-
-## Browser limits
-
-Cleanup can remove JavaScript-accessible first-party cookies and keys in the
-current origin's `localStorage` and `sessionStorage`. It cannot remove
-`HttpOnly` cookies or another origin's data. Keep `HttpOnly` protections and
-use your server to expire cookies that require server access. Cookie deletion
-must match the cookie's scope. See the
-[browser cookie documentation](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/Cookies).
-
-Browser restrictions can prevent reads or deletions. Cleanup failures do not
-block consent updates. A running SDK may write data again after a sweep, so
-keep script gating and the integration's consent-change or teardown behavior
-configured. Deleting a script element cannot undo JavaScript it already ran.