@stacksjs/ts-analytics 0.1.6

package/dist/local.d.ts

@@ -0,0 +1,56 @@
+import type { AnalyticsConfig } from './config';
+/**
+ * Generate CreateTable input for analytics table (local development)
+ */
+export declare function generateLocalCreateTableInput(config?: AnalyticsConfig): {
+  TableName: string
+  KeySchema: Array<{ AttributeName: string, KeyType: 'HASH' | 'RANGE' }>
+  AttributeDefinitions: Array<{ AttributeName: string, AttributeType: 'S' | 'N' | 'B' }>
+  BillingMode: string
+  GlobalSecondaryIndexes?: Array<{
+    IndexName: string
+    KeySchema: Array<{ AttributeName: string, KeyType: 'HASH' | 'RANGE' }>
+    Projection: { ProjectionType: string }
+  }>
+};
+/**
+ * Generate AWS CLI command to create the table
+ */
+export declare function generateAwsCliCommand(config?: AnalyticsConfig): string;
+/**
+ * Generate docker-compose.yml for local development
+ */
+export declare function generateDockerCompose(localConfig?: Partial<LocalDynamoDBConfig>): string;
+/**
+ * Generate seed data for local development
+ */
+export declare function generateSeedData(options?: Partial<SeedDataOptions>): {
+  sites: Array<Record<string, unknown>>
+  pageViews: Array<Record<string, unknown>>
+  sessions: Array<Record<string, unknown>>
+};
+/**
+ * Print setup instructions for local development
+ */
+export declare function printLocalSetupInstructions(): void;
+export declare const defaultLocalConfig: LocalDynamoDBConfig;
+export declare const defaultSeedOptions: SeedDataOptions;
+// ============================================================================
+// Local DynamoDB Configuration
+// ============================================================================
+export declare interface LocalDynamoDBConfig {
+  port: number
+  region: string
+  endpoint: string
+  sharedDb: boolean
+  dbPath: string
+}
+// ============================================================================
+// Seed Data
+// ============================================================================
+export declare interface SeedDataOptions {
+  sites: number
+  pageViewsPerSite: number
+  sessionsPerSite: number
+  daysOfHistory: number
+}

package/dist/model-connector.d.ts

@@ -0,0 +1,145 @@
+/**
+ * Get all analytics model names
+ */
+export declare function getAnalyticsModelNames(): string[];
+/**
+ * Get a specific analytics model
+ */
+export declare function getAnalyticsModel(name: string): StacksModelDefinition | undefined;
+/**
+ * Get all analytics models
+ */
+export declare function getAllAnalyticsModels(): StacksModelDefinition[];
+/**
+ * Generate single-table design from analytics models
+ */
+export declare function generateAnalyticsSingleTableDesign(tableName?: string): SingleTableDesign;
+/**
+ * Generate markdown documentation for analytics single-table design
+ */
+export declare function generateAnalyticsDesignDoc(): string;
+/**
+ * Generate access pattern matrix
+ */
+export declare function generateAccessPatternMatrix(): string;
+/**
+ * Map of all analytics models
+ */
+export declare const analyticsModelRegistry: {
+  Site: unknown;
+  PageView: unknown;
+  Session: unknown;
+  CustomEvent: unknown;
+  Goal: unknown;
+  Conversion: unknown;
+  AggregatedStats: unknown;
+  PageStats: unknown;
+  ReferrerStats: unknown;
+  GeoStats: unknown;
+  DeviceStats: unknown;
+  CampaignStats: unknown;
+  EventStats: unknown;
+  GoalStats: unknown;
+  RealtimeStats: unknown
+};
+/**
+ * Stacks model definition (matches model-parser types)
+ */
+export declare interface StacksModelDefinition {
+  name: string
+  table?: string
+  primaryKey?: string | string[]
+  autoIncrement?: boolean
+  attributes: Record<string, AttributeDefinition>
+  hasOne?: string[]
+  hasMany?: string[]
+  belongsTo?: string[]
+  belongsToMany?: string[]
+  traits?: ModelTraits
+  dynamodb?: DynamoDBKeyPatterns
+  indexes?: IndexDefinition[]
+}
+export declare interface AttributeDefinition {
+  required?: boolean
+  unique?: boolean
+  fillable?: boolean
+  hidden?: boolean
+  default?: unknown
+  validation?: {
+    rule?: string
+    message?: Record<string, string>
+  }
+  cast?: string
+  comment?: string
+}
+export declare interface ModelTraits {
+  useUuid?: boolean
+  useTimestamps?: boolean
+  useSoftDeletes?: boolean
+  useTtl?: boolean
+  useVersioning?: boolean
+}
+export declare interface DynamoDBKeyPatterns {
+  pk: (entity: Record<string, unknown>) => string
+  sk: (entity: Record<string, unknown>) => string
+  gsi1pk?: (entity: Record<string, unknown>) => string
+  gsi1sk?: (entity: Record<string, unknown>) => string
+  gsi2pk?: (entity: Record<string, unknown>) => string
+  gsi2sk?: (entity: Record<string, unknown>) => string
+}
+export declare interface IndexDefinition {
+  name: string
+  columns: string[]
+}
+/**
+ * Access pattern definition
+ */
+export declare interface AccessPattern {
+  name: string
+  description: string
+  operation: 'Get' | 'Query' | 'Scan'
+  index?: 'main' | 'GSI1' | 'GSI2'
+  keyCondition: string
+  filterExpression?: string
+  example?: string
+}
+/**
+ * Single-table design output
+ */
+export declare interface SingleTableDesign {
+  tableName: string
+  keySchema: {
+    partitionKey: { name: string, type: 'S' | 'N' | 'B' }
+    sortKey: { name: string, type: 'S' | 'N' | 'B' }
+  }
+  globalSecondaryIndexes: Array<{
+    indexName: string
+    partitionKey: { name: string, type: 'S' | 'N' | 'B' }
+    sortKey: { name: string, type: 'S' | 'N' | 'B' }
+    projection: 'ALL' | 'KEYS_ONLY' | string[]
+  }>
+  entities: EntityDesign[]
+  accessPatterns: AccessPattern[]
+}
+export declare interface EntityDesign {
+  name: string
+  keyPattern: {
+    pk: string
+    sk: string
+    gsi1pk?: string
+    gsi1sk?: string
+    gsi2pk?: string
+    gsi2sk?: string
+  }
+  attributes: Array<{
+    name: string
+    type: string
+    dynamoType: 'S' | 'N' | 'B' | 'BOOL' | 'L' | 'M' | 'SS' | 'NS' | 'BS'
+    required: boolean
+  }>
+  relationships: Array<{
+    type: 'hasOne' | 'hasMany' | 'belongsTo' | 'belongsToMany'
+    target: string
+    foreignKey?: string
+  }>
+}

package/dist/models/AggregatedStats.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Aggregated stats (pre-computed for fast dashboard queries)
+ *
+ * DynamoDB Keys:
+ * - PK: SITE#{siteId}
+ * - SK: STATS#{PERIOD}#{periodStart}
+ */
+declare const AggregatedStatsModel: Model;
+export default AggregatedStatsModel;

package/dist/models/CampaignStats.d.ts

@@ -0,0 +1,9 @@
+/**
+ * UTM Campaign stats
+ *
+ * DynamoDB Keys:
+ * - PK: SITE#{siteId}
+ * - SK: CAMPSTATS#{PERIOD}#{periodStart}#{utmSource}[#{utmCampaign}]
+ */
+declare const CampaignStatsModel: Model;
+export default CampaignStatsModel;

package/dist/models/Conversion.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Conversion record (goal completion)
+ *
+ * DynamoDB Keys:
+ * - PK: SITE#{siteId}
+ * - SK: CONVERSION#{timestamp}#{conversionId}
+ * - GSI1PK: SITE#{siteId}#GOAL#{goalId}
+ * - GSI1SK: CONVERSION#{timestamp}
+ */
+declare const ConversionModel: Model;
+export default ConversionModel;

package/dist/models/CustomEvent.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 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}
+ */
+declare const CustomEventModel: Model;
+export default CustomEventModel;

package/dist/models/DeviceStats.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Device/Browser stats
+ *
+ * DynamoDB Keys:
+ * - PK: SITE#{siteId}
+ * - SK: DEVICESTATS#{PERIOD}#{periodStart}#{dimension}#{value}
+ */
+declare const DeviceStatsModel: Model;
+export default DeviceStatsModel;

package/dist/models/EventStats.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Custom event stats
+ *
+ * DynamoDB Keys:
+ * - PK: SITE#{siteId}
+ * - SK: EVENTSTATS#{PERIOD}#{periodStart}#{eventName}
+ */
+declare const EventStatsModel: Model;
+export default EventStatsModel;

package/dist/models/GeoStats.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Geographic stats
+ *
+ * DynamoDB Keys:
+ * - PK: SITE#{siteId}
+ * - SK: GEOSTATS#{PERIOD}#{periodStart}#{country}[#{region}]
+ */
+declare const GeoStatsModel: Model;
+export default GeoStatsModel;

package/dist/models/Goal.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Goal/Conversion definition
+ *
+ * DynamoDB Keys:
+ * - PK: SITE#{siteId}
+ * - SK: GOAL#{goalId}
+ */
+declare const GoalModel: Model;
+export default GoalModel;

package/dist/models/GoalStats.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Goal stats (conversions)
+ *
+ * DynamoDB Keys:
+ * - PK: SITE#{siteId}
+ * - SK: GOALSTATS#{goalId}#{PERIOD}#{periodStart}
+ */
+declare const GoalStatsModel: Model;
+export default GoalStatsModel;

package/dist/models/PageStats.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 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)
+ */
+declare const PageStatsModel: Model;
+export default PageStatsModel;

package/dist/models/PageView.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 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}
+ */
+declare const PageViewModel: Model;
+export default PageViewModel;

package/dist/models/RealtimeStats.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Real-time stats (last 5 minutes, stored with short TTL)
+ *
+ * DynamoDB Keys:
+ * - PK: SITE#{siteId}
+ * - SK: REALTIME#{minute}
+ */
+declare const RealtimeStatsModel: Model;
+export default RealtimeStatsModel;

package/dist/models/ReferrerStats.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Referrer stats
+ *
+ * DynamoDB Keys:
+ * - PK: SITE#{siteId}
+ * - SK: REFSTATS#{PERIOD}#{periodStart}#{source}
+ */
+declare const ReferrerStatsModel: Model;
+export default ReferrerStatsModel;

package/dist/models/Session.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Visitor session
+ *
+ * DynamoDB Keys:
+ * - PK: SITE#{siteId}
+ * - SK: SESSION#{sessionId}
+ * - GSI1PK: SITE#{siteId}#SESSIONS#{date}
+ * - GSI1SK: SESSION#{sessionId}
+ */
+declare const SessionModel: Model;
+export default SessionModel;

package/dist/models/Site.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Site/Website being tracked
+ *
+ * DynamoDB Keys:
+ * - PK: SITE#{siteId}
+ * - SK: SITE#{siteId}
+ * - GSI1PK: OWNER#{ownerId}
+ * - GSI1SK: SITE#{siteId}
+ */
+declare const SiteModel: Model;
+export default SiteModel;

package/dist/models/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * All analytics models for batch processing
+ */
+export declare const analyticsModels: readonly [unknown, 'PageView', 'Session', 'CustomEvent', 'Goal', 'Conversion', unknown, 'PageStats', 'ReferrerStats', 'GeoStats', 'DeviceStats', 'CampaignStats', 'EventStats', 'GoalStats', 'RealtimeStats'];
+export type AnalyticsModelName = typeof analyticsModels[number];
+/**
+ * Analytics Models Index
+ *
+ * This module exports all Stacks-compatible model definitions
+ * for the privacy-focused web analytics system.
+ */
+// Aggregation stats
+export { default as AggregatedStatsModel } from './AggregatedStats';
+export { default as CampaignStatsModel } from './CampaignStats';
+export { default as ConversionModel } from './Conversion';
+export { default as CustomEventModel } from './CustomEvent';
+export { default as DeviceStatsModel } from './DeviceStats';
+export { default as EventStatsModel } from './EventStats';
+export { default as GeoStatsModel } from './GeoStats';
+export { default as GoalModel } from './Goal';
+export { default as GoalStatsModel } from './GoalStats';
+export { default as PageStatsModel } from './PageStats';
+export { default as PageViewModel } from './PageView';
+export { default as RealtimeStatsModel } from './RealtimeStats';
+export { default as ReferrerStatsModel } from './ReferrerStats';
+export { default as SessionModel } from './Session';
+// Core entities
+export { default as SiteModel } from './Site';

package/dist/models/types.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Attribute validation configuration
+ */
+export declare interface AttributeValidation {
+  rule: string
+  min?: number
+  max?: number
+  message?: string | Record<string, string>
+}
+/**
+ * Model attribute definition
+ */
+export declare interface ModelAttributeDefinition {
+  required?: boolean
+  unique?: boolean
+  fillable?: boolean
+  default?: unknown
+  validation?: AttributeValidation
+  cast?: string
+  comment?: string
+}
+/**
+ * Model traits configuration
+ */
+export declare interface ModelTraits {
+  useUuid?: boolean
+  useTtl?: boolean
+  useTimestamps?: boolean
+  useSoftDeletes?: boolean
+}
+/**
+ * DynamoDB key configuration for single-table design
+ */
+export declare interface DynamoDBKeyConfig {
+  pk?: KeyFunction
+  sk?: KeyFunction
+  gsi1pk?: KeyFunction
+  gsi1sk?: KeyFunction
+  gsi2pk?: KeyFunction
+  gsi2sk?: KeyFunction
+  gsi3pk?: KeyFunction
+  gsi3sk?: KeyFunction
+}
+/**
+ * Stacks Model definition interface
+ * Compatible with @stacksjs/types Model
+ */
+export declare interface Model {
+  name: string
+  table?: string
+  primaryKey?: string | string[]
+  autoIncrement?: boolean
+  traits?: ModelTraits
+  belongsTo?: string[]
+  hasMany?: string[]
+  hasOne?: string[]
+  attributes: Record<string, ModelAttributeDefinition>
+  dynamodb?: DynamoDBKeyConfig
+}
+declare type KeyFunction = (_item: any) => string;