@stacksjs/ts-analytics 0.1.6

package/src/models/PageView.ts

@@ -0,0 +1,277 @@
+import type { Model } from './types'
+
+/**
+ * Page view event (raw event - stored temporarily for aggregation)
+ *
+ * DynamoDB Keys:
+ * - PK: SITE#{siteId}
+ * - SK: PV#{timestamp}#{pageViewId}
+ * - GSI1PK: SITE#{siteId}#DATE#{date}
+ * - GSI1SK: PATH#{path}#{pageViewId}
+ * - GSI2PK: SITE#{siteId}#VISITOR#{visitorId}
+ * - GSI2SK: PV#{timestamp}
+ */
+const PageViewModel: Model = {
+  name: 'PageView',
+  table: 'analytics', // Single-table design
+  primaryKey: 'id',
+  autoIncrement: false,
+
+  traits: {
+    useUuid: true,
+    useTtl: true, // Auto-delete after aggregation
+  },
+
+  belongsTo: ['Site', 'Session'],
+
+  attributes: {
+    id: {
+      required: true,
+      unique: true,
+      validation: {
+        rule: 'string',
+      },
+    },
+
+    siteId: {
+      required: true,
+      fillable: true,
+      validation: {
+        rule: 'string',
+      },
+    },
+
+    visitorId: {
+      required: true,
+      fillable: true,
+      validation: {
+        rule: 'string',
+      },
+      comment: 'Hashed, anonymous visitor identifier',
+    },
+
+    sessionId: {
+      required: true,
+      fillable: true,
+      validation: {
+        rule: 'string',
+      },
+    },
+
+    path: {
+      required: true,
+      fillable: true,
+      validation: {
+        rule: 'string',
+      },
+    },
+
+    hostname: {
+      required: true,
+      fillable: true,
+      validation: {
+        rule: 'string',
+      },
+    },
+
+    title: {
+      fillable: true,
+      validation: {
+        rule: 'string',
+      },
+    },
+
+    referrer: {
+      fillable: true,
+      validation: {
+        rule: 'string',
+      },
+    },
+
+    referrerSource: {
+      fillable: true,
+      validation: {
+        rule: 'string',
+      },
+      comment: 'e.g., google, twitter, direct',
+    },
+
+    // UTM parameters
+    utmSource: {
+      fillable: true,
+      validation: {
+        rule: 'string',
+      },
+    },
+
+    utmMedium: {
+      fillable: true,
+      validation: {
+        rule: 'string',
+      },
+    },
+
+    utmCampaign: {
+      fillable: true,
+      validation: {
+        rule: 'string',
+      },
+    },
+
+    utmContent: {
+      fillable: true,
+      validation: {
+        rule: 'string',
+      },
+    },
+
+    utmTerm: {
+      fillable: true,
+      validation: {
+        rule: 'string',
+      },
+    },
+
+    // Geolocation (privacy-sensitive)
+    country: {
+      fillable: true,
+      validation: {
+        rule: 'string',
+      },
+      comment: 'ISO 3166-1 alpha-2 country code',
+    },
+
+    region: {
+      fillable: true,
+      validation: {
+        rule: 'string',
+      },
+    },
+
+    city: {
+      fillable: true,
+      validation: {
+        rule: 'string',
+      },
+    },
+
+    // Device information
+    deviceType: {
+      fillable: true,
+      validation: {
+        rule: 'enum:desktop,mobile,tablet,unknown',
+      },
+    },
+
+    browser: {
+      fillable: true,
+      validation: {
+        rule: 'string',
+      },
+    },
+
+    browserVersion: {
+      fillable: true,
+      validation: {
+        rule: 'string',
+      },
+    },
+
+    os: {
+      fillable: true,
+      validation: {
+        rule: 'string',
+      },
+    },
+
+    osVersion: {
+      fillable: true,
+      validation: {
+        rule: 'string',
+      },
+    },
+
+    screenWidth: {
+      fillable: true,
+      validation: {
+        rule: 'number',
+      },
+      cast: 'number',
+    },
+
+    screenHeight: {
+      fillable: true,
+      validation: {
+        rule: 'number',
+      },
+      cast: 'number',
+    },
+
+    // Session metrics
+    isUnique: {
+      required: true,
+      fillable: true,
+      default: false,
+      validation: {
+        rule: 'boolean',
+      },
+      cast: 'boolean',
+      comment: 'First page view in session',
+    },
+
+    isBounce: {
+      required: true,
+      fillable: true,
+      default: true,
+      validation: {
+        rule: 'boolean',
+      },
+      cast: 'boolean',
+      comment: 'Only page view in session',
+    },
+
+    timeOnPage: {
+      fillable: true,
+      validation: {
+        rule: 'number',
+      },
+      cast: 'number',
+      comment: 'Milliseconds - updated on next page view or session end',
+    },
+
+    timestamp: {
+      required: true,
+      fillable: true,
+      validation: {
+        rule: 'date',
+      },
+      cast: 'datetime',
+    },
+
+    ttl: {
+      fillable: true,
+      validation: {
+        rule: 'number',
+      },
+      cast: 'number',
+      comment: 'Unix timestamp for DynamoDB TTL auto-deletion',
+    },
+  },
+
+  // DynamoDB single-table key patterns
+  dynamodb: {
+    pk: (pv: { siteId: string }): string => `SITE#${pv.siteId}`,
+    sk: (pv: { timestamp: Date, id: string }): string =>
+      `PV#${pv.timestamp.toISOString()}#${pv.id}`,
+    gsi1pk: (pv: { siteId: string, timestamp: Date }): string =>
+      `SITE#${pv.siteId}#DATE#${pv.timestamp.toISOString().split('T')[0]}`,
+    gsi1sk: (pv: { path: string, id: string }): string =>
+      `PATH#${pv.path}#${pv.id}`,
+    gsi2pk: (pv: { siteId: string, visitorId: string }): string =>
+      `SITE#${pv.siteId}#VISITOR#${pv.visitorId}`,
+    gsi2sk: (pv: { timestamp: Date }): string =>
+      `PV#${pv.timestamp.toISOString()}`,
+  },
+}
+
+export default PageViewModel

package/src/models/RealtimeStats.ts

@@ -0,0 +1,96 @@
+import type { Model } from './types'
+
+/**
+ * Real-time stats (last 5 minutes, stored with short TTL)
+ *
+ * DynamoDB Keys:
+ * - PK: SITE#{siteId}
+ * - SK: REALTIME#{minute}
+ */
+const RealtimeStatsModel: Model = {
+  name: 'RealtimeStats',
+  table: 'analytics', // Single-table design
+  primaryKey: ['siteId', 'minute'], // Composite key
+  autoIncrement: false,
+
+  traits: {
+    useTtl: true,
+  },
+
+  belongsTo: ['Site'],
+
+  attributes: {
+    siteId: {
+      required: true,
+      fillable: true,
+      validation: {
+        rule: 'string',
+      },
+    },
+
+    minute: {
+      required: true,
+      fillable: true,
+      validation: {
+        rule: 'string',
+      },
+      comment: 'ISO timestamp truncated to minute',
+    },
+
+    currentVisitors: {
+      required: true,
+      fillable: true,
+      default: 0,
+      validation: {
+        rule: 'number',
+      },
+      cast: 'number',
+      comment: 'Active visitors in this minute',
+    },
+
+    pageViews: {
+      required: true,
+      fillable: true,
+      default: 0,
+      validation: {
+        rule: 'number',
+      },
+      cast: 'number',
+      comment: 'Page views in this minute',
+    },
+
+    activePages: {
+      required: true,
+      fillable: true,
+      cast: 'json',
+      default: {},
+      comment: 'Map of path -> visitor count',
+    },
+
+    visitorIds: {
+      required: false,
+      fillable: true,
+      cast: 'json',
+      default: [],
+      comment: 'Set of unique visitor IDs for this minute (for counting)',
+    },
+
+    ttl: {
+      required: true,
+      fillable: true,
+      validation: {
+        rule: 'number',
+      },
+      cast: 'number',
+      comment: 'Auto-delete after 10 minutes',
+    },
+  },
+
+  // DynamoDB single-table key patterns
+  dynamodb: {
+    pk: (stats: { siteId: string }): string => `SITE#${stats.siteId}`,
+    sk: (stats: { minute: string }): string => `REALTIME#${stats.minute}`,
+  },
+}
+
+export default RealtimeStatsModel

package/src/models/ReferrerStats.ts

@@ -0,0 +1,115 @@
+import type { Model } from './types'
+
+/**
+ * Referrer stats
+ *
+ * DynamoDB Keys:
+ * - PK: SITE#{siteId}
+ * - SK: REFSTATS#{PERIOD}#{periodStart}#{source}
+ */
+const ReferrerStatsModel: Model = {
+  name: 'ReferrerStats',
+  table: 'analytics', // Single-table design
+  primaryKey: ['siteId', 'period', 'periodStart', 'source'], // Composite key
+  autoIncrement: false,
+
+  traits: {
+    useTtl: true,
+  },
+
+  belongsTo: ['Site'],
+
+  attributes: {
+    siteId: {
+      required: true,
+      fillable: true,
+      validation: {
+        rule: 'string',
+      },
+    },
+
+    period: {
+      required: true,
+      fillable: true,
+      validation: {
+        rule: 'enum:hour,day,month',
+      },
+    },
+
+    periodStart: {
+      required: true,
+      fillable: true,
+      validation: {
+        rule: 'string',
+      },
+    },
+
+    source: {
+      required: true,
+      fillable: true,
+      validation: {
+        rule: 'string',
+      },
+      comment: 'Referrer source (e.g., google, twitter, direct)',
+    },
+
+    referrer: {
+      fillable: true,
+      validation: {
+        rule: 'string',
+      },
+      comment: 'Full referrer URL (for non-grouped view)',
+    },
+
+    visitors: {
+      required: true,
+      fillable: true,
+      default: 0,
+      validation: {
+        rule: 'number',
+      },
+      cast: 'number',
+    },
+
+    pageViews: {
+      required: true,
+      fillable: true,
+      default: 0,
+      validation: {
+        rule: 'number',
+      },
+      cast: 'number',
+    },
+
+    bounceRate: {
+      required: true,
+      fillable: true,
+      default: 0,
+      validation: {
+        rule: 'number',
+      },
+      cast: 'number',
+      comment: '0-1 decimal',
+    },
+
+    avgSessionDuration: {
+      required: true,
+      fillable: true,
+      default: 0,
+      validation: {
+        rule: 'number',
+      },
+      cast: 'number',
+      comment: 'Milliseconds',
+    },
+  },
+
+  // DynamoDB single-table key patterns
+  dynamodb: {
+    pk: (stats: { siteId: string }): string => `SITE#${stats.siteId}`,
+    sk: (stats: { period: string, periodStart: string, source: string }): string =>
+      `REFSTATS#${stats.period.toUpperCase()}#${stats.periodStart}#${stats.source}`,
+  },
+}
+
+export default ReferrerStatsModel

package/src/models/Session.ts

@@ -0,0 +1,235 @@
+import type { Model } from './types'
+
+/**
+ * Visitor session
+ *
+ * DynamoDB Keys:
+ * - PK: SITE#{siteId}
+ * - SK: SESSION#{sessionId}
+ * - GSI1PK: SITE#{siteId}#SESSIONS#{date}
+ * - GSI1SK: SESSION#{sessionId}
+ */
+const SessionModel: Model = {
+  name: 'Session',
+  table: 'analytics', // Single-table design
+  primaryKey: 'id',
+  autoIncrement: false,
+
+  traits: {
+    useUuid: true,
+    useTtl: true,
+  },
+
+  belongsTo: ['Site'],
+
+  hasMany: ['PageView', 'CustomEvent'],
+
+  attributes: {
+    id: {
+      required: true,
+      unique: true,
+      validation: {
+        rule: 'string',
+      },
+    },
+
+    siteId: {
+      required: true,
+      fillable: true,
+      validation: {
+        rule: 'string',
+      },
+    },
+
+    visitorId: {
+      required: true,
+      fillable: true,
+      validation: {
+        rule: 'string',
+      },
+      comment: 'Hashed, anonymous visitor identifier',
+    },
+
+    entryPath: {
+      required: true,
+      fillable: true,
+      validation: {
+        rule: 'string',
+      },
+      comment: 'First page in session',
+    },
+
+    exitPath: {
+      required: true,
+      fillable: true,
+      validation: {
+        rule: 'string',
+      },
+      comment: 'Last page in session',
+    },
+
+    referrer: {
+      fillable: true,
+      validation: {
+        rule: 'string',
+      },
+    },
+
+    referrerSource: {
+      fillable: true,
+      validation: {
+        rule: 'string',
+      },
+    },
+
+    // UTM parameters
+    utmSource: {
+      fillable: true,
+      validation: {
+        rule: 'string',
+      },
+    },
+
+    utmMedium: {
+      fillable: true,
+      validation: {
+        rule: 'string',
+      },
+    },
+
+    utmCampaign: {
+      fillable: true,
+      validation: {
+        rule: 'string',
+      },
+    },
+
+    // Geolocation
+    country: {
+      fillable: true,
+      validation: {
+        rule: 'string',
+      },
+    },
+
+    region: {
+      fillable: true,
+      validation: {
+        rule: 'string',
+      },
+      comment: 'Region/state code or name',
+    },
+
+    city: {
+      fillable: true,
+      validation: {
+        rule: 'string',
+      },
+      comment: 'City name',
+    },
+
+    // Device information
+    deviceType: {
+      fillable: true,
+      validation: {
+        rule: 'enum:desktop,mobile,tablet,unknown',
+      },
+    },
+
+    browser: {
+      fillable: true,
+      validation: {
+        rule: 'string',
+      },
+    },
+
+    os: {
+      fillable: true,
+      validation: {
+        rule: 'string',
+      },
+    },
+
+    // Session metrics
+    pageViewCount: {
+      required: true,
+      fillable: true,
+      default: 0,
+      validation: {
+        rule: 'number',
+      },
+      cast: 'number',
+    },
+
+    eventCount: {
+      required: true,
+      fillable: true,
+      default: 0,
+      validation: {
+        rule: 'number',
+      },
+      cast: 'number',
+    },
+
+    isBounce: {
+      required: true,
+      fillable: true,
+      default: true,
+      validation: {
+        rule: 'boolean',
+      },
+      cast: 'boolean',
+      comment: 'Single page session',
+    },
+
+    duration: {
+      required: true,
+      fillable: true,
+      default: 0,
+      validation: {
+        rule: 'number',
+      },
+      cast: 'number',
+      comment: 'Session duration in milliseconds',
+    },
+
+    startedAt: {
+      required: true,
+      fillable: true,
+      validation: {
+        rule: 'date',
+      },
+      cast: 'datetime',
+    },
+
+    endedAt: {
+      required: true,
+      fillable: true,
+      validation: {
+        rule: 'date',
+      },
+      cast: 'datetime',
+      comment: 'Last activity timestamp',
+    },
+
+    ttl: {
+      fillable: true,
+      validation: {
+        rule: 'number',
+      },
+      cast: 'number',
+      comment: 'Unix timestamp for DynamoDB TTL auto-deletion',
+    },
+  },
+
+  // DynamoDB single-table key patterns
+  dynamodb: {
+    pk: (session: { siteId: string }): string => `SITE#${session.siteId}`,
+    sk: (session: { id: string }): string => `SESSION#${session.id}`,
+    gsi1pk: (session: { siteId: string, startedAt: Date }): string =>
+      `SITE#${session.siteId}#SESSIONS#${session.startedAt.toISOString().split('T')[0]}`,
+    gsi1sk: (session: { id: string }): string => `SESSION#${session.id}`,
+  },
+}
+
+export default SessionModel