@stacksjs/ts-analytics 0.1.6

package/src/integrations/runtime/use-ts-analytics.ts

@@ -0,0 +1,32 @@
+/**
+ * `useTsAnalytics()` — custom event tracking for the ts-analytics Nuxt module.
+ *
+ * The injected tracker exposes a Fathom-API-compatible global
+ * (`window.fathom.track(name, value)`); this composable wraps it with an
+ * SSR-safe no-op on the server. Auto-imported by `@stacksjs/ts-analytics/nuxt`.
+ *
+ * ```ts
+ * const { track } = useTsAnalytics()
+ * track('signup')
+ * track('purchase', 4200) // optional numeric value (e.g. cents)
+ * track('signup', 0, { plan: 'pro' }) // custom properties
+ * ```
+ */
+export interface TsAnalyticsApi {
+  /** Track a custom event by name, with an optional numeric value and
+   * custom properties (Plausible-style) that appear under Event Properties. */
+  track: (name: string, value?: number, props?: Record<string, string | number | boolean>) => void
+}
+
+export function useTsAnalytics(): TsAnalyticsApi {
+  return {
+    track(name: string, value?: number, props?: Record<string, string | number | boolean>): void {
+      if (typeof window === 'undefined')
+        return // SSR: the tracker only exists in the browser
+      const tracker = (window as unknown as {
+        fathom?: { track?: (name: string, value?: number, props?: Record<string, string | number | boolean>) => void }
+      }).fathom
+      tracker?.track?.(name, value, props)
+    },
+  }
+}

package/src/integrations/stx.ts

@@ -0,0 +1,138 @@
+/**
+ * stx / Stacks Config Integration
+ *
+ * Add ts-analytics to a stx (or Stacks) app the way you'd add a Nuxt analytics
+ * module — from the config file, keyed by an **App ID**.
+ *
+ * ts-analytics serves one shared, cacheable tracker at `<apiEndpoint>/script.js`
+ * (Fathom/Plausible-style). The tracker reads its App ID from the `data-site`
+ * attribute and derives the collector endpoint from its own `src` origin, so
+ * the only thing a host app supplies is the App ID + the API origin.
+ *
+ * Spread the result into your stx config's `app.head.script`:
+ *
+ * ```ts
+ * // config/stx.ts (Stacks)  — or  stx.config.ts
+ * import { tsAnalytics } from '@stacksjs/ts-analytics/stx'
+ *
+ * export default {
+ *   app: {
+ *     head: {
+ *       script: [
+ *         ...tsAnalytics({ appId: 'my-app' }),   // endpoint is baked in
+ *       ],
+ *     },
+ *   },
+ * }
+ * ```
+ *
+ * **Why a head helper and not a `plugins: [...]` entry?** stx's plugin render
+ * lifecycle hooks (`afterRender`) are not invoked by the dev/serve render
+ * pipeline, and a plugin's `setup()` config mutation does not propagate to
+ * rendering. The head config *is* read on every render, so this is the reliable
+ * mechanism — and it mirrors what framework analytics modules do internally
+ * (push a tag onto the document head).
+ */
+
+/**
+ * Generate a short, unguessable App ID (Fathom-style `data-site`, 8 chars). Run
+ * once per site and paste the result into your config — the backend
+ * auto-provisions the site on its first event, so nothing else is needed.
+ *
+ * ```ts
+ * import { generateAppId } from '@stacksjs/ts-analytics/stx'
+ * console.log(generateAppId()) // e.g. 'K7MN4PQR'
+ * ```
+ */
+export { generateAppId } from '../lib/crypto-random'
+
+/**
+ * Default ts-analytics API origin — where `/script.js` is served and events are
+ * collected. Baked in (Fathom-style) so host apps supply *only* an App ID.
+ *
+ * Endpoint resolution order: an explicit `apiEndpoint` option → the
+ * `TS_ANALYTICS_ENDPOINT` env var → this constant. Set this to your production
+ * ts-analytics host so deployed apps need zero endpoint config.
+ */
+export const DEFAULT_API_ENDPOINT = 'http://localhost:2027'
+
+/** Resolve the API origin from an explicit override, env, then the default. */
+export function resolveApiEndpoint(explicit?: string): string {
+  const raw = (explicit ?? process.env.TS_ANALYTICS_ENDPOINT ?? DEFAULT_API_ENDPOINT).trim()
+  return raw.replace(/\/+$/, '')
+}
+
+/** A stx head `<script>` entry — an item of the config `app.head.script` array. */
+export interface StxHeadScript {
+  src?: string
+  content?: string
+  defer?: boolean
+  async?: boolean
+  type?: string
+  /** Arbitrary attributes (e.g. `data-site`) are rendered verbatim. */
+  [attr: string]: unknown
+}
+
+export interface TsAnalyticsOptions {
+  /**
+   * Your ts-analytics **App ID** — rendered as the tracker's `data-site`. A long,
+   * unguessable random string (see {@link generateAppId}); the backend
+   * auto-provisions the site on its first event, so no pre-registration needed.
+   */
+  appId: string
+  /**
+   * Origin of your ts-analytics API — where `/script.js` is served and where the
+   * tracker POSTs. **Optional**: defaults to the `TS_ANALYTICS_ENDPOINT` env var,
+   * then {@link DEFAULT_API_ENDPOINT}. Set this only for a one-off override — the
+   * point is that host apps supply *just* an App ID (Fathom-style). Trailing
+   * slashes are trimmed.
+   */
+  apiEndpoint?: string
+  /** Path of the shared tracker script. Default `'/script.js'`. */
+  scriptPath?: string
+  /** Load the tracker in stealth mode (appends `?stealth=true`). Default false. */
+  stealth?: boolean
+}
+
+/**
+ * Build the ts-analytics head `<script>` entry for a stx/Stacks app config.
+ *
+ * Returns an **array** (so it spreads cleanly into `app.head.script` and can
+ * grow later — e.g. an error-tracking tag — without changing call sites).
+ * Returns `[]` when `appId`/`apiEndpoint` are missing, so a half-configured
+ * environment never injects a broken tag.
+ */
+export function tsAnalytics(options: TsAnalyticsOptions): StxHeadScript[] {
+  const appId = options?.appId?.trim()
+  if (!appId)
+    return []
+
+  const origin = resolveApiEndpoint(options?.apiEndpoint)
+  if (!origin)
+    return []
+  const rawPath = options.scriptPath ?? '/script.js'
+  const path = rawPath.startsWith('/') ? rawPath : `/${rawPath}`
+  const src = `${origin}${path}${options.stealth ? '?stealth=true' : ''}`
+
+  return [
+    {
+      src,
+      defer: true,
+      'data-site': appId,
+    },
+  ]
+}
+
+/**
+ * Raw `<script>` tag string for non-stx contexts — paste into a plain HTML
+ * `<head>`, or inject server-side. Same inputs as {@link tsAnalytics}. Returns
+ * `''` when required options are missing.
+ */
+export function tsAnalyticsTag(options: TsAnalyticsOptions): string {
+  const [entry] = tsAnalytics(options)
+  if (!entry)
+    return ''
+  return `<script defer data-site="${String(entry['data-site'])}" src="${String(entry.src)}"></script>`
+}
+
+export default tsAnalytics

package/src/jobs/index.ts

@@ -0,0 +1,127 @@
+/**
+ * Job registration bootstrap.
+ *
+ * Called once at startup to register every periodic job with the scheduler.
+ * Feature jobs (error alerts #80, uptime checks #91, webhook delivery #92,
+ * email digests #93) register here.
+ */
+import { registerJob } from '../lib/scheduler'
+import { runUptimeChecks } from '../handlers/uptime'
+import { sendDueEmailDigests } from '../handlers/alerts'
+import { processWebhookDeliveries } from '../handlers/webhooks'
+import { runDailyRollups } from '../lib/rollups'
+
+let bootstrapped = false
+
+export function bootstrapJobs(): void {
+  if (bootstrapped)
+    return
+  bootstrapped = true
+
+  // Heartbeat — proves the runtime ticks + persists last-run end to end.
+  registerJob({
+    name: 'heartbeat',
+    intervalMs: 60_000,
+    run: async () => {
+      console.log(`[jobs] heartbeat ${new Date().toISOString()}`)
+    },
+  })
+
+  // Ingest-drop watchdog (#175): a site whose collected-beacon count falls
+  // off a cliff day-over-day is silently broken (CORS, firewall misconfig,
+  // removed snippet) — exactly the failure mode that shipped twice unnoticed.
+  registerJob({
+    name: 'ingest-drop-watch',
+    intervalMs: 60 * 60_000,
+    run: async () => {
+      const { queryAllItems, unmarshall, dynamodb, TABLE_NAME } = await import('../lib/dynamodb')
+      const { log } = await import('../lib/log')
+      const sitesRes = await dynamodb.query({
+        TableName: TABLE_NAME,
+        KeyConditionExpression: 'pk = :pk',
+        ExpressionAttributeValues: { ':pk': { S: 'SITES' } },
+      }) as { Items?: any[] }
+      const now = Date.now()
+      const hourIso = (ms: number): string => new Date(ms).toISOString().slice(0, 13)
+      for (const raw of (sitesRes.Items || [])) {
+        const site = unmarshall(raw)
+        const siteId = site.id || site.siteId
+        if (!siteId)
+          continue
+        const res = await queryAllItems({
+          TableName: TABLE_NAME,
+          KeyConditionExpression: 'pk = :pk AND sk BETWEEN :start AND :end',
+          ExpressionAttributeValues: {
+            ':pk': { S: `SITE#${siteId}` },
+            ':start': { S: `INGEST#${hourIso(now - 48 * 3600_000)}` },
+            ':end': { S: `INGEST#${hourIso(now)}~` },
+          },
+        })
+        let recent = 0
+        let previous = 0
+        for (const item of (res.Items || []).map(unmarshall)) {
+          const hour = String(item.sk).slice('INGEST#'.length)
+          const n = Number(item.collected || 0)
+          if (hour >= hourIso(now - 24 * 3600_000))
+            recent += n
+          else previous += n
+        }
+        // Alert only with a meaningful baseline; 70%+ drop is a cliff.
+        if (previous >= 100 && recent < previous * 0.3) {
+          log.error('ingest.drop_detected', { siteId, previous24h: previous, recent24h: recent })
+        }
+      }
+    },
+  })
+
+  // Uptime checks — probe each due monitor's URL and record up/down + latency,
+  // notifying on a down transition (#91). Runs every minute; each monitor is
+  // probed on its own configured interval.
+  registerJob({
+    name: 'uptime-checks',
+    intervalMs: 60_000,
+    run: async () => {
+      const n = await runUptimeChecks()
+      if (n > 0)
+        console.log(`[jobs] uptime-checks: probed ${n} monitor(s)`)
+    },
+  })
+
+  // Email digests — send each email-report on its schedule (daily/weekly/
+  // monthly) with the period's pageview summary (#93). Checked hourly; the
+  // per-report schedule gates the actual send.
+  registerJob({
+    name: 'email-digests',
+    intervalMs: 60 * 60_000,
+    run: async () => {
+      const n = await sendDueEmailDigests()
+      if (n > 0)
+        console.log(`[jobs] email-digests: sent ${n} report(s)`)
+    },
+  })
+
+  // Webhook delivery — drain the queue, POST each event (HMAC-signed) with
+  // retry/backoff (#92).
+  registerJob({
+    name: 'webhook-delivery',
+    intervalMs: 60_000,
+    run: async () => {
+      const n = await processWebhookDeliveries()
+      if (n > 0)
+        console.log(`[jobs] webhook-delivery: processed ${n} delivery(s)`)
+    },
+  })
+
+  // Daily rollups — pre-aggregate each site's complete days so /stats and
+  // /timeseries read O(buckets) instead of re-scanning raw events (#94).
+  // Hourly cadence: idempotent, so most runs are no-ops once days are covered.
+  registerJob({
+    name: 'daily-rollups',
+    intervalMs: 60 * 60_000,
+    run: async () => {
+      const n = await runDailyRollups()
+      if (n > 0)
+        console.log(`[jobs] daily-rollups: wrote ${n} day rollup(s)`)
+    },
+  })
+}

package/src/lib/crypto-random.ts

@@ -0,0 +1,41 @@
+/**
+ * Cryptographically-secure random tokens.
+ *
+ * `Math.random()` is not a CSPRNG — its output is predictable, so anything that
+ * must be unguessable (API keys, share tokens, ids used as capabilities) has to
+ * come from `crypto.getRandomValues()`. Rejection sampling avoids the modulo
+ * bias you'd get from `byte % charset.length`. (#130)
+ */
+const DEFAULT_CHARS = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789'
+
+/** A random string of `length` chars drawn uniformly from `chars`. */
+export function randomToken(length: number, chars: string = DEFAULT_CHARS): string {
+  if (length <= 0)
+    return ''
+  // Largest multiple of charset length that fits in a byte; reject above it so
+  // every character is equally likely.
+  const limit = Math.floor(256 / chars.length) * chars.length
+  let out = ''
+  const buf = new Uint8Array(length * 2)
+  while (out.length < length) {
+    crypto.getRandomValues(buf)
+    for (let i = 0; i < buf.length && out.length < length; i++) {
+      if (buf[i] < limit)
+        out += chars[buf[i] % chars.length]
+    }
+  }
+  return out
+}
+
+/**
+ * Site / App IDs — short, unambiguous, Fathom-style (`WOLZMJDL`). Uppercase +
+ * digits with the ambiguous chars (0/O/1/I) removed, so an id is easy to eyeball
+ * in DynamoDB and logs. 8 chars over a 32-char alphabet ≈ 1e12 combinations —
+ * plenty of headroom for site ids while staying short.
+ */
+const APP_ID_CHARS = 'ABCDEFGHJKLMNPQRSTUVWXYZ23456789'
+
+/** A short, random, unguessable App ID (default 8 chars). */
+export function generateAppId(length: number = 8): string {
+  return randomToken(length, APP_ID_CHARS)
+}

package/src/lib/ddb-errors.ts

@@ -0,0 +1,20 @@
+/**
+ * DynamoDB error classification. Lives in its own dependency-free module so
+ * both src/lib/dynamodb and the ORM can import it without creating a circular
+ * import (the ORM must never import lib/dynamodb — lib/dynamodb imports the
+ * ORM, and the cycle trips a TDZ depending on entry order, #177).
+ */
+
+/**
+ * Whether an error is a DynamoDB conditional-check failure. Matches BOTH the
+ * AWS SDK shape (name === 'ConditionalCheckFailedException') and the ts-cloud
+ * client's wrapping (generic Error whose message contains the DynamoDB
+ * error text "The conditional request failed").
+ */
+export function isConditionalCheckFailed(e: unknown): boolean {
+  const err = e as { name?: string, message?: string } | null
+  return !!err && (
+    String(err.name || '').includes('ConditionalCheckFailed')
+    || /conditional request failed/i.test(String(err.message || err))
+  )
+}

package/src/lib/dynamodb.ts

@@ -0,0 +1,216 @@
+/**
+ * DynamoDB client configuration and utilities
+ */
+
+import {
+  configureAnalytics,
+  createClient,
+  marshall,
+  unmarshall,
+} from '../../src/models/orm'
+
+// Configuration
+export const TABLE_NAME: string = process.env.ANALYTICS_TABLE_NAME || 'ts-analytics'
+export const REGION: string = process.env.AWS_REGION || 'us-east-1'
+/**
+ * Optional endpoint override (#177): point every DynamoDB client at a local
+ * instance (DynamoDB Local, or the in-process fake the test harness starts)
+ * instead of AWS. Unset in production.
+ */
+export const DYNAMODB_ENDPOINT: string | undefined = process.env.ANALYTICS_DYNAMODB_ENDPOINT || undefined
+
+// Configure analytics models on module load
+configureAnalytics({
+  tableName: TABLE_NAME,
+  region: REGION,
+  ...(DYNAMODB_ENDPOINT ? { endpoint: DYNAMODB_ENDPOINT } : {}),
+})
+
+// Create native DynamoDB client for direct queries (used in dashboard handlers)
+export const dynamodb: ReturnType<typeof createClient> = createClient({ region: REGION, ...(DYNAMODB_ENDPOINT ? { endpoint: DYNAMODB_ENDPOINT } : {}) })
+
+// Re-export marshalling utilities
+export { marshall, unmarshall }
+
+/**
+ * Whether an error is a DynamoDB conditional-check failure. Matches BOTH the
+ * AWS SDK shape (name === 'ConditionalCheckFailedException') and the ts-cloud
+ * client's wrapped form (a generic Error whose message contains
+ * "The conditional request failed") — code that checked only e.name silently
+ * misclassified expected condition failures as real errors.
+ */
+export { isConditionalCheckFailed } from './ddb-errors'
+
+
+/**
+ * Build a DynamoDB query expression for date range
+ */
+export function buildDateRangeExpression(
+  startDate: Date,
+  endDate: Date,
+  timestampField = 'timestamp'
+): {
+  expression: string
+  names: Record<string, string>
+  values: Record<string, unknown>
+} {
+  return {
+    expression: `#${timestampField} BETWEEN :startDate AND :endDate`,
+    names: { [`#${timestampField}`]: timestampField },
+    values: {
+      ':startDate': { S: startDate.toISOString() },
+      ':endDate': { S: endDate.toISOString() },
+    },
+  }
+}
+
+/**
+ * Build a DynamoDB key condition for site queries
+ */
+export function buildSiteKeyCondition(siteId: string): {
+  expression: string
+  values: Record<string, unknown>
+} {
+  return {
+    expression: 'pk = :pk',
+    values: { ':pk': { S: `SITE#${siteId}` } },
+  }
+}
+
+/**
+ * Execute a paginated DynamoDB query
+ */
+export async function paginatedQuery<T>(
+  params: {
+    TableName: string
+    KeyConditionExpression: string
+    ExpressionAttributeValues: Record<string, unknown>
+    ExpressionAttributeNames?: Record<string, string>
+    FilterExpression?: string
+    Limit?: number
+    ScanIndexForward?: boolean
+    IndexName?: string
+  },
+  maxItems = 1000
+): Promise<T[]> {
+  const items: T[] = []
+  let lastKey: Record<string, unknown> | undefined
+
+  do {
+    const response = await dynamodb.query({
+      ...params,
+      ExclusiveStartKey: lastKey,
+    })
+
+    if (response.Items) {
+      for (const item of response.Items) {
+        items.push(unmarshall(item) as T)
+        if (items.length >= maxItems) {
+          return items
+        }
+      }
+    }
+
+    lastKey = response.LastEvaluatedKey
+  } while (lastKey)
+
+  return items
+}
+
+/**
+ * All sessions for a site whose startedAt falls in [startDate, endDate],
+ * via the time-keyed GSI entry (#171) — replaces the full-partition
+ * begins_with(sk, SESSION#) scans that silently truncated at scale. Returns
+ * marshalled Items (same shape as queryAllItems) so call sites keep their
+ * existing unmarshall + filter pipelines.
+ */
+export async function querySessionItemsInRange(
+  siteId: string,
+  startDate: Date,
+  endDate: Date,
+): Promise<{ Items: any[], Count: number }> {
+  return queryAllItems({
+    TableName: TABLE_NAME,
+    IndexName: 'GSI1',
+    KeyConditionExpression: 'gsi1pk = :pk AND gsi1sk BETWEEN :start AND :end',
+    ExpressionAttributeValues: {
+      ':pk': { S: `SITE#${siteId}#SESSIONS` },
+      ':start': { S: startDate.toISOString() },
+      ':end': { S: `${endDate.toISOString()}~` },
+    },
+  })
+}
+
+/**
+ * Query every page of a key condition and return the raw (still-marshalled)
+ * items. Drop-in for `dynamodb.query(...)` at call sites that read `.Items` and
+ * `.map(unmarshall)` themselves, but it no longer silently truncates at
+ * DynamoDB's 1MB page limit (#151). A high safety cap guards against pathological
+ * partitions and is logged when hit — never a silent drop.
+ */
+export async function queryAllItems(
+  params: {
+    TableName: string
+    KeyConditionExpression: string
+    ExpressionAttributeValues: Record<string, unknown>
+    ExpressionAttributeNames?: Record<string, string>
+    FilterExpression?: string
+    Limit?: number
+    ScanIndexForward?: boolean
+    IndexName?: string
+  },
+  cap = 100_000,
+): Promise<{ Items: any[], Count: number }> {
+  const items: any[] = []
+  let lastKey: Record<string, any> | undefined
+  do {
+    const page = await dynamodb.query({ ...params, ExclusiveStartKey: lastKey }) as { Items?: any[], LastEvaluatedKey?: Record<string, any> }
+    if (page.Items)
+      items.push(...page.Items)
+    lastKey = page.LastEvaluatedKey
+    if (items.length >= cap) {
+      console.warn(`[queryAllItems] hit ${cap}-item cap (table ${String(params.TableName)}) — results truncated; counts may undercount`)
+      break
+    }
+  } while (lastKey)
+  return { Items: items, Count: items.length }
+}
+
+/**
+ * Batch get items from DynamoDB
+ */
+export async function batchGet<T>(
+  keys: Array<{ pk: string; sk: string }>
+): Promise<T[]> {
+  if (keys.length === 0) return []
+
+  const items: T[] = []
+  const batches: Array<Array<{ pk: string; sk: string }>> = []
+
+  // Split into batches of 100 (DynamoDB limit)
+  for (let i = 0; i < keys.length; i += 100) {
+    batches.push(keys.slice(i, i + 100))
+  }
+
+  for (const batch of batches) {
+    const response = await dynamodb.batchGetItem({
+      RequestItems: {
+        [TABLE_NAME]: {
+          Keys: batch.map(key => ({
+            pk: { S: key.pk },
+            sk: { S: key.sk },
+          })),
+        },
+      },
+    })
+
+    const tableItems = response.Responses?.[TABLE_NAME]
+    if (tableItems) {
+      for (const item of tableItems) {
+        items.push(unmarshall(item) as T)
+      }
+    }
+  }
+
+  return items
+}

package/src/lib/email.ts

@@ -0,0 +1,38 @@
+/**
+ * Pluggable transactional email sender.
+ *
+ * Until a real provider (SES/SMTP/Resend) is configured via env, emails are
+ * logged to the server console so verification / reset links are usable in
+ * development. Wire a provider in `deliver()` for production.
+ */
+
+export interface EmailMessage {
+  to: string
+  subject: string
+  text: string
+  html?: string
+}
+
+/** Base URL used to build links in emails (falls back to localhost in dev). */
+export function appBaseUrl(): string {
+  // Dev fallback points at the dashboard, which proxies /api to this server —
+  // follows DASHBOARD_PORT (default 2026) so reset/verify/OAuth links resolve.
+  return process.env.ANALYTICS_APP_URL
+    || process.env.STX_PUBLIC_API_ENDPOINT
+    || `http://localhost:${process.env.DASHBOARD_PORT || '2026'}`
+}
+
+async function deliver(msg: EmailMessage): Promise<void> {
+  // TODO: plug a real provider here (SES via @aws-sdk/client-ses, SMTP, Resend…)
+  // when ANALYTICS_EMAIL_PROVIDER is configured. Until then, log so dev works.
+  console.log(`[email] to=${msg.to} | ${msg.subject}\n${msg.text}\n`)
+}
+
+export async function sendEmail(msg: EmailMessage): Promise<void> {
+  try {
+    await deliver(msg)
+  }
+catch (e) {
+    console.error('[email] delivery failed:', (e as Error).message)
+  }
+}