@c15t/scripts 2.2.0 → 2.3.0

package/docs/integrations/front-chat.md

@@ -0,0 +1,178 @@
+---
+title: Front Chat
+description: Load Front Chat after functionality consent and initialize the
+  widget when its SDK is ready.
+group: integrations
+---
+Front Chat adds a live chat widget connected to your Front inbox. c15t waits for
+functionality consent before loading the widget's SDK and calling `FrontChat('init')`.
+
+## Official Front documentation
+
+* [Set up a Front Chat inbox and install the widget](https://help.front.com/en/articles/2049)
+* [Chat Widget SDK reference](https://dev.frontapp.com/docs/chat-sdk-reference)
+
+## Integrate with c15t
+
+Copy the `chatId` from the widget code snippet in your Front Chat channel's
+**Installation** tab. Pass that value to `frontChat()` instead of adding Front's
+script snippet separately.
+
+**React**
+
+```tsx
+import { type ReactNode } from 'react';
+import { ConsentManagerProvider } from '@c15t/react';
+import { frontChat } from '@c15t/scripts/front-chat';
+
+const scripts = [frontChat({ chatId: 'YOUR_FRONT_CHAT_ID' })];
+
+export function ConsentProvider({ children }: { children: ReactNode }) {
+  return (
+    <ConsentManagerProvider
+      options={{
+        mode: 'hosted',
+        backendURL: 'https://your-instance.c15t.dev',
+        scripts,
+      }}
+    >
+      {children}
+    </ConsentManagerProvider>
+  );
+}
+```
+
+**Next.js**
+
+```tsx
+'use client';
+
+import { type ReactNode } from 'react';
+import { ConsentManagerProvider } from '@c15t/nextjs';
+import { frontChat } from '@c15t/scripts/front-chat';
+
+const scripts = [frontChat({ chatId: 'YOUR_FRONT_CHAT_ID' })];
+
+export function ConsentProvider({ children }: { children: ReactNode }) {
+  return (
+    <ConsentManagerProvider
+      options={{
+        mode: 'hosted',
+        backendURL: '/api/c15t',
+        scripts,
+      }}
+    >
+      {children}
+    </ConsentManagerProvider>
+  );
+}
+```
+
+**JavaScript**
+
+```ts
+import { getOrCreateConsentRuntime } from 'c15t';
+import { frontChat } from '@c15t/scripts/front-chat';
+
+getOrCreateConsentRuntime({
+  mode: 'hosted',
+  backendURL: 'https://your-instance.c15t.dev',
+  scripts: [frontChat({ chatId: 'YOUR_FRONT_CHAT_ID' })],
+});
+```
+
+## How c15t loads it
+
+* **Category:** `functionality` (Functional)
+* **Loads when:** functionality consent is granted
+* **Script:** `https://chat-assets.frontapp.com/v1/chat.bundle.js`
+* **After load:** c15t calls `window.FrontChat('init', ...)` with your chat ID and launcher options
+* **On revocation:** c15t reloads the page by default and leaves Front Chat unloaded while functionality consent is denied
+
+Keep the default `reloadOnConsentRevoked: true` behavior. Removing a script tag
+does not stop a widget that has already initialized, and this integration does
+not provide automatic widget shutdown when you disable the reload.
+
+## Configure the integration
+
+`chatId` must be a non-empty string. The default launcher is enabled unless you
+set `useDefaultLauncher` to `false`:
+
+```ts
+frontChat({
+  chatId: 'YOUR_FRONT_CHAT_ID',
+  useDefaultLauncher: false,
+})
+```
+
+With the default launcher hidden, use Front's SDK to open the widget from your
+own launcher after consent is granted and the widget has initialized. See the
+[SDK reference](https://dev.frontapp.com/docs/chat-sdk-reference) for commands
+and initialization requirements.
+
+### Content Security Policy
+
+If your Content Security Policy (CSP) uses nonces, pass the server-generated nonce
+for the current response. c15t applies it to the loader script and forwards it
+to Front's initialization call:
+
+```ts
+function createChatScripts(nonce: string) {
+  return [frontChat({ chatId: 'YOUR_FRONT_CHAT_ID', nonce })];
+}
+```
+
+Front creates additional resources for the widget. Follow Front's
+[CSP setup instructions](https://help.front.com/en/articles/2049) for the
+remaining policy requirements. You can override the loader URL with `scriptSrc`
+if you serve the SDK through your own proxy; this does not proxy the widget's
+other requests.
+
+### Optional session cleanup
+
+`frontChat()` does not automatically delete an existing Front session. You can
+also request session cleanup before c15t's revocation reload using
+`shutdownFrontChat()`:
+
+```ts
+import { getOrCreateConsentRuntime } from 'c15t';
+import { frontChat, shutdownFrontChat } from '@c15t/scripts/front-chat';
+
+getOrCreateConsentRuntime({
+  mode: 'hosted',
+  backendURL: 'https://your-instance.c15t.dev',
+  scripts: [frontChat({ chatId: 'YOUR_FRONT_CHAT_ID' })],
+  callbacks: {
+    onBeforeConsentRevocationReload: ({ preferences }) => {
+      if (!preferences.functionality) {
+        shutdownFrontChat();
+      }
+    },
+  },
+});
+```
+
+The function calls Front's `shutdown` command with `clearSession: true` when
+the SDK is available. This is a best-effort request: the reload does not wait
+for Front to finish clearing its session. Keep reload on revocation enabled;
+the cleanup call does not replace it.
+
+## Types
+
+### FrontChatOptions
+
+|Property|Value|
+|:--|:--|
+|Type Name|\`FrontChatOptions\`|
+|Source Path|\`./packages/scripts/src/vendors/functional/front-chat.ts\`|
+
+\*ExtractedTypeTable: Could not extract "FrontChatOptions" from "./packages/scripts/src/vendors/functional/front-chat.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*
+
+### Script
+
+|Property|Value|
+|:--|:--|
+|Type Name|\`Script\`|
+|Source Path|\`./packages/core/src/libs/script-loader/types.ts\`|
+
+\*ExtractedTypeTable: Could not extract "Script" from "./packages/core/src/libs/script-loader/types.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*

package/docs/integrations/one-dollar-stats.md

@@ -0,0 +1,118 @@
+---
+title: OneDollarStats
+description: Load OneDollarStats after measurement consent with optional tracker
+  data attributes.
+group: integrations
+---
+[OneDollarStats](https://onedollarstats.com/) matches events to the domain registered in your dashboard, so no API key is needed. This helper loads its classic deferred script after measurement consent and forwards settings as `data-*` attributes.
+
+## Integrate with c15t
+
+**React**
+
+```tsx
+import { type ReactNode } from 'react';
+import { ConsentManagerProvider } from '@c15t/react';
+import { oneDollarStats } from '@c15t/scripts/one-dollar-stats';
+
+const scripts = [oneDollarStats()];
+
+export function ConsentProvider({ children }: { children: ReactNode }) {
+  return (
+    <ConsentManagerProvider
+      options={{
+        mode: 'hosted',
+        backendURL: 'https://your-instance.c15t.dev',
+        scripts,
+      }}
+    >
+      {children}
+    </ConsentManagerProvider>
+  );
+}
+```
+
+**Next.js**
+
+```tsx
+'use client';
+
+import { type ReactNode } from 'react';
+import { ConsentManagerProvider } from '@c15t/nextjs';
+import { oneDollarStats } from '@c15t/scripts/one-dollar-stats';
+
+const scripts = [oneDollarStats()];
+
+export function ConsentProvider({ children }: { children: ReactNode }) {
+  return (
+    <ConsentManagerProvider
+      options={{
+        mode: 'hosted',
+        backendURL: '/api/c15t',
+        scripts,
+      }}
+    >
+      {children}
+    </ConsentManagerProvider>
+  );
+}
+```
+
+**JavaScript**
+
+```ts
+import { getOrCreateConsentRuntime } from 'c15t';
+import { oneDollarStats } from '@c15t/scripts/one-dollar-stats';
+
+getOrCreateConsentRuntime({
+  mode: 'hosted',
+  backendURL: 'https://your-instance.c15t.dev',
+  scripts: [oneDollarStats()],
+});
+```
+
+## Tracker settings
+
+All settings use strings and omit the `data-` prefix. Unknown settings are forwarded for compatibility with future tracker options.
+
+```ts
+oneDollarStats({
+  hostname: 'docs.example.com',
+  devmode: 'true',
+  autocollect: 'false',
+  'hash-routing': 'true',
+  url: 'https://analytics.example.com/events',
+})
+```
+
+* `hostname` must be a bare hostname, optionally including a port. It overrides the event hostname on every host, including production.
+* Local testing needs both `hostname` and `devmode: 'true'`.
+* `autocollect: 'false'` disables automatic pageview and click collection.
+* `'hash-routing': 'false'` omits the attribute entirely: the CDN tracker enables hash routing whenever the attribute is present, regardless of its value.
+* `url` overrides the collection endpoint. Leave it unset to use the vendor default.
+
+The tracker handles browser history navigation itself; no extra router hook is required. See the [vendor installation reference](https://docs.onedollarstats.com/installation) for its settings.
+
+## Consent behaviour
+
+The script uses the `measurement` category and loads only when that consent is granted. On revocation, c15t removes its script element. Removing a script does not undo code that already executed, including the tracker's history hooks and event listeners. Use c15t's reload-on-revocation behaviour to clear the running tracker, and check measurement consent before making manual tracking calls.
+
+## Types
+
+### OneDollarStatsOptions
+
+|Property|Value|
+|:--|:--|
+|Type Name|\`OneDollarStatsOptions\`|
+|Source Path|\`./packages/scripts/src/vendors/analytics/one-dollar-stats.ts\`|
+
+\*ExtractedTypeTable: Could not extract "OneDollarStatsOptions" from "./packages/scripts/src/vendors/analytics/one-dollar-stats.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*
+
+### Script
+
+|Property|Value|
+|:--|:--|
+|Type Name|\`Script\`|
+|Source Path|\`./packages/core/src/libs/script-loader/types.ts\`|
+
+\*ExtractedTypeTable: Could not extract "Script" from "./packages/core/src/libs/script-loader/types.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*

package/docs/integrations/overview.md

@@ -94,6 +94,7 @@ Analytics integrations usually require `measurement` consent. Some vendors can r
 * [LogRocket](/docs/integrations/logrocket)
 * [Matomo Analytics](/docs/integrations/matomo-analytics)
 * [PostHog](/docs/integrations/posthog)
+* [OneDollarStats](/docs/integrations/one-dollar-stats)
 * [Promptwatch](/docs/integrations/promptwatch)
 * [Pirsch](/docs/integrations/pirsch)
 * [RudderStack](/docs/integrations/rudderstack)
@@ -107,6 +108,7 @@ Analytics integrations usually require `measurement` consent. Some vendors can r
 Functional integrations usually require `functionality` consent. They add optional user-facing capabilities, such as chat widgets, that should only run after the user allows them.
 
 * [Crisp](/docs/integrations/crisp)
+* [Front Chat](/docs/integrations/front-chat)
 * [Intercom](/docs/integrations/intercom)
 
 ## Ads & Pixels
@@ -120,6 +122,7 @@ Advertising pixels usually require `marketing` consent. Many of them need startu
 * [LinkedIn Insight Tag](/docs/integrations/linkedin-insights)
 * [Microsoft UET](/docs/integrations/microsoft-uet)
 * [X (Twitter) Pixel](/docs/integrations/x-pixel)
+* [Pinterest Tag](/docs/integrations/pinterest-tag)
 
 ## Tag Managers
 

package/docs/integrations/pinterest-tag.md

@@ -0,0 +1,236 @@
+---
+title: Pinterest Tag
+description: Track conversions and build audiences for Pinterest advertising campaigns.
+icon: pinterest
+group: integrations
+---
+Pinterest Tag is Pinterest's conversion tracking and audience building tool. It measures the actions people take on your site after seeing your Pins, so you can attribute conversions and build retargeting audiences for Pinterest Ads.
+
+## Official Pinterest documentation
+
+* [Install the Pinterest Tag (Pinterest Business Help)](https://help.pinterest.com/en/business/article/install-the-pinterest-tag)
+* [Pinterest Tag event codes](https://help.pinterest.com/en/business/article/add-event-codes)
+
+## Integrate with c15t
+
+**React**
+
+```tsx
+import { type ReactNode } from 'react';
+import { ConsentManagerProvider } from '@c15t/react';
+import { pinterestTag } from '@c15t/scripts/pinterest-tag';
+
+const scripts = [pinterestTag({ tagId: '2613654212508' })];
+
+export function ConsentProvider({ children }: { children: ReactNode }) {
+  return (
+    <ConsentManagerProvider
+      options={{
+        mode: 'hosted',
+        backendURL: 'https://your-instance.c15t.dev',
+        scripts,
+      }}
+    >
+      {children}
+    </ConsentManagerProvider>
+  );
+}
+```
+
+**Next.js**
+
+```tsx
+'use client';
+
+import { type ReactNode } from 'react';
+import { ConsentManagerProvider } from '@c15t/nextjs';
+import { pinterestTag } from '@c15t/scripts/pinterest-tag';
+
+const scripts = [pinterestTag({ tagId: '2613654212508' })];
+
+export function ConsentProvider({ children }: { children: ReactNode }) {
+  return (
+    <ConsentManagerProvider
+      options={{
+        mode: 'hosted',
+        backendURL: '/api/c15t',
+        scripts,
+      }}
+    >
+      {children}
+    </ConsentManagerProvider>
+  );
+}
+```
+
+**JavaScript**
+
+```ts
+import { getOrCreateConsentRuntime } from 'c15t';
+import { pinterestTag } from '@c15t/scripts/pinterest-tag';
+
+getOrCreateConsentRuntime({
+  mode: 'hosted',
+  backendURL: 'https://your-instance.c15t.dev',
+  scripts: [pinterestTag({ tagId: '2613654212508' })],
+});
+```
+
+## How c15t loads it
+
+* **Category:** `marketing` (Ads & Pixels)
+* **Loads when:** marketing consent is granted
+* **On revocation:** [persists](/docs/frameworks/react/script-loader#persist-after-revocation) — c15t calls `pintrk('setconsent', false)`, which stops Pinterest from sending events and clears its first-party cookies without removing the script
+
+Before the loader runs, c15t recreates Pinterest's base code: it defines the `pintrk` queue stub with `version = "3.0"`, then queues `pintrk('load', tagId)`, `pintrk('setconsent', true)`, and `pintrk('page')`. Pinterest's `core.js` replays the queue once it loads.
+
+## Configure the integration
+
+You can pass extra load options and disable the default page-visit event when you need finer control:
+
+```ts
+pinterestTag({
+  tagId: '2613654212508',
+  loadOptions: {
+    em: 'hello@example.com',
+  },
+  trackPageVisit: false,
+});
+```
+
+`loadOptions` is forwarded as the third argument to `pintrk('load', tagId, loadOptions)`. Pinterest uses `em` (email) and `external_id` for enhanced match, and hashes plain values before sending them.
+
+> ⚠️ **Warning:**
+> Enhanced match values are personal data. Only pass em or external\_id when your application has separately obtained consent to share them with Pinterest — marketing consent alone does not cover this.
+
+## Tracking events in your app
+
+c15t gates the Pinterest Tag from loading until `marketing` consent is granted. After consent is granted the script stays in the DOM, and c15t calls `pintrk('setconsent', false)` if consent is later revoked, so Pinterest itself suppresses events.
+
+This means `window.pintrk` is only defined after the user has granted marketing consent at least once. Use `pinterestTagEvent()` for typed standard and custom events — it's a no-op until `pintrk` exists, so it's safe to call before consent, and it doesn't bypass consent afterwards. Guarding with `has('marketing')` is still good practice so you don't queue events Pinterest will drop:
+
+```tsx
+import { useCallback } from 'react';
+import { useConsentManager } from '@c15t/react';
+import { pinterestTagEvent } from '@c15t/scripts/pinterest-tag';
+
+function useTrackCheckout() {
+  const { has } = useConsentManager();
+  return useCallback(() => {
+    if (has('marketing')) {
+      pinterestTagEvent('checkout', {
+        event_id: 'eventId0001',
+        value: 99.99,
+        order_quantity: 1,
+        currency: 'USD',
+        order_id: 'X-15148',
+        line_items: [
+          {
+            product_name: 'Parker Boots',
+            product_id: '1414',
+            product_category: 'Shoes',
+            product_price: 99.99,
+            product_quantity: 1,
+          },
+        ],
+      });
+    }
+  }, [has]);
+}
+
+function CheckoutButton() {
+  const trackCheckout = useTrackCheckout();
+  return <button onClick={trackCheckout}>Complete checkout</button>;
+}
+```
+
+From plain JavaScript:
+
+```ts
+import { getOrCreateConsentRuntime } from 'c15t';
+import { pinterestTagEvent } from '@c15t/scripts/pinterest-tag';
+
+const { consentStore } = getOrCreateConsentRuntime();
+
+if (consentStore.getState().has('marketing')) {
+  pinterestTagEvent('lead', { lead_type: 'newsletter' });
+}
+```
+
+Pass `event_id` when you also send the same event through the Pinterest Conversions API so Pinterest can deduplicate the two. Product details (`product_name`, `product_id`, `product_price`, and so on) go inside `line_items`, one entry per product — Pinterest ignores them at the top level.
+
+### Event names
+
+Pinterest recognises 20 event types for conversion tracking: `checkout`, `addtocart`, `pagevisit`, `signup`, `watchvideo`, `lead`, `search`, `viewcategory`, `custom`, `addpaymentinfo`, `addtowishlist`, `initiatecheckout`, `subscribe`, `viewcontent`, `contact`, `schedule`, `findlocation`, `customizeproduct`, `submitapplication`, and `starttrial`. `pinterestTagEvent()` also accepts any other string as a user-defined event, which Pinterest uses for audience targeting only — it logs a console warning for these.
+
+Which events you need depends on the campaign type. Conversions campaigns require at least one of `signup`, `lead`, `addtocart`, or `checkout`; catalog sales, conversion insights, dynamic retargeting, and the Verified Merchant Program all require `pagevisit`, `addtocart`, and `checkout` with `currency` set. See [Add event codes](https://help.pinterest.com/en/business/article/add-event-codes) for the full matrix.
+
+### Debugging with a callback
+
+Pinterest accepts an optional `(didInit, error)` callback after the event data. Pass it as the third argument to `pinterestTagEvent()` to surface tag errors during development:
+
+```ts
+import { pinterestTagEvent } from '@c15t/scripts/pinterest-tag';
+
+pinterestTagEvent('lead', { lead_type: 'Newsletter' }, (didInit, error) => {
+  if (!didInit) {
+    console.error('Pinterest Tag error:', error);
+  }
+});
+```
+
+## Types
+
+### PinterestTagOptions
+
+|Property|Value|
+|:--|:--|
+|Type Name|\`PinterestTagOptions\`|
+|Source Path|\`./packages/scripts/src/vendors/ads-and-pixels/pinterest-tag.ts\`|
+
+\*ExtractedTypeTable: Could not extract "PinterestTagOptions" from "./packages/scripts/src/vendors/ads-and-pixels/pinterest-tag.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*
+
+### PinterestTagLoadOptions
+
+|Property|Value|
+|:--|:--|
+|Type Name|\`PinterestTagLoadOptions\`|
+|Source Path|\`./packages/scripts/src/vendors/ads-and-pixels/pinterest-tag.ts\`|
+
+\*ExtractedTypeTable: Could not extract "PinterestTagLoadOptions" from "./packages/scripts/src/vendors/ads-and-pixels/pinterest-tag.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*
+
+### PinterestTagEventData
+
+|Property|Value|
+|:--|:--|
+|Type Name|\`PinterestTagEventData\`|
+|Source Path|\`./packages/scripts/src/vendors/ads-and-pixels/pinterest-tag.ts\`|
+
+\*ExtractedTypeTable: Could not extract "PinterestTagEventData" from "./packages/scripts/src/vendors/ads-and-pixels/pinterest-tag.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*
+
+### PinterestTagLineItem
+
+|Property|Value|
+|:--|:--|
+|Type Name|\`PinterestTagLineItem\`|
+|Source Path|\`./packages/scripts/src/vendors/ads-and-pixels/pinterest-tag.ts\`|
+
+\*ExtractedTypeTable: Could not extract "PinterestTagLineItem" from "./packages/scripts/src/vendors/ads-and-pixels/pinterest-tag.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*
+
+### PinterestTagEventCallback
+
+|Property|Value|
+|:--|:--|
+|Type Name|\`PinterestTagEventCallback\`|
+|Source Path|\`./packages/scripts/src/vendors/ads-and-pixels/pinterest-tag.ts\`|
+
+\*ExtractedTypeTable: Could not extract "PinterestTagEventCallback" from "./packages/scripts/src/vendors/ads-and-pixels/pinterest-tag.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*
+
+### Script
+
+|Property|Value|
+|:--|:--|
+|Type Name|\`Script\`|
+|Source Path|\`./packages/core/src/libs/script-loader/types.ts\`|
+
+\*ExtractedTypeTable: Could not extract "Script" from "./packages/core/src/libs/script-loader/types.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@c15t/scripts",
-	"version": "2.2.0",
+	"version": "2.3.0",
 	"description": "Consent-aware script integrations for Google Tag Manager, Google Consent Mode v2, GA4, Google Ads, Meta Pixel, and more.",
 	"keywords": [
 		"c15t",
@@ -28,6 +28,7 @@
 		"linkedin-insights",
 		"microsoft-uet",
 		"x-pixel",
+		"pinterest-tag",
 		"analytics-consent",
 		"consent-mode",
 		"consent-mode-v2",
@@ -127,6 +128,11 @@
 			"import": "./dist/vendors/analytics/mixpanel-analytics.js",
 			"require": "./dist/vendors/analytics/mixpanel-analytics.cjs"
 		},
+		"./one-dollar-stats": {
+			"types": "./dist-types/vendors/analytics/one-dollar-stats.d.ts",
+			"import": "./dist/vendors/analytics/one-dollar-stats.js",
+			"require": "./dist/vendors/analytics/one-dollar-stats.cjs"
+		},
 		"./pirsch": {
 			"types": "./dist-types/vendors/analytics/pirsch.d.ts",
 			"import": "./dist/vendors/analytics/pirsch.js",
@@ -172,6 +178,11 @@
 			"import": "./dist/vendors/functional/crisp.js",
 			"require": "./dist/vendors/functional/crisp.cjs"
 		},
+		"./front-chat": {
+			"types": "./dist-types/vendors/functional/front-chat.d.ts",
+			"import": "./dist/vendors/functional/front-chat.js",
+			"require": "./dist/vendors/functional/front-chat.cjs"
+		},
 		"./intercom": {
 			"types": "./dist-types/vendors/functional/intercom.d.ts",
 			"import": "./dist/vendors/functional/intercom.js",
@@ -217,6 +228,11 @@
 			"import": "./dist/vendors/ads-and-pixels/x-pixel.js",
 			"require": "./dist/vendors/ads-and-pixels/x-pixel.cjs"
 		},
+		"./pinterest-tag": {
+			"types": "./dist-types/vendors/ads-and-pixels/pinterest-tag.d.ts",
+			"import": "./dist/vendors/ads-and-pixels/pinterest-tag.js",
+			"require": "./dist/vendors/ads-and-pixels/pinterest-tag.cjs"
+		},
 		"./registry": {
 			"types": "./dist-types/registry.d.ts",
 			"import": "./dist/registry.js",
@@ -253,7 +269,7 @@
 	"devDependencies": {
 		"@c15t/typescript-config": "0.0.1",
 		"@c15t/vitest-config": "1.0.0",
-		"c15t": "2.2.0",
+		"c15t": "2.3.0",
 		"playwright": "1.58.2"
 	},
 	"publishConfig": {