@sealmetrics/mcp 0.1.0 → 1.2.0

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,0BAA0B,EAC1B,sBAAsB,GACvB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AAEvC,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC/C,MAAM,EAAE,OAAO,EAAE,WAAW,EAAE,GAAG,OAAO,CAAC,iBAAiB,CAAwB,CAAC;AAEnF,MAAM,mBAAmB,GAAG,OAAO,CAAC;AAEpC,MAAM,aAAa,GAAG,CAAC,oBAAoB,EAAE,qBAAqB,EAAE,WAAW,CAAC,CAAC;AAEjF,SAAS,eAAe,CAAC,GAAW;IAClC,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;QAC5B,IAAI,CAAC,aAAa,CAAC,QAAQ,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC7C,OAAO,CAAC,KAAK,CACX,yDAAyD,MAAM,CAAC,QAAQ,MAAM;gBAC5E,kBAAkB,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAC/C,CAAC;YACF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,CAAC,KAAK,CAAC,wCAAwC,GAAG,EAAE,CAAC,CAAC;QAC7D,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;AACH,CAAC;AAED,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,mBAAmB,CAAC;AAChD,MAAM,QAAQ,GACZ,OAAO,CAAC,GAAG,CAAC,oBAAoB,IAAI,mCAAmC,CAAC;AAE1E,IAAI,OAAO,CAAC,GAAG,CAAC,oBAAoB,EAAE,CAAC;IACrC,eAAe,CAAC,QAAQ,CAAC,CAAC;AAC5B,CAAC;AAED,MAAM,MAAM,GAA6B,OAAO;IAC9C,CAAC,CAAC,IAAI,iBAAiB,CAAC,OAAO,EAAE,QAAQ,CAAC;IAC1C,CAAC,CAAC,IAAI,CAAC;AAET,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;IAC3B,IAAI,EAAE,aAAa;IACnB,OAAO,EAAE,WAAW;CACrB,CAAC,CAAC;AAEH,SAAS,eAAe,CAAC,IAA6B;IACpD,MAAM,IAAI,GAAG,IAAI,CAAC,IAA0B,CAAC;IAC7C,MAAM,UAAU,GAAG,IAAI,CAAC,IAA4B,CAAC;IACrD,MAAM,WAAW,GAAG,IAAI,CAAC,WAAiC,CAAC;IAE3D,IAAI,MAAoB,CAAC;IAEzB,IAAI,UAAU,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxC,MAAM,GAAG,CAAC,CAAC,IAAI,CAAC,UAAmC,CAAC,CAAC;IACvD,CAAC;SAAM,IAAI,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACnD,MAAM,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC;IACtB,CAAC;SAAM,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QAC9B,MAAM,GAAG,CAAC,CAAC,OAAO,EAAE,CAAC;IACvB,CAAC;SAAM,CAAC;QACN,MAAM,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC;IACtB,CAAC;IAED,IAAI,WAAW,EAAE,CAAC;QAChB,MAAM,GAAG,MAAM,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;IACxC,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,SAAS,aAAa,CAAC,KAAc;IACnC,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;QAC5C,IAAI,IAAI,CAAC,MAAM,GAAG,mBAAmB,EAAE,CAAC;YACtC,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,mBAAmB,CAAC,GAAG,mBAAmB,CAAC;QAClE,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,+CAA+C,CAAC;IACzD,CAAC;AACH,CAAC;AAED,qBAAqB;AACrB,KAAK,MAAM,IAAI,IAAI,SAAS,EAAE,CAAC;IAC7B,MAAM,KAAK,GAAiC,EAAE,CAAC;IAC/C,KAAK,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,WAAW,CAAC,UAAU,CAAC,EAAE,CAAC;QACtE,iFAAiF;QACjF,KAAK,CAAC,GAAG,CAAC,GAAG,eAAe,CAAC,IAA+B,CAAC,CAAC,QAAQ,EAAE,CAAC;IAC3E,CAAC;IAED,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC;IAC3B,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC;IAE7B,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,WAAW,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;QAC5D,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,OAAO;gBACL,OAAO,EAAE;oBACP;wBACE,IAAI,EAAE,MAAe;wBACrB,IAAI,EAAE,mDAAmD;4BACvD,iBAAiB;4BACjB,6FAA6F;4BAC7F,8CAA8C;4BAC9C,wFAAwF;4BACxF,2BAA2B;qBAC9B;iBACF;gBACD,OAAO,EAAE,IAAI;aACd,CAAC;QACJ,CAAC;QACD,IAAI,CAAC;YACH,yEAAyE;YACzE,MAAM,aAAa,GAA4B,EAAE,CAAC;YAClD,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;gBAChD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;oBAC9B,aAAa,CAAC,GAAG,CAAC,GAAG,aAAa,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;gBACjD,CAAC;qBAAM,CAAC;oBACN,aAAa,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;gBAC7B,CAAC;YACH,CAAC;YACD,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;YACpD,OAAO;gBACL,OAAO,EAAE;oBACP;wBACE,IAAI,EAAE,MAAe;wBACrB,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC;qBAC5B;iBACF;aACF,CAAC;QACJ,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,OAAO,GACX,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,wBAAwB,CAAC;YACpE,OAAO;gBACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,UAAU,OAAO,EAAE,EAAE,CAAC;gBAC/D,OAAO,EAAE,IAAI;aACd,CAAC;QACJ,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC;AAED,qBAAqB;AACrB,MAAM,CAAC,QAAQ,CACb,mBAAmB,EACnB,kBAAkB,EAClB,EAAE,WAAW,EAAE,0BAA0B,EAAE,QAAQ,EAAE,eAAe,EAAE,EACtE,KAAK,IAAI,EAAE,CAAC,CAAC;IACX,QAAQ,EAAE;QACR;YACE,GAAG,EAAE,kBAAkB;YACvB,QAAQ,EAAE,eAAe;YACzB,IAAI,EAAE,sBAAsB;SAC7B;KACF;CACF,CAAC,CACH,CAAC;AAEF,mBAAmB;AACnB,KAAK,UAAU,IAAI;IACjB,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;AAClC,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;IACrB,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACvE,OAAO,CAAC,KAAK,CAAC,cAAc,EAAE,OAAO,CAAC,CAAC;IACvC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/resources/tracking-guide.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Static tracking guide exposed as an MCP resource.
+ * Claude reads this on connect and knows how to implement SealMetrics tracking
+ * without calling any tool.
+ *
+ * This is an operational playbook, not just an API reference.
+ * It tells the agent WHAT to do, HOW to decide, and WHERE to put things.
+ */
+export declare const TRACKING_GUIDE_URI = "sealmetrics://tracking-guide";
+export declare const TRACKING_GUIDE_NAME = "SealMetrics Tracking Guide";
+export declare const TRACKING_GUIDE_DESCRIPTION = "Operational playbook for implementing SealMetrics tracking on any website: pixel installation, conversions, microconversions, content grouping, and framework-specific patterns.";
+export declare const TRACKING_GUIDE_CONTENT = "# SealMetrics Tracking \u2014 Implementation Playbook\n\nYou are implementing SealMetrics analytics on a website. This guide tells you exactly what to do, step by step.\n\n---\n\n## Step 1: Get the pixel\n\nCall the `get_tracking_code` tool with the user's `site_id`. It returns:\n- `script_tag`: the exact `<script>` tag to insert (with the real site ID baked in)\n- `tracker_url`: the URL of the tracker JS file\n\nIf you don't know the site_id, call `list_sites` first to find it.\n\n---\n\n## Step 2: Find where to insert the script\n\nThe script tag goes in the `<head>` of every page, **once**. Where that is depends on the framework:\n\n| Framework | Where to put it |\n|-----------|----------------|\n| **Plain HTML** | Inside `<head>` in every `.html` file, or in a shared template/layout |\n| **Next.js (App Router)** | `app/layout.tsx` \u2014 use `import Script from 'next/script'` with `strategy=\"afterInteractive\"` |\n| **Next.js (Pages Router)** | `pages/_app.tsx` \u2014 use `<Script>` component |\n| **React (CRA/Vite)** | `index.html` inside `<head>` |\n| **Vue / Nuxt** | `nuxt.config.ts` head section, or `app.vue` |\n| **Angular** | `src/index.html` inside `<head>` |\n| **Astro** | Shared layout component `<head>` |\n| **WordPress** | `header.php` or via a \"header scripts\" plugin/setting |\n| **Shopify** | `theme.liquid` inside `<head>` |\n\n**How to find it**: Search for `</head>`, or look for the root layout/template file. Every framework has one place that wraps all pages \u2014 that's where the script goes.\n\n### Plain HTML\n```html\n<head>\n  <!-- other tags... -->\n  <script src=\"https://t.sealmetrics.com/t.js?id=SITE_ID\" defer></script>\n</head>\n```\n\n### Next.js (App Router)\n```tsx\n// app/layout.tsx\nimport Script from 'next/script';\n\nexport default function RootLayout({ children }: { children: React.ReactNode }) {\n  return (\n    <html lang=\"en\">\n      <head />\n      <body>\n        {children}\n        <Script src=\"https://t.sealmetrics.com/t.js?id=SITE_ID\" strategy=\"afterInteractive\" />\n      </body>\n    </html>\n  );\n}\n```\n\n### Vue / Nuxt\n```ts\n// nuxt.config.ts\nexport default defineNuxtConfig({\n  app: {\n    head: {\n      script: [{ src: 'https://t.sealmetrics.com/t.js?id=SITE_ID', defer: true }]\n    }\n  }\n});\n```\n\n**Once the script is in place, pageviews are tracked automatically** \u2014 on load, on SPA navigation (pushState, replaceState, popstate), on back/forward. You do NOT need to add manual pageview calls.\n\n---\n\n## Step 3: Identify what to track\n\nAnalyze the website code and identify trackeable user actions. Classify each one as a **conversion** or a **microconversion**.\n\n### What is a conversion?\n\nA conversion is a **business goal** \u2014 the main thing the site owner wants users to do. It typically has monetary value or represents a completed transaction.\n\n| What you see in the code | Conversion type | Has value? |\n|--------------------------|-----------------|------------|\n| Purchase/checkout completion, order confirmation page | `purchase` | Yes \u2014 the order total |\n| Subscription payment, plan upgrade | `purchase` | Yes \u2014 the subscription price |\n| Contact form, demo request, quote request | `lead` | No (use `0`) |\n| Account registration, signup form | `signup` | No (use `0`) |\n| Booking confirmation, appointment scheduled | `booking` | Yes if there's a price, otherwise `0` |\n\n**Rule of thumb**: If the business would pay money to make this action happen, it's a conversion.\n\n### What is a microconversion?\n\nA microconversion is a **step toward a conversion** or an **engagement signal**. It tells you how users interact with the site before converting.\n\n| What you see in the code | Microconversion type |\n|--------------------------|---------------------|\n| \"Add to cart\" button | `add_to_cart` |\n| \"Add to wishlist\" / \"Save for later\" | `add_to_wishlist` |\n| Checkout step buttons (shipping, payment...) | `begin_checkout`, `checkout_shipping`, `checkout_payment` |\n| Newsletter/email signup form | `newsletter_signup` |\n| PDF/resource download link | `download` |\n| Video play button | `video_play` |\n| Video ends | `video_complete` |\n| Pricing page visited or pricing toggle clicked | `pricing_view` |\n| Share/social buttons | `share` |\n| Search form used | `search` |\n| Filter/sort applied | `filter_applied` |\n| Tab/accordion clicked to reveal content | `content_expand` |\n| Chat widget opened | `chat_open` |\n| Scroll milestones (25%, 50%, 75%, 100%) | `scroll_25`, `scroll_50`, `scroll_75`, `scroll_100` |\n\n**Rule of thumb**: If it shows intent or engagement but isn't the final goal, it's a microconversion.\n\n---\n\n## Step 4: Implement conversions\n\n### Syntax\n```js\nsealmetrics.conv(type, amount, properties?)\n```\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `type` | string | Yes | snake_case name for this conversion |\n| `amount` | number | Yes | Monetary value. Use `0` if no value (leads, signups) |\n| `properties` | object | No | Extra metadata (see \"Using properties\" below) |\n\n### Where to put it\n\nThe conversion call goes **at the moment the action succeeds**, not when the user clicks. For example:\n\n- **Form submission**: In the `onSubmit` handler, AFTER validation passes (or on the thank-you page)\n- **Purchase**: On the order confirmation/thank-you page, or in the success callback of the payment API\n- **Signup**: After the registration API call succeeds\n\n### Examples by pattern\n\n**Form submit (vanilla JS):**\n```js\ndocument.querySelector('#contact-form').addEventListener('submit', function(e) {\n  // The form is about to submit \u2014 track the lead\n  sealmetrics.conv('lead', 0, { form_name: 'contact', page: location.pathname });\n});\n```\n\n**Form submit (React):**\n```tsx\nconst handleSubmit = async (data: FormData) => {\n  await api.submitContactForm(data);\n  window.sealmetrics?.conv('lead', 0, { form_name: 'contact' });\n};\n```\n\n**Purchase (thank-you page):**\n```html\n<!-- This script runs on /order-confirmation or /thank-you -->\n<script>\n  // Pull values from the page or from server-rendered data\n  sealmetrics.conv('purchase', 149.99, {\n    currency: 'EUR',\n    payment_method: 'credit_card'\n  });\n</script>\n```\n\n**Purchase (React, after payment API):**\n```tsx\nconst handlePayment = async () => {\n  const result = await processPayment(cart);\n  if (result.success) {\n    window.sealmetrics?.conv('purchase', cart.total, {\n      currency: cart.currency,\n      payment_method: result.method\n    });\n    router.push('/thank-you');\n  }\n};\n```\n\n**Signup (after API success):**\n```tsx\nconst handleRegister = async (formData: RegisterForm) => {\n  const user = await api.register(formData);\n  window.sealmetrics?.conv('signup', 0, { plan: formData.plan });\n  router.push('/welcome');\n};\n```\n\n---\n\n## Step 5: Implement microconversions\n\n### Syntax\n```js\nsealmetrics.micro(type, properties?)\n```\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `type` | string | Yes | snake_case name for this event |\n| `properties` | object | No | Extra metadata (see \"Using properties\" below) |\n\n### Where to put it\n\nMicroconversions go **on the user action** \u2014 usually in click handlers, submit handlers, or event listeners.\n\n### Examples by pattern\n\n**Add to cart (vanilla):**\n```js\ndocument.querySelectorAll('.add-to-cart').forEach(function(btn) {\n  btn.addEventListener('click', function() {\n    sealmetrics.micro('add_to_cart', {\n      product_id: this.dataset.productId,\n      product_name: this.dataset.productName,\n      price: parseFloat(this.dataset.price)\n    });\n  });\n});\n```\n\n**Add to cart (React):**\n```tsx\nfunction AddToCartButton({ product }: { product: Product }) {\n  const handleClick = () => {\n    addToCart(product);\n    window.sealmetrics?.micro('add_to_cart', {\n      product_id: product.id,\n      product_name: product.name,\n      price: product.price\n    });\n  };\n  return <button onClick={handleClick}>Add to Cart</button>;\n}\n```\n\n**Newsletter signup:**\n```js\ndocument.querySelector('#newsletter-form').addEventListener('submit', function() {\n  sealmetrics.micro('newsletter_signup', {\n    position: this.closest('footer') ? 'footer' : 'inline'\n  });\n});\n```\n\n**Video engagement:**\n```js\nvar video = document.querySelector('video');\nvideo.addEventListener('play', function() {\n  sealmetrics.micro('video_play', { video_id: this.dataset.videoId });\n});\nvideo.addEventListener('ended', function() {\n  sealmetrics.micro('video_complete', { video_id: this.dataset.videoId });\n});\n```\n\n**Scroll depth tracking:**\n```js\nvar scrollTracked = {};\nwindow.addEventListener('scroll', function() {\n  var pct = Math.round(window.scrollY / (document.body.scrollHeight - window.innerHeight) * 100);\n  [25, 50, 75, 100].forEach(function(milestone) {\n    if (pct >= milestone && !scrollTracked[milestone]) {\n      scrollTracked[milestone] = true;\n      sealmetrics.micro('scroll_' + milestone);\n    }\n  });\n});\n```\n\n**Checkout funnel steps (React):**\n```tsx\n// When user moves from step to step\nconst goToStep = (step: number) => {\n  setCurrentStep(step);\n  const stepNames: Record<number, string> = {\n    1: 'begin_checkout',\n    2: 'checkout_shipping',\n    3: 'checkout_payment',\n  };\n  if (stepNames[step]) {\n    window.sealmetrics?.micro(stepNames[step], { items_count: cart.items.length });\n  }\n};\n```\n\n---\n\n## Step 6: Set up content grouping\n\nContent grouping lets the site owner analyze metrics by section: \"how does the blog perform vs product pages?\"\n\n### When to use it\n\nUse content grouping when the site has **distinct sections** that serve different purposes. If the site is a single-purpose landing page, skip it.\n\n### How to decide groups\n\nLook at the URL structure and page purpose:\n\n| URL pattern | Group |\n|-------------|-------|\n| `/blog/*`, `/posts/*`, `/articles/*` | `blog` |\n| `/products/*`, `/shop/*`, `/item/*` | `product` |\n| `/category/*`, `/collections/*` | `category` |\n| `/cart`, `/checkout/*`, `/order/*` | `checkout` |\n| `/docs/*`, `/help/*`, `/faq` | `docs` |\n| `/dashboard/*`, `/app/*`, `/account/*` | `app` |\n| `/pricing`, `/plans` | `pricing` |\n| `/`, `/about`, `/features`, `/contact` | `landing` |\n\n### How to implement it\n\n**Option A \u2014 Static (via URL param in the script tag):**\n\nBest when you can set a different script tag per section (e.g., different templates, layouts).\n\n```html\n<!-- Blog layout -->\n<script src=\"https://t.sealmetrics.com/t.js?id=SITE_ID&group=blog\" defer></script>\n\n<!-- Product layout -->\n<script src=\"https://t.sealmetrics.com/t.js?id=SITE_ID&group=product\" defer></script>\n```\n\n**Option B \u2014 Dynamic (via JS, based on URL):**\n\nBest for SPAs or when you can't change the script tag per section.\n\n```js\n// Determine group from the current path\nfunction getContentGroup() {\n  var path = location.pathname;\n  if (path.startsWith('/blog') || path.startsWith('/posts')) return 'blog';\n  if (path.startsWith('/products') || path.startsWith('/shop')) return 'product';\n  if (path.startsWith('/cart') || path.startsWith('/checkout')) return 'checkout';\n  if (path.startsWith('/docs') || path.startsWith('/help')) return 'docs';\n  return 'landing';\n}\n\nsealmetrics({ group: getContentGroup() });\n```\n\n**Option C \u2014 Next.js (per layout segment):**\n```tsx\n// app/blog/layout.tsx\nimport Script from 'next/script';\nexport default function BlogLayout({ children }: { children: React.ReactNode }) {\n  return (\n    <>\n      <Script src=\"https://t.sealmetrics.com/t.js?id=SITE_ID&group=blog\" strategy=\"afterInteractive\" />\n      {children}\n    </>\n  );\n}\n```\nNote: if you use per-layout scripts with groups, remove the global script from the root layout to avoid double-tracking.\n\n---\n\n## Using properties effectively\n\nProperties are key-value metadata attached to conversions and microconversions. They power drill-down analysis in the dashboard.\n\n### What to include\n\n| Property | When to use | Example |\n|----------|------------|---------|\n| `currency` | Any monetary conversion | `'EUR'`, `'USD'` |\n| `payment_method` | Purchase conversions | `'credit_card'`, `'paypal'`, `'stripe'` |\n| `plan` | Signup/subscription conversions | `'free'`, `'pro'`, `'enterprise'` |\n| `product_id` | Product-related events | `'SKU-123'` |\n| `product_name` | Product-related events | `'Wireless Headphones'` |\n| `price` | Add-to-cart, wishlist | `49.99` |\n| `category` | Product events | `'electronics'`, `'shoes'` |\n| `form_name` | Lead/form conversions | `'contact'`, `'demo_request'`, `'quote'` |\n| `position` | UI element interactions | `'header'`, `'footer'`, `'popup'`, `'sidebar'` |\n| `video_id` | Video events | `'intro-video'`, `'product-demo'` |\n| `search_term` | Search events | The user's search query |\n\n### What NOT to include\n\n- **Order IDs, user IDs, transaction IDs** \u2014 these are high-cardinality and don't help analysis. Never put them in the type name either.\n- **Email addresses, names, or PII** \u2014 SealMetrics is privacy-first.\n- **Timestamps** \u2014 the system already records when events happen.\n- **Page URLs** \u2014 already tracked automatically.\n\n### Property values\n\n- Keep values **low-cardinality** when possible: `'credit_card'` not `'visa_ending_4242'`\n- Use **consistent values**: always `'credit_card'`, never sometimes `'cc'` and sometimes `'Credit Card'`\n- **Numbers** should be numbers, not strings: `price: 49.99`, not `price: '49.99'`\n\n---\n\n## Naming conventions\n\n- **snake_case** always: `add_to_cart`, not `addToCart` or `Add To Cart`\n- **Descriptive**: `begin_checkout` not `step2`, `newsletter_signup` not `nl`\n- **Stable**: once you name a type, don't rename it \u2014 it breaks historical data\n- **No IDs in the type name**: `sealmetrics.conv('purchase', 99)`, not `sealmetrics.conv('purchase_order_12345', 99)`\n\n---\n\n## TypeScript type declarations\n\nIf the project uses TypeScript, add this declaration so `window.sealmetrics` doesn't show type errors:\n\n```ts\n// types/sealmetrics.d.ts (or at the top of a component file)\ndeclare global {\n  interface Window {\n    sealmetrics?: {\n      (options?: { group?: string }): void;\n      conv: (type: string, amount: number, properties?: Record<string, unknown>) => void;\n      micro: (type: string, properties?: Record<string, unknown>) => void;\n    };\n  }\n}\n```\n\nThen call via `window.sealmetrics?.conv(...)` instead of `sealmetrics.conv(...)`.\n\n---\n\n## Complete implementation checklist\n\nUse this to verify you haven't missed anything:\n\n1. **Pixel installed**: Script tag is in the `<head>` (or root layout) of every page \u2014 ONE time only\n2. **Pageviews working**: Automatic, no code needed. Verify with `?debug=1`\n3. **Conversions identified**: Every business goal (purchase, lead, signup) has a `sealmetrics.conv()` call\n4. **Conversion placement**: Each conversion fires at the right moment (after success, not on click)\n5. **Conversion values**: Purchases have the real `amount`, leads/signups use `0`\n6. **Microconversions identified**: Funnel steps and engagement signals have `sealmetrics.micro()` calls\n7. **Properties added**: Events carry useful metadata (currency, product_id, form_name, etc.)\n8. **Content grouping**: If the site has distinct sections, groups are assigned\n9. **Naming**: All types are snake_case, descriptive, and stable\n10. **No PII**: No emails, user IDs, or personal data in properties\n\n---\n\n## Debugging\n\nAdd `?debug=1` to any page URL to see all tracking events in the browser console:\n\n```\nhttps://yoursite.com/products?debug=1\n```\n\nShows: session ID, account ID, event type, payload, and any errors.\n\n---\n\n## Technical notes\n\n- **No cookies, no localStorage** \u2014 GDPR-friendly, no consent banner needed\n- **SPA support is automatic** \u2014 History API (pushState/replaceState/popstate) is intercepted\n- **Uses sendBeacon** \u2014 non-blocking, guaranteed delivery even on tab close\n- **Three equivalent globals**: `sealmetrics`, `sm`, `_sm` \u2014 use `sealmetrics` in new code\n- **Script loads async** with `defer` \u2014 never blocks page rendering\n";
+//# sourceMappingURL=tracking-guide.d.ts.map

package/dist/resources/tracking-guide.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracking-guide.d.ts","sourceRoot":"","sources":["../../src/resources/tracking-guide.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,iCAAiC,CAAC;AACjE,eAAO,MAAM,mBAAmB,+BAA+B,CAAC;AAChE,eAAO,MAAM,0BAA0B,qLAC6I,CAAC;AAErL,eAAO,MAAM,sBAAsB,gigBAkdlC,CAAC"}

package/dist/resources/tracking-guide.js

@@ -0,0 +1,479 @@
+/**
+ * Static tracking guide exposed as an MCP resource.
+ * Claude reads this on connect and knows how to implement SealMetrics tracking
+ * without calling any tool.
+ *
+ * This is an operational playbook, not just an API reference.
+ * It tells the agent WHAT to do, HOW to decide, and WHERE to put things.
+ */
+export const TRACKING_GUIDE_URI = "sealmetrics://tracking-guide";
+export const TRACKING_GUIDE_NAME = "SealMetrics Tracking Guide";
+export const TRACKING_GUIDE_DESCRIPTION = "Operational playbook for implementing SealMetrics tracking on any website: pixel installation, conversions, microconversions, content grouping, and framework-specific patterns.";
+export const TRACKING_GUIDE_CONTENT = `# SealMetrics Tracking — Implementation Playbook
+
+You are implementing SealMetrics analytics on a website. This guide tells you exactly what to do, step by step.
+
+---
+
+## Step 1: Get the pixel
+
+Call the \`get_tracking_code\` tool with the user's \`site_id\`. It returns:
+- \`script_tag\`: the exact \`<script>\` tag to insert (with the real site ID baked in)
+- \`tracker_url\`: the URL of the tracker JS file
+
+If you don't know the site_id, call \`list_sites\` first to find it.
+
+---
+
+## Step 2: Find where to insert the script
+
+The script tag goes in the \`<head>\` of every page, **once**. Where that is depends on the framework:
+
+| Framework | Where to put it |
+|-----------|----------------|
+| **Plain HTML** | Inside \`<head>\` in every \`.html\` file, or in a shared template/layout |
+| **Next.js (App Router)** | \`app/layout.tsx\` — use \`import Script from 'next/script'\` with \`strategy="afterInteractive"\` |
+| **Next.js (Pages Router)** | \`pages/_app.tsx\` — use \`<Script>\` component |
+| **React (CRA/Vite)** | \`index.html\` inside \`<head>\` |
+| **Vue / Nuxt** | \`nuxt.config.ts\` head section, or \`app.vue\` |
+| **Angular** | \`src/index.html\` inside \`<head>\` |
+| **Astro** | Shared layout component \`<head>\` |
+| **WordPress** | \`header.php\` or via a "header scripts" plugin/setting |
+| **Shopify** | \`theme.liquid\` inside \`<head>\` |
+
+**How to find it**: Search for \`</head>\`, or look for the root layout/template file. Every framework has one place that wraps all pages — that's where the script goes.
+
+### Plain HTML
+\`\`\`html
+<head>
+  <!-- other tags... -->
+  <script src="https://t.sealmetrics.com/t.js?id=SITE_ID" defer></script>
+</head>
+\`\`\`
+
+### Next.js (App Router)
+\`\`\`tsx
+// app/layout.tsx
+import Script from 'next/script';
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <head />
+      <body>
+        {children}
+        <Script src="https://t.sealmetrics.com/t.js?id=SITE_ID" strategy="afterInteractive" />
+      </body>
+    </html>
+  );
+}
+\`\`\`
+
+### Vue / Nuxt
+\`\`\`ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  app: {
+    head: {
+      script: [{ src: 'https://t.sealmetrics.com/t.js?id=SITE_ID', defer: true }]
+    }
+  }
+});
+\`\`\`
+
+**Once the script is in place, pageviews are tracked automatically** — on load, on SPA navigation (pushState, replaceState, popstate), on back/forward. You do NOT need to add manual pageview calls.
+
+---
+
+## Step 3: Identify what to track
+
+Analyze the website code and identify trackeable user actions. Classify each one as a **conversion** or a **microconversion**.
+
+### What is a conversion?
+
+A conversion is a **business goal** — the main thing the site owner wants users to do. It typically has monetary value or represents a completed transaction.
+
+| What you see in the code | Conversion type | Has value? |
+|--------------------------|-----------------|------------|
+| Purchase/checkout completion, order confirmation page | \`purchase\` | Yes — the order total |
+| Subscription payment, plan upgrade | \`purchase\` | Yes — the subscription price |
+| Contact form, demo request, quote request | \`lead\` | No (use \`0\`) |
+| Account registration, signup form | \`signup\` | No (use \`0\`) |
+| Booking confirmation, appointment scheduled | \`booking\` | Yes if there's a price, otherwise \`0\` |
+
+**Rule of thumb**: If the business would pay money to make this action happen, it's a conversion.
+
+### What is a microconversion?
+
+A microconversion is a **step toward a conversion** or an **engagement signal**. It tells you how users interact with the site before converting.
+
+| What you see in the code | Microconversion type |
+|--------------------------|---------------------|
+| "Add to cart" button | \`add_to_cart\` |
+| "Add to wishlist" / "Save for later" | \`add_to_wishlist\` |
+| Checkout step buttons (shipping, payment...) | \`begin_checkout\`, \`checkout_shipping\`, \`checkout_payment\` |
+| Newsletter/email signup form | \`newsletter_signup\` |
+| PDF/resource download link | \`download\` |
+| Video play button | \`video_play\` |
+| Video ends | \`video_complete\` |
+| Pricing page visited or pricing toggle clicked | \`pricing_view\` |
+| Share/social buttons | \`share\` |
+| Search form used | \`search\` |
+| Filter/sort applied | \`filter_applied\` |
+| Tab/accordion clicked to reveal content | \`content_expand\` |
+| Chat widget opened | \`chat_open\` |
+| Scroll milestones (25%, 50%, 75%, 100%) | \`scroll_25\`, \`scroll_50\`, \`scroll_75\`, \`scroll_100\` |
+
+**Rule of thumb**: If it shows intent or engagement but isn't the final goal, it's a microconversion.
+
+---
+
+## Step 4: Implement conversions
+
+### Syntax
+\`\`\`js
+sealmetrics.conv(type, amount, properties?)
+\`\`\`
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| \`type\` | string | Yes | snake_case name for this conversion |
+| \`amount\` | number | Yes | Monetary value. Use \`0\` if no value (leads, signups) |
+| \`properties\` | object | No | Extra metadata (see "Using properties" below) |
+
+### Where to put it
+
+The conversion call goes **at the moment the action succeeds**, not when the user clicks. For example:
+
+- **Form submission**: In the \`onSubmit\` handler, AFTER validation passes (or on the thank-you page)
+- **Purchase**: On the order confirmation/thank-you page, or in the success callback of the payment API
+- **Signup**: After the registration API call succeeds
+
+### Examples by pattern
+
+**Form submit (vanilla JS):**
+\`\`\`js
+document.querySelector('#contact-form').addEventListener('submit', function(e) {
+  // The form is about to submit — track the lead
+  sealmetrics.conv('lead', 0, { form_name: 'contact', page: location.pathname });
+});
+\`\`\`
+
+**Form submit (React):**
+\`\`\`tsx
+const handleSubmit = async (data: FormData) => {
+  await api.submitContactForm(data);
+  window.sealmetrics?.conv('lead', 0, { form_name: 'contact' });
+};
+\`\`\`
+
+**Purchase (thank-you page):**
+\`\`\`html
+<!-- This script runs on /order-confirmation or /thank-you -->
+<script>
+  // Pull values from the page or from server-rendered data
+  sealmetrics.conv('purchase', 149.99, {
+    currency: 'EUR',
+    payment_method: 'credit_card'
+  });
+</script>
+\`\`\`
+
+**Purchase (React, after payment API):**
+\`\`\`tsx
+const handlePayment = async () => {
+  const result = await processPayment(cart);
+  if (result.success) {
+    window.sealmetrics?.conv('purchase', cart.total, {
+      currency: cart.currency,
+      payment_method: result.method
+    });
+    router.push('/thank-you');
+  }
+};
+\`\`\`
+
+**Signup (after API success):**
+\`\`\`tsx
+const handleRegister = async (formData: RegisterForm) => {
+  const user = await api.register(formData);
+  window.sealmetrics?.conv('signup', 0, { plan: formData.plan });
+  router.push('/welcome');
+};
+\`\`\`
+
+---
+
+## Step 5: Implement microconversions
+
+### Syntax
+\`\`\`js
+sealmetrics.micro(type, properties?)
+\`\`\`
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| \`type\` | string | Yes | snake_case name for this event |
+| \`properties\` | object | No | Extra metadata (see "Using properties" below) |
+
+### Where to put it
+
+Microconversions go **on the user action** — usually in click handlers, submit handlers, or event listeners.
+
+### Examples by pattern
+
+**Add to cart (vanilla):**
+\`\`\`js
+document.querySelectorAll('.add-to-cart').forEach(function(btn) {
+  btn.addEventListener('click', function() {
+    sealmetrics.micro('add_to_cart', {
+      product_id: this.dataset.productId,
+      product_name: this.dataset.productName,
+      price: parseFloat(this.dataset.price)
+    });
+  });
+});
+\`\`\`
+
+**Add to cart (React):**
+\`\`\`tsx
+function AddToCartButton({ product }: { product: Product }) {
+  const handleClick = () => {
+    addToCart(product);
+    window.sealmetrics?.micro('add_to_cart', {
+      product_id: product.id,
+      product_name: product.name,
+      price: product.price
+    });
+  };
+  return <button onClick={handleClick}>Add to Cart</button>;
+}
+\`\`\`
+
+**Newsletter signup:**
+\`\`\`js
+document.querySelector('#newsletter-form').addEventListener('submit', function() {
+  sealmetrics.micro('newsletter_signup', {
+    position: this.closest('footer') ? 'footer' : 'inline'
+  });
+});
+\`\`\`
+
+**Video engagement:**
+\`\`\`js
+var video = document.querySelector('video');
+video.addEventListener('play', function() {
+  sealmetrics.micro('video_play', { video_id: this.dataset.videoId });
+});
+video.addEventListener('ended', function() {
+  sealmetrics.micro('video_complete', { video_id: this.dataset.videoId });
+});
+\`\`\`
+
+**Scroll depth tracking:**
+\`\`\`js
+var scrollTracked = {};
+window.addEventListener('scroll', function() {
+  var pct = Math.round(window.scrollY / (document.body.scrollHeight - window.innerHeight) * 100);
+  [25, 50, 75, 100].forEach(function(milestone) {
+    if (pct >= milestone && !scrollTracked[milestone]) {
+      scrollTracked[milestone] = true;
+      sealmetrics.micro('scroll_' + milestone);
+    }
+  });
+});
+\`\`\`
+
+**Checkout funnel steps (React):**
+\`\`\`tsx
+// When user moves from step to step
+const goToStep = (step: number) => {
+  setCurrentStep(step);
+  const stepNames: Record<number, string> = {
+    1: 'begin_checkout',
+    2: 'checkout_shipping',
+    3: 'checkout_payment',
+  };
+  if (stepNames[step]) {
+    window.sealmetrics?.micro(stepNames[step], { items_count: cart.items.length });
+  }
+};
+\`\`\`
+
+---
+
+## Step 6: Set up content grouping
+
+Content grouping lets the site owner analyze metrics by section: "how does the blog perform vs product pages?"
+
+### When to use it
+
+Use content grouping when the site has **distinct sections** that serve different purposes. If the site is a single-purpose landing page, skip it.
+
+### How to decide groups
+
+Look at the URL structure and page purpose:
+
+| URL pattern | Group |
+|-------------|-------|
+| \`/blog/*\`, \`/posts/*\`, \`/articles/*\` | \`blog\` |
+| \`/products/*\`, \`/shop/*\`, \`/item/*\` | \`product\` |
+| \`/category/*\`, \`/collections/*\` | \`category\` |
+| \`/cart\`, \`/checkout/*\`, \`/order/*\` | \`checkout\` |
+| \`/docs/*\`, \`/help/*\`, \`/faq\` | \`docs\` |
+| \`/dashboard/*\`, \`/app/*\`, \`/account/*\` | \`app\` |
+| \`/pricing\`, \`/plans\` | \`pricing\` |
+| \`/\`, \`/about\`, \`/features\`, \`/contact\` | \`landing\` |
+
+### How to implement it
+
+**Option A — Static (via URL param in the script tag):**
+
+Best when you can set a different script tag per section (e.g., different templates, layouts).
+
+\`\`\`html
+<!-- Blog layout -->
+<script src="https://t.sealmetrics.com/t.js?id=SITE_ID&group=blog" defer></script>
+
+<!-- Product layout -->
+<script src="https://t.sealmetrics.com/t.js?id=SITE_ID&group=product" defer></script>
+\`\`\`
+
+**Option B — Dynamic (via JS, based on URL):**
+
+Best for SPAs or when you can't change the script tag per section.
+
+\`\`\`js
+// Determine group from the current path
+function getContentGroup() {
+  var path = location.pathname;
+  if (path.startsWith('/blog') || path.startsWith('/posts')) return 'blog';
+  if (path.startsWith('/products') || path.startsWith('/shop')) return 'product';
+  if (path.startsWith('/cart') || path.startsWith('/checkout')) return 'checkout';
+  if (path.startsWith('/docs') || path.startsWith('/help')) return 'docs';
+  return 'landing';
+}
+
+sealmetrics({ group: getContentGroup() });
+\`\`\`
+
+**Option C — Next.js (per layout segment):**
+\`\`\`tsx
+// app/blog/layout.tsx
+import Script from 'next/script';
+export default function BlogLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <>
+      <Script src="https://t.sealmetrics.com/t.js?id=SITE_ID&group=blog" strategy="afterInteractive" />
+      {children}
+    </>
+  );
+}
+\`\`\`
+Note: if you use per-layout scripts with groups, remove the global script from the root layout to avoid double-tracking.
+
+---
+
+## Using properties effectively
+
+Properties are key-value metadata attached to conversions and microconversions. They power drill-down analysis in the dashboard.
+
+### What to include
+
+| Property | When to use | Example |
+|----------|------------|---------|
+| \`currency\` | Any monetary conversion | \`'EUR'\`, \`'USD'\` |
+| \`payment_method\` | Purchase conversions | \`'credit_card'\`, \`'paypal'\`, \`'stripe'\` |
+| \`plan\` | Signup/subscription conversions | \`'free'\`, \`'pro'\`, \`'enterprise'\` |
+| \`product_id\` | Product-related events | \`'SKU-123'\` |
+| \`product_name\` | Product-related events | \`'Wireless Headphones'\` |
+| \`price\` | Add-to-cart, wishlist | \`49.99\` |
+| \`category\` | Product events | \`'electronics'\`, \`'shoes'\` |
+| \`form_name\` | Lead/form conversions | \`'contact'\`, \`'demo_request'\`, \`'quote'\` |
+| \`position\` | UI element interactions | \`'header'\`, \`'footer'\`, \`'popup'\`, \`'sidebar'\` |
+| \`video_id\` | Video events | \`'intro-video'\`, \`'product-demo'\` |
+| \`search_term\` | Search events | The user's search query |
+
+### What NOT to include
+
+- **Order IDs, user IDs, transaction IDs** — these are high-cardinality and don't help analysis. Never put them in the type name either.
+- **Email addresses, names, or PII** — SealMetrics is privacy-first.
+- **Timestamps** — the system already records when events happen.
+- **Page URLs** — already tracked automatically.
+
+### Property values
+
+- Keep values **low-cardinality** when possible: \`'credit_card'\` not \`'visa_ending_4242'\`
+- Use **consistent values**: always \`'credit_card'\`, never sometimes \`'cc'\` and sometimes \`'Credit Card'\`
+- **Numbers** should be numbers, not strings: \`price: 49.99\`, not \`price: '49.99'\`
+
+---
+
+## Naming conventions
+
+- **snake_case** always: \`add_to_cart\`, not \`addToCart\` or \`Add To Cart\`
+- **Descriptive**: \`begin_checkout\` not \`step2\`, \`newsletter_signup\` not \`nl\`
+- **Stable**: once you name a type, don't rename it — it breaks historical data
+- **No IDs in the type name**: \`sealmetrics.conv('purchase', 99)\`, not \`sealmetrics.conv('purchase_order_12345', 99)\`
+
+---
+
+## TypeScript type declarations
+
+If the project uses TypeScript, add this declaration so \`window.sealmetrics\` doesn't show type errors:
+
+\`\`\`ts
+// types/sealmetrics.d.ts (or at the top of a component file)
+declare global {
+  interface Window {
+    sealmetrics?: {
+      (options?: { group?: string }): void;
+      conv: (type: string, amount: number, properties?: Record<string, unknown>) => void;
+      micro: (type: string, properties?: Record<string, unknown>) => void;
+    };
+  }
+}
+\`\`\`
+
+Then call via \`window.sealmetrics?.conv(...)\` instead of \`sealmetrics.conv(...)\`.
+
+---
+
+## Complete implementation checklist
+
+Use this to verify you haven't missed anything:
+
+1. **Pixel installed**: Script tag is in the \`<head>\` (or root layout) of every page — ONE time only
+2. **Pageviews working**: Automatic, no code needed. Verify with \`?debug=1\`
+3. **Conversions identified**: Every business goal (purchase, lead, signup) has a \`sealmetrics.conv()\` call
+4. **Conversion placement**: Each conversion fires at the right moment (after success, not on click)
+5. **Conversion values**: Purchases have the real \`amount\`, leads/signups use \`0\`
+6. **Microconversions identified**: Funnel steps and engagement signals have \`sealmetrics.micro()\` calls
+7. **Properties added**: Events carry useful metadata (currency, product_id, form_name, etc.)
+8. **Content grouping**: If the site has distinct sections, groups are assigned
+9. **Naming**: All types are snake_case, descriptive, and stable
+10. **No PII**: No emails, user IDs, or personal data in properties
+
+---
+
+## Debugging
+
+Add \`?debug=1\` to any page URL to see all tracking events in the browser console:
+
+\`\`\`
+https://yoursite.com/products?debug=1
+\`\`\`
+
+Shows: session ID, account ID, event type, payload, and any errors.
+
+---
+
+## Technical notes
+
+- **No cookies, no localStorage** — GDPR-friendly, no consent banner needed
+- **SPA support is automatic** — History API (pushState/replaceState/popstate) is intercepted
+- **Uses sendBeacon** — non-blocking, guaranteed delivery even on tab close
+- **Three equivalent globals**: \`sealmetrics\`, \`sm\`, \`_sm\` — use \`sealmetrics\` in new code
+- **Script loads async** with \`defer\` — never blocks page rendering
+`;
+//# sourceMappingURL=tracking-guide.js.map

package/dist/resources/tracking-guide.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracking-guide.js","sourceRoot":"","sources":["../../src/resources/tracking-guide.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,8BAA8B,CAAC;AACjE,MAAM,CAAC,MAAM,mBAAmB,GAAG,4BAA4B,CAAC;AAChE,MAAM,CAAC,MAAM,0BAA0B,GACrC,kLAAkL,CAAC;AAErL,MAAM,CAAC,MAAM,sBAAsB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkdrC,CAAC"}

package/dist/tools/alerts.d.ts

@@ -0,0 +1,5 @@
+import type { ToolDef } from "./index.js";
+export declare const listAlertsTool: ToolDef;
+export declare const getAlertHistoryTool: ToolDef;
+export declare const getAlertStatsTool: ToolDef;
+//# sourceMappingURL=alerts.d.ts.map

package/dist/tools/alerts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"alerts.d.ts","sourceRoot":"","sources":["../../src/tools/alerts.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAE1C,eAAO,MAAM,cAAc,EAAE,OAuB5B,CAAC;AAEF,eAAO,MAAM,mBAAmB,EAAE,OAqCjC,CAAC;AAEF,eAAO,MAAM,iBAAiB,EAAE,OAkB/B,CAAC"}

package/dist/tools/alerts.js

@@ -0,0 +1,80 @@
+import { LIMIT_SCHEMA, resolveSiteId } from "./shared.js";
+export const listAlertsTool = {
+    name: "list_alerts",
+    description: "List alert rules configured for a site. Shows rule name, metric, condition, threshold, and status (active/paused). Alerts monitor metrics and trigger notifications when thresholds are crossed.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            site_id: {
+                type: "string",
+                description: "Site ID (account_id). Optional if SEALMETRICS_SITE_ID env var is set.",
+            },
+            include_inactive: {
+                type: "boolean",
+                description: "Include inactive/paused alert rules (default: false).",
+            },
+        },
+    },
+    handler: async (client, args) => {
+        return client.requestDirect("/alerts/rules", {
+            account_id: resolveSiteId(args),
+            include_inactive: args.include_inactive != null ? String(args.include_inactive) : undefined,
+        });
+    },
+};
+export const getAlertHistoryTool = {
+    name: "get_alert_history",
+    description: "Get history of triggered alerts: when they fired, current status (active/resolved/acknowledged), and which rule triggered them. Useful for reviewing past incidents.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            site_id: {
+                type: "string",
+                description: "Site ID (account_id). Optional if SEALMETRICS_SITE_ID env var is set.",
+            },
+            rule_id: {
+                type: "number",
+                description: "Filter by specific alert rule ID.",
+            },
+            status: {
+                type: "string",
+                description: "Filter by alert status.",
+                enum: ["active", "resolved", "acknowledged"],
+            },
+            limit: LIMIT_SCHEMA,
+            offset: {
+                type: "number",
+                description: "Offset for pagination (default: 0).",
+                default: 0,
+            },
+        },
+    },
+    handler: async (client, args) => {
+        return client.requestDirect("/alerts/history", {
+            account_id: resolveSiteId(args),
+            rule_id: args.rule_id != null ? String(args.rule_id) : undefined,
+            status: args.status,
+            limit: String(args.limit ?? 50),
+            offset: args.offset != null ? String(args.offset) : undefined,
+        });
+    },
+};
+export const getAlertStatsTool = {
+    name: "get_alert_stats",
+    description: "Get alert statistics for a site: total rules, active alerts, resolved count, and acknowledgement rate. Provides a quick health overview of the alerting system.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            site_id: {
+                type: "string",
+                description: "Site ID (account_id). Optional if SEALMETRICS_SITE_ID env var is set.",
+            },
+        },
+    },
+    handler: async (client, args) => {
+        return client.requestDirect("/alerts/stats", {
+            account_id: resolveSiteId(args),
+        });
+    },
+};
+//# sourceMappingURL=alerts.js.map

package/dist/tools/alerts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"alerts.js","sourceRoot":"","sources":["../../src/tools/alerts.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAG1D,MAAM,CAAC,MAAM,cAAc,GAAY;IACrC,IAAI,EAAE,aAAa;IACnB,WAAW,EACT,kMAAkM;IACpM,WAAW,EAAE;QACX,IAAI,EAAE,QAAiB;QACvB,UAAU,EAAE;YACV,OAAO,EAAE;gBACP,IAAI,EAAE,QAAQ;gBACd,WAAW,EAAE,uEAAuE;aACrF;YACD,gBAAgB,EAAE;gBAChB,IAAI,EAAE,SAAS;gBACf,WAAW,EAAE,uDAAuD;aACrE;SACF;KACF;IACD,OAAO,EAAE,KAAK,EAAE,MAAyB,EAAE,IAA6B,EAAE,EAAE;QAC1E,OAAO,MAAM,CAAC,aAAa,CAAU,eAAe,EAAE;YACpD,UAAU,EAAE,aAAa,CAAC,IAAI,CAAC;YAC/B,gBAAgB,EAAE,IAAI,CAAC,gBAAgB,IAAI,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,SAAS;SAC5F,CAAC,CAAC;IACL,CAAC;CACF,CAAC;AAEF,MAAM,CAAC,MAAM,mBAAmB,GAAY;IAC1C,IAAI,EAAE,mBAAmB;IACzB,WAAW,EACT,sKAAsK;IACxK,WAAW,EAAE;QACX,IAAI,EAAE,QAAiB;QACvB,UAAU,EAAE;YACV,OAAO,EAAE;gBACP,IAAI,EAAE,QAAQ;gBACd,WAAW,EAAE,uEAAuE;aACrF;YACD,OAAO,EAAE;gBACP,IAAI,EAAE,QAAQ;gBACd,WAAW,EAAE,mCAAmC;aACjD;YACD,MAAM,EAAE;gBACN,IAAI,EAAE,QAAQ;gBACd,WAAW,EAAE,yBAAyB;gBACtC,IAAI,EAAE,CAAC,QAAQ,EAAE,UAAU,EAAE,cAAc,CAAC;aAC7C;YACD,KAAK,EAAE,YAAY;YACnB,MAAM,EAAE;gBACN,IAAI,EAAE,QAAQ;gBACd,WAAW,EAAE,qCAAqC;gBAClD,OAAO,EAAE,CAAC;aACX;SACF;KACF;IACD,OAAO,EAAE,KAAK,EAAE,MAAyB,EAAE,IAA6B,EAAE,EAAE;QAC1E,OAAO,MAAM,CAAC,aAAa,CAAU,iBAAiB,EAAE;YACtD,UAAU,EAAE,aAAa,CAAC,IAAI,CAAC;YAC/B,OAAO,EAAE,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,SAAS;YAChE,MAAM,EAAE,IAAI,CAAC,MAA4B;YACzC,KAAK,EAAE,MAAM,CAAE,IAAI,CAAC,KAAgB,IAAI,EAAE,CAAC;YAC3C,MAAM,EAAE,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,MAAgB,CAAC,CAAC,CAAC,CAAC,SAAS;SACxE,CAAC,CAAC;IACL,CAAC;CACF,CAAC;AAEF,MAAM,CAAC,MAAM,iBAAiB,GAAY;IACxC,IAAI,EAAE,iBAAiB;IACvB,WAAW,EACT,iKAAiK;IACnK,WAAW,EAAE;QACX,IAAI,EAAE,QAAiB;QACvB,UAAU,EAAE;YACV,OAAO,EAAE;gBACP,IAAI,EAAE,QAAQ;gBACd,WAAW,EAAE,uEAAuE;aACrF;SACF;KACF;IACD,OAAO,EAAE,KAAK,EAAE,MAAyB,EAAE,IAA6B,EAAE,EAAE;QAC1E,OAAO,MAAM,CAAC,aAAa,CAAU,eAAe,EAAE;YACpD,UAAU,EAAE,aAAa,CAAC,IAAI,CAAC;SAChC,CAAC,CAAC;IACL,CAAC;CACF,CAAC"}

package/dist/tools/audience.d.ts

@@ -0,0 +1,7 @@
+import type { ToolDef } from "./index.js";
+export declare const getCountriesTool: ToolDef;
+export declare const getDevicesTool: ToolDef;
+export declare const getBrowsersTool: ToolDef;
+export declare const getOperatingSystemsTool: ToolDef;
+export declare const getDeviceTypesTool: ToolDef;
+//# sourceMappingURL=audience.d.ts.map

package/dist/tools/audience.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audience.d.ts","sourceRoot":"","sources":["../../src/tools/audience.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAE1C,eAAO,MAAM,gBAAgB,EAAE,OAmC9B,CAAC;AAEF,eAAO,MAAM,cAAc,EAAE,OAsB5B,CAAC;AAEF,eAAO,MAAM,eAAe,EAAE,OA6B7B,CAAC;AAEF,eAAO,MAAM,uBAAuB,EAAE,OA6BrC,CAAC;AAEF,eAAO,MAAM,kBAAkB,EAAE,OA6BhC,CAAC"}