@stacksjs/ts-analytics 0.1.6

package/src/handlers/views.ts

@@ -0,0 +1,390 @@
+/**
+ * View handlers for HTML pages
+ *
+ * Serves pre-built HTML templates with runtime placeholder replacement.
+ * Falls back to STX processing for local development.
+ */
+
+import { generateTrackingScript, generateMinimalTrackingScript, getConfig } from '../index'
+import { htmlResponse, jsResponse } from '../utils/response'
+import { getQueryParams, getLambdaEvent } from '../../deploy/lambda-adapter'
+import { injectQueryPreservationScript } from '@stacksjs/bun-router'
+import { requireAuth } from './auth'
+import path from 'node:path'
+import fs from 'node:fs'
+
+// Query preservation config for dashboard pages
+const queryPreservationConfig = {
+  enabled: true,
+  preserve: ['siteId'],
+  exclude: ['_t', '_cache', 'callback'],
+  routes: ['/dashboard', '/dashboard/*'],
+}
+
+// Pre-built views directory - check multiple locations in order of priority
+// 1. Lambda deployment: /var/task/views/ (Lambda working directory)
+// 2. Bundled location: views/ relative to this file
+// 3. Development: dist/views/ from project root
+function findViewsDir(): string {
+  const candidates = [
+    '/var/task/views', // Lambda deployment
+    path.resolve(import.meta.dir, './views'), // Relative to bundled file
+    path.resolve(import.meta.dir, '../../dist/views'), // Development
+    path.resolve(process.cwd(), 'views'), // Current working directory
+    path.resolve(process.cwd(), 'dist/views'), // CWD dist
+  ]
+
+  for (const dir of candidates) {
+    try {
+      if (fs.existsSync(path.join(dir, 'dashboard/index.html'))) {
+        return dir
+      }
+    }
+catch {
+      // Continue to next candidate
+    }
+  }
+
+  // Fallback to source views for STX processing
+  return path.resolve(import.meta.dir, '../views')
+}
+
+const PREBUILT_DIR = findViewsDir()
+
+// Source views directory (for development fallback with STX processing)
+const VIEWS_DIR = path.resolve(import.meta.dir, '../views')
+
+// Check if pre-built views exist
+const hasPrebuiltViews = fs.existsSync(path.join(PREBUILT_DIR, 'dashboard/index.html'))
+
+// Placeholder tokens used in pre-built HTML
+const PLACEHOLDERS = {
+  siteId: '{{__SITE_ID__}}',
+  apiEndpoint: '{{__API_ENDPOINT__}}',
+  errorId: '{{__ERROR_ID__}}',
+  section: '{{__SECTION__}}',
+  title: '{{__TITLE__}}',
+  iconPath: '{{__ICON_PATH__}}',
+}
+
+/**
+ * Replace placeholders in pre-built HTML
+ */
+function replacePlaceholders(html: string, values: Record<string, string>): string {
+  let result = html
+  for (const [key, placeholder] of Object.entries(PLACEHOLDERS)) {
+    if (values[key] !== undefined) {
+      result = result.replaceAll(placeholder, values[key])
+    }
+  }
+  return result
+}
+
+/**
+ * Load and process a pre-built view
+ */
+async function loadPrebuiltView(name: string, values: Record<string, string>): Promise<string> {
+  const filePath = path.join(PREBUILT_DIR, `${name}.html`)
+  const html = await Bun.file(filePath).text()
+  return replacePlaceholders(html, values)
+}
+
+/**
+ * Fallback: Render STX template directly (for development)
+ */
+async function renderStxDirect(templateName: string, props: Record<string, unknown> = {}): Promise<string> {
+  // Dynamic import to avoid bundling STX in Lambda
+  const { processDirectives, extractVariables, defaultConfig } = await import('@stacksjs/stx')
+
+  const templatePath = path.join(VIEWS_DIR, templateName)
+  const content = await Bun.file(templatePath).text()
+
+  // Extract script content and template
+  const scriptMatch = content.match(/<script\s+server\s*>([\s\S]*?)<\/script>/i)
+  const scriptContent = scriptMatch ? scriptMatch[1] : ''
+  let templateContent = scriptMatch
+    ? content.replace(/<script\s+server\s*>[\s\S]*?<\/script>/i, '')
+    : content
+
+  // Replace <script client> with regular <script> for output
+  templateContent = templateContent.replace(/<script\s+client\s*>/gi, '<script>')
+
+  // Preserve external <script src> tags from STX validation (re-injected after processing)
+  const externalScripts: string[] = []
+  templateContent = templateContent.replace(/<script\s+([^>]*src\s*=\s*[^>]+)><\/script>/gi, (match) => {
+    externalScripts.push(match)
+    return `<!--STX_EXTERNAL_SCRIPT_${externalScripts.length - 1}-->`
+  })
+
+  // Build context with props
+  const context: Record<string, unknown> = {
+    __filename: templatePath,
+    __dirname: path.dirname(templatePath),
+    props,
+    ...props,
+  }
+
+  // Extract variables from server script
+  if (scriptContent) {
+    await extractVariables(scriptContent, context, templatePath)
+  }
+
+  // Process STX directives
+  const config = {
+    ...defaultConfig,
+    componentsDir: path.resolve(import.meta.dir, '../components'),
+    layoutsDir: path.join(VIEWS_DIR, 'layouts'),
+    partialsDir: path.join(VIEWS_DIR, 'partials'),
+  }
+
+  let result = await processDirectives(templateContent, context, templatePath, config, new Set())
+
+  // Re-inject external script tags
+  for (let i = 0; i < externalScripts.length; i++) {
+    result = result.replace(`<!--STX_EXTERNAL_SCRIPT_${i}-->`, externalScripts[i])
+  }
+
+  return result
+}
+
+/**
+ * GET /dashboard or /
+ */
+export async function handleDashboard(request: Request): Promise<Response> {
+  const authResult = await requireAuth(request)
+  if (authResult instanceof Response) return authResult
+
+  const query = getQueryParams(request)
+  const event = getLambdaEvent(request)
+  const siteId = query.siteId || ''
+  const apiEndpoint = `https://${event?.requestContext?.domainName || 'analytics.stacksjs.com'}`
+
+  let html: string
+  if (hasPrebuiltViews) {
+    html = await loadPrebuiltView('dashboard/index', { siteId, apiEndpoint })
+  }
+else {
+    html = await renderStxDirect('dashboard/index.stx', { siteId, apiEndpoint })
+  }
+
+  // Inject query preservation script for siteId
+  html = injectQueryPreservationScript(html, queryPreservationConfig)
+
+  return htmlResponse(html)
+}
+
+/**
+ * GET /dashboard/{tab} - Serve individual tab pages
+ */
+export async function handleDashboardTab(request: Request, tab: string): Promise<Response> {
+  const authResult = await requireAuth(request)
+  if (authResult instanceof Response) return authResult
+
+  const query = getQueryParams(request)
+  const event = getLambdaEvent(request)
+  const siteId = query.siteId || ''
+  const apiEndpoint = `https://${event?.requestContext?.domainName || 'analytics.stacksjs.com'}`
+
+  // Valid tabs that have their own pages
+  const validTabs = [
+    'errors', 'sessions', 'vitals', 'live', 'funnels', 'flow', 'insights', 'settings',
+    'pages', 'referrers', 'devices', 'browsers', 'countries', 'campaigns', 'events', 'goals'
+  ]
+
+  if (!validTabs.includes(tab)) {
+    // Fallback to main dashboard for unknown tabs
+    return handleDashboard(request)
+  }
+
+  let html: string
+  if (hasPrebuiltViews) {
+    html = await loadPrebuiltView(`dashboard/${tab}`, { siteId, apiEndpoint })
+  }
+else {
+    html = await renderStxDirect(`dashboard/${tab}.stx`, { siteId, apiEndpoint })
+  }
+
+  // Inject query preservation script for siteId
+  html = injectQueryPreservationScript(html, queryPreservationConfig)
+
+  return htmlResponse(html)
+}
+
+/**
+ * GET /test-errors
+ */
+export async function handleTestErrors(request: Request): Promise<Response> {
+  const query = getQueryParams(request)
+  const event = getLambdaEvent(request)
+  const siteId = query.siteId || 'test-site'
+  const apiEndpoint = `https://${event?.requestContext?.domainName || 'analytics.stacksjs.com'}`
+
+  let html: string
+  if (hasPrebuiltViews) {
+    html = await loadPrebuiltView('test-errors', { siteId, apiEndpoint })
+  }
+else {
+    html = await renderStxDirect('test-errors.stx', { siteId, apiEndpoint })
+  }
+
+  return htmlResponse(html)
+}
+
+/**
+ * GET /errors/{errorId}
+ */
+export async function handleErrorDetailPage(request: Request, errorId: string): Promise<Response> {
+  const authResult = await requireAuth(request)
+  if (authResult instanceof Response) return authResult
+
+  const query = getQueryParams(request)
+  const event = getLambdaEvent(request)
+  const siteId = query.siteId || ''
+  const apiEndpoint = `https://${event?.requestContext?.domainName || 'analytics.stacksjs.com'}`
+
+  let html: string
+  if (hasPrebuiltViews) {
+    html = await loadPrebuiltView('error-detail', { errorId, siteId, apiEndpoint })
+  }
+else {
+    html = await renderStxDirect('error-detail.stx', { errorId, siteId, apiEndpoint })
+  }
+
+  // Inject query preservation script for siteId
+  html = injectQueryPreservationScript(html, queryPreservationConfig)
+
+  return htmlResponse(html)
+}
+
+/**
+ * GET /dashboard/{section}
+ */
+export async function handleDetailPage(request: Request, section: string): Promise<Response> {
+  const query = getQueryParams(request)
+  const event = getLambdaEvent(request)
+  const siteId = query.siteId || ''
+  const apiEndpoint = `https://${event?.requestContext?.domainName || 'analytics.stacksjs.com'}`
+
+  const titles: Record<string, string> = {
+    pages: 'Pages',
+    referrers: 'Referrers',
+    devices: 'Devices',
+    browsers: 'Browsers',
+    countries: 'Countries',
+    campaigns: 'Campaigns',
+    events: 'Events',
+    goals: 'Goals',
+  }
+
+  const icons: Record<string, string> = {
+    pages: '<path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M9 12h6m-6 4h6m2 5H7a2 2 0 01-2-2V5a2 2 0 012-2h5.586a1 1 0 01.707.293l5.414 5.414a1 1 0 01.293.707V19a2 2 0 01-2 2z"/>',
+    referrers: '<path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M13.828 10.172a4 4 0 00-5.656 0l-4 4a4 4 0 105.656 5.656l1.102-1.101m-.758-4.899a4 4 0 005.656 0l4-4a4 4 0 00-5.656-5.656l-1.1 1.1"/>',
+    devices: '<path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M9.75 17L9 20l-1 1h8l-1-1-.75-3M3 13h18M5 17h14a2 2 0 002-2V5a2 2 0 00-2-2H5a2 2 0 00-2 2v10a2 2 0 002 2z"/>',
+    browsers: '<path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M21 12a9 9 0 01-9 9m9-9a9 9 0 00-9-9m9 9H3m9 9a9 9 0 01-9-9m9 9c1.657 0 3-4.03 3-9s-1.343-9-3-9m0 18c-1.657 0-3-4.03-3-9s1.343-9 3-9m-9 9a9 9 0 019-9"/>',
+    countries: '<path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M3.055 11H5a2 2 0 012 2v1a2 2 0 002 2 2 2 0 012 2v2.945M8 3.935V5.5A2.5 2.5 0 0010.5 8h.5a2 2 0 012 2 2 2 0 104 0 2 2 0 012-2h1.064M15 20.488V18a2 2 0 012-2h3.064M21 12a9 9 0 11-18 0 9 9 0 0118 0z"/>',
+    campaigns: '<path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M11 5.882V19.24a1.76 1.76 0 01-3.417.592l-2.147-6.15M18 13a3 3 0 100-6M5.436 13.683A4.001 4.001 0 017 6h1.832c4.1 0 7.625-1.234 9.168-3v14c-1.543-1.766-5.067-3-9.168-3H7a3.988 3.988 0 01-1.564-.317z"/>',
+    events: '<path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M15 15l-2 5L9 9l11 4-5 2zm0 0l5 5M7.188 2.239l.777 2.897M5.136 7.965l-2.898-.777M13.95 4.05l-2.122 2.122m-5.657 5.656l-2.12 2.122"/>',
+    goals: '<path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M9 12l2 2 4-4m5.618-4.016A11.955 11.955 0 0112 2.944a11.955 11.955 0 01-8.618 3.04A12.02 12.02 0 003 9c0 5.591 3.824 10.29 9 11.622 5.176-1.332 9-6.03 9-11.622 0-1.042-.133-2.052-.382-3.016z"/>',
+  }
+
+  const title = titles[section] || section
+  const iconPath = icons[section] || icons.pages
+
+  let html: string
+  if (hasPrebuiltViews) {
+    html = await loadPrebuiltView('detail', { section, siteId, apiEndpoint, title, iconPath })
+  }
+else {
+    html = await renderStxDirect('detail.stx', { section, siteId, apiEndpoint, title, iconPath })
+  }
+
+  // Inject query preservation script for siteId
+  html = injectQueryPreservationScript(html, queryPreservationConfig)
+
+  return htmlResponse(html)
+}
+
+/**
+ * GET /sites/{siteId}/script
+ */
+export async function handleScript(request: Request): Promise<Response> {
+  const query = getQueryParams(request)
+  const event = getLambdaEvent(request)
+  const minimal = query.minimal === 'true'
+  const url = new URL(request.url)
+
+  // Where /collect lives: explicit ?api= override, else the deployed domain
+  // (Lambda), else the request origin (covers local dev + self-hosted).
+  const apiEndpoint = query.api
+    || (event?.requestContext?.domainName ? `https://${event.requestContext.domainName}` : url.origin)
+
+  // Extract siteId from path
+  const pathMatch = url.pathname.match(/\/sites\/([^/]+)\/script/)
+  const siteId = pathMatch?.[1] || 'unknown'
+
+  // Embed the project's ingest-only error key so captured errors go to the keyed
+  // /errors/collect (Sentry-style), not the public /collect.
+
+  // ?stealth=true → beacons go to the shorter /t path instead of /collect,
+  // which generic blocklists target. Pair with a first-party proxy (#85).
+  const stealthMode = query.stealth === 'true'
+
+  // Honor the configured DNT/GPC opt-out (defaults on) — the served scripts
+  // previously dropped this, so the privacy promise wasn't kept (#142).
+  const honorDnt = getConfig().privacy.honorDnt
+  let script = minimal
+    ? generateMinimalTrackingScript({ siteId, apiEndpoint, honorDnt })
+    : generateTrackingScript({ siteId, apiEndpoint, honorDnt, trackLinkClicks: true, trackSpaRoutes: true, trackEngagement: true, stealthMode })
+
+  // Raw-JS variant (for the `<script src=".../script.js">` one-liner): strip the
+  // HTML comment + <script> wrapper so the response is loadable JavaScript. The
+  // IIFE derives site/api from its own src URL, so no data-* attributes are needed.
+  const raw = url.pathname.endsWith('.js') || query.format === 'js' || query.raw === 'true'
+  if (raw) {
+    script = script
+      .replace(/^<!--[\s\S]*?-->\s*/, '')
+      .replace(/^<script[^>]*>\s*/, '')
+      .replace(/\s*<\/script>\s*$/, '')
+  }
+
+  return jsResponse(script, {}, request)
+}
+
+/**
+ * GET /script.js — the shared, cacheable analytics tracker (Fathom/Plausible
+ * style). One file for every site: the site is identified at runtime by the
+ * tag's `data-site` attribute and the collect endpoint is the script's own
+ * origin (the IIFE reads `currentScript.dataset.site` / `.src`). No per-site
+ * key is baked in, so it stays cacheable across sites; uncaught errors fall
+ * back to the public /collect as `error` events. For Sentry-style error
+ * tracking with a private DSN, use /sdk.js + the project's DSN instead.
+ *
+ *   <script defer data-site="SITE_ID" src="https://your-host/script.js"></script>
+ */
+export function handleSharedScript(request: Request): Response {
+  const query = getQueryParams(request)
+  const event = getLambdaEvent(request)
+  const url = new URL(request.url)
+
+  const apiEndpoint = query.api
+    || (event?.requestContext?.domainName ? `https://${event.requestContext.domainName}` : url.origin)
+  const stealthMode = query.stealth === 'true'
+
+  // No siteId / ingest key baked in — both are resolved from the visitor's tag
+  // at runtime, which is what keeps this one script shared and cacheable.
+  const script = generateTrackingScript({
+    siteId: '',
+    apiEndpoint,
+    honorDnt: getConfig().privacy.honorDnt,
+    trackLinkClicks: true,
+    trackSpaRoutes: true,
+    trackEngagement: true,
+    stealthMode,
+  })
+    .replace(/^<!--[\s\S]*?-->\s*/, '')
+    .replace(/^<script[^>]*>\s*/, '')
+    .replace(/\s*<\/script>\s*$/, '')
+
+  return jsResponse(script, {}, request)
+}
+

package/src/handlers/webhooks.ts

@@ -0,0 +1,226 @@
+/**
+ * Webhook handlers
+ */
+
+import { createHmac } from 'node:crypto'
+import { generateId } from '../index'
+import { dynamodb, TABLE_NAME, unmarshall, marshall } from '../lib/dynamodb'
+import { jsonResponse, errorResponse } from '../utils/response'
+import { getQueryParams } from '../../deploy/lambda-adapter'
+
+/**
+ * POST /api/sites/{siteId}/webhooks
+ */
+export async function handleCreateWebhook(request: Request, siteId: string): Promise<Response> {
+  try {
+    const body = await request.json() as Record<string, any>
+
+    if (!body.url || !body.events || !Array.isArray(body.events) || body.events.length === 0) {
+      return jsonResponse({ error: 'Missing required fields: url, events (array)' }, 400)
+    }
+
+    const validEvents = ['pageview', 'session.start', 'session.end', 'goal.conversion', 'error', 'alert.triggered']
+    const invalidEvents = body.events.filter((e: string) => !validEvents.includes(e))
+    if (invalidEvents.length > 0) {
+      return jsonResponse({ error: `Invalid events: ${invalidEvents.join(', ')}. Valid events: ${validEvents.join(', ')}` }, 400)
+    }
+
+    const webhookId = generateId()
+    const webhook = {
+      pk: `SITE#${siteId}`,
+      sk: `WEBHOOK#${webhookId}`,
+      id: webhookId,
+      siteId,
+      url: body.url,
+      events: body.events,
+      secret: body.secret || generateId(),
+      headers: body.headers || {},
+      isActive: body.isActive ?? true,
+      lastTriggered: null,
+      failureCount: 0,
+      createdAt: new Date().toISOString(),
+    }
+
+    await dynamodb.putItem({
+      TableName: TABLE_NAME,
+      Item: marshall(webhook),
+    })
+
+    return jsonResponse({ webhook }, 201)
+  }
+catch (error) {
+    console.error('Create webhook error:', error)
+    return errorResponse('Failed to create webhook')
+  }
+}
+
+/**
+ * GET /api/sites/{siteId}/webhooks
+ */
+export async function handleGetWebhooks(_request: Request, siteId: string): Promise<Response> {
+  try {
+    const result = await dynamodb.query({
+      TableName: TABLE_NAME,
+      KeyConditionExpression: 'pk = :pk AND begins_with(sk, :prefix)',
+      ExpressionAttributeValues: {
+        ':pk': { S: `SITE#${siteId}` },
+        ':prefix': { S: 'WEBHOOK#' },
+      },
+    }) as { Items?: any[] }
+
+    const webhooks = (result.Items || []).map(unmarshall).map(w => ({
+      id: w.id,
+      url: w.url,
+      events: w.events,
+      isActive: w.isActive,
+      lastTriggered: w.lastTriggered,
+      failureCount: w.failureCount,
+      createdAt: w.createdAt,
+    }))
+
+    return jsonResponse({ webhooks })
+  }
+catch (error) {
+    console.error('Get webhooks error:', error)
+    return errorResponse('Failed to fetch webhooks')
+  }
+}
+
+/**
+ * DELETE /api/sites/{siteId}/webhooks/{webhookId}
+ */
+export async function handleDeleteWebhook(_request: Request, siteId: string, webhookId: string): Promise<Response> {
+  try {
+    await dynamodb.deleteItem({
+      TableName: TABLE_NAME,
+      Key: marshall({
+        pk: `SITE#${siteId}`,
+        sk: `WEBHOOK#${webhookId}`,
+      }),
+    })
+
+    return jsonResponse({ success: true })
+  }
+catch (error) {
+    console.error('Delete webhook error:', error)
+    return errorResponse('Failed to delete webhook')
+  }
+}
+
+// ── Webhook delivery (#92) ─────────────────────────────────────────────────
+// Events are enqueued to a WEBHOOK_QUEUE partition (sk = nextAttemptIso#id) and
+// drained by a scheduled job: each delivery is a signed POST (HMAC-SHA256),
+// retried with backoff up to MAX_WEBHOOK_ATTEMPTS, then dropped (failureCount++).
+const MAX_WEBHOOK_ATTEMPTS = 5
+const BACKOFF_MS = [0, 60_000, 5 * 60_000, 30 * 60_000, 2 * 60 * 60_000]
+
+/** Enqueue an event for every active webhook on the site subscribed to it. */
+export async function enqueueWebhookEvent(siteId: string, eventType: string, payload: Record<string, unknown>): Promise<number> {
+  const subs = await dynamodb.query({
+    TableName: TABLE_NAME,
+    KeyConditionExpression: 'pk = :pk AND begins_with(sk, :p)',
+    ExpressionAttributeValues: { ':pk': { S: `SITE#${siteId}` }, ':p': { S: 'WEBHOOK#' } },
+  }) as { Items?: any[] }
+
+  const now = Date.now()
+  const nowIso = new Date(now).toISOString()
+  let queued = 0
+  for (const raw of (subs.Items || [])) {
+    const wh = unmarshall(raw)
+    if (wh.isActive === false)
+      continue
+    const events: string[] = wh.events || []
+    if (!events.includes('*') && !events.includes(eventType))
+      continue
+    const id = generateId()
+    await dynamodb.putItem({
+      TableName: TABLE_NAME,
+      Item: marshall({
+        pk: 'WEBHOOK_QUEUE', sk: `${nowIso}#${id}`, id, siteId, webhookId: wh.id, url: wh.url,
+        secret: wh.secret, headers: wh.headers || {}, eventType, payload: JSON.stringify(payload),
+        attempts: 0, createdAt: nowIso, ttl: Math.floor(now / 1000) + 3 * 24 * 60 * 60,
+      }),
+    })
+    queued++
+  }
+  return queued
+}
+
+async function deliverOne(d: any): Promise<boolean> {
+  try {
+    let body: string = d.payload || '{}'
+    // Native Slack incoming-webhooks (#129): Slack requires {text: ...} and
+    // rejects arbitrary JSON — reshape the event into a readable message so
+    // pointing a webhook at hooks.slack.com just works.
+    if (/hooks\.slack\.com\//.test(String(d.url || ''))) {
+      try {
+        const evt = JSON.parse(body)
+        const fields = Object.entries(evt)
+          .filter(([k]) => !['event', 'siteId'].includes(k))
+          .map(([k, v]) => `${k}: ${typeof v === 'object' ? JSON.stringify(v) : v}`)
+          .join('\n')
+        body = JSON.stringify({ text: `*${d.eventType || evt.event || 'analytics event'}* — ${evt.siteId || ''}\n${fields}` })
+      }
+      catch {}
+    }
+    const sig = createHmac('sha256', String(d.secret || '')).update(body).digest('hex')
+    const res = await fetch(d.url, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', 'X-Webhook-Event': d.eventType || '', 'X-Webhook-Signature': `sha256=${sig}`, ...(d.headers || {}) },
+      body,
+      signal: AbortSignal.timeout(10_000),
+    })
+    return res.status >= 200 && res.status < 300
+  }
+catch {
+    return false
+  }
+}
+
+async function updateWebhook(siteId: string, webhookId: string, expr: string, values: Record<string, any>): Promise<void> {
+  try {
+    await dynamodb.updateItem({
+      TableName: TABLE_NAME,
+      Key: { pk: { S: `SITE#${siteId}` }, sk: { S: `WEBHOOK#${webhookId}` } },
+      UpdateExpression: expr,
+      ExpressionAttributeValues: values,
+    })
+  }
+catch (e) {
+    console.error('Webhook update failed:', (e as Error).message)
+  }
+}
+
+/** Drain due webhook deliveries (scheduled job, #92/#90). Returns count processed. */
+export async function processWebhookDeliveries(): Promise<number> {
+  const nowIso = new Date().toISOString()
+  const due = await dynamodb.query({
+    TableName: TABLE_NAME,
+    KeyConditionExpression: 'pk = :pk AND sk <= :now',
+    ExpressionAttributeValues: { ':pk': { S: 'WEBHOOK_QUEUE' }, ':now': { S: nowIso } },
+    Limit: 100,
+  }) as { Items?: any[] }
+
+  let processed = 0
+  for (const raw of (due.Items || [])) {
+    const d = unmarshall(raw)
+    const ok = await deliverOne(d)
+    await dynamodb.deleteItem({ TableName: TABLE_NAME, Key: { pk: { S: 'WEBHOOK_QUEUE' }, sk: { S: d.sk } } })
+
+    if (ok) {
+      await updateWebhook(d.siteId, d.webhookId, 'SET lastTriggered = :now', { ':now': { S: nowIso } })
+    }
+    else {
+      const attempts = (d.attempts || 0) + 1
+      if (attempts < MAX_WEBHOOK_ATTEMPTS) {
+        const next = Date.now() + (BACKOFF_MS[attempts] || 2 * 60 * 60_000)
+        await dynamodb.putItem({ TableName: TABLE_NAME, Item: marshall({ ...d, sk: `${new Date(next).toISOString()}#${d.id}`, attempts }) })
+      }
+      else {
+        await updateWebhook(d.siteId, d.webhookId, 'ADD failureCount :one', { ':one': { N: '1' } })
+      }
+    }
+    processed++
+  }
+  return processed
+}

package/src/heatmap/index.ts

@@ -0,0 +1,32 @@
+/**
+ * Heatmap Tracking Module
+ *
+ * Provides client-side tracking for click heatmaps, movement heatmaps,
+ * and scroll depth visualization.
+ *
+ * @example
+ * ```typescript
+ * import { generateHeatmapScript, buildHeatmapTracking } from './heatmap'
+ *
+ * // Generate a standalone heatmap script
+ * const script = generateHeatmapScript('my-site', 'https://api.example.com', {
+ *   trackClicks: true,
+ *   trackMovements: true,
+ *   trackScrollPositions: true,
+ * })
+ *
+ * // Or build just the tracking code to integrate with main script
+ * const trackingCode = buildHeatmapTracking({
+ *   trackClicks: true,
+ *   trackMovements: true,
+ * })
+ * ```
+ */
+
+export { buildHeatmapTracking, generateHeatmapScript } from './tracking-script'
+export type {
+  HeatmapConfig,
+  HeatmapClickEvent,
+  HeatmapMovementBatch,
+  HeatmapScrollData,
+} from './types'