@jwiedeman/gtm-kit-vue 1.0.1

package/README.md

@@ -0,0 +1,335 @@
+# @react-gtm-kit/vue
+
+[![CI](https://github.com/jwiedeman/react-gtm-kit/actions/workflows/ci.yml/badge.svg)](https://github.com/jwiedeman/react-gtm-kit/actions/workflows/ci.yml)
+[![Coverage](https://codecov.io/gh/jwiedeman/react-gtm-kit/graph/badge.svg?flag=vue)](https://codecov.io/gh/jwiedeman/react-gtm-kit)
+[![npm version](https://img.shields.io/npm/v/@react-gtm-kit/vue.svg)](https://www.npmjs.com/package/@react-gtm-kit/vue)
+[![Bundle Size](https://img.shields.io/bundlephobia/minzip/@react-gtm-kit/vue)](https://bundlephobia.com/package/@react-gtm-kit/vue)
+[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Vue 3](https://img.shields.io/badge/Vue-3.3+-4FC08D.svg?logo=vue.js)](https://vuejs.org/)
+
+**Vue 3 plugin and composables for Google Tag Manager. Composition API ready.**
+
+The Vue adapter for GTM Kit - provides a plugin and composables for clean Vue integration.
+
+---
+
+## Installation
+
+```bash
+npm install @react-gtm-kit/core @react-gtm-kit/vue
+```
+
+```bash
+yarn add @react-gtm-kit/core @react-gtm-kit/vue
+```
+
+```bash
+pnpm add @react-gtm-kit/core @react-gtm-kit/vue
+```
+
+---
+
+## Quick Start
+
+### Step 1: Add Plugin
+
+```ts
+// main.ts
+import { createApp } from 'vue';
+import { GtmPlugin } from '@react-gtm-kit/vue';
+import App from './App.vue';
+
+createApp(App).use(GtmPlugin, { containers: 'GTM-XXXXXX' }).mount('#app');
+```
+
+### Step 2: Push Events
+
+```vue
+<script setup>
+import { useGtm } from '@react-gtm-kit/vue';
+
+const { push } = useGtm();
+
+function handleClick() {
+  push({ event: 'purchase', value: 49.99 });
+}
+</script>
+
+<template>
+  <button @click="handleClick">Buy Now</button>
+</template>
+```
+
+**That's it!** GTM is now running.
+
+---
+
+## Features
+
+| Feature             | Description                    |
+| ------------------- | ------------------------------ |
+| **Vue 3 Native**    | Built for Composition API      |
+| **Composables**     | Clean, reactive Vue patterns   |
+| **TypeScript**      | Full type definitions included |
+| **Consent Mode v2** | Built-in GDPR compliance       |
+| **SSR Compatible**  | Safe for Nuxt and Vite SSR     |
+| **Lightweight**     | ~4KB gzipped                   |
+
+---
+
+## Available Composables
+
+### `useGtm()`
+
+Get the full GTM API.
+
+```vue
+<script setup>
+import { useGtm } from '@react-gtm-kit/vue';
+
+const { client, push, updateConsent, setConsentDefaults } = useGtm();
+
+push({ event: 'page_view', page_path: '/' });
+</script>
+```
+
+### `useGtmPush()`
+
+Get just the push function.
+
+```vue
+<script setup>
+import { useGtmPush } from '@react-gtm-kit/vue';
+
+const push = useGtmPush();
+
+push({ event: 'button_click', button_id: 'cta-main' });
+</script>
+```
+
+### `useGtmConsent()`
+
+Manage consent state.
+
+```vue
+<script setup>
+import { useGtmConsent } from '@react-gtm-kit/vue';
+
+const { updateConsent } = useGtmConsent();
+
+function acceptAll() {
+  updateConsent({
+    ad_storage: 'granted',
+    analytics_storage: 'granted',
+    ad_user_data: 'granted',
+    ad_personalization: 'granted'
+  });
+}
+</script>
+```
+
+### `useGtmClient()`
+
+Get the raw GTM client instance.
+
+```vue
+<script setup>
+import { useGtmClient } from '@react-gtm-kit/vue';
+
+const client = useGtmClient();
+
+onMounted(async () => {
+  await client.whenReady();
+  console.log('GTM is ready!');
+});
+</script>
+```
+
+### `useGtmReady()`
+
+Get a function that resolves when GTM is loaded.
+
+```vue
+<script setup>
+import { useGtmReady } from '@react-gtm-kit/vue';
+
+const whenReady = useGtmReady();
+
+onMounted(async () => {
+  await whenReady();
+  console.log('GTM scripts loaded!');
+});
+</script>
+```
+
+---
+
+## Plugin Options
+
+```ts
+app.use(GtmPlugin, {
+  containers: 'GTM-XXXXXX', // Required
+  dataLayerName: 'dataLayer', // Optional
+  host: 'https://custom.host.com', // Optional
+  scriptAttributes: { nonce: '...' }, // Optional: CSP
+  onBeforeInit: (client) => {
+    // Called before GTM initializes
+    // Perfect for consent defaults
+  },
+  onAfterInit: (client) => {
+    // Called after GTM initializes
+  }
+});
+```
+
+---
+
+## Vue Router Integration
+
+```vue
+<script setup>
+import { useGtm } from '@react-gtm-kit/vue';
+import { watch } from 'vue';
+import { useRoute } from 'vue-router';
+
+const route = useRoute();
+const { push } = useGtm();
+
+watch(
+  () => route.fullPath,
+  (path) => {
+    push({ event: 'page_view', page_path: path });
+  }
+);
+</script>
+```
+
+Or create a reusable composable:
+
+```ts
+// composables/usePageTracking.ts
+import { useGtm } from '@react-gtm-kit/vue';
+import { watch, onMounted } from 'vue';
+import { useRoute } from 'vue-router';
+
+export function usePageTracking() {
+  const route = useRoute();
+  const { push } = useGtm();
+
+  onMounted(() => {
+    // Track initial page
+    push({ event: 'page_view', page_path: route.fullPath });
+  });
+
+  watch(
+    () => route.fullPath,
+    (path, oldPath) => {
+      if (path !== oldPath) {
+        push({ event: 'page_view', page_path: path });
+      }
+    }
+  );
+}
+```
+
+---
+
+## Consent Mode v2 (GDPR)
+
+```ts
+// main.ts
+import { createApp } from 'vue';
+import { GtmPlugin } from '@react-gtm-kit/vue';
+import { consentPresets } from '@react-gtm-kit/core';
+import App from './App.vue';
+
+createApp(App)
+  .use(GtmPlugin, {
+    containers: 'GTM-XXXXXX',
+    onBeforeInit: (client) => {
+      // Deny by default for EU users
+      client.setConsentDefaults(consentPresets.eeaDefault, { region: ['EEA'] });
+    }
+  })
+  .mount('#app');
+```
+
+```vue
+<!-- CookieBanner.vue -->
+<script setup>
+import { useGtmConsent } from '@react-gtm-kit/vue';
+import { consentPresets } from '@react-gtm-kit/core';
+
+const { updateConsent } = useGtmConsent();
+
+// Accept all tracking
+const acceptAll = () => updateConsent(consentPresets.allGranted);
+
+// Reject all tracking
+const rejectAll = () => updateConsent(consentPresets.eeaDefault);
+
+// Analytics only (mixed consent)
+const analyticsOnly = () => updateConsent(consentPresets.analyticsOnly);
+
+// Granular: custom selection
+const customChoice = () =>
+  updateConsent({
+    analytics_storage: 'granted',
+    ad_storage: 'denied',
+    ad_user_data: 'denied',
+    ad_personalization: 'denied'
+  });
+</script>
+
+<template>
+  <div class="cookie-banner">
+    <p>We use cookies to improve your experience.</p>
+    <button @click="acceptAll">Accept All</button>
+    <button @click="rejectAll">Reject All</button>
+    <button @click="analyticsOnly">Analytics Only</button>
+  </div>
+</template>
+```
+
+**Partial Updates** - Only update changed categories:
+
+```vue
+<script setup>
+import { useGtmConsent } from '@react-gtm-kit/vue';
+
+const { updateConsent } = useGtmConsent();
+
+// User later opts into ads from preference center
+const enableAds = () =>
+  updateConsent({
+    ad_storage: 'granted',
+    ad_user_data: 'granted'
+  });
+// Other categories (analytics_storage, ad_personalization) remain unchanged
+</script>
+```
+
+---
+
+## Nuxt 3
+
+For Nuxt 3 projects, use [`@react-gtm-kit/nuxt`](https://www.npmjs.com/package/@react-gtm-kit/nuxt) which provides:
+
+- Native Nuxt module integration
+- Auto-import of composables
+- Automatic page tracking
+- SSR support out of the box
+
+---
+
+## Requirements
+
+- Vue 3.3+
+- `@react-gtm-kit/core` (peer dependency)
+
+---
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,16 @@
+'use strict';
+
+var vue = require('vue');
+var gtmKit = require('@jwiedeman/gtm-kit');
+
+var a=Symbol("gtm-kit"),c={install(t,s){let{autoInit:u=!0,onBeforeInit:p,...m}=s,e=gtmKit.createGtmClient(m),r={client:e,push:n=>e.push(n),setConsentDefaults:(n,i)=>e.setConsentDefaults(n,i),updateConsent:(n,i)=>e.updateConsent(n,i),whenReady:()=>e.whenReady(),onReady:n=>e.onReady(n)};t.provide(a,r),t.config.globalProperties.$gtm=r,p&&p(e),u&&e.init(),t.mixin({unmounted(){}});}},o=()=>{let t=vue.inject(a);if(!t)throw new Error('[gtm-kit] useGtm() was called outside of a Vue app with GtmPlugin installed. Make sure to call app.use(GtmPlugin, { containers: "GTM-XXXXXX" }) before using GTM composables.');return t},G=()=>o(),d=()=>o().push,y=()=>{let{setConsentDefaults:t,updateConsent:s}=o();return {setConsentDefaults:t,updateConsent:s}},x=()=>o().client,g=()=>o().whenReady;
+
+exports.GTM_INJECTION_KEY = a;
+exports.GtmPlugin = c;
+exports.useGtm = G;
+exports.useGtmClient = x;
+exports.useGtmConsent = y;
+exports.useGtmPush = d;
+exports.useGtmReady = g;
+//# sourceMappingURL=out.js.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/plugin.ts"],"names":["inject","createGtmClient","GTM_INJECTION_KEY","GtmPlugin","app","options","autoInit","onBeforeInit","clientOptions","client","context","value","state","regionOptions","callback","useGtmContext","useGtm","useGtmPush","useGtmConsent","setConsentDefaults","updateConsent","useGtmClient","useGtmReady"],"mappings":"AAAA,OAAS,UAAAA,MAA2C,MACpD,OACE,mBAAAC,MAOK,qBAkDA,IAAMC,EAA8C,OAAO,SAAS,EAe9DC,EAAY,CACvB,QAAQC,EAAUC,EAAiC,CACjD,GAAM,CAAE,SAAAC,EAAW,GAAM,aAAAC,EAAc,GAAGC,CAAc,EAAIH,EAEtDI,EAASR,EAAgBO,CAAa,EAEtCE,EAAsB,CAC1B,OAAAD,EACA,KAAOE,GAA0BF,EAAO,KAAKE,CAAK,EAClD,mBAAoB,CAACC,EAAqBC,IACxCJ,EAAO,mBAAmBG,EAAOC,CAAa,EAChD,cAAe,CAACD,EAAqBC,IACnCJ,EAAO,cAAcG,EAAOC,CAAa,EAC3C,UAAW,IAAMJ,EAAO,UAAU,EAClC,QAAUK,GAAiDL,EAAO,QAAQK,CAAQ,CACpF,EAGAV,EAAI,QAAQF,EAAmBQ,CAAO,EAGtCN,EAAI,OAAO,iBAAiB,KAAOM,EAG/BH,GACFA,EAAaE,CAAM,EAIjBH,GACFG,EAAO,KAAK,EAIdL,EAAI,MAAM,CACR,WAAY,CAGZ,CACF,CAAC,CACH,CACF,EAKMW,EAAgB,IAAkB,CACtC,IAAML,EAAUV,EAAOE,CAAiB,EACxC,GAAI,CAACQ,EACH,MAAM,IAAI,MACR,+KAEF,EAEF,OAAOA,CACT,EAkBaM,EAAS,IACbD,EAAc,EAoBVE,EAAa,IACjBF,EAAc,EAAE,KAwBZG,EAAgB,IAAqB,CAChD,GAAM,CAAE,mBAAAC,EAAoB,cAAAC,CAAc,EAAIL,EAAc,EAC5D,MAAO,CAAE,mBAAAI,EAAoB,cAAAC,CAAc,CAC7C,EAoBaC,EAAe,IACnBN,EAAc,EAAE,OAsBZO,EAAc,IAClBP,EAAc,EAAE","sourcesContent":["import { inject, type App, type InjectionKey } from 'vue';\nimport {\n  createGtmClient,\n  type ConsentRegionOptions,\n  type ConsentState,\n  type CreateGtmClientOptions,\n  type DataLayerValue,\n  type GtmClient,\n  type ScriptLoadState\n} from '@jwiedeman/gtm-kit';\n\n/**\n * Options for the GTM Vue plugin.\n * Extends CreateGtmClientOptions with Vue-specific options.\n */\nexport interface GtmPluginOptions extends CreateGtmClientOptions {\n  /**\n   * Whether to automatically initialize GTM when the plugin is installed.\n   * @default true\n   */\n  autoInit?: boolean;\n\n  /**\n   * Callback executed before GTM initialization.\n   * Use this to set consent defaults.\n   */\n  onBeforeInit?: (client: GtmClient) => void;\n}\n\n/**\n * The GTM context value provided to components via inject().\n */\nexport interface GtmContext {\n  /** The underlying GTM client instance */\n  client: GtmClient;\n  /** Push a value to the data layer */\n  push: (value: DataLayerValue) => void;\n  /** Set consent defaults (must be called before init) */\n  setConsentDefaults: (state: ConsentState, options?: ConsentRegionOptions) => void;\n  /** Update consent state */\n  updateConsent: (state: ConsentState, options?: ConsentRegionOptions) => void;\n  /** Returns a promise that resolves when all GTM scripts are loaded */\n  whenReady: () => Promise<ScriptLoadState[]>;\n  /** Register a callback for when GTM scripts are ready */\n  onReady: (callback: (state: ScriptLoadState[]) => void) => () => void;\n}\n\n/**\n * Consent-specific API subset.\n */\nexport interface GtmConsentApi {\n  setConsentDefaults: (state: ConsentState, options?: ConsentRegionOptions) => void;\n  updateConsent: (state: ConsentState, options?: ConsentRegionOptions) => void;\n}\n\n/**\n * Injection key for the GTM context.\n * Use this with inject() to access the GTM context directly.\n */\nexport const GTM_INJECTION_KEY: InjectionKey<GtmContext> = Symbol('gtm-kit');\n\n/**\n * Vue 3 plugin for GTM Kit.\n *\n * @example\n * ```ts\n * import { createApp } from 'vue';\n * import { GtmPlugin } from '@jwiedeman/gtm-kit-vue';\n *\n * createApp(App)\n *   .use(GtmPlugin, { containers: 'GTM-XXXXXX' })\n *   .mount('#app');\n * ```\n */\nexport const GtmPlugin = {\n  install(app: App, options: GtmPluginOptions): void {\n    const { autoInit = true, onBeforeInit, ...clientOptions } = options;\n\n    const client = createGtmClient(clientOptions);\n\n    const context: GtmContext = {\n      client,\n      push: (value: DataLayerValue) => client.push(value),\n      setConsentDefaults: (state: ConsentState, regionOptions?: ConsentRegionOptions) =>\n        client.setConsentDefaults(state, regionOptions),\n      updateConsent: (state: ConsentState, regionOptions?: ConsentRegionOptions) =>\n        client.updateConsent(state, regionOptions),\n      whenReady: () => client.whenReady(),\n      onReady: (callback: (state: ScriptLoadState[]) => void) => client.onReady(callback)\n    };\n\n    // Provide the context to all components\n    app.provide(GTM_INJECTION_KEY, context);\n\n    // Also make it available as a global property for Options API users\n    app.config.globalProperties.$gtm = context;\n\n    // Call onBeforeInit hook if provided (for consent defaults)\n    if (onBeforeInit) {\n      onBeforeInit(client);\n    }\n\n    // Auto-initialize if enabled\n    if (autoInit) {\n      client.init();\n    }\n\n    // Register cleanup on app unmount\n    app.mixin({\n      unmounted() {\n        // Note: This runs for each component, but teardown is idempotent\n        // The actual teardown should only happen when the app is fully unmounted\n      }\n    });\n  }\n};\n\n/**\n * Internal helper to get the GTM context with proper error handling.\n */\nconst useGtmContext = (): GtmContext => {\n  const context = inject(GTM_INJECTION_KEY);\n  if (!context) {\n    throw new Error(\n      '[gtm-kit] useGtm() was called outside of a Vue app with GtmPlugin installed. ' +\n        'Make sure to call app.use(GtmPlugin, { containers: \"GTM-XXXXXX\" }) before using GTM composables.'\n    );\n  }\n  return context;\n};\n\n/**\n * Composable to access the full GTM context.\n *\n * @example\n * ```vue\n * <script setup>\n * import { useGtm } from '@jwiedeman/gtm-kit-vue';\n *\n * const { push, client, whenReady } = useGtm();\n *\n * function trackClick() {\n *   push({ event: 'button_click', button_name: 'hero_cta' });\n * }\n * </script>\n * ```\n */\nexport const useGtm = (): GtmContext => {\n  return useGtmContext();\n};\n\n/**\n * Composable to get just the push function.\n * Use this when you only need to push events.\n *\n * @example\n * ```vue\n * <script setup>\n * import { useGtmPush } from '@jwiedeman/gtm-kit-vue';\n *\n * const push = useGtmPush();\n *\n * function handlePurchase() {\n *   push({ event: 'purchase', value: 99.99 });\n * }\n * </script>\n * ```\n */\nexport const useGtmPush = (): ((value: DataLayerValue) => void) => {\n  return useGtmContext().push;\n};\n\n/**\n * Composable to access consent management functions.\n *\n * @example\n * ```vue\n * <script setup>\n * import { useGtmConsent } from '@jwiedeman/gtm-kit-vue';\n *\n * const { updateConsent } = useGtmConsent();\n *\n * function acceptAll() {\n *   updateConsent({\n *     ad_storage: 'granted',\n *     analytics_storage: 'granted',\n *     ad_user_data: 'granted',\n *     ad_personalization: 'granted'\n *   });\n * }\n * </script>\n * ```\n */\nexport const useGtmConsent = (): GtmConsentApi => {\n  const { setConsentDefaults, updateConsent } = useGtmContext();\n  return { setConsentDefaults, updateConsent };\n};\n\n/**\n * Composable to get the raw GTM client instance.\n * Use this when you need direct access to the client.\n *\n * @example\n * ```vue\n * <script setup>\n * import { useGtmClient } from '@jwiedeman/gtm-kit-vue';\n *\n * const client = useGtmClient();\n *\n * // Check if client is initialized\n * if (client.isInitialized()) {\n *   console.log('GTM is ready');\n * }\n * </script>\n * ```\n */\nexport const useGtmClient = (): GtmClient => {\n  return useGtmContext().client;\n};\n\n/**\n * Composable to get the whenReady function.\n * Use this to wait for GTM scripts to load.\n *\n * @example\n * ```vue\n * <script setup>\n * import { useGtmReady } from '@jwiedeman/gtm-kit-vue';\n * import { onMounted } from 'vue';\n *\n * const whenReady = useGtmReady();\n *\n * onMounted(async () => {\n *   const states = await whenReady();\n *   console.log('GTM scripts loaded:', states);\n * });\n * </script>\n * ```\n */\nexport const useGtmReady = (): (() => Promise<ScriptLoadState[]>) => {\n  return useGtmContext().whenReady;\n};\n\n// Extend Vue's ComponentCustomProperties for Options API users\ndeclare module 'vue' {\n  interface ComponentCustomProperties {\n    $gtm: GtmContext;\n  }\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,167 @@
+import { InjectionKey, App } from 'vue';
+import { CreateGtmClientOptions, GtmClient, DataLayerValue, ConsentState, ConsentRegionOptions, ScriptLoadState } from '@jwiedeman/gtm-kit';
+
+/**
+ * Options for the GTM Vue plugin.
+ * Extends CreateGtmClientOptions with Vue-specific options.
+ */
+interface GtmPluginOptions extends CreateGtmClientOptions {
+    /**
+     * Whether to automatically initialize GTM when the plugin is installed.
+     * @default true
+     */
+    autoInit?: boolean;
+    /**
+     * Callback executed before GTM initialization.
+     * Use this to set consent defaults.
+     */
+    onBeforeInit?: (client: GtmClient) => void;
+}
+/**
+ * The GTM context value provided to components via inject().
+ */
+interface GtmContext {
+    /** The underlying GTM client instance */
+    client: GtmClient;
+    /** Push a value to the data layer */
+    push: (value: DataLayerValue) => void;
+    /** Set consent defaults (must be called before init) */
+    setConsentDefaults: (state: ConsentState, options?: ConsentRegionOptions) => void;
+    /** Update consent state */
+    updateConsent: (state: ConsentState, options?: ConsentRegionOptions) => void;
+    /** Returns a promise that resolves when all GTM scripts are loaded */
+    whenReady: () => Promise<ScriptLoadState[]>;
+    /** Register a callback for when GTM scripts are ready */
+    onReady: (callback: (state: ScriptLoadState[]) => void) => () => void;
+}
+/**
+ * Consent-specific API subset.
+ */
+interface GtmConsentApi {
+    setConsentDefaults: (state: ConsentState, options?: ConsentRegionOptions) => void;
+    updateConsent: (state: ConsentState, options?: ConsentRegionOptions) => void;
+}
+/**
+ * Injection key for the GTM context.
+ * Use this with inject() to access the GTM context directly.
+ */
+declare const GTM_INJECTION_KEY: InjectionKey<GtmContext>;
+/**
+ * Vue 3 plugin for GTM Kit.
+ *
+ * @example
+ * ```ts
+ * import { createApp } from 'vue';
+ * import { GtmPlugin } from '@jwiedeman/gtm-kit-vue';
+ *
+ * createApp(App)
+ *   .use(GtmPlugin, { containers: 'GTM-XXXXXX' })
+ *   .mount('#app');
+ * ```
+ */
+declare const GtmPlugin: {
+    install(app: App, options: GtmPluginOptions): void;
+};
+/**
+ * Composable to access the full GTM context.
+ *
+ * @example
+ * ```vue
+ * <script setup>
+ * import { useGtm } from '@jwiedeman/gtm-kit-vue';
+ *
+ * const { push, client, whenReady } = useGtm();
+ *
+ * function trackClick() {
+ *   push({ event: 'button_click', button_name: 'hero_cta' });
+ * }
+ * </script>
+ * ```
+ */
+declare const useGtm: () => GtmContext;
+/**
+ * Composable to get just the push function.
+ * Use this when you only need to push events.
+ *
+ * @example
+ * ```vue
+ * <script setup>
+ * import { useGtmPush } from '@jwiedeman/gtm-kit-vue';
+ *
+ * const push = useGtmPush();
+ *
+ * function handlePurchase() {
+ *   push({ event: 'purchase', value: 99.99 });
+ * }
+ * </script>
+ * ```
+ */
+declare const useGtmPush: () => ((value: DataLayerValue) => void);
+/**
+ * Composable to access consent management functions.
+ *
+ * @example
+ * ```vue
+ * <script setup>
+ * import { useGtmConsent } from '@jwiedeman/gtm-kit-vue';
+ *
+ * const { updateConsent } = useGtmConsent();
+ *
+ * function acceptAll() {
+ *   updateConsent({
+ *     ad_storage: 'granted',
+ *     analytics_storage: 'granted',
+ *     ad_user_data: 'granted',
+ *     ad_personalization: 'granted'
+ *   });
+ * }
+ * </script>
+ * ```
+ */
+declare const useGtmConsent: () => GtmConsentApi;
+/**
+ * Composable to get the raw GTM client instance.
+ * Use this when you need direct access to the client.
+ *
+ * @example
+ * ```vue
+ * <script setup>
+ * import { useGtmClient } from '@jwiedeman/gtm-kit-vue';
+ *
+ * const client = useGtmClient();
+ *
+ * // Check if client is initialized
+ * if (client.isInitialized()) {
+ *   console.log('GTM is ready');
+ * }
+ * </script>
+ * ```
+ */
+declare const useGtmClient: () => GtmClient;
+/**
+ * Composable to get the whenReady function.
+ * Use this to wait for GTM scripts to load.
+ *
+ * @example
+ * ```vue
+ * <script setup>
+ * import { useGtmReady } from '@jwiedeman/gtm-kit-vue';
+ * import { onMounted } from 'vue';
+ *
+ * const whenReady = useGtmReady();
+ *
+ * onMounted(async () => {
+ *   const states = await whenReady();
+ *   console.log('GTM scripts loaded:', states);
+ * });
+ * </script>
+ * ```
+ */
+declare const useGtmReady: () => (() => Promise<ScriptLoadState[]>);
+declare module 'vue' {
+    interface ComponentCustomProperties {
+        $gtm: GtmContext;
+    }
+}
+
+export { GTM_INJECTION_KEY, GtmConsentApi, GtmContext, GtmPlugin, GtmPluginOptions, useGtm, useGtmClient, useGtmConsent, useGtmPush, useGtmReady };

package/dist/index.d.ts

@@ -0,0 +1,167 @@
+import { InjectionKey, App } from 'vue';
+import { CreateGtmClientOptions, GtmClient, DataLayerValue, ConsentState, ConsentRegionOptions, ScriptLoadState } from '@jwiedeman/gtm-kit';
+
+/**
+ * Options for the GTM Vue plugin.
+ * Extends CreateGtmClientOptions with Vue-specific options.
+ */
+interface GtmPluginOptions extends CreateGtmClientOptions {
+    /**
+     * Whether to automatically initialize GTM when the plugin is installed.
+     * @default true
+     */
+    autoInit?: boolean;
+    /**
+     * Callback executed before GTM initialization.
+     * Use this to set consent defaults.
+     */
+    onBeforeInit?: (client: GtmClient) => void;
+}
+/**
+ * The GTM context value provided to components via inject().
+ */
+interface GtmContext {
+    /** The underlying GTM client instance */
+    client: GtmClient;
+    /** Push a value to the data layer */
+    push: (value: DataLayerValue) => void;
+    /** Set consent defaults (must be called before init) */
+    setConsentDefaults: (state: ConsentState, options?: ConsentRegionOptions) => void;
+    /** Update consent state */
+    updateConsent: (state: ConsentState, options?: ConsentRegionOptions) => void;
+    /** Returns a promise that resolves when all GTM scripts are loaded */
+    whenReady: () => Promise<ScriptLoadState[]>;
+    /** Register a callback for when GTM scripts are ready */
+    onReady: (callback: (state: ScriptLoadState[]) => void) => () => void;
+}
+/**
+ * Consent-specific API subset.
+ */
+interface GtmConsentApi {
+    setConsentDefaults: (state: ConsentState, options?: ConsentRegionOptions) => void;
+    updateConsent: (state: ConsentState, options?: ConsentRegionOptions) => void;
+}
+/**
+ * Injection key for the GTM context.
+ * Use this with inject() to access the GTM context directly.
+ */
+declare const GTM_INJECTION_KEY: InjectionKey<GtmContext>;
+/**
+ * Vue 3 plugin for GTM Kit.
+ *
+ * @example
+ * ```ts
+ * import { createApp } from 'vue';
+ * import { GtmPlugin } from '@jwiedeman/gtm-kit-vue';
+ *
+ * createApp(App)
+ *   .use(GtmPlugin, { containers: 'GTM-XXXXXX' })
+ *   .mount('#app');
+ * ```
+ */
+declare const GtmPlugin: {
+    install(app: App, options: GtmPluginOptions): void;
+};
+/**
+ * Composable to access the full GTM context.
+ *
+ * @example
+ * ```vue
+ * <script setup>
+ * import { useGtm } from '@jwiedeman/gtm-kit-vue';
+ *
+ * const { push, client, whenReady } = useGtm();
+ *
+ * function trackClick() {
+ *   push({ event: 'button_click', button_name: 'hero_cta' });
+ * }
+ * </script>
+ * ```
+ */
+declare const useGtm: () => GtmContext;
+/**
+ * Composable to get just the push function.
+ * Use this when you only need to push events.
+ *
+ * @example
+ * ```vue
+ * <script setup>
+ * import { useGtmPush } from '@jwiedeman/gtm-kit-vue';
+ *
+ * const push = useGtmPush();
+ *
+ * function handlePurchase() {
+ *   push({ event: 'purchase', value: 99.99 });
+ * }
+ * </script>
+ * ```
+ */
+declare const useGtmPush: () => ((value: DataLayerValue) => void);
+/**
+ * Composable to access consent management functions.
+ *
+ * @example
+ * ```vue
+ * <script setup>
+ * import { useGtmConsent } from '@jwiedeman/gtm-kit-vue';
+ *
+ * const { updateConsent } = useGtmConsent();
+ *
+ * function acceptAll() {
+ *   updateConsent({
+ *     ad_storage: 'granted',
+ *     analytics_storage: 'granted',
+ *     ad_user_data: 'granted',
+ *     ad_personalization: 'granted'
+ *   });
+ * }
+ * </script>
+ * ```
+ */
+declare const useGtmConsent: () => GtmConsentApi;
+/**
+ * Composable to get the raw GTM client instance.
+ * Use this when you need direct access to the client.
+ *
+ * @example
+ * ```vue
+ * <script setup>
+ * import { useGtmClient } from '@jwiedeman/gtm-kit-vue';
+ *
+ * const client = useGtmClient();
+ *
+ * // Check if client is initialized
+ * if (client.isInitialized()) {
+ *   console.log('GTM is ready');
+ * }
+ * </script>
+ * ```
+ */
+declare const useGtmClient: () => GtmClient;
+/**
+ * Composable to get the whenReady function.
+ * Use this to wait for GTM scripts to load.
+ *
+ * @example
+ * ```vue
+ * <script setup>
+ * import { useGtmReady } from '@jwiedeman/gtm-kit-vue';
+ * import { onMounted } from 'vue';
+ *
+ * const whenReady = useGtmReady();
+ *
+ * onMounted(async () => {
+ *   const states = await whenReady();
+ *   console.log('GTM scripts loaded:', states);
+ * });
+ * </script>
+ * ```
+ */
+declare const useGtmReady: () => (() => Promise<ScriptLoadState[]>);
+declare module 'vue' {
+    interface ComponentCustomProperties {
+        $gtm: GtmContext;
+    }
+}
+
+export { GTM_INJECTION_KEY, GtmConsentApi, GtmContext, GtmPlugin, GtmPluginOptions, useGtm, useGtmClient, useGtmConsent, useGtmPush, useGtmReady };

package/dist/index.js

@@ -0,0 +1,8 @@
+import { inject } from 'vue';
+import { createGtmClient } from '@jwiedeman/gtm-kit';
+
+var a=Symbol("gtm-kit"),c={install(t,s){let{autoInit:u=!0,onBeforeInit:p,...m}=s,e=createGtmClient(m),r={client:e,push:n=>e.push(n),setConsentDefaults:(n,i)=>e.setConsentDefaults(n,i),updateConsent:(n,i)=>e.updateConsent(n,i),whenReady:()=>e.whenReady(),onReady:n=>e.onReady(n)};t.provide(a,r),t.config.globalProperties.$gtm=r,p&&p(e),u&&e.init(),t.mixin({unmounted(){}});}},o=()=>{let t=inject(a);if(!t)throw new Error('[gtm-kit] useGtm() was called outside of a Vue app with GtmPlugin installed. Make sure to call app.use(GtmPlugin, { containers: "GTM-XXXXXX" }) before using GTM composables.');return t},G=()=>o(),d=()=>o().push,y=()=>{let{setConsentDefaults:t,updateConsent:s}=o();return {setConsentDefaults:t,updateConsent:s}},x=()=>o().client,g=()=>o().whenReady;
+
+export { a as GTM_INJECTION_KEY, c as GtmPlugin, G as useGtm, x as useGtmClient, y as useGtmConsent, d as useGtmPush, g as useGtmReady };
+//# sourceMappingURL=out.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/plugin.ts"],"names":["inject","createGtmClient","GTM_INJECTION_KEY","GtmPlugin","app","options","autoInit","onBeforeInit","clientOptions","client","context","value","state","regionOptions","callback","useGtmContext","useGtm","useGtmPush","useGtmConsent","setConsentDefaults","updateConsent","useGtmClient","useGtmReady"],"mappings":"AAAA,OAAS,UAAAA,MAA2C,MACpD,OACE,mBAAAC,MAOK,qBAkDA,IAAMC,EAA8C,OAAO,SAAS,EAe9DC,EAAY,CACvB,QAAQC,EAAUC,EAAiC,CACjD,GAAM,CAAE,SAAAC,EAAW,GAAM,aAAAC,EAAc,GAAGC,CAAc,EAAIH,EAEtDI,EAASR,EAAgBO,CAAa,EAEtCE,EAAsB,CAC1B,OAAAD,EACA,KAAOE,GAA0BF,EAAO,KAAKE,CAAK,EAClD,mBAAoB,CAACC,EAAqBC,IACxCJ,EAAO,mBAAmBG,EAAOC,CAAa,EAChD,cAAe,CAACD,EAAqBC,IACnCJ,EAAO,cAAcG,EAAOC,CAAa,EAC3C,UAAW,IAAMJ,EAAO,UAAU,EAClC,QAAUK,GAAiDL,EAAO,QAAQK,CAAQ,CACpF,EAGAV,EAAI,QAAQF,EAAmBQ,CAAO,EAGtCN,EAAI,OAAO,iBAAiB,KAAOM,EAG/BH,GACFA,EAAaE,CAAM,EAIjBH,GACFG,EAAO,KAAK,EAIdL,EAAI,MAAM,CACR,WAAY,CAGZ,CACF,CAAC,CACH,CACF,EAKMW,EAAgB,IAAkB,CACtC,IAAML,EAAUV,EAAOE,CAAiB,EACxC,GAAI,CAACQ,EACH,MAAM,IAAI,MACR,+KAEF,EAEF,OAAOA,CACT,EAkBaM,EAAS,IACbD,EAAc,EAoBVE,EAAa,IACjBF,EAAc,EAAE,KAwBZG,EAAgB,IAAqB,CAChD,GAAM,CAAE,mBAAAC,EAAoB,cAAAC,CAAc,EAAIL,EAAc,EAC5D,MAAO,CAAE,mBAAAI,EAAoB,cAAAC,CAAc,CAC7C,EAoBaC,EAAe,IACnBN,EAAc,EAAE,OAsBZO,EAAc,IAClBP,EAAc,EAAE","sourcesContent":["import { inject, type App, type InjectionKey } from 'vue';\nimport {\n  createGtmClient,\n  type ConsentRegionOptions,\n  type ConsentState,\n  type CreateGtmClientOptions,\n  type DataLayerValue,\n  type GtmClient,\n  type ScriptLoadState\n} from '@jwiedeman/gtm-kit';\n\n/**\n * Options for the GTM Vue plugin.\n * Extends CreateGtmClientOptions with Vue-specific options.\n */\nexport interface GtmPluginOptions extends CreateGtmClientOptions {\n  /**\n   * Whether to automatically initialize GTM when the plugin is installed.\n   * @default true\n   */\n  autoInit?: boolean;\n\n  /**\n   * Callback executed before GTM initialization.\n   * Use this to set consent defaults.\n   */\n  onBeforeInit?: (client: GtmClient) => void;\n}\n\n/**\n * The GTM context value provided to components via inject().\n */\nexport interface GtmContext {\n  /** The underlying GTM client instance */\n  client: GtmClient;\n  /** Push a value to the data layer */\n  push: (value: DataLayerValue) => void;\n  /** Set consent defaults (must be called before init) */\n  setConsentDefaults: (state: ConsentState, options?: ConsentRegionOptions) => void;\n  /** Update consent state */\n  updateConsent: (state: ConsentState, options?: ConsentRegionOptions) => void;\n  /** Returns a promise that resolves when all GTM scripts are loaded */\n  whenReady: () => Promise<ScriptLoadState[]>;\n  /** Register a callback for when GTM scripts are ready */\n  onReady: (callback: (state: ScriptLoadState[]) => void) => () => void;\n}\n\n/**\n * Consent-specific API subset.\n */\nexport interface GtmConsentApi {\n  setConsentDefaults: (state: ConsentState, options?: ConsentRegionOptions) => void;\n  updateConsent: (state: ConsentState, options?: ConsentRegionOptions) => void;\n}\n\n/**\n * Injection key for the GTM context.\n * Use this with inject() to access the GTM context directly.\n */\nexport const GTM_INJECTION_KEY: InjectionKey<GtmContext> = Symbol('gtm-kit');\n\n/**\n * Vue 3 plugin for GTM Kit.\n *\n * @example\n * ```ts\n * import { createApp } from 'vue';\n * import { GtmPlugin } from '@jwiedeman/gtm-kit-vue';\n *\n * createApp(App)\n *   .use(GtmPlugin, { containers: 'GTM-XXXXXX' })\n *   .mount('#app');\n * ```\n */\nexport const GtmPlugin = {\n  install(app: App, options: GtmPluginOptions): void {\n    const { autoInit = true, onBeforeInit, ...clientOptions } = options;\n\n    const client = createGtmClient(clientOptions);\n\n    const context: GtmContext = {\n      client,\n      push: (value: DataLayerValue) => client.push(value),\n      setConsentDefaults: (state: ConsentState, regionOptions?: ConsentRegionOptions) =>\n        client.setConsentDefaults(state, regionOptions),\n      updateConsent: (state: ConsentState, regionOptions?: ConsentRegionOptions) =>\n        client.updateConsent(state, regionOptions),\n      whenReady: () => client.whenReady(),\n      onReady: (callback: (state: ScriptLoadState[]) => void) => client.onReady(callback)\n    };\n\n    // Provide the context to all components\n    app.provide(GTM_INJECTION_KEY, context);\n\n    // Also make it available as a global property for Options API users\n    app.config.globalProperties.$gtm = context;\n\n    // Call onBeforeInit hook if provided (for consent defaults)\n    if (onBeforeInit) {\n      onBeforeInit(client);\n    }\n\n    // Auto-initialize if enabled\n    if (autoInit) {\n      client.init();\n    }\n\n    // Register cleanup on app unmount\n    app.mixin({\n      unmounted() {\n        // Note: This runs for each component, but teardown is idempotent\n        // The actual teardown should only happen when the app is fully unmounted\n      }\n    });\n  }\n};\n\n/**\n * Internal helper to get the GTM context with proper error handling.\n */\nconst useGtmContext = (): GtmContext => {\n  const context = inject(GTM_INJECTION_KEY);\n  if (!context) {\n    throw new Error(\n      '[gtm-kit] useGtm() was called outside of a Vue app with GtmPlugin installed. ' +\n        'Make sure to call app.use(GtmPlugin, { containers: \"GTM-XXXXXX\" }) before using GTM composables.'\n    );\n  }\n  return context;\n};\n\n/**\n * Composable to access the full GTM context.\n *\n * @example\n * ```vue\n * <script setup>\n * import { useGtm } from '@jwiedeman/gtm-kit-vue';\n *\n * const { push, client, whenReady } = useGtm();\n *\n * function trackClick() {\n *   push({ event: 'button_click', button_name: 'hero_cta' });\n * }\n * </script>\n * ```\n */\nexport const useGtm = (): GtmContext => {\n  return useGtmContext();\n};\n\n/**\n * Composable to get just the push function.\n * Use this when you only need to push events.\n *\n * @example\n * ```vue\n * <script setup>\n * import { useGtmPush } from '@jwiedeman/gtm-kit-vue';\n *\n * const push = useGtmPush();\n *\n * function handlePurchase() {\n *   push({ event: 'purchase', value: 99.99 });\n * }\n * </script>\n * ```\n */\nexport const useGtmPush = (): ((value: DataLayerValue) => void) => {\n  return useGtmContext().push;\n};\n\n/**\n * Composable to access consent management functions.\n *\n * @example\n * ```vue\n * <script setup>\n * import { useGtmConsent } from '@jwiedeman/gtm-kit-vue';\n *\n * const { updateConsent } = useGtmConsent();\n *\n * function acceptAll() {\n *   updateConsent({\n *     ad_storage: 'granted',\n *     analytics_storage: 'granted',\n *     ad_user_data: 'granted',\n *     ad_personalization: 'granted'\n *   });\n * }\n * </script>\n * ```\n */\nexport const useGtmConsent = (): GtmConsentApi => {\n  const { setConsentDefaults, updateConsent } = useGtmContext();\n  return { setConsentDefaults, updateConsent };\n};\n\n/**\n * Composable to get the raw GTM client instance.\n * Use this when you need direct access to the client.\n *\n * @example\n * ```vue\n * <script setup>\n * import { useGtmClient } from '@jwiedeman/gtm-kit-vue';\n *\n * const client = useGtmClient();\n *\n * // Check if client is initialized\n * if (client.isInitialized()) {\n *   console.log('GTM is ready');\n * }\n * </script>\n * ```\n */\nexport const useGtmClient = (): GtmClient => {\n  return useGtmContext().client;\n};\n\n/**\n * Composable to get the whenReady function.\n * Use this to wait for GTM scripts to load.\n *\n * @example\n * ```vue\n * <script setup>\n * import { useGtmReady } from '@jwiedeman/gtm-kit-vue';\n * import { onMounted } from 'vue';\n *\n * const whenReady = useGtmReady();\n *\n * onMounted(async () => {\n *   const states = await whenReady();\n *   console.log('GTM scripts loaded:', states);\n * });\n * </script>\n * ```\n */\nexport const useGtmReady = (): (() => Promise<ScriptLoadState[]>) => {\n  return useGtmContext().whenReady;\n};\n\n// Extend Vue's ComponentCustomProperties for Options API users\ndeclare module 'vue' {\n  interface ComponentCustomProperties {\n    $gtm: GtmContext;\n  }\n}\n"]}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@jwiedeman/gtm-kit-vue",
+  "version": "1.0.1",
+  "description": "Vue 3 composables and plugin for GTM Kit - Google Tag Manager integration.",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jwiedeman/GTM-Kit.git",
+    "directory": "packages/vue"
+  },
+  "author": "jwiedeman",
+  "keywords": [
+    "gtm",
+    "google-tag-manager",
+    "vue",
+    "vue3",
+    "composables"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "clean": "rm -rf dist",
+    "lint": "eslint --max-warnings=0 \"src/**/*.{ts,tsx}\"",
+    "test": "jest --config ./jest.config.cjs --runInBand",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@jwiedeman/gtm-kit": "^1.0.1"
+  },
+  "peerDependencies": {
+    "vue": "^3.3.0"
+  },
+  "devDependencies": {
+    "@vue/test-utils": "^2.4.6",
+    "@vue/vue3-jest": "^29.2.6",
+    "vue": "^3.4.21",
+    "tslib": "^2.6.2"
+  }
+}