@stacksjs/ts-analytics 0.1.6

package/src/models/EventStats.ts

@@ -0,0 +1,108 @@
+import type { Model } from './types'
+
+/**
+ * Custom event stats
+ *
+ * DynamoDB Keys:
+ * - PK: SITE#{siteId}
+ * - SK: EVENTSTATS#{PERIOD}#{periodStart}#{eventName}
+ */
+const EventStatsModel: Model = {
+  name: 'EventStats',
+  table: 'analytics', // Single-table design
+  primaryKey: ['siteId', 'period', 'periodStart', 'eventName'], // 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',
+      },
+    },
+
+    eventName: {
+      required: true,
+      fillable: true,
+      validation: {
+        rule: 'string',
+      },
+    },
+
+    count: {
+      required: true,
+      fillable: true,
+      default: 0,
+      validation: {
+        rule: 'number',
+      },
+      cast: 'number',
+      comment: 'Total occurrences',
+    },
+
+    uniqueVisitors: {
+      required: true,
+      fillable: true,
+      default: 0,
+      validation: {
+        rule: 'number',
+      },
+      cast: 'number',
+      comment: 'Unique visitors who triggered event',
+    },
+
+    totalValue: {
+      required: true,
+      fillable: true,
+      default: 0,
+      validation: {
+        rule: 'number',
+      },
+      cast: 'number',
+      comment: 'For revenue tracking',
+    },
+
+    avgValue: {
+      required: true,
+      fillable: true,
+      default: 0,
+      validation: {
+        rule: 'number',
+      },
+      cast: 'number',
+      comment: 'Average value per event',
+    },
+  },
+
+  // DynamoDB single-table key patterns
+  dynamodb: {
+    pk: (stats: { siteId: string }): string => `SITE#${stats.siteId}`,
+    sk: (stats: { period: string, periodStart: string, eventName: string }): string =>
+      `EVENTSTATS#${stats.period.toUpperCase()}#${stats.periodStart}#${stats.eventName}`,
+  },
+}
+
+export default EventStatsModel

package/src/models/GeoStats.ts

@@ -0,0 +1,112 @@
+import type { Model } from './types'
+
+/**
+ * Geographic stats
+ *
+ * DynamoDB Keys:
+ * - PK: SITE#{siteId}
+ * - SK: GEOSTATS#{PERIOD}#{periodStart}#{country}[#{region}]
+ */
+const GeoStatsModel: Model = {
+  name: 'GeoStats',
+  table: 'analytics', // Single-table design
+  primaryKey: ['siteId', 'period', 'periodStart', 'country'], // 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',
+      },
+    },
+
+    country: {
+      required: true,
+      fillable: true,
+      validation: {
+        rule: 'string',
+      },
+      comment: 'ISO 3166-1 alpha-2 country code',
+    },
+
+    region: {
+      fillable: true,
+      validation: {
+        rule: 'string',
+      },
+      comment: 'For country drilldown',
+    },
+
+    city: {
+      fillable: true,
+      validation: {
+        rule: 'string',
+      },
+      comment: 'For region drilldown',
+    },
+
+    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, country: string, region?: string }): string =>
+      `GEOSTATS#${stats.period.toUpperCase()}#${stats.periodStart}#${stats.country}${stats.region ? `#${stats.region}` : ''}`,
+  },
+}
+
+export default GeoStatsModel

package/src/models/Goal.ts

@@ -0,0 +1,105 @@
+import type { Model } from './types'
+
+/**
+ * Goal/Conversion definition
+ *
+ * DynamoDB Keys:
+ * - PK: SITE#{siteId}
+ * - SK: GOAL#{goalId}
+ */
+const GoalModel: Model = {
+  name: 'Goal',
+  table: 'analytics', // Single-table design
+  primaryKey: 'id',
+  autoIncrement: false,
+
+  traits: {
+    useUuid: true,
+    useTimestamps: true,
+  },
+
+  belongsTo: ['Site'],
+
+  hasMany: ['Conversion'],
+
+  attributes: {
+    id: {
+      required: true,
+      unique: true,
+      validation: {
+        rule: 'string',
+      },
+    },
+
+    siteId: {
+      required: true,
+      fillable: true,
+      validation: {
+        rule: 'string',
+      },
+    },
+
+    name: {
+      required: true,
+      fillable: true,
+      validation: {
+        rule: 'string',
+      },
+      comment: 'Human-readable goal name',
+    },
+
+    type: {
+      required: true,
+      fillable: true,
+      validation: {
+        rule: 'enum:pageview,event',
+      },
+      comment: 'Goal type - pageview or event based',
+    },
+
+    pattern: {
+      required: true,
+      fillable: true,
+      validation: {
+        rule: 'string',
+      },
+      comment: 'Match pattern (path pattern or event name)',
+    },
+
+    matchType: {
+      required: true,
+      fillable: true,
+      default: 'exact',
+      validation: {
+        rule: 'enum:exact,contains,regex',
+      },
+    },
+
+    value: {
+      fillable: true,
+      validation: {
+        rule: 'number',
+      },
+      cast: 'number',
+      comment: 'Revenue value per conversion',
+    },
+
+    isActive: {
+      required: true,
+      fillable: true,
+      default: true,
+      validation: {
+        rule: 'boolean',
+      },
+      cast: 'boolean',
+    },
+  },
+
+  // DynamoDB single-table key patterns
+  dynamodb: {
+    pk: (goal: { siteId: string }): string => `SITE#${goal.siteId}`,
+    sk: (goal: { id: string }): string => `GOAL#${goal.id}`,
+  },
+}
+
+export default GoalModel

package/src/models/GoalStats.ts

@@ -0,0 +1,106 @@
+import type { Model } from './types'
+
+/**
+ * Goal stats (conversions)
+ *
+ * DynamoDB Keys:
+ * - PK: SITE#{siteId}
+ * - SK: GOALSTATS#{goalId}#{PERIOD}#{periodStart}
+ */
+const GoalStatsModel: Model = {
+  name: 'GoalStats',
+  table: 'analytics', // Single-table design
+  primaryKey: ['siteId', 'goalId', 'period', 'periodStart'], // Composite key
+  autoIncrement: false,
+
+  traits: {
+    useTtl: true,
+  },
+
+  belongsTo: ['Site', 'Goal'],
+
+  attributes: {
+    siteId: {
+      required: true,
+      fillable: true,
+      validation: {
+        rule: 'string',
+      },
+    },
+
+    goalId: {
+      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',
+      },
+    },
+
+    conversions: {
+      required: true,
+      fillable: true,
+      default: 0,
+      validation: {
+        rule: 'number',
+      },
+      cast: 'number',
+    },
+
+    uniqueConversions: {
+      required: true,
+      fillable: true,
+      default: 0,
+      validation: {
+        rule: 'number',
+      },
+      cast: 'number',
+      comment: 'Unique visitors who converted',
+    },
+
+    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',
+    },
+  },
+
+  // DynamoDB single-table key patterns
+  dynamodb: {
+    pk: (stats: { siteId: string }): string => `SITE#${stats.siteId}`,
+    sk: (stats: { goalId: string, period: string, periodStart: string }): string =>
+      `GOALSTATS#${stats.goalId}#${stats.period.toUpperCase()}#${stats.periodStart}`,
+  },
+}
+
+export default GoalStatsModel

package/src/models/PageStats.ts

@@ -0,0 +1,152 @@
+import type { Model } from './types'
+
+/**
+ * Page-level aggregated stats
+ *
+ * DynamoDB Keys:
+ * - PK: SITE#{siteId}
+ * - SK: PAGESTATS#{PERIOD}#{periodStart}#{path}
+ * - GSI1PK: SITE#{siteId}#PAGESTATS#{PERIOD}#{periodStart}
+ * - GSI1SK: PV#{pageViews}#{path} (for sorting by page views)
+ */
+const PageStatsModel: Model = {
+  name: 'PageStats',
+  table: 'analytics', // Single-table design
+  primaryKey: ['siteId', 'period', 'periodStart', 'path'], // 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',
+      },
+    },
+
+    path: {
+      required: true,
+      fillable: true,
+      validation: {
+        rule: 'string',
+      },
+    },
+
+    title: {
+      fillable: true,
+      validation: {
+        rule: 'string',
+      },
+      comment: 'Most recent page title',
+    },
+
+    pageViews: {
+      required: true,
+      fillable: true,
+      default: 0,
+      validation: {
+        rule: 'number',
+      },
+      cast: 'number',
+    },
+
+    uniqueVisitors: {
+      required: true,
+      fillable: true,
+      default: 0,
+      validation: {
+        rule: 'number',
+      },
+      cast: 'number',
+    },
+
+    entries: {
+      required: true,
+      fillable: true,
+      default: 0,
+      validation: {
+        rule: 'number',
+      },
+      cast: 'number',
+      comment: 'Sessions starting on this page',
+    },
+
+    exits: {
+      required: true,
+      fillable: true,
+      default: 0,
+      validation: {
+        rule: 'number',
+      },
+      cast: 'number',
+      comment: 'Sessions ending on this page',
+    },
+
+    bounces: {
+      required: true,
+      fillable: true,
+      default: 0,
+      validation: {
+        rule: 'number',
+      },
+      cast: 'number',
+    },
+
+    avgTimeOnPage: {
+      required: true,
+      fillable: true,
+      default: 0,
+      validation: {
+        rule: 'number',
+      },
+      cast: 'number',
+      comment: 'Milliseconds',
+    },
+
+    exitRate: {
+      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, path: string }): string =>
+      `PAGESTATS#${stats.period.toUpperCase()}#${stats.periodStart}#${encodeURIComponent(stats.path)}`,
+    gsi1pk: (stats: { siteId: string, period: string, periodStart: string }): string =>
+      `SITE#${stats.siteId}#PAGESTATS#${stats.period.toUpperCase()}#${stats.periodStart}`,
+    gsi1sk: (stats: { pageViews: number, path: string }): string =>
+      `PV#${String(stats.pageViews).padStart(10, '0')}#${encodeURIComponent(stats.path)}`,
+  },
+}
+
+export default PageStatsModel