@stacksjs/ts-analytics 0.1.6

package/CHANGELOG.md

@@ -0,0 +1,68 @@
+[Compare changes](https://github.com/stacksjs/ts-analytics/compare/v0.1.5...v0.1.6)
+
+## 🤖 Continuous Integration
+
+- **release**: use pantry action @main (matches the working publish setup) ([c5bd2db](https://github.com/stacksjs/ts-analytics/commit/c5bd2db)) _(by Chris <chrisbreuer93@gmail.com>)_
+
+## 🧹 Chores
+
+- release v0.1.6 ([2d0da27](https://github.com/stacksjs/ts-analytics/commit/2d0da27)) _(by Chris <chrisbreuer93@gmail.com>)_
+
+## Contributors
+
+- _Chris <chrisbreuer93@gmail.com>_
+
+[Compare changes](https://github.com/stacksjs/ts-analytics/compare/v0.1.4...v0.1.5)
+
+## 🐛 Bug Fixes
+
+- **publish**: set publishConfig.access to public ([9f98feb](https://github.com/stacksjs/ts-analytics/commit/9f98feb)) _(by Chris <chrisbreuer93@gmail.com>)_
+
+## 🧹 Chores
+
+- release v0.1.5 ([97b857c](https://github.com/stacksjs/ts-analytics/commit/97b857c)) _(by Chris <chrisbreuer93@gmail.com>)_
+
+## Contributors
+
+- _Chris <chrisbreuer93@gmail.com>_
+
+[Compare changes](https://github.com/stacksjs/ts-analytics/compare/v0.1.3...v0.1.4)
+
+## 🧹 Chores
+
+- release v0.1.4 ([fee7677](https://github.com/stacksjs/ts-analytics/commit/fee7677)) _(by Chris <chrisbreuer93@gmail.com>)_
+- remove orphaned error-sdk (@stacksjs/error-tracker) ([b451ce5](https://github.com/stacksjs/ts-analytics/commit/b451ce5)) _(by Chris <chrisbreuer93@gmail.com>)_
+
+## Contributors
+
+- _Chris <chrisbreuer93@gmail.com>_
+
+[Compare changes](https://github.com/stacksjs/ts-analytics/compare/v0.1.2...v0.1.3)
+
+## 🚀 Features
+
+- **tracking**: restore dependency-free /tracking entry point ([76651b6](https://github.com/stacksjs/ts-analytics/commit/76651b6)) _(by glennmichael123 <gtorregosa@gmail.com>)_
+
+## 🧹 Chores
+
+- release v0.1.3 ([229e391](https://github.com/stacksjs/ts-analytics/commit/229e391)) _(by Chris <chrisbreuer93@gmail.com>)_
+- **deps**: refresh bun.lock to pick up pickier 0.1.37 ([e81ebd1](https://github.com/stacksjs/ts-analytics/commit/e81ebd1)) _(by glennmichael123 <gtorregosa@gmail.com>)_
+
+## Contributors
+
+- _Chris <chrisbreuer93@gmail.com>_
+- _glennmichael123 <gtorregosa@gmail.com>_
+
+[Compare changes](https://github.com/stacksjs/ts-analytics/compare/v0.1.1...v0.1.2)
+
+## 🚀 Features
+
+- **tracking**: add dependency-free ./tracking subpath export ([20bba2c](https://github.com/stacksjs/ts-analytics/commit/20bba2c)) _(by Chris <chrisbreuer93@gmail.com>)_
+
+## 🧹 Chores
+
+- release v0.1.2 ([9b41b91](https://github.com/stacksjs/ts-analytics/commit/9b41b91)) _(by Chris <chrisbreuer93@gmail.com>)_
+
+## Contributors
+
+- _Chris <chrisbreuer93@gmail.com>_

package/LICENSE.md

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright (c) 2024 Open Web Foundation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,361 @@
+<p align="center"><img src="https://github.com/stacksjs/ts-analytics/blob/main/.github/art/cover.png?raw=true" alt="Social Card of this repo"></p>
+
+[![npm version][npm-version-src]][npm-version-href]
+[![GitHub Actions][github-actions-src]][github-actions-href]
+[![Commitizen friendly](https://img.shields.io/badge/commitizen-friendly-brightgreen.svg)](http://commitizen.github.io/cz-cli/)
+[![npm downloads][npm-downloads-src]][npm-downloads-href]
+
+# @stacksjs/analytics
+
+A privacy-first analytics toolkit for web applications, powered by DynamoDB single-table design.
+
+## Features
+
+- **Privacy-First**: No cookies, no personal data collection, GDPR-compliant by design
+- **DynamoDB Single-Table Design**: Efficient, scalable, and cost-effective storage
+- **Real-time Analytics**: Live visitor tracking and dashboard updates
+- **Goal Tracking**: Define and track conversion goals
+- **Vue Dashboard Components**: Ready-to-use dashboard UI components
+- **Framework Agnostic**: Works with Bun, Express, Hono, AWS Lambda, and more
+- **Stacks Integration**: First-class support for the Stacks framework
+
+## Installation
+
+```bash
+bun add @stacksjs/analytics
+```
+
+## Integrate on Your Site (the 3-step recipe)
+
+The validated pattern for adding ts-analytics to any site (docs sites included):
+
+1. **Create a project** in the dashboard (or let the first event auto-create it), then copy the one-liner from **Settings → Installation**:
+
+   ```html
+   <script defer src="https://your-analytics-host/api/sites/YOUR_SITE_ID/script.js"></script>
+   ```
+
+   It captures page views, SPA route changes, link & outbound clicks, engagement time, web vitals, and JS errors — no cookies, no consent banner needed.
+
+2. **Verify** with the *Verify installation* button in Settings (fires a real event through `/collect` and confirms the round trip), or just visit your site and watch the dashboard.
+
+3. **Optional hardening**: append `?stealth=true` for the unlisted beacon path, or serve it first-party from your own domain — see the [ad-blocker resilience guide](docs/guide/tracking-script.md#ad-blocker-resilience-first-party-proxy). Error tracking without analytics: grab the DSN + SDK snippet from the same Settings page.
+
+## Quick Start
+
+### 1. Set Up the Analytics Store
+
+```typescript
+import { AnalyticsStore, createAnalyticsTable } from '@stacksjs/analytics'
+import { DynamoDBClient } from '@aws-sdk/client-dynamodb'
+import { CreateTableCommand, DescribeTableCommand } from '@aws-sdk/client-dynamodb'
+
+const client = new DynamoDBClient({ region: 'us-east-1' })
+
+// Create the analytics table (one-time setup)
+await createAnalyticsTable(client, {
+  tableName: 'my-analytics',
+  billingMode: 'PAY_PER_REQUEST',
+}, { CreateTableCommand, DescribeTableCommand })
+
+// Initialize the store
+const store = new AnalyticsStore({
+  tableName: 'my-analytics',
+})
+```
+
+### 2. Add the Tracking Script
+
+```typescript
+import { generateTrackingScript } from '@stacksjs/analytics'
+
+const script = generateTrackingScript({
+  siteId: 'my-site-id',
+  endpoint: 'https://api.example.com/collect',
+  // Optional settings
+  trackPageviews: true,
+  trackOutboundLinks: true,
+  respectDoNotTrack: true,
+})
+
+// Inject into your HTML
+const html = `<html><head>${script}</head>...</html>`
+```
+
+### 3. Create API Handlers
+
+```typescript
+import { AnalyticsAPI, createBunRouter } from '@stacksjs/analytics'
+
+const api = new AnalyticsAPI({
+  tableName: 'my-analytics',
+  siteId: 'my-site-id',
+})
+
+// For Bun
+const router = createBunRouter(api, executeCommand)
+
+// For AWS Lambda
+import { createLambdaHandler } from '@stacksjs/analytics'
+export const handler = createLambdaHandler(api, executeCommand)
+```
+
+## Architecture: Source of Truth
+
+The repository has two API layers — only one is live:
+
+| Layer | Status | Where |
+|---|---|---|
+| **Live server** | ✅ source of truth | `src/router.ts` + `src/handlers/*` (DynamoDB-backed), served by `server/index.ts`; jobs in `src/jobs/`, pre-aggregation in `src/lib/rollups.ts` |
+| Legacy library | ⚠️ compatibility only | `src/api.ts`, `src/stacks-integration.ts`, and the in-memory `AnalyticsStore`/`AnalyticsQueryAPI`/`AggregationPipeline` classes in `src/Analytics.ts` |
+
+New endpoints and features belong in `src/router.ts` + `src/handlers/`. The legacy layer is kept so existing imports of the published package keep compiling; it does not serve the bundled server or dashboard. (`generateTrackingScript` in `src/Analytics.ts` **is** live — it builds the served `/script.js`.)
+
+## Core Concepts
+
+### Analytics Store
+
+The `AnalyticsStore` provides DynamoDB operations for all analytics entities:
+
+```typescript
+const store = new AnalyticsStore({
+  tableName: 'analytics',
+  useTtl: true,
+  rawEventTtl: 30 _ 24 _ 60 * 60, // 30 days
+})
+
+// Create a site
+const siteCommand = store.createSiteCommand({
+  id: 'site-123',
+  name: 'My Website',
+  domains: ['example.com'],
+  ownerId: 'user-456',
+})
+
+// Record a page view
+const pvCommand = store.recordPageViewCommand({
+  id: 'pv-789',
+  siteId: 'site-123',
+  path: '/blog/hello-world',
+  visitorId: 'visitor-hash',
+  sessionId: 'session-abc',
+  timestamp: new Date(),
+})
+```
+
+### Aggregation Pipeline
+
+Pre-compute statistics for fast dashboard queries:
+
+```typescript
+import { AggregationPipeline, AnalyticsAggregator } from '@stacksjs/analytics'
+
+const pipeline = new AggregationPipeline({
+  tableName: 'analytics',
+})
+
+// Run hourly aggregation
+const aggregator = new AnalyticsAggregator({
+  tableName: 'analytics',
+})
+
+await aggregator.aggregateHourly('site-123', new Date())
+```
+
+### Query API
+
+Fetch analytics data for dashboards:
+
+```typescript
+import { AnalyticsQueryAPI } from '@stacksjs/analytics'
+
+const queryApi = new AnalyticsQueryAPI({
+  tableName: 'analytics',
+})
+
+// Generate dashboard queries
+const queries = queryApi.generateDashboardQueries({
+  siteId: 'site-123',
+  dateRange: { start: new Date('2024-01-01'), end: new Date() },
+})
+```
+
+### Goal Tracking
+
+Define and track conversion goals:
+
+```typescript
+import { GoalMatcher } from '@stacksjs/analytics'
+
+const goals = [
+  { id: 'signup', type: 'pageview', pattern: '/signup/complete', matchType: 'exact' },
+  { id: 'purchase', type: 'event', pattern: 'purchase', matchType: 'exact' },
+]
+
+const matcher = new GoalMatcher(goals)
+
+// Check if a page view matches any goals
+const matches = matcher.matchPageView('/signup/complete')
+// => [{ goalId: 'signup', value: undefined }]
+```
+
+## Dashboard Components
+
+Vue 3 components for building analytics dashboards:
+
+```vue
+<script setup>
+import {
+  AnalyticsDashboard,
+  StatCard,
+  TimeSeriesChart,
+  TopList,
+  DeviceBreakdown,
+  RealtimeCounter,
+  DateRangePicker,
+} from '@stacksjs/analytics'
+</script>
+
+<template>
+  <AnalyticsDashboard
+    :config="{ baseUrl: '/api/analytics', siteId: 'my-site' }"
+  />
+</template>
+```
+
+### Composables
+
+```typescript
+import { createAnalyticsComposable, fetchDashboardData } from '@stacksjs/analytics'
+
+// Create a composable for Vue
+const analytics = createAnalyticsComposable({
+  baseUrl: '/api/analytics',
+  siteId: 'my-site',
+})
+
+// Or fetch data directly
+const data = await fetchDashboardData(
+  { baseUrl: '/api/analytics', siteId: 'my-site' },
+  { startDate: new Date('2024-01-01'), endDate: new Date() }
+)
+```
+
+## Stacks Framework Integration
+
+First-class integration with the Stacks framework:
+
+```typescript
+import { createAnalyticsDriver, createAnalyticsMiddleware } from '@stacksjs/analytics'
+
+// Create the driver
+const driver = await createAnalyticsDriver({
+  tableName: 'analytics',
+  siteId: 'my-site',
+  region: 'us-east-1',
+})
+
+// Add tracking middleware
+app.use(createAnalyticsMiddleware(driver))
+
+// Server-side tracking
+app.use(createServerTrackingMiddleware(driver, {
+  excludedPaths: [/^\/api/, /^\/admin/],
+}))
+
+// Dashboard actions
+const actions = createDashboardActions(driver)
+const stats = await actions.getDashboardStats({ startDate: '2024-01-01' })
+```
+
+## Infrastructure
+
+Generate infrastructure code for deployment:
+
+```typescript
+import {
+  generateCloudFormationTemplate,
+  generateCdkCode,
+  generateSamTemplate,
+  generateAwsCliCommands,
+} from '@stacksjs/analytics'
+
+// CloudFormation
+const cfn = generateCloudFormationTemplate({ tableName: 'analytics' })
+
+// AWS CDK
+const cdk = generateCdkCode({ tableName: 'analytics' })
+
+// SAM
+const sam = generateSamTemplate({ tableName: 'analytics' })
+
+// AWS CLI commands
+const cli = generateAwsCliCommands({ tableName: 'analytics' })
+```
+
+## Models
+
+Stacks-compatible model definitions for all analytics entities:
+
+```typescript
+import {
+  SiteModel,
+  PageViewModel,
+  SessionModel,
+  CustomEventModel,
+  GoalModel,
+  AggregatedStatsModel,
+  // ... and more
+} from '@stacksjs/analytics'
+```
+
+## Testing
+
+```bash
+bun test
+```
+
+## Changelog
+
+Please see our [releases](https://github.com/stacksjs/analytics/releases) page for more information on what has changed recently.
+
+## Contributing
+
+Please see [CONTRIBUTING](.github/CONTRIBUTING.md) for details.
+
+## Community
+
+For help, discussion about best practices, or any other conversation that would benefit from being searchable:
+
+[Discussions on GitHub](https://github.com/stacksjs/stacks/discussions)
+
+For casual chit-chat with others using this package:
+
+[Join the Stacks Discord Server](https://discord.gg/stacksjs)
+
+## Postcardware
+
+Stacks OSS will always stay open-sourced, and we will always love to receive postcards from wherever Stacks is used! _And we also determine the OSS dependencies we utilize._
+
+Our address: Stacks.js, 12665 Village Ln #2306, Playa Vista, CA 90094, USA
+
+## Sponsors
+
+We would like to extend our thanks to the following sponsors for funding Stacks development. If you are interested in becoming a sponsor, please reach out to us.
+
+- [JetBrains](https://www.jetbrains.com/)
+- [The Solana Foundation](https://solana.com/)
+
+## License
+
+The MIT License (MIT). Please see [LICENSE](LICENSE.md) for more information.
+
+Made with love by [Chris Breuer](https://github.com/chrisbbreuer) and [contributors](https://github.com/stacksjs/analytics/graphs/contributors).
+
+<!-- Badges -->
+[npm-version-src]: https://img.shields.io/npm/v/@stacksjs/analytics?style=flat-square
+[npm-version-href]: https://npmjs.com/package/@stacksjs/analytics
+[github-actions-src]: https://img.shields.io/github/actions/workflow/status/stacksjs/analytics/ci.yml?style=flat-square&branch=main
+[github-actions-href]: https://github.com/stacksjs/analytics/actions?query=workflow%3Aci
+[npm-downloads-src]: https://img.shields.io/npm/dm/@stacksjs/analytics?style=flat-square
+[npm-downloads-href]: https://npmjs.com/package/@stacksjs/analytics

package/bin/cli.ts

@@ -0,0 +1,169 @@
+#!/usr/bin/env bun
+/**
+ * Analytics CLI
+ *
+ * Command-line interface for managing analytics.
+ *
+ * Usage:
+ *   analytics setup           - Print setup instructions
+ *   analytics create-table    - Generate create table command
+ *   analytics docker-compose  - Generate docker-compose.yml
+ *   analytics seed            - Generate seed data
+ *   analytics tracking-script - Generate tracking script
+ */
+
+import {
+  defineConfig,
+  generateAwsCliCommand,
+  generateDockerCompose,
+  generateLocalCreateTableInput,
+  generateSeedData,
+  generateTrackingScript,
+  printLocalSetupInstructions,
+} from '../src'
+
+const args = process.argv.slice(2)
+const command = args[0]
+
+function printHelp(): void {
+  console.log(`
+Analytics CLI - Privacy-first web analytics toolkit
+
+Usage:
+  analytics <command> [options]
+
+Commands:
+  setup               Print local development setup instructions
+  create-table        Generate AWS CLI command to create DynamoDB table
+  docker-compose      Generate docker-compose.yml for local development
+  seed [options]      Generate seed data for testing
+  tracking-script     Generate tracking script for a site
+  help                Show this help message
+
+Options:
+  --table-name <name>    Table name (default: AnalyticsTable)
+  --region <region>      AWS region (default: us-east-1)
+  --port <port>          DynamoDB Local port (default: 8000)
+  --site-id <id>         Site ID for tracking script
+  --api-endpoint <url>   API endpoint for tracking script
+  --sites <n>            Number of sites to seed (default: 1)
+  --page-views <n>       Page views per site (default: 100)
+  --sessions <n>         Sessions per site (default: 50)
+  --days <n>             Days of history (default: 7)
+
+Examples:
+  analytics setup
+  analytics create-table --table-name MyAnalytics
+  analytics docker-compose --port 8001
+  analytics seed --sites 3 --page-views 500
+  analytics tracking-script --site-id site_001 --api-endpoint https://api.example.com
+`)
+}
+
+function getArg(name: string, defaultValue?: string): string | undefined {
+  const index = args.indexOf(`--${name}`)
+  if (index === -1)
+    return defaultValue
+  return args[index + 1] || defaultValue
+}
+
+function getNumericArg(name: string, defaultValue: number): number {
+  const value = getArg(name)
+  return value ? Number.parseInt(value, 10) : defaultValue
+}
+
+async function main(): Promise<void> {
+  switch (command) {
+    case 'setup':
+      printLocalSetupInstructions()
+      break
+
+    case 'create-table': {
+      const tableName = getArg('table-name', 'AnalyticsTable')!
+      const config = defineConfig({
+        table: { tableName },
+        region: getArg('region', 'us-east-1'),
+      })
+
+      console.log('# Create DynamoDB table for analytics\n')
+      console.log(generateAwsCliCommand(config))
+      console.log('\n# Or use this JSON input:')
+      console.log(JSON.stringify(generateLocalCreateTableInput(config), null, 2))
+      break
+    }
+
+    case 'docker-compose': {
+      const port = getNumericArg('port', 8000)
+      console.log(generateDockerCompose({ port }))
+      break
+    }
+
+    case 'seed': {
+      const options = {
+        sites: getNumericArg('sites', 1),
+        pageViewsPerSite: getNumericArg('page-views', 100),
+        sessionsPerSite: getNumericArg('sessions', 50),
+        daysOfHistory: getNumericArg('days', 7),
+      }
+
+      console.log(`Generating seed data:`)
+      console.log(`  Sites: ${options.sites}`)
+      console.log(`  Page views per site: ${options.pageViewsPerSite}`)
+      console.log(`  Sessions per site: ${options.sessionsPerSite}`)
+      console.log(`  Days of history: ${options.daysOfHistory}`)
+      console.log('')
+
+      const data = generateSeedData(options)
+
+      console.log(`Generated:`)
+      console.log(`  ${data.sites.length} sites`)
+      console.log(`  ${data.sessions.length} sessions`)
+      console.log(`  ${data.pageViews.length} page views`)
+      console.log('')
+      console.log('// Seed data JSON:')
+      console.log(JSON.stringify(data, null, 2))
+      break
+    }
+
+    case 'tracking-script': {
+      const siteId = getArg('site-id')
+      const apiEndpoint = getArg('api-endpoint', 'https://api.example.com/analytics')!
+
+      if (!siteId) {
+        console.error('Error: --site-id is required')
+        console.error('Usage: analytics tracking-script --site-id <id> [--api-endpoint <url>]')
+        process.exit(1)
+      }
+
+      const script = generateTrackingScript({
+        siteId,
+        apiEndpoint,
+        honorDnt: true,
+        trackHashChanges: false,
+        trackOutboundLinks: true,
+      })
+
+      console.log('<!-- Add this script to your website -->')
+      console.log(script)
+      break
+    }
+
+    case 'help':
+    case '--help':
+    case '-h':
+      printHelp()
+      break
+
+    default:
+      if (command) {
+        console.error(`Unknown command: ${command}`)
+      }
+      printHelp()
+      process.exit(command ? 1 : 0)
+  }
+}
+
+main().catch((error) => {
+  console.error('Error:', error.message)
+  process.exit(1)
+})