@c15t/scripts 3.0.0-alpha.2 → 3.0.0-alpha.4

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.

package/docs/integrations/granular-consent.md

@@ -1,210 +0,0 @@
----
-title: Granular consent
-description: Let visitors grant a category and still turn one vendor off,
-  without adopting IAB TCF.
-group: integrations
----
-
-Granular consent is choice below the category level: a visitor grants
-marketing and still turns Meta off. The unit of that choice is a vendor, so
-the API names them `vendors`, `vendor` and `data-vendor`, and the hooks
-`useVendorAllowed` and `useVendorDraft`. Everything else stays as it is:
-categories, policies, and the preference center gain vendor rows rather than
-a second consent model.
-
-## Declare vendors
-
-Add `vendors` to your runtime options. Each vendor sits inside a category
-condition and needs a name and a privacy policy URL so the preference surface
-can list it. The React provider takes the same option once its preference
-center renders vendor rows; scripts, rules and iframes are gated the same way
-whichever place declares it:
-
-```ts
-import { hosted, type Vendor } from 'c15t';
-import { createConsentRuntime } from 'c15t/runtime';
-
-const vendors = [
-	{
-		id: 'meta-pixel',
-		name: 'Meta Pixel',
-		category: 'marketing',
-		privacyPolicyUrl: 'https://www.facebook.com/privacy/policy/',
-		description: 'Ad conversion measurement and audiences.',
-	},
-	{
-		id: 'google-analytics',
-		name: 'Google Analytics',
-		category: 'measurement',
-		privacyPolicyUrl: 'https://policies.google.com/privacy',
-	},
-] satisfies Vendor[];
-
-const runtime = createConsentRuntime({
-	mode: hosted({ url: '/api/c15t' }),
-	vendors,
-	scripts: [
-		{
-			id: 'meta-pixel',
-			category: 'marketing',
-			vendor: 'meta-pixel',
-			src: 'https://connect.facebook.net/en_US/fbevents.js',
-		},
-	],
-});
-
-// Start in the browser after mount. The endpoint must serve your c15t backend.
-runtime.start();
-```
-
-The `id` is a lowercase slug of up to 64 characters. Reuse it as the `vendor`
-field on scripts and network rules and as the `data-vendor` attribute on
-iframes. Integrations from `@c15t/scripts` already set `vendor` to their
-manifest slug, so `gtag()` and `metaPixel()` need no extra wiring.
-
-A backend can also declare vendors. Add `vendors` and an optional
-`vendorListVersion` to the manifest configuration; `/init` returns them and the
-client merges them with the vendors declared in code. When both declare the
-same id, the copy declared in code wins, and the backend copy comes back if the
-code declaration is removed later. A slug used by a script, rule or iframe
-but declared nowhere still gates loading. It is hidden from the preference surface, and the
-runtime warns about it outside production.
-
-## How a vendor is gated
-
-A target loads when its category condition passes and the visitor has not
-turned its vendor off:
-
-```text
-loads  =  category condition satisfied  AND  vendor not denied
-```
-
-The category is evaluated first, so an unknown category still throws as a
-configuration error. The iframe blocker is the exception: an `<iframe>` with an
-unknown `data-category` stays blocked and logs a console warning, so one typo
-can't stop the other iframes on the page from being gated. A vendor toggle never grants a category on its own: with
-marketing denied, `meta-pixel` stays blocked whatever its own switch says.
-A script with `alwaysLoad` still mounts, as it does for a denied category;
-its callbacks receive the vendor result in `info.vendor.granted` so a
-self-managing SDK can honor it.
-
-Under an `iab` policy the `vendor` slug is inert. Vendor consent then comes from
-the TC string through `vendorId`, and the vendor rows are not shown.
-
-The same rule applies to the three gates:
-
-| Surface         | Field                           |
-| --------------- | ------------------------------- |
-| Script loader   | `Script.vendor`                 |
-| Network blocker | `NetworkBlockerRule.vendor`     |
-| Iframe blocker  | `data-vendor` on the `<iframe>` |
-
-An iframe with `data-vendor` and no `data-category` is gated on the vendor
-alone. An unknown `data-vendor` value is granted rather than thrown: a vendor
-the visitor never saw cannot have been turned off. Such a frame has no
-category to follow, so a denial the visitor recorded earlier holds even while
-nothing declares the slug, for example before the backend's vendor list has
-arrived on a cold start.
-
-A script, rule or frame keeps its slug declared for as long as it is
-configured. If a backend list or a provider update drops the entry, the
-loader or blocker puts it back, so a stored denial keeps gating it. A slug
-several modules share stays under every category they name it with, whichever
-module updates last, and drops a category only once no module names it there.
-Disposing a loader or blocker, or removing a gated frame from the page, drops
-what only it named, so a vendor no live module owns stops being toggleable.
-
-## Record a vendor choice
-
-Vendor grants travel with the save. Stage them and confirm with the next save,
-or pass them next to the categories:
-
-```ts
-// Stage from a toggle handler; nothing changes until save({}) runs. The
-// empty patch confirms no category, so only the staged vendor is recorded;
-// save() with no input would reconfirm every displayed category too.
-runtime.stageVendorConsent('meta-pixel', false);
-await runtime.kernel.commands.save({});
-
-// Or confirm categories and vendors in one action.
-await runtime.kernel.commands.save({
-	marketing: true,
-	measurement: true,
-	vendors: { 'meta-pixel': false },
-});
-```
-
-`stageVendorConsent` stages a vendor slug for the next save; it is not the
-IAB handle's `setVendorConsent`, which sets a TCF vendor by numeric id and
-takes effect at once. The grants can also travel in the save context as
-`{ vendors }`, which wins when both are given.
-
-Only the vendors the visitor turned off are stored. Accept all and reject all
-both clear that list, so vendors follow their category on a bulk action. A bulk
-action narrowed to the displayed categories only lifts the denials of vendors
-those categories decide on their own; a vendor another granted category would
-still load keeps its denial. A
-vendor that is not declared, or is declared with `disabled: true`, is ignored.
-Under an opt-out policy every vendor starts on and the stored list is the
-do-not-sell list.
-
-A vendor-only change records without touching category receipts. The kernel
-emits `vendors:recorded` rather than `choice:recorded`, writes the
-`<storageKey>-vendors` cookie and localStorage entry, and sends the complete
-grant map to the backend as `vendorChoice`. Category confirmation times are not
-renewed. The vendor entry also carries the subject id, so a visitor whose first
-act only decided vendors keeps the same subject after a reload even though no
-category record exists yet.
-
-Scripts see the vendor result in their callbacks. `ScriptCallbackInfo.vendor`
-carries `{ id, granted }` outside IAB mode. Integrations that send Google
-Consent Mode or RudderStack signals send every category as denied while their
-vendor is off, so the vendor's own consent API cannot re-enable tracking.
-
-## Show vendors in the preference center
-
-The `ConsentWidget` and `ConsentDialog` in React, Vue and Svelte list vendors
-under their category when the provider declares them. Pass the same `vendors`
-array to `ConsentProvider`, to the `vendors` prop of `ConsentRoot` in
-[Next.js](../frameworks/next/script-loader.md#granular-consent) and
-[TanStack Start](https://c15t.com/docs/frameworks/tanstack-start/quickstart#granular-consent),
-to the Nuxt module or Vue plugin config next to `scripts`, or to
-`ConsentManagerProvider` options in Svelte:
-
-```tsx
-import { ConsentProvider, hosted } from 'c15t/react';
-
-<ConsentProvider options={{ mode: hosted({ url: '/api/c15t' }), vendors }}>
-	{children}
-</ConsentProvider>;
-```
-
-Each category row expands to one card per vendor with its own switch. The
-switches disable while the category is off in the draft, and Save records the
-vendors the visitor moved. A custom control uses `useVendorDraft()` from
-`c15t/react` to read and stage the same grants, with `isStale` and `reset` for
-a draft the policy or vendor list changed under, and `useVendorAllowed(id)` to
-read one vendor's effective result. Copy comes from
-`consentManagerDialog.vendors.{title, privacyPolicy, disabledByCategory,
-switchLabel}` in the translations. In Vue, `useConsentDraft()` returns the
-same `vendors` map and `setVendor`; in Svelte, `getConsentManager()` exposes
-`selectedVendors`, `setSelectedVendor` and `getDisplayedVendors(category)`.
-The three frameworks render the same cards, and the parity suite compares
-their markup, accessibility tree, computed styles and geometry.
-
-## What a denial does not do
-
-Turning a vendor off blocks future loads and requests. It does not delete the
-cookies that vendor already set, and
-[clear on revocation](./clear-on-revocation.md) does not help here:
-it runs when a category is denied, and the category stays granted when only one
-of its vendors is off. Remove that vendor's cookies yourself from an
-`onConsentChange` callback that checks `info.vendor.granted`.
-
-A vendor denial has no expiry and no policy basis. It stays until the visitor
-changes it or a bulk action clears it, including across a policy change that
-requires the category choice again.
-
-Adding a vendor to the list does not reopen consent. New vendors default to on
-inside a granted category. Use the policy rule's `copyRevision` when a new
-vendor should prompt the visitor again.