@c15t/browser 3.0.0-alpha.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (93) hide show
  1. package/AGENTS.md +64 -0
  2. package/CHANGELOG.md +27 -0
  3. package/README.md +128 -0
  4. package/dist/861.js +1079 -0
  5. package/dist/925.js +649 -0
  6. package/dist/c15t.css +213 -0
  7. package/dist/c15t.devtools.js +1 -0
  8. package/dist/c15t.headless.js +1 -0
  9. package/dist/c15t.iab.css +190 -0
  10. package/dist/c15t.iab.js +221 -0
  11. package/dist/c15t.js +30 -0
  12. package/dist/devtools.js +11 -0
  13. package/dist/headless.js +17 -0
  14. package/dist/iab.js +784 -0
  15. package/dist/index.js +17 -0
  16. package/dist-types/auto-init.d.ts +42 -0
  17. package/dist-types/client.d.ts +51 -0
  18. package/dist-types/deferred.d.ts +13 -0
  19. package/dist-types/devtools.d.ts +32 -0
  20. package/dist-types/entries/cdn-devtools.d.ts +13 -0
  21. package/dist-types/entries/cdn-headless.d.ts +8 -0
  22. package/dist-types/entries/cdn-iab.d.ts +1 -0
  23. package/dist-types/entries/cdn.d.ts +8 -0
  24. package/dist-types/gated-scripts.d.ts +35 -0
  25. package/dist-types/generated/iab-styles.d.ts +144 -0
  26. package/dist-types/generated/styles.d.ts +137 -0
  27. package/dist-types/global.d.ts +112 -0
  28. package/dist-types/headless.d.ts +41 -0
  29. package/dist-types/iab/mount.d.ts +8 -0
  30. package/dist-types/iab/preferences.d.ts +9 -0
  31. package/dist-types/iab/styles.d.ts +2 -0
  32. package/dist-types/iab/surface.d.ts +4 -0
  33. package/dist-types/iab/vendor-disclosures.d.ts +14 -0
  34. package/dist-types/iab.d.ts +20 -0
  35. package/dist-types/index.d.ts +43 -0
  36. package/dist-types/transports/manifest.d.ts +62 -0
  37. package/dist-types/transports/offline.d.ts +18 -0
  38. package/dist-types/types.d.ts +290 -0
  39. package/dist-types/ui/actions.d.ts +29 -0
  40. package/dist-types/ui/banner.d.ts +13 -0
  41. package/dist-types/ui/branding.d.ts +25 -0
  42. package/dist-types/ui/copy.d.ts +28 -0
  43. package/dist-types/ui/dialog.d.ts +14 -0
  44. package/dist-types/ui/dom.d.ts +48 -0
  45. package/dist-types/ui/mount.d.ts +27 -0
  46. package/dist-types/ui/surface.d.ts +43 -0
  47. package/dist-types/ui/trigger.d.ts +14 -0
  48. package/dist-types/ui/widget.d.ts +27 -0
  49. package/dist-types/version.d.ts +1 -0
  50. package/docs/README.md +64 -0
  51. package/docs/frameworks/javascript/script-loader.md +47 -0
  52. package/docs/frameworks/javascript/script-tag.md +375 -0
  53. package/docs/integrations/adobe-analytics.md +294 -0
  54. package/docs/integrations/ahrefs-analytics.md +291 -0
  55. package/docs/integrations/amplitude.md +292 -0
  56. package/docs/integrations/building-integrations.md +47 -0
  57. package/docs/integrations/clearbit.md +291 -0
  58. package/docs/integrations/cloudflare-web-analytics.md +292 -0
  59. package/docs/integrations/crisp.md +294 -0
  60. package/docs/integrations/databuddy.md +311 -0
  61. package/docs/integrations/fathom-analytics.md +293 -0
  62. package/docs/integrations/google-maps.md +384 -0
  63. package/docs/integrations/google-tag-manager.md +306 -0
  64. package/docs/integrations/google-tag.md +305 -0
  65. package/docs/integrations/heap.md +292 -0
  66. package/docs/integrations/hightouch.md +293 -0
  67. package/docs/integrations/hotjar.md +292 -0
  68. package/docs/integrations/intercom.md +285 -0
  69. package/docs/integrations/linkedin-insights.md +291 -0
  70. package/docs/integrations/logrocket.md +293 -0
  71. package/docs/integrations/matomo-analytics.md +316 -0
  72. package/docs/integrations/meta-pixel.md +285 -0
  73. package/docs/integrations/microsoft-clarity.md +292 -0
  74. package/docs/integrations/microsoft-uet.md +291 -0
  75. package/docs/integrations/mixpanel-analytics.md +295 -0
  76. package/docs/integrations/openai-pixel.md +441 -0
  77. package/docs/integrations/overview.md +111 -0
  78. package/docs/integrations/pirsch.md +295 -0
  79. package/docs/integrations/plausible-analytics.md +295 -0
  80. package/docs/integrations/posthog.md +397 -0
  81. package/docs/integrations/promptwatch.md +291 -0
  82. package/docs/integrations/reddit-pixel.md +294 -0
  83. package/docs/integrations/rudderstack.md +328 -0
  84. package/docs/integrations/rybbit-analytics.md +296 -0
  85. package/docs/integrations/segment.md +292 -0
  86. package/docs/integrations/snapchat-pixel.md +293 -0
  87. package/docs/integrations/tiktok-pixel.md +291 -0
  88. package/docs/integrations/umami-analytics.md +295 -0
  89. package/docs/integrations/vercel-analytics.md +293 -0
  90. package/docs/integrations/x-pixel.md +291 -0
  91. package/docs/integrations/youtube.md +405 -0
  92. package/package.json +117 -0
  93. package/readme.json +44 -0
package/dist-types/ui/dom.d.ts ADDED
@@ -0,0 +1,48 @@
1
+ /** Anything `h()` accepts as a child. */
2
+ export type Child = Node | string | number | null | undefined | false;
3
+ /** Attribute values `h()` accepts. `true` sets an empty attribute. */
4
+ export type AttrValue = string | number | boolean | null | undefined | EventListener;
5
+ /**
6
+ * Create an element with attributes and children.
7
+ *
8
+ * Attributes starting with `on` and holding a function become event
9
+ * listeners; `class` is a plain attribute so an empty string stays off
10
+ * the element when `noStyle` blanks every class.
11
+ *
12
+ * @param tag - Element tag.
13
+ * @param attrs - Attributes.
14
+ * @param children - Text or nodes to append.
15
+ * @returns The element.
16
+ */
17
+ export declare const h: <TagName extends keyof HTMLElementTagNameMap>(tag: TagName, attrs?: Record<string, AttrValue>, ...children: Child[]) => HTMLElementTagNameMap[TagName];
18
+ /**
19
+ * Create an inline SVG icon.
20
+ *
21
+ * @param viewBox - The `viewBox`.
22
+ * @param paths - Path `d` strings, filled with `currentColor`.
23
+ * @param attrs - Extra attributes on the `<svg>`.
24
+ * @returns The element.
25
+ */
26
+ export declare const svg: (viewBox: string, paths: string[], attrs?: Record<string, AttrValue>) => SVGSVGElement;
27
+ /**
28
+ * Join class names, dropping blanks.
29
+ *
30
+ * @param names - Class names, possibly empty or undefined.
31
+ * @returns The joined string.
32
+ */
33
+ export declare const cx: (...names: (string | undefined | false | null)[]) => string;
34
+ /**
35
+ * Read a CSS duration custom property from an element, in milliseconds.
36
+ *
37
+ * @param element - The element carrying the variable.
38
+ * @param name - The custom property name.
39
+ * @param fallback - Used when the property is unset or unparsable.
40
+ * @returns Milliseconds.
41
+ */
42
+ export declare const readDurationMs: (element: Element, name: string, fallback: number) => number;
43
+ /**
44
+ * Whether the visitor asked for reduced motion.
45
+ *
46
+ * @returns `true` when the media query matches.
47
+ */
48
+ export declare const prefersReducedMotion: () => boolean;
package/dist-types/ui/mount.d.ts ADDED
@@ -0,0 +1,27 @@
1
+ import type { ConsentClient, ConsentUIHandle, ConsentUIOptions } from '../types';
2
+ import type { Surface, SurfaceContext } from './surface';
3
+ /**
4
+ * Mount the banner, preference centre and trigger for a client.
5
+ *
6
+ * By default everything renders inside a shadow root on a host element
7
+ * appended to `<body>`, carrying its own copy of the `@c15t/ui`
8
+ * stylesheet, so a Framer or WordPress theme's global `button {}` rules
9
+ * cannot reach it. Pass `shadow: false` to render into the page and style
10
+ * it yourself.
11
+ *
12
+ * @param client - The client to render.
13
+ * @param options - Where and how to mount.
14
+ * @returns A handle that re-renders or tears down.
15
+ * @throws {Error} When `container` is a selector that matches nothing.
16
+ *
17
+ * @example
18
+ * ```ts
19
+ * const client = createConsentClient({ backendURL: 'https://x.c15t.dev' });
20
+ * client.start();
21
+ * mountConsentUI(client, { colorScheme: 'dark', trigger: true });
22
+ * ```
23
+ */
24
+ export declare const mountConsentUI: (client: ConsentClient, options?: ConsentUIOptions, extension?: {
25
+ stylesheet: string;
26
+ createSurfaces: (ctx: SurfaceContext) => Surface[];
27
+ }) => ConsentUIHandle;
package/dist-types/ui/surface.d.ts ADDED
@@ -0,0 +1,43 @@
1
+ import type { ConsentSnapshot, LegalLinks } from '@c15t/core';
2
+ import type { LegalLinksTranslations } from '@c15t/translations';
3
+ import type { ConsentClient } from '../types';
4
+ /** What every surface renders against. */
5
+ export interface SurfaceContext {
6
+ /** The client whose kernel drives the surface. */
7
+ client: ConsentClient;
8
+ /** The `.c15t-theme-root` element surfaces append to. */
9
+ root: HTMLElement;
10
+ /** Ship the DOM without class names. */
11
+ noStyle: boolean;
12
+ /** Skip enter and exit transitions. */
13
+ disableAnimation: boolean;
14
+ /** The site's legal links, if configured. */
15
+ legalLinks: LegalLinks | undefined;
16
+ }
17
+ /** A mounted surface. */
18
+ export interface Surface {
19
+ /** Reconcile the DOM with a snapshot. */
20
+ sync: (snapshot: ConsentSnapshot) => void;
21
+ /** Remove the surface and release listeners. */
22
+ destroy: () => void;
23
+ }
24
+ /** What {@link renderLegalLinks} needs. */
25
+ export interface LegalLinksParams {
26
+ /** Which links to render; `null` or empty renders none. */
27
+ keys: (keyof LegalLinks)[] | null | undefined;
28
+ /** The configured links. */
29
+ legalLinks: LegalLinks | undefined;
30
+ /** Translated labels, used when a link carries none of its own. */
31
+ labels: Partial<LegalLinksTranslations>;
32
+ /** Prefix for each link's test id. */
33
+ testIdPrefix: string;
34
+ /** Ship the DOM without class names. */
35
+ noStyle: boolean;
36
+ }
37
+ /**
38
+ * Render the inline legal links a surface shows after its description.
39
+ *
40
+ * @param params - Which links, their config and labels.
41
+ * @returns The link elements, possibly empty.
42
+ */
43
+ export declare const renderLegalLinks: (params: LegalLinksParams) => HTMLElement[];
package/dist-types/ui/trigger.d.ts ADDED
@@ -0,0 +1,14 @@
1
+ import type { ConsentTriggerOptions } from '../types';
2
+ import type { Surface, SurfaceContext } from './surface';
3
+ /**
4
+ * The floating button that reopens the preference centre.
5
+ *
6
+ * Hidden while the banner or dialog is up. Drag it to another corner and
7
+ * it snaps there and remembers the choice, the way the framework triggers
8
+ * do.
9
+ *
10
+ * @param ctx - The mount context.
11
+ * @param options - Trigger options.
12
+ * @returns The surface.
13
+ */
14
+ export declare const createTrigger: (ctx: SurfaceContext, options: ConsentTriggerOptions) => Surface;
package/dist-types/ui/widget.d.ts ADDED
@@ -0,0 +1,27 @@
1
+ import type { ConsentSnapshot } from '@c15t/core';
2
+ import type { SurfaceContext } from './surface';
3
+ /** The preference list plus its footer. */
4
+ export interface Widget {
5
+ /** The widget root. */
6
+ readonly element: HTMLElement;
7
+ /** Reconcile the rows and switches with a snapshot. */
8
+ sync: (snapshot: ConsentSnapshot) => void;
9
+ /** Drop unsaved toggles. */
10
+ resetDraft: () => void;
11
+ }
12
+ /** Options for {@link createWidget}. */
13
+ export interface WidgetOptions {
14
+ /** Drop the "Secured by c15t" tag. Defaults to `true`. */
15
+ hideBranding?: boolean;
16
+ }
17
+ /**
18
+ * The category list the preference centre renders.
19
+ *
20
+ * Toggles are a draft until the visitor saves, the way every other adapter
21
+ * treats them; "Accept all" and "Reject all" bypass the draft.
22
+ *
23
+ * @param ctx - The mount context.
24
+ * @param options - Widget options.
25
+ * @returns The widget.
26
+ */
27
+ export declare const createWidget: (ctx: SurfaceContext, options?: WidgetOptions) => Widget;
package/dist-types/version.d.ts ADDED
@@ -0,0 +1 @@
1
+ export declare const version = "3.0.0-alpha.0";
package/docs/README.md ADDED
@@ -0,0 +1,64 @@
1
+ # @c15t/browser
2
+
3
+ > Script-tag consent docs for c15t on Framer, Webflow, WordPress, and plain HTML: the data attributes, the window.c15t API, headless use, styling, manifest mode, and integrations.
4
+
5
+ These docs ship inside the package so coding agents can read them offline. Open the topic file you need from the list below — paths are relative to this file.
6
+
7
+ ## Using these docs
8
+
9
+ These docs describe v3. Start with Inth hosted setup, identify the framework, router and deployment, then read its quickstart. Static sites can use Inth directly. Use page Markdown and package-bundled docs for targeted context. Verify scripts, rejection, reload and preferences; banner visibility alone is insufficient.
10
+
11
+ ## Start here
12
+
13
+ - [Script tag setup](./frameworks/javascript/script-tag.md)
14
+
15
+ ## More documentation
16
+
17
+ [Documentation index](https://c15t.com/docs/llms.txt) · [Full Markdown context](https://c15t.com/llms-full.txt). Prefer the index and individual pages for focused tasks.
18
+
19
+ ## Frameworks
20
+
21
+ - [JavaScript script loading](./frameworks/javascript/script-loader.md): Attach a script loader to the consent kernel and dispose it with the application.
22
+ - [Script tag](./frameworks/javascript/script-tag.md): Add a consent banner to Framer, Webflow, WordPress, Squarespace, or any HTML page with one script tag and no build step.
23
+
24
+ ## Integrations
25
+
26
+ - [Adobe Analytics](./integrations/adobe-analytics.md): Configure Adobe Analytics with c15t v3, understand measurement permission and verify loading and revocation.
27
+ - [Ahrefs Analytics](./integrations/ahrefs-analytics.md): Configure Ahrefs Analytics with c15t v3, understand measurement permission and verify loading and revocation.
28
+ - [Amplitude](./integrations/amplitude.md): Configure Amplitude with c15t v3, understand measurement permission and verify loading and revocation.
29
+ - [Custom integrations](./integrations/building-integrations.md): Define loading, initialization and consent-change behavior for a vendor without a helper.
30
+ - [Clearbit](./integrations/clearbit.md): Configure Clearbit with c15t v3, understand marketing permission and verify loading and revocation.
31
+ - [Cloudflare Web Analytics](./integrations/cloudflare-web-analytics.md): Configure Cloudflare Web Analytics with c15t v3, understand measurement permission and verify loading and revocation.
32
+ - [Crisp](./integrations/crisp.md): Configure Crisp with c15t v3, understand functionality permission and verify loading and revocation.
33
+ - [Databuddy](./integrations/databuddy.md): Configure Databuddy's initial and updated consent state with c15t v3.
34
+ - [Fathom Analytics](./integrations/fathom-analytics.md): Configure Fathom Analytics with c15t v3, understand measurement permission and verify loading and revocation.
35
+ - [Google Maps](./integrations/google-maps.md): Prevent a map iframe from mounting before the required permission.
36
+ - [Google Tag](./integrations/google-tag.md): Configure gtag with c15t Consent Mode signals and understand its loading behavior.
37
+ - [Google Tag Manager](./integrations/google-tag-manager.md): Load GTM with c15t consent signals and verify the tags inside your container.
38
+ - [Heap](./integrations/heap.md): Configure Heap with c15t v3, understand measurement permission and verify loading and revocation.
39
+ - [Hightouch](./integrations/hightouch.md): Configure Hightouch with c15t v3, understand measurement permission and verify loading and revocation.
40
+ - [Hotjar](./integrations/hotjar.md): Configure Hotjar with c15t v3, understand measurement permission and verify loading and revocation.
41
+ - [Intercom](./integrations/intercom.md): Load the Intercom messenger with functionality permission and configure its region.
42
+ - [LinkedIn Insight Tag](./integrations/linkedin-insights.md): Configure LinkedIn Insight Tag with c15t v3, understand marketing permission and verify loading and revocation.
43
+ - [LogRocket](./integrations/logrocket.md): Configure LogRocket with c15t v3, understand measurement permission and verify loading and revocation.
44
+ - [Matomo Analytics](./integrations/matomo-analytics.md): Choose gated loading or Matomo consent signaling and configure the correct tracker endpoints.
45
+ - [Meta Pixel](./integrations/meta-pixel.md): Register the Meta Pixel under marketing permission and verify event calls after revocation.
46
+ - [Microsoft Clarity](./integrations/microsoft-clarity.md): Configure Microsoft Clarity with c15t v3, understand measurement permission and verify loading and revocation.
47
+ - [Microsoft UET](./integrations/microsoft-uet.md): Configure Microsoft UET with c15t v3, understand marketing permission and verify loading and revocation.
48
+ - [Mixpanel](./integrations/mixpanel-analytics.md): Configure Mixpanel with c15t v3, understand measurement permission and verify loading and revocation.
49
+ - [OpenAI Pixel](./integrations/openai-pixel.md): Configure the OpenAI Measurement Pixel for ChatGPT Ads with c15t v3, manage marketing permission and verify conversion delivery.
50
+ - [Overview](./integrations/overview.md): Find all c15t integrations for analytics, tag managers, advertising, chat and embedded content.
51
+ - [Pirsch](./integrations/pirsch.md): Configure Pirsch with c15t v3, understand measurement permission and verify loading and revocation.
52
+ - [Plausible Analytics](./integrations/plausible-analytics.md): Configure Plausible Analytics with c15t v3, understand measurement permission and verify loading and revocation.
53
+ - [PostHog](./integrations/posthog.md): Choose PostHog loading and cookieless behavior, configure the region, and synchronize v3 permissions.
54
+ - [Promptwatch](./integrations/promptwatch.md): Configure Promptwatch with c15t v3, understand measurement permission and verify loading and revocation.
55
+ - [Reddit Pixel](./integrations/reddit-pixel.md): Configure Reddit Pixel with c15t v3, understand marketing permission and verify loading and revocation.
56
+ - [RudderStack](./integrations/rudderstack.md): Gate the RudderStack browser SDK or map c15t categories to destination consent IDs.
57
+ - [Rybbit Analytics](./integrations/rybbit-analytics.md): Configure Rybbit Analytics with c15t v3, understand measurement permission and verify loading and revocation.
58
+ - [Segment](./integrations/segment.md): Configure Segment with c15t v3, understand measurement permission and verify loading and revocation.
59
+ - [Snapchat Pixel](./integrations/snapchat-pixel.md): Configure Snapchat Pixel with c15t v3, understand marketing permission and verify loading and revocation.
60
+ - [TikTok Pixel](./integrations/tiktok-pixel.md): Configure TikTok Pixel with c15t v3, understand marketing permission and verify loading and revocation.
61
+ - [Umami Analytics](./integrations/umami-analytics.md): Configure Umami Analytics with c15t v3, understand measurement permission and verify loading and revocation.
62
+ - [Vercel Analytics](./integrations/vercel-analytics.md): Configure Vercel Analytics with c15t v3, understand measurement permission and verify loading and revocation.
63
+ - [X Pixel](./integrations/x-pixel.md): Configure X Pixel with c15t v3, understand marketing permission and verify loading and revocation.
64
+ - [YouTube](./integrations/youtube.md): Gate YouTube embeds with c15t v3 in Next.js, TanStack Start, React, Nuxt, Vue, Astro, Svelte, SvelteKit or JavaScript.
package/docs/frameworks/javascript/script-loader.md ADDED
@@ -0,0 +1,47 @@
1
+ ---
2
+ title: JavaScript script loading
3
+ description: Attach a script loader to the consent kernel and dispose it with
4
+ the application.
5
+ group: frameworks
6
+ ---
7
+
8
+ ## Attach the loader before initialization
9
+
10
+ Install `@c15t/scripts` alongside `c15t`. This browser example adds a
11
+ marketing integration to a hosted kernel:
12
+
13
+ ```ts
14
+ import { createConsentKernel, createHostedTransport } from 'c15t';
15
+ import { createPersistence } from 'c15t/modules/persistence';
16
+ import { createScriptLoader } from 'c15t/modules/script-loader';
17
+ import { metaPixel } from '@c15t/scripts/meta-pixel';
18
+
19
+ const kernel = createConsentKernel({
20
+ transport: createHostedTransport({ backendURL: 'https://your-project.inth.app' }),
21
+ });
22
+ const persistence = createPersistence({ kernel });
23
+ const loader = createScriptLoader({ kernel, scripts: [metaPixel({ pixelId: '123456789012345' })] });
24
+ await kernel.commands.init();
25
+
26
+ function dispose() {
27
+ loader.dispose();
28
+ persistence.dispose();
29
+ kernel.dispose();
30
+ }
31
+ ```
32
+
33
+ Replace the URL and pixel ID. Call `dispose()` when your application tears down.
34
+ The headless kernel does not render a banner; connect a policy-aware UI before
35
+ shipping this integration. A framework provider already manages these modules,
36
+ so do not attach a second loader to a provider-owned kernel.
37
+
38
+ ## Keep one owner per vendor
39
+
40
+ Use stable script IDs and remove the vendor's original snippet. Ordinary scripts
41
+ wait for effective permission. Helpers with `alwaysLoad` instead load and signal
42
+ permission through the vendor API. Read the individual integration guide before
43
+ assuming all helpers have the same network behavior.
44
+
45
+ The loader exposes `updateScripts`, `getLoadedScriptIds` and `dispose`.
46
+ Unloading an element cannot reverse requests or code that already ran. Test
47
+ revocation and vendor cleanup with [verification](https://c15t.com/docs/guides/verify-consent).