@c15t/nextjs 2.0.0-rc.1 → 2.0.0-rc.12

package/docs/hooks/use-consent-manager/checking-consent.md

@@ -0,0 +1,94 @@
+---
+title: Checking Consent
+description: Use has() for flexible consent checks with AND, OR, and NOT logic. Check if any consent exists with hasConsented().
+---
+## has(condition)
+
+The `has()` method evaluates whether the current consent state satisfies a condition. It supports simple category checks and complex logical expressions.
+
+### Simple Check
+
+```tsx
+const { has } = useConsentManager();
+
+if (has('measurement')) {
+  // User has granted measurement consent
+}
+```
+
+### AND Logic
+
+All conditions must be true:
+
+```tsx
+has({ and: ['measurement', 'marketing'] })
+// true only if BOTH measurement AND marketing are granted
+```
+
+### OR Logic
+
+At least one condition must be true:
+
+```tsx
+has({ or: ['measurement', 'marketing'] })
+// true if EITHER measurement OR marketing is granted
+```
+
+### NOT Logic
+
+Negates a condition:
+
+```tsx
+has({ not: 'marketing' })
+// true if marketing consent is NOT granted
+```
+
+### Nested Conditions
+
+Combine operators for complex logic:
+
+```tsx
+has({
+  and: [
+    'necessary',
+    { or: ['measurement', 'marketing'] },
+    { not: 'functionality' },
+  ],
+})
+// true if: necessary AND (measurement OR marketing) AND NOT functionality
+```
+
+### HasCondition Type
+
+```ts
+type HasCondition<CategoryType> =
+  | CategoryType                                    // "measurement"
+  | { and: HasCondition[] | HasCondition }          // { and: ["a", "b"] }
+  | { or: HasCondition[] | HasCondition }           // { or: ["a", "b"] }
+  | { not: HasCondition }                           // { not: "a" }
+```
+
+## hasConsented()
+
+Returns `true` if the user has made any consent choice (accepted, rejected, or customized). Returns `false` if no consent has been recorded yet.
+
+```tsx
+const { hasConsented } = useConsentManager();
+
+if (hasConsented()) {
+  // User has previously made a consent choice
+} else {
+  // First visit — no consent recorded
+}
+```
+
+## getDisplayedConsents()
+
+Returns the consent types that should be displayed in the UI (based on active `consentCategories` and each type's `display` property):
+
+```tsx
+const { getDisplayedConsents } = useConsentManager();
+
+const visibleCategories = getDisplayedConsents();
+// Returns ConsentType[] with name, description, defaultValue, etc.
+```

package/docs/hooks/use-consent-manager/location-info.md

@@ -0,0 +1,95 @@
+---
+title: Location Info
+description: Access detected jurisdiction, country, and region. Override geolocation for testing.
+---
+## locationInfo
+
+The `locationInfo` state contains the user's detected geographic information:
+
+```tsx
+const { locationInfo } = useConsentManager();
+
+if (locationInfo) {
+  console.log(locationInfo.jurisdiction); // 'GDPR', 'CCPA', etc.
+  console.log(locationInfo.countryCode);  // 'DE', 'US', etc.
+  console.log(locationInfo.regionCode);   // 'BY', 'CA', etc.
+}
+```
+
+`locationInfo` is `null` until the backend responds with geolocation data (or in offline mode if no overrides are set).
+
+## Jurisdiction Codes
+
+|Code|Region|Consent Model|
+|--|--|--|
+|`GDPR`|European Union|opt-in|
+|`UK_GDPR`|United Kingdom|opt-in|
+|`CH`|Switzerland|opt-in|
+|`BR`|Brazil (LGPD)|opt-in|
+|`APPI`|Japan|opt-in|
+|`PIPA`|South Korea|opt-in|
+|`PIPEDA`|Canada (excl. Quebec)|opt-out|
+|`QC_LAW25`|Quebec, Canada|opt-in|
+|`CCPA`|California, USA|opt-out|
+|`AU`|Australia|opt-out|
+|`NONE`|No jurisdiction|null model|
+
+## setOverrides()
+
+Override detected values for testing or manual configuration. This triggers a re-fetch of consent banner data with the new values:
+
+```tsx
+const { setOverrides } = useConsentManager();
+
+// Override country (triggers jurisdiction detection)
+await setOverrides({ country: 'DE' });
+
+// Override language
+await setOverrides({ language: 'de' });
+
+// Override both
+await setOverrides({ country: 'US', region: 'CA', language: 'es' });
+```
+
+## setLocationInfo()
+
+Directly set location info without triggering a re-fetch:
+
+```tsx
+const { setLocationInfo } = useConsentManager();
+
+setLocationInfo({
+  jurisdiction: 'GDPR',
+  countryCode: 'DE',
+  regionCode: 'BY',
+});
+```
+
+## Testing Different Jurisdictions
+
+A development-only component for testing consent behavior across jurisdictions:
+
+```tsx
+function JurisdictionTester() {
+  const { setOverrides, model, locationInfo } = useConsentManager();
+
+  const testCases = [
+    { label: 'GDPR', country: 'DE' },
+    { label: 'CCPA', country: 'US', region: 'CA' },
+    { label: 'PIPEDA', country: 'CA', region: undefined },
+    { label: 'QC_LAW25', country: 'CA', region: 'QC' },
+    { label: 'NONE', country: 'US', region: 'TX' },
+  ];
+
+  return (
+    <div>
+      <p>Current: {locationInfo?.jurisdiction ?? 'none'} → model: {model}</p>
+      {testCases.map((tc) => (
+        <button key={tc.label} onClick={() => setOverrides({ country: tc.country, region: tc.region })}>
+          Test as {tc.label}
+        </button>
+      ))}
+    </div>
+  );
+}
+```

package/docs/hooks/use-consent-manager/overview.md

@@ -0,0 +1,420 @@
+---
+title: useConsentManager
+description: The primary hook for accessing consent state and actions. Returns the full consent store including all state properties and action methods.
+---
+`useConsentManager()` is the primary hook for interacting with the consent system. It returns the complete consent store state and all action methods.
+
+```tsx
+import { useConsentManager } from '@c15t/nextjs';
+
+function MyComponent() {
+  const {
+    consents,
+    model,
+    has,
+    saveConsents,
+    // ... all state and actions
+  } = useConsentManager();
+}
+```
+
+> ℹ️ **Info:**
+> Must be used within a ConsentManagerProvider. Throws an error if used outside the provider.
+
+## State Properties
+
+### StoreRuntimeState
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|branding|"c15t" \|"inth" \|"consent" \|"none"|Whether to show the branding. "consent" is a deprecated alias for "inth".|-|✅ Required|
+|consents|ConsentState|Current consent states for all consent types|-|✅ Required|
+|selectedConsents|ConsentState|Selected consents (Not Saved) - use saveConsents to save|-|✅ Required|
+|consentInfo|ConsentInfo \|null|Information about when and how consent was given|-|✅ Required|
+|activeUI|ActiveUI|Which consent UI component is currently visible.|-|✅ Required|
+|isLoadingConsentInfo|boolean|Whether consent banner information is currently being loaded|-|✅ Required|
+|hasFetchedBanner|boolean|Whether consent banner information has been successfully fetched|-|✅ Required|
+|lastBannerFetchData|Object \|undefined \|null|Last consent banner fetch data for callback replay|-|✅ Required|
+|debug|boolean|Whether debug logging is enabled|-|✅ Required|
+|consentCategories|AllConsentNames|Active consent categories|-|✅ Required|
+|locationInfo|LocationInfo \|null|Subject's location information|-|✅ Required|
+|includeNonDisplayedConsents|boolean|Whether to include non-displayed consents in operations|-|✅ Required|
+|consentTypes|ConsentType|Available consent type configurations|-|✅ Required|
+|iframeBlockerConfig|IframeBlockerConfig|Configuration for the iframe blocker|-|✅ Required|
+|loadedScripts|Record\<string, boolean>|Map of currently loaded script IDs to a boolean loaded-state|-|✅ Required|
+|scriptIdMap|Record\<string, string>|Map of anonymized script IDs to their original IDs|-|✅ Required|
+|model|Model|What type of consent model to use for the consent manager.|-|✅ Required|
+|policyBanner|PolicySurfaceState|Policy-driven UI hints for the consent banner surface.|-|✅ Required|
+|policyDialog|PolicySurfaceState|Policy-driven UI hints for the consent dialog surface.|-|✅ Required|
+|policyCategories|string\[] \|null|Active runtime policy category scope from \`/init\`.|-|✅ Required|
+|policyScopeMode|PolicyScopeMode \|null|Runtime policy scope mode from \`/init\`. Controls whether out-of-scope categories are treated as permissive at runtime.|-|✅ Required|
+|initDataSource|InitDataSource \|null|Source that provided the most recent \`/init\` payload used to hydrate runtime state.|-|✅ Required|
+|initDataSourceDetail|string \|null|Optional source detail for diagnostics (for example, cache header values).|-|✅ Required|
+|iab|IABManager \|null|IAB TCF 2.3 state and actions (null when not configured or not in IAB mode).|-|✅ Required|
+|reloadOnConsentRevoked|boolean|Whether to reload the page when consent is revoked.|-|✅ Required|
+|ssrDataUsed|boolean|Whether SSR data was successfully used for initialization.|-|✅ Required|
+|ssrSkippedReason|SSRSkippedReason|Reason SSR data was skipped, if applicable.|-|✅ Required|
+
+#### `consents` ConsentState
+
+Current consent states for all consent types
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|experience|boolean|-|-|✅ Required|
+|functionality|boolean|-|-|✅ Required|
+|marketing|boolean|-|-|✅ Required|
+|measurement|boolean|-|-|✅ Required|
+|necessary|boolean|-|-|✅ Required|
+
+#### `selectedConsents` ConsentState
+
+Selected consents (Not Saved) - use saveConsents to save
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|experience|boolean|-|-|✅ Required|
+|functionality|boolean|-|-|✅ Required|
+|marketing|boolean|-|-|✅ Required|
+|measurement|boolean|-|-|✅ Required|
+|necessary|boolean|-|-|✅ Required|
+
+#### `consentInfo` ConsentInfo
+
+Information about when and how consent was given
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|time|number|The epoch timestamp of when the consent was recorded|-|✅ Required|
+|subjectId|string \|undefined|The client-generated subject ID in sub\_xxx format|-|Optional|
+|id|string \|undefined|Effective GPC signal used for the request.|-|Optional|
+|externalId|string \|undefined|The external user ID linked to this subject|-|Optional|
+|materialPolicyFingerprint|string \|undefined|Material fingerprint of the active policy when this consent was accepted.|-|Optional|
+|identityProvider|string \|undefined|The identity provider that provided the external ID|-|Optional|
+
+#### `locationInfo` LocationInfo
+
+Subject's location information
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|countryCode|string \|null|ISO country code (e.g., 'US', 'GB', 'DE')|-|✅ Required|
+|regionCode|string \|null|Region or state code within the country (e.g., 'CA', 'ENG')|-|✅ Required|
+|jurisdiction|Object \|null|Jurisdiction code (e.g. 'GDPR')|-|✅ Required|
+
+#### `consentTypes` ConsentType
+
+Available consent type configurations
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|defaultValue|boolean|Whether consent is granted by default|-|✅ Required|
+|description|string|Subject-friendly description of what this consent enables|-|✅ Required|
+|disabled|boolean \|undefined|Whether users can modify this consent setting|-|Optional|
+|display|boolean|Whether to show this consent option in the UI|-|✅ Required|
+|gdprType|number|GDPR category identifier (1-5)|-|✅ Required|
+|name|AllConsentNames|The consent category name|-|✅ Required|
+
+#### `iframeBlockerConfig` IframeBlockerConfig
+
+Configuration for the iframe blocker
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|disableAutomaticBlocking|boolean \|undefined|Whether to disable automatic iframe blocking (defaults to false)|-|Optional|
+
+#### `policyBanner` PolicySurfaceState
+
+Policy-driven UI hints for the consent banner surface.
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|allowedActions|PolicyUiAction \|undefined|Allowed actions for this surface derived from backend runtime policy.|-|Optional|
+|primaryActions|PolicyUiAction \|undefined|Preferred primary action hints from backend runtime policy.|-|Optional|
+|layout|PolicyUiActionGroup \|undefined|Explicit grouped action layout hint from backend runtime policy.|-|Optional|
+|direction|PolicyUiActionDirection \|undefined|Direction hint for the grouped action layout.|-|Optional|
+|uiProfile|PolicyUiProfile \|undefined|Presentation profile hint from backend runtime policy.|-|Optional|
+|scrollLock|boolean \|undefined|Scroll lock hint from backend runtime policy.|-|Optional|
+
+#### `policyDialog` PolicySurfaceState
+
+Policy-driven UI hints for the consent dialog surface.
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|allowedActions|PolicyUiAction \|undefined|Allowed actions for this surface derived from backend runtime policy.|-|Optional|
+|primaryActions|PolicyUiAction \|undefined|Preferred primary action hints from backend runtime policy.|-|Optional|
+|layout|PolicyUiActionGroup \|undefined|Explicit grouped action layout hint from backend runtime policy.|-|Optional|
+|direction|PolicyUiActionDirection \|undefined|Direction hint for the grouped action layout.|-|Optional|
+|uiProfile|PolicyUiProfile \|undefined|Presentation profile hint from backend runtime policy.|-|Optional|
+|scrollLock|boolean \|undefined|Scroll lock hint from backend runtime policy.|-|Optional|
+
+#### `iab` IABManager
+
+IAB TCF 2.3 state and actions (null when not configured or not in IAB mode).
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|config|IABConfig|IAB TCF configuration|-|✅ Required|
+|gvl|Object \|undefined \|null|Global Vendor List data (null when not yet fetched or in non-IAB region)|-|✅ Required|
+|isLoadingGVL|boolean|Whether GVL is currently being fetched|-|✅ Required|
+|nonIABVendors|NonIABVendor|Non-IAB vendors configured by the publisher|-|✅ Required|
+|tcString|string \|null|IAB TCF consent string (TC String)|-|✅ Required|
+|vendorConsents|Record\<string, boolean>|Per-vendor consent state (keyed by vendor ID)|-|✅ Required|
+|vendorLegitimateInterests|Record\<string, boolean>|Per-vendor legitimate interest state|-|✅ Required|
+|purposeConsents|Record\<number, boolean>|Per-purpose consent state (IAB purposes 1-11)|-|✅ Required|
+|purposeLegitimateInterests|Record\<number, boolean>|Per-purpose legitimate interest state|-|✅ Required|
+|specialFeatureOptIns|Record\<number, boolean>|Special feature opt-ins (e.g., precise geolocation)|-|✅ Required|
+|vendorsDisclosed|Record\<number, boolean>|Vendors disclosed to the user in the CMP UI (TCF 2.3 requirement). This tracks which vendors were shown to the user, regardless of whether consent was given. Required for TC String generation.|-|✅ Required|
+|cmpApi|CMPApi \|null|CMP API controls (manages \_\_tcfapi)|-|✅ Required|
+|preferenceCenterTab|"purposes" \|"vendors"|Active tab for the IAB preference center UI|-|✅ Required|
+|setPurposeConsent|(purposeId: number, value: boolean) => void|Sets IAB purpose consent.|-|✅ Required|
+|setPurposeLegitimateInterest|(purposeId: number, value: boolean) => void|Sets IAB purpose legitimate interest.|-|✅ Required|
+|setVendorConsent|(vendorId: string \|number, value: boolean) => void|Sets IAB vendor consent.|-|✅ Required|
+|setVendorLegitimateInterest|(vendorId: string \|number, value: boolean) => void|Sets IAB vendor legitimate interest.|-|✅ Required|
+|setSpecialFeatureOptIn|(featureId: number, value: boolean) => void|Sets special feature opt-in.|-|✅ Required|
+|setPreferenceCenterTab|(tab: "purposes" \|"vendors") => void|Sets the active tab for the IAB preference center.|-|✅ Required|
+|acceptAll|() => void|Accepts all IAB purposes, vendors, and special features.|-|✅ Required|
+|rejectAll|() => void|Rejects all IAB purposes (except necessary/Purpose 1) and vendors.|-|✅ Required|
+|save|() => Promise\<void>|Saves IAB consents and generates TC String.|-|✅ Required|
+|\_updateState|(updates: Partial\<IABState>) => void|Updates IAB state (internal use).|-|✅ Required|
+
+## Action Methods
+
+### StoreActions
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|setTranslationConfig|Object|Updates the translation configuration.|-|✅ Required|
+|setOverrides|Object \|undefined \|null|Sets the overrides for the consent manager. Automatically attempts to fetch the consent manager again with the new overrides.|-|✅ Required|
+|setLanguage|Object \|undefined \|null|Set the language override for the consent manager. This will override the language detected from the browser and re-fetch the consent banner information.|-|✅ Required|
+|identifyUser|Object|Identifies the user by setting the external ID.|-|✅ Required|
+|unstable\_acceptPolicyConsent|Object \|undefined|Writes a policy-based consent such as terms and conditions.|-|✅ Required|
+|setSelectedConsent|(name: AllConsentNames, value: boolean) => void|Updates the selected consent state for a specific consent type.|-|✅ Required|
+|saveConsents|Object \|undefined|Saves the user's consent preferences.|-|✅ Required|
+|setConsent|(name: AllConsentNames, value: boolean) => void|Updates the consent state for a specific consent type & automatically save the consent.|-|✅ Required|
+|resetConsents|() => void|Resets all consent preferences to their default values|-|✅ Required|
+|setActiveUI|(ui: ActiveUI, options?: \{ force?: boolean \|undefined; } \|undefined) => void|Sets the active consent UI component.|-|✅ Required|
+|setConsentCategories|(types: AllConsentNames\[]) => void|Updates the active GDPR consent types.|-|✅ Required|
+|setCallback|Object \|undefined|Sets a callback for a specific consent event.|-|✅ Required|
+|subscribeToConsentChanges|Object|Subscribes to change-only consent saves.|-|✅ Required|
+|setLocationInfo|Object \|null|Updates the user's location information.|-|✅ Required|
+|initConsentManager|Object \|undefined \|null|Initializes the consent manager by fetching jurisdiction, location, translations, and branding information.|-|✅ Required|
+|getDisplayedConsents|ConsentType|Retrieves the list of consent types that should be displayed|-|✅ Required|
+|hasConsented|() => boolean|Checks if the user has provided any form of consent|-|✅ Required|
+|has|Object|Evaluates whether current consent state satisfies the given condition.|-|✅ Required|
+|setScripts|Object|Sets multiple script configurations to the store.|-|✅ Required|
+|removeScript|(scriptId: string) => void|Removes a script configuration from the store.|-|✅ Required|
+|updateScripts|Object|Updates scripts based on current consent state. Loads scripts that have consent and aren't loaded yet. Unloads scripts that no longer have consent.|-|✅ Required|
+|isScriptLoaded|(scriptId: string) => boolean|Checks if a script is currently loaded.|-|✅ Required|
+|getLoadedScriptIds|() => string\[]|Gets all currently loaded script IDs.|-|✅ Required|
+|initializeIframeBlocker|() => void|Initializes the iframe blocker instance.|-|✅ Required|
+|updateIframeConsents|() => void|Updates the active consents used by the iframe blocker.|-|✅ Required|
+|destroyIframeBlocker|() => void|Destroys the iframe blocker instance and cleans up resources.|-|✅ Required|
+|initializeNetworkBlocker|() => void|Initializes the network blocker instance.|-|✅ Required|
+|updateNetworkBlockerConsents|() => void|Updates the consent snapshot used by the network blocker.|-|✅ Required|
+|setNetworkBlocker|Object \|undefined|Updates the network blocker configuration at runtime.|-|✅ Required|
+|destroyNetworkBlocker|() => void|Destroys the network blocker instance and cleans up resources.|-|✅ Required|
+|updateConsentCategories|(newCategories: AllConsentNames\[]) => void|Extends the active GDPR consent categories with any categories used by configured scripts.|-|✅ Required|
+
+#### `setTranslationConfig`
+
+Updates the translation configuration.
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|translations|Record\<string, Partial\<Translations>>|-|-|✅ Required|
+|defaultLanguage|string \|undefined|-|-|Optional|
+|disableAutoLanguageSwitch|boolean \|undefined|-|-|Optional|
+
+#### `setOverrides`
+
+Sets the overrides for the consent manager. Automatically attempts to fetch the consent manager again with the new overrides.
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|country|string \|undefined|Country code to forcefully set|-|Optional|
+|region|string \|undefined|Region code to forcefully set|-|Optional|
+|language|string \|undefined|Language code to forcefully set|-|Optional|
+|gpc|boolean \|undefined|Override the Global Privacy Control (GPC) signal. When \`true\`, simulates GPC being active (opt-out of marketing/measurement). When \`false\`, suppresses the real browser GPC signal. When \`undefined\`, falls back to the browser's \`navigator.globalPrivacyControl\`.|-|Optional|
+
+#### `identifyUser`
+
+Identifies the user by setting the external ID.
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|id|string|Usually your own internal ID for the user from your auth provider|-|✅ Required|
+|identityProvider|string \|undefined|The identity provider of the user. Usually the name of the identity provider e.g. 'clerk', 'auth0', 'custom', etc.|-|Optional|
+
+#### `unstable_acceptPolicyConsent`
+
+Writes a policy-based consent such as terms and conditions.
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|type|Object|-|-|✅ Required|
+|domain|string \|undefined|-|-|Optional|
+|givenAt|number \|undefined|-|-|Optional|
+|metadata|Record\<string, unknown> \|undefined|-|-|Optional|
+|preferences|Record\<string, boolean> \|undefined|-|-|Optional|
+|uiSource|string \|undefined|-|-|Optional|
+|externalId|string \|undefined|-|-|Optional|
+|identityProvider|string \|undefined|-|-|Optional|
+
+#### `subscribeToConsentChanges`
+
+Subscribes to change-only consent saves.
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|preferences|ConsentState|-|-|✅ Required|
+|previousPreferences|ConsentState|-|-|✅ Required|
+|allowedCategories|AllConsentNames|-|-|✅ Required|
+|deniedCategories|AllConsentNames|-|-|✅ Required|
+|previousAllowedCategories|AllConsentNames|-|-|✅ Required|
+|previousDeniedCategories|AllConsentNames|-|-|✅ Required|
+
+#### `setLocationInfo`
+
+Updates the user's location information.
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|countryCode|string \|null|ISO country code (e.g., 'US', 'GB', 'DE')|-|✅ Required|
+|regionCode|string \|null|Region or state code within the country (e.g., 'CA', 'ENG')|-|✅ Required|
+|jurisdiction|Object \|null|Jurisdiction code (e.g. 'GDPR')|-|✅ Required|
+
+#### `setScripts`
+
+Sets multiple script configurations to the store.
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|id|string|Unique identifier for the script|-|✅ Required|
+|src|string \|undefined|URL of the script to load|-|Optional|
+|textContent|string \|undefined|Inline JavaScript code to execute|-|Optional|
+|category|HasCondition\<AllConsentNames>|Consent category or condition required to load this script|-|✅ Required|
+|callbackOnly|boolean \|undefined|Whether this is a callback-only script that doesn't need to load an external resource. When true, no script tag will be added to the DOM, only callbacks will be executed.|-|Optional|
+|persistAfterConsentRevoked|boolean \|undefined|Whether the script should persist after consent is revoked.|-|Optional|
+|alwaysLoad|boolean \|undefined|Whether the script should always load regardless of consent state. This is useful for scripts like Google Tag Manager or PostHog that manage their own consent state internally. The script will load immediately and never be unloaded based on consent changes. Note: When using this option, you are responsible for ensuring the script itself respects user consent preferences through its own consent management.|-|Optional|
+|fetchPriority|"high" \|"low" \|"auto" \|undefined|Priority hint for browser resource loading|-|Optional|
+|attributes|Record\<string, string> \|undefined|Additional attributes to add to the script element|-|Optional|
+|async|boolean \|undefined|Whether to use async loading|-|Optional|
+|defer|boolean \|undefined|Whether to defer script loading|-|Optional|
+|nonce|string \|undefined|Content Security Policy nonce|-|Optional|
+|anonymizeId|boolean \|undefined|Whether to use an anonymized ID for the script element, this helps ensure the script is not blocked by ad blockers|-|Optional|
+|target|"head" \|"body" \|undefined|Where to inject the script element in the DOM. Options: \`'head'\`: Scripts are appended to \`\<head>\` (default); \`'body'\`: Scripts are appended to \`\<body>\`|-|Optional|
+|onBeforeLoad|((info: ScriptCallbackInfo) => void) \|undefined|Callback executed before the script is loaded|-|Optional|
+|onLoad|((info: ScriptCallbackInfo) => void) \|undefined|Callback executed when the script loads successfully|-|Optional|
+|onError|((info: ScriptCallbackInfo) => void) \|undefined|Callback executed if the script fails to load|-|Optional|
+|onConsentChange|((info: ScriptCallbackInfo) => void) \|undefined|Callback executed whenever the consent store is changed. This callback only applies to scripts already loaded.|-|Optional|
+|vendorId|string \|number \|undefined|IAB TCF vendor ID - links script to a registered vendor. When in IAB mode, the script will only load if this vendor has consent. Takes precedence over \`category\` when in IAB mode. Use custom vendor IDs (string or number) to gate non-IAB vendors too.|-|Optional|
+|iabPurposes|number\[] \|undefined|IAB TCF purpose IDs this script requires consent for. When in IAB mode and no vendorId is set, the script will only load if ALL specified purposes have consent.|-|Optional|
+|iabLegIntPurposes|number\[] \|undefined|IAB TCF legitimate interest purpose IDs. These purposes can operate under legitimate interest instead of consent. The script loads if all iabPurposes have consent OR all iabLegIntPurposes have legitimate interest established.|-|Optional|
+|iabSpecialFeatures|number\[] \|undefined|IAB TCF special feature IDs this script requires. Options: 1: Use precise geolocation data; 2: Actively scan device characteristics for identification|-|Optional|
+
+#### `setNetworkBlocker`
+
+Updates the network blocker configuration at runtime.
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|enabled|boolean \|undefined|Whether the network blocker is enabled.|-|Optional|
+|initialConsents|ConsentState \|undefined|The consent state snapshot that is currently used for blocking logic.|-|Optional|
+|logBlockedRequests|boolean \|undefined|Whether to automatically log blocked requests to the console.|-|Optional|
+|onRequestBlocked|((info: BlockedRequestInfo) => void) \|undefined|Callback invoked whenever a request is blocked.|-|Optional|
+|rules|NetworkBlockerRule|Domain rules that determine which requests should be blocked.|-|✅ Required|
+
+## identifyUser
+
+The `identifyUser()` method links anonymous consent records to an authenticated user. Call it after a user logs in to associate their consent preferences with their account.
+
+```tsx
+import { useConsentManager } from '@c15t/nextjs';
+
+function LoginForm() {
+  const { identifyUser } = useConsentManager();
+
+  async function handleLogin(email: string) {
+    // ... your login logic
+    const user = await api.login(email);
+
+    // Link consent to the authenticated user
+    await identifyUser({
+      id: user.id,
+      identityProvider: 'your-auth-provider', // e.g. 'clerk', 'auth0'
+    });
+  }
+
+  return (
+    <form onSubmit={(e) => {
+      e.preventDefault();
+      handleLogin(new FormData(e.currentTarget).get('email') as string);
+    }}>
+      <input name="email" type="email" placeholder="Email" />
+      <button type="submit">Log in</button>
+    </form>
+  );
+}
+```
+
+> ℹ️ **Info:**
+> identifyUser sends the user data to the c15t backend. It works in hosted mode, including the legacy alias mode: 'c15t'. In mode: 'offline', the call is a no-op.
+
+## Key Types
+
+<details>
+  <summary>`ConsentState`</summary>
+
+  A record mapping consent category names to their boolean values:
+
+  ```ts
+  type ConsentState = Record<AllConsentNames, boolean>;
+  // Example: { necessary: true, measurement: true, marketing: false }
+  ```
+</details>
+
+<details>
+  <summary>`ConsentInfo`</summary>
+
+  Metadata about when and how consent was recorded:
+
+  ```ts
+  interface ConsentInfo {
+    time: number;                    // Epoch timestamp when consent was recorded
+    subjectId?: string;              // Client-generated subject ID (sub_xxx format)
+    externalId?: string;             // External user ID linked via identifyUser()
+    identityProvider?: string;       // Identity provider (e.g. 'clerk', 'auth0')
+  }
+  ```
+</details>
+
+<details>
+  <summary>`LocationInfo`</summary>
+
+  Detected geographic location from the c15t backend:
+
+  ```ts
+  interface LocationInfo {
+    countryCode: string;     // ISO 3166-1 alpha-2 (e.g. 'DE')
+    regionCode: string;      // Region/state code (e.g. 'BY')
+    jurisdiction: string;    // Applicable jurisdiction (e.g. 'GDPR', 'CCPA')
+  }
+  ```
+</details>
+
+<details>
+  <summary>`Model`</summary>
+
+  The active consent model:
+
+  ```ts
+  type Model = 'opt-in' | 'opt-out' | 'iab' | null;
+  ```
+
+  * `'opt-in'` — Explicit consent required before tracking (GDPR)
+  * `'opt-out'` — Tracking allowed by default, user can opt out (CCPA)
+  * `'iab'` — IAB TCF 2.3 compliance mode
+  * `null` — No jurisdiction detected yet
+</details>