@c15t/scripts 3.0.0-alpha.1 → 3.0.0-alpha.3

package/docs/frameworks/next/script-loader.md

@@ -1,210 +0,0 @@
----
-title: Load scripts with consent
-description: Register vendor scripts in your existing Next.js ConsentRoot and
-  handle loading and revocation.
-group: frameworks
----
-
-## Keep one owner for vendor scripts
-
-The [App Router](https://c15t.com/docs/frameworks/next/app-router) and
-[Pages Router](https://c15t.com/docs/frameworks/next/pages-router) setups already register scripts
-in a client wrapper. Keep that wrapper and add vendors to `lib/scripts.ts`.
-If you are adding scripts to an existing c15t setup, install the helpers and
-use the same registration pattern below.
-
-| Package manager | Command                     |
-| :-------------- | :-------------------------- |
-| npm             | `npm install @c15t/scripts` |
-| pnpm            | `pnpm add @c15t/scripts`    |
-| yarn            | `yarn add @c15t/scripts`    |
-| bun             | `bun add @c15t/scripts`     |
-
-Keep `c15t.config.ts` and the manifest route from your router setup. These shared
-URLs connect initialization and consent submissions to the same backend.
-
-## Register scripts in a client wrapper
-
-The [runnable Next.js example](https://c15t.com/docs/examples) uses PostHog for measurement and
-X Pixel for marketing. Set `NEXT_PUBLIC_POSTHOG_KEY` and
-`NEXT_PUBLIC_X_PIXEL_ID` to your own project identifiers before building.
-`NEXT_PUBLIC_POSTHOG_HOST` optionally selects your PostHog region's API host.
-Omit a vendor's ID to leave that integration disabled, or replace its helper
-with the [integration](../../integrations/overview.md) your application uses. Include the
-measurement and marketing categories in your policy for these two vendors.
-
-Create `lib/scripts.ts` with the example's script configuration:
-
-```ts title="lib/scripts.ts"
-import { posthog } from '@c15t/scripts/posthog';
-import { xPixel } from '@c15t/scripts/x-pixel';
-import type { Script } from 'c15t';
-
-export const posthogConfigured = Boolean(process.env.NEXT_PUBLIC_POSTHOG_KEY);
-export const xPixelConfigured = Boolean(process.env.NEXT_PUBLIC_X_PIXEL_ID);
-
-export const scripts: Script[] = [];
-
-if (process.env.NEXT_PUBLIC_POSTHOG_KEY) {
-	scripts.push(
-		posthog({
-			apiHost: process.env.NEXT_PUBLIC_POSTHOG_HOST,
-			id: process.env.NEXT_PUBLIC_POSTHOG_KEY,
-			initOptions: { cookieless_mode: 'never' },
-			loadMode: 'after-consent',
-		})
-	);
-}
-
-if (process.env.NEXT_PUBLIC_X_PIXEL_ID) {
-	scripts.push(xPixel({ pixelId: process.env.NEXT_PUBLIC_X_PIXEL_ID }));
-}
-```
-
-PostHog waits for measurement consent here. `cookieless_mode: 'never'` disables
-cookieless capture after rejection. X Pixel waits for marketing consent. Remove
-any existing loader for these vendors, including `next/script` and tag-manager
-entries, so each integration loads once.
-
-Create this client wrapper. It keeps scripts and browser callbacks in the client
-while the router supplies the visitor's resolved state through `state`:
-
-```tsx title="components/consent.tsx"
-'use client';
-
-import type { ReactNode } from 'react';
-import {
-  ConsentBanner,
-  ConsentDialog,
-  ConsentDialogLink,
-  ConsentRoot,
-} from 'c15t/next';
-import type { ConsentRootProps } from 'c15t/next';
-import { consentConfig } from '../c15t.config';
-import { scripts } from '../lib/scripts';
-
-export function Consent({
-  children,
-  state,
-}: {
-  children: ReactNode;
-  state: ConsentRootProps['state'];
-}) {
-  return (
-    <ConsentRoot state={state} config={consentConfig} scripts={scripts}>
-      {children}
-      <ConsentBanner />
-      <ConsentDialog />
-      <footer>
-        <ConsentDialogLink>Privacy settings</ConsentDialogLink>
-      </footer>
-    </ConsentRoot>
-  );
-}
-```
-
-`ConsentRoot` already provides the consent runtime. Mount this wrapper once;
-do not add a second provider. Keep your site's content and footer inside it.
-
-## Pass prepared consent through your router
-
-App Router awaits the prefetch in the `ResolvedConsent` Server Component from
-the [App Router guide](https://c15t.com/docs/frameworks/next/app-router) and renders the
-wrapper inside it. This partial example is that component; keep the
-`Suspense` boundary, `html`, `body` and stylesheet from your existing layout:
-
-```tsx
-import type { ReactNode } from 'react';
-import { resolveConsent } from 'c15t/next/server';
-import { consentConfig } from '../c15t.config';
-import { Consent } from '../components/consent';
-
-async function ResolvedConsent({ children }: { children: ReactNode }) {
-  const state = await resolveConsent({ config: consentConfig });
-  return <Consent state={state}>{children}</Consent>;
-}
-```
-
-To stream the page shell before consent resolves instead, pass the unawaited
-promise from a synchronous layout as described in
-[stream the page while consent resolves](https://c15t.com/docs/frameworks/next/app-router#stream-the-page-while-consent-resolves).
-
-Pages Router passes `state={pageProps.consentState ?? {}}` to this wrapper
-in `_app.tsx`. Keep `getServerSideProps` and its `c15t/next/pages` helper.
-The router guides contain complete layout and `_app.tsx` files.
-
-For static export or browser-only initialization, pass `state={{}}` and keep
-that setup's existing transport. Register scripts on its existing `ConsentRoot`;
-do not introduce server prefetch or local routes just to add a vendor.
-
-## Check each vendor's loading behavior
-
-The example explicitly configures PostHog to load after consent and disables
-cookieless capture. Those settings are deliberate; its default helper can load
-before consent and use the SDK's consent controls. Read the
-[PostHog guide](../../integrations/posthog.md) before changing them.
-
-Ordinary scripts wait for their category's effective permission. Give each
-script a stable unique `id` and remove any other loader for the same vendor.
-Helpers with `alwaysLoad` may load an SDK before permission is granted; a
-category field alone does not guarantee no requests. See the
-[vendor guides](../../integrations/overview.md) for their exact contracts.
-
-Removing a script element cannot undo executed JavaScript or requests already
-sent. PostHog exposes capture controls; X Pixel has no consent-update API.
-Stop future event calls after revocation and test a change from allowed to
-denied, as well as initial denial.
-
-## Verify the integration
-
-With an opt-in policy and no saved choice, neither configured example vendor
-should load. Allow measurement only: PostHog loads and X Pixel remains blocked.
-Reject, reload, and reopen Privacy settings to confirm the choice persists.
-
-Use the [runnable example](https://c15t.com/docs/examples) to inspect the same script definitions
-with DevTools, or follow [verification](../../guides/verify-consent.md) in your app.
-Use [custom integrations](../../integrations/building-integrations.md) for an
-unlisted vendor. Google helpers have a separate
-[Consent Mode contract](../../integrations/google-tag-manager.md).
-
-## Granular consent
-
-A visitor can grant marketing and still turn one vendor off. Declare the
-vendors next to the scripts in `lib/scripts.ts`, with the `vendor` slug each
-script already carries, and pass both to `ConsentRoot`:
-
-```ts title="lib/scripts.ts"
-import type { Vendor } from 'c15t';
-
-export const vendors: Vendor[] = [
-  {
-    id: 'x-pixel',
-    name: 'X Pixel',
-    category: 'marketing',
-    privacyPolicyUrl: 'https://x.com/privacy',
-  },
-];
-```
-
-```tsx title="components/consent.tsx"
-import { scripts, vendors } from '../lib/scripts';
-
-<ConsentRoot state={state} config={consentConfig} scripts={scripts} vendors={vendors}>
-  {children}
-</ConsentRoot>
-```
-
-The preference center lists each vendor under its category with a switch.
-Integrations from `@c15t/scripts` set `vendor` to their manifest slug, so
-`xPixel()` needs no extra wiring; give a hand-written script the same slug
-in its `vendor` field. A backend manifest can declare vendors too. See
-[granular consent](../../integrations/granular-consent.md) for storage,
-bulk actions and the hooks a custom control uses.
-
-## Clear stored tracking data
-
-Script gating does not remove cookies or Web Storage entries that a script
-already wrote. Add `clearOnRevocation` to your `ConsentRoot` or provider
-options to remove declared data when its category is denied. See
-[clear on revocation](../../integrations/clear-on-revocation.md) for configuration
-and browser limits.

package/docs/frameworks/react/script-loader.md

@@ -1,63 +0,0 @@
----
-title: Load scripts with consent
-description: Register vendor scripts once and let effective permissions control loading.
-group: frameworks
----
-
-## Register scripts on the provider
-
-Install `@c15t/scripts` for vendor helpers. This React-compatible client component
-uses Inth as the backend. Set the URL to the endpoint supplied by your Inth
-project and keep the component mounted around your application.
-
-```tsx title="components/consent.tsx"
-'use client';
-
-import type { ReactNode } from 'react';
-import { ConsentProvider, ConsentBanner, ConsentDialog, ConsentDialogLink, hosted } from 'c15t/react';
-import { metaPixel } from '@c15t/scripts/meta-pixel';
-
-const mode = hosted({ url: 'https://your-project.inth.app' });
-const scripts = [metaPixel({ pixelId: '123456789012345' })];
-
-export function Consent({ children }: { children: ReactNode }) {
-  return (
-    <ConsentProvider options={{ mode, scripts }}>
-      {children}
-      <ConsentBanner />
-      <ConsentDialog />
-      <ConsentDialogLink>Privacy settings</ConsentDialogLink>
-    </ConsentProvider>
-  );
-}
-```
-
-Import your adapter's stylesheet globally, as in the framework quickstart. For
-an existing server-resolved `ConsentRoot`, keep that root and pass
-`scripts` as a top-level prop instead of mounting a second provider.
-
-## Understand loading and revocation
-
-Ordinary scripts wait for their category's effective permission. Give each
-script a stable unique `id` and remove any other loader for the same vendor.
-Some helpers use `alwaysLoad` to load the SDK and signal consent through its own
-API. Read the vendor guide; a category field alone does not guarantee no
-requests.
-
-Removing a script element cannot undo JavaScript that already executed or
-requests already sent. Use the vendor's supported consent and cleanup behavior,
-and stop future event calls after revocation. Test both initial denial and a
-change from allowed to denied.
-
-Use [custom integrations](../../integrations/building-integrations.md) for an
-unlisted vendor and [verification](../../guides/verify-consent.md) for the network
-checks. Google helpers have a separate
-[Consent Mode contract](../../integrations/google-tag-manager.md).
-
-## Clear stored tracking data
-
-Script gating does not remove cookies or Web Storage entries that a script
-already wrote. Add `clearOnRevocation` to `ConsentProvider.options` to remove
-declared data when its category is denied. See
-[clear on revocation](../../integrations/clear-on-revocation.md) for configuration
-and browser limits.

package/docs/guides/consent-state.md

@@ -1,60 +0,0 @@
----
-title: Understand consent state
-description: Distinguish policy resolution, effective permissions, explicit
-  choices, notices and privacy signals.
-group: guides
----
-
-## Use effective permissions to gate features
-
-`effectivePermissions` answers whether a category is allowed now. It combines
-the resolved policy, stored choices and privacy signals. Under an opt-out rule,
-permission can be true before the visitor acts. It is not evidence of a recorded
-grant.
-
-| Task                                        | State or API                                         |
-| ------------------------------------------- | ---------------------------------------------------- |
-| Load a script or render an optional feature | `effectivePermissions`, React `useConsent(category)` |
-| Inspect what the visitor confirmed          | `explicitChoice`                                     |
-| Decide whether to show a prompt             | `promptRequirement`                                  |
-| Explain regional behavior                   | `policyRule`                                         |
-| Diagnose initialization                     | `resolution`                                         |
-
-## Record only explicit visitor actions
-
-```ts
-// Run in the corresponding click or form-submit handler.
-await kernel.commands.save('all');
-await kernel.commands.save('none');
-await kernel.commands.save({ marketing: false });
-```
-
-These are three separate examples: accept, reject and a partial save. A partial
-save confirms only the supplied categories and keeps the other categories'
-confirmation times. Do not call all three in one handler.
-
-`onChoiceRecorded` reports an explicit choice. `onPermissionsChanged` reports
-changes in effective permissions, including changes caused by expiry or privacy
-signals. Hydration must not be counted as another visitor choice.
-
-## Treat notices and privacy signals separately
-
-`commands.dismissNotice()` acknowledges the current notice. It does not grant
-categories or overwrite existing denials. Global Privacy Control, or GPC, is a
-browser privacy signal. Its configured restrictions can change permissions
-without creating an explicit choice.
-
-A rule with `prompt: 'none'` can still require a persistent preferences entry
-point. Check the policy's rights instead of hiding preferences merely because
-the banner is absent. An unresolved rule is another distinct state; optional
-permissions stay denied until resolution succeeds.
-
-## Preserve records during hydration
-
-Server helpers return records with policy information and evaluation time.
-Forward that configuration intact. Copying an allowed category into a receipt
-would invent a grant and lose its original confirmation time.
-
-Valid v2 records can be read without a startup rewrite. The next explicit action
-writes the v3 format. See [migration](../upgrade-v3.md) for expiry, partial saves,
-custom transports and backend contract changes.

package/docs/guides/deployment-modes.md

@@ -1,75 +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.
-
-Manifest resolution removes the per-visitor `/init` request, and with it the
-backend's only count of visitors. The server adapters replace it with a session
-report: after each resolution, on a server-rendered page or the same-origin
-init route, the host posts a small report to the backend's `POST /sessions`,
-server-to-server and detached from the response. The browser makes no request
-and the report stores no identity; the visitor's IP and user agent travel as
-forwarded headers under the backend's usual IP handling. Each report is one
-resolution; a page view can produce a `render` and a `route` report, and the
-consuming side groups them into sessions by address and user agent within a
-window. Static output resolves in the browser and sends none. Set `reportSessions: false` on an adapter to turn
-it off.
-
-## 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.