@stacksjs/ts-analytics 0.1.6

package/src/models/AggregatedStats.ts

@@ -0,0 +1,162 @@
+import type { Model } from './types'
+
+/**
+ * Aggregated stats (pre-computed for fast dashboard queries)
+ *
+ * DynamoDB Keys:
+ * - PK: SITE#{siteId}
+ * - SK: STATS#{PERIOD}#{periodStart}
+ */
+const AggregatedStatsModel: Model = {
+  name: 'AggregatedStats',
+  table: 'analytics', // Single-table design
+  primaryKey: ['siteId', 'period', 'periodStart'], // Composite key
+  autoIncrement: false,
+
+  traits: {
+    useTimestamps: true,
+    useTtl: true, // Hourly stats can be TTL'd after time
+  },
+
+  belongsTo: ['Site'],
+
+  attributes: {
+    siteId: {
+      required: true,
+      fillable: true,
+      validation: {
+        rule: 'string',
+      },
+    },
+
+    period: {
+      required: true,
+      fillable: true,
+      validation: {
+        rule: 'enum:hour,day,month',
+      },
+      comment: 'Aggregation period type',
+    },
+
+    periodStart: {
+      required: true,
+      fillable: true,
+      validation: {
+        rule: 'string',
+      },
+      comment: 'Period start timestamp (ISO string)',
+    },
+
+    pageViews: {
+      required: true,
+      fillable: true,
+      default: 0,
+      validation: {
+        rule: 'number',
+      },
+      cast: 'number',
+    },
+
+    uniqueVisitors: {
+      required: true,
+      fillable: true,
+      default: 0,
+      validation: {
+        rule: 'number',
+      },
+      cast: 'number',
+    },
+
+    sessions: {
+      required: true,
+      fillable: true,
+      default: 0,
+      validation: {
+        rule: 'number',
+      },
+      cast: 'number',
+    },
+
+    bounces: {
+      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',
+    },
+
+    avgPagesPerSession: {
+      required: true,
+      fillable: true,
+      default: 0,
+      validation: {
+        rule: 'number',
+      },
+      cast: 'number',
+    },
+
+    totalTimeOnSite: {
+      required: true,
+      fillable: true,
+      default: 0,
+      validation: {
+        rule: 'number',
+      },
+      cast: 'number',
+      comment: 'Milliseconds',
+    },
+
+    newVisitors: {
+      required: true,
+      fillable: true,
+      default: 0,
+      validation: {
+        rule: 'number',
+      },
+      cast: 'number',
+    },
+
+    returningVisitors: {
+      required: true,
+      fillable: true,
+      default: 0,
+      validation: {
+        rule: 'number',
+      },
+      cast: 'number',
+    },
+  },
+
+  // DynamoDB single-table key patterns
+  dynamodb: {
+    pk: (stats: { siteId: string }): string => `SITE#${stats.siteId}`,
+    sk: (stats: { period: string, periodStart: string }): string =>
+      `STATS#${stats.period.toUpperCase()}#${stats.periodStart}`,
+  },
+}
+
+export default AggregatedStatsModel

package/src/models/CampaignStats.ts

@@ -0,0 +1,141 @@
+import type { Model } from './types'
+
+/**
+ * UTM Campaign stats
+ *
+ * DynamoDB Keys:
+ * - PK: SITE#{siteId}
+ * - SK: CAMPSTATS#{PERIOD}#{periodStart}#{utmSource}[#{utmCampaign}]
+ */
+const CampaignStatsModel: Model = {
+  name: 'CampaignStats',
+  table: 'analytics', // Single-table design
+  primaryKey: ['siteId', 'period', 'periodStart', 'utmSource'], // 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',
+      },
+    },
+
+    utmSource: {
+      required: true,
+      fillable: true,
+      validation: {
+        rule: 'string',
+      },
+    },
+
+    utmMedium: {
+      fillable: true,
+      validation: {
+        rule: 'string',
+      },
+    },
+
+    utmCampaign: {
+      fillable: true,
+      validation: {
+        rule: 'string',
+      },
+    },
+
+    visitors: {
+      required: true,
+      fillable: true,
+      default: 0,
+      validation: {
+        rule: 'number',
+      },
+      cast: 'number',
+    },
+
+    pageViews: {
+      required: true,
+      fillable: true,
+      default: 0,
+      validation: {
+        rule: 'number',
+      },
+      cast: 'number',
+    },
+
+    conversions: {
+      required: true,
+      fillable: true,
+      default: 0,
+      validation: {
+        rule: 'number',
+      },
+      cast: 'number',
+      comment: 'Custom events marked as goals',
+    },
+
+    conversionRate: {
+      required: true,
+      fillable: true,
+      default: 0,
+      validation: {
+        rule: 'number',
+      },
+      cast: 'number',
+      comment: '0-1 decimal',
+    },
+
+    revenue: {
+      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',
+    },
+  },
+
+  // DynamoDB single-table key patterns
+  dynamodb: {
+    pk: (stats: { siteId: string }): string => `SITE#${stats.siteId}`,
+    sk: (stats: { period: string, periodStart: string, utmSource: string, utmCampaign?: string }): string =>
+      `CAMPSTATS#${stats.period.toUpperCase()}#${stats.periodStart}#${stats.utmSource}${stats.utmCampaign ? `#${stats.utmCampaign}` : ''}`,
+  },
+}
+
+export default CampaignStatsModel

package/src/models/Conversion.ts

@@ -0,0 +1,135 @@
+import type { Model } from './types'
+
+/**
+ * Conversion record (goal completion)
+ *
+ * DynamoDB Keys:
+ * - PK: SITE#{siteId}
+ * - SK: CONVERSION#{timestamp}#{conversionId}
+ * - GSI1PK: SITE#{siteId}#GOAL#{goalId}
+ * - GSI1SK: CONVERSION#{timestamp}
+ */
+const ConversionModel: Model = {
+  name: 'Conversion',
+  table: 'analytics', // Single-table design
+  primaryKey: 'id',
+  autoIncrement: false,
+
+  traits: {
+    useUuid: true,
+    useTtl: true,
+  },
+
+  belongsTo: ['Site', 'Goal', 'Session'],
+
+  attributes: {
+    id: {
+      required: true,
+      unique: true,
+      validation: {
+        rule: 'string',
+      },
+    },
+
+    siteId: {
+      required: true,
+      fillable: true,
+      validation: {
+        rule: 'string',
+      },
+    },
+
+    goalId: {
+      required: true,
+      fillable: true,
+      validation: {
+        rule: 'string',
+      },
+    },
+
+    visitorId: {
+      required: true,
+      fillable: true,
+      validation: {
+        rule: 'string',
+      },
+    },
+
+    sessionId: {
+      required: true,
+      fillable: true,
+      validation: {
+        rule: 'string',
+      },
+    },
+
+    value: {
+      fillable: true,
+      validation: {
+        rule: 'number',
+      },
+      cast: 'number',
+      comment: 'Conversion value (from goal or event)',
+    },
+
+    path: {
+      required: true,
+      fillable: true,
+      validation: {
+        rule: 'string',
+      },
+      comment: 'Page path where conversion occurred',
+    },
+
+    referrerSource: {
+      fillable: true,
+      validation: {
+        rule: 'string',
+      },
+    },
+
+    utmSource: {
+      fillable: true,
+      validation: {
+        rule: 'string',
+      },
+    },
+
+    utmCampaign: {
+      fillable: true,
+      validation: {
+        rule: 'string',
+      },
+    },
+
+    timestamp: {
+      required: true,
+      fillable: true,
+      validation: {
+        rule: 'date',
+      },
+      cast: 'datetime',
+    },
+
+    ttl: {
+      fillable: true,
+      validation: {
+        rule: 'number',
+      },
+      cast: 'number',
+    },
+  },
+
+  // DynamoDB single-table key patterns
+  dynamodb: {
+    pk: (conv: { siteId: string }): string => `SITE#${conv.siteId}`,
+    sk: (conv: { timestamp: Date, id: string }): string =>
+      `CONVERSION#${conv.timestamp.toISOString()}#${conv.id}`,
+    gsi1pk: (conv: { siteId: string, goalId: string }): string =>
+      `SITE#${conv.siteId}#GOAL#${conv.goalId}`,
+    gsi1sk: (conv: { timestamp: Date }): string =>
+      `CONVERSION#${conv.timestamp.toISOString()}`,
+  },
+}
+
+export default ConversionModel

package/src/models/CustomEvent.ts

@@ -0,0 +1,123 @@
+import type { Model } from './types'
+
+/**
+ * Custom event (non-pageview events like button clicks, form submissions)
+ *
+ * DynamoDB Keys:
+ * - PK: SITE#{siteId}
+ * - SK: EVENT#{timestamp}#{eventId}
+ * - GSI1PK: SITE#{siteId}#EVENTNAME#{eventName}
+ * - GSI1SK: EVENT#{timestamp}
+ */
+const CustomEventModel: Model = {
+  name: 'CustomEvent',
+  table: 'analytics', // Single-table design
+  primaryKey: 'id',
+  autoIncrement: false,
+
+  traits: {
+    useUuid: true,
+    useTtl: true,
+  },
+
+  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',
+      },
+    },
+
+    name: {
+      required: true,
+      fillable: true,
+      validation: {
+        rule: 'string',
+      },
+      comment: 'Event name (e.g., button_click, form_submit)',
+    },
+
+    value: {
+      fillable: true,
+      validation: {
+        rule: 'number',
+      },
+      cast: 'number',
+      comment: 'Optional value for revenue tracking',
+    },
+
+    properties: {
+      fillable: true,
+      cast: 'json',
+      comment: 'Custom event properties',
+    },
+
+    path: {
+      required: true,
+      fillable: true,
+      validation: {
+        rule: 'string',
+      },
+      comment: 'Page path where event occurred',
+    },
+
+    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: (event: { siteId: string }): string => `SITE#${event.siteId}`,
+    sk: (event: { timestamp: Date, id: string }): string =>
+      `EVENT#${event.timestamp.toISOString()}#${event.id}`,
+    gsi1pk: (event: { siteId: string, name: string }): string =>
+      `SITE#${event.siteId}#EVENTNAME#${event.name}`,
+    gsi1sk: (event: { timestamp: Date }): string =>
+      `EVENT#${event.timestamp.toISOString()}`,
+  },
+}
+
+export default CustomEventModel

package/src/models/DeviceStats.ts

@@ -0,0 +1,105 @@
+import type { Model } from './types'
+
+/**
+ * Device/Browser stats
+ *
+ * DynamoDB Keys:
+ * - PK: SITE#{siteId}
+ * - SK: DEVICESTATS#{PERIOD}#{periodStart}#{dimension}#{value}
+ */
+const DeviceStatsModel: Model = {
+  name: 'DeviceStats',
+  table: 'analytics', // Single-table design
+  primaryKey: ['siteId', 'period', 'periodStart', 'dimension', 'value'], // 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',
+      },
+    },
+
+    dimension: {
+      required: true,
+      fillable: true,
+      validation: {
+        rule: 'enum:device,browser,os,screen',
+      },
+      comment: 'Type of device dimension',
+    },
+
+    value: {
+      required: true,
+      fillable: true,
+      validation: {
+        rule: 'string',
+      },
+      comment: 'e.g., "mobile", "Chrome", "Windows", "1920x1080"',
+    },
+
+    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',
+    },
+  },
+
+  // DynamoDB single-table key patterns
+  dynamodb: {
+    pk: (stats: { siteId: string }): string => `SITE#${stats.siteId}`,
+    sk: (stats: { period: string, periodStart: string, dimension: string, value: string }): string =>
+      `DEVICESTATS#${stats.period.toUpperCase()}#${stats.periodStart}#${stats.dimension}#${stats.value}`,
+  },
+}
+
+export default DeviceStatsModel