@stacksjs/ts-analytics 0.1.6

package/dist/sqs-buffering.d.ts

@@ -0,0 +1,243 @@
+import type { CustomEvent, PageView, Session } from './types';
+/**
+ * Generate a partition key with time-based sharding to avoid hot partitions
+ *
+ * For high-volume sites, we add a shard suffix based on the current minute
+ * to distribute writes across multiple partitions.
+ *
+ * Pattern: SITE#{siteId}#SHARD#{shardId}
+ *
+ * This helps with:
+ * - Distributing write throughput across partitions
+ * - Avoiding hot partition throttling
+ * - Supporting burst traffic patterns
+ */
+export declare function getShardedPartitionKey(siteId: string, shardCount?: number): string;
+/**
+ * Generate partition key with random sharding for even distribution
+ */
+export declare function getRandomShardedPartitionKey(siteId: string, shardCount?: number): string;
+/**
+ * Get all shard keys for a site (used for queries)
+ */
+export declare function getAllShardKeys(siteId: string, shardCount?: number): string[];
+/**
+ * Generate CloudFormation resources for SQS-based buffering
+ */
+export declare function generateSQSResources(config: {
+  queueName: string
+  deadLetterQueueName?: string
+  visibilityTimeout?: number
+  messageRetention?: number
+  maxReceiveCount?: number
+  fifo?: boolean
+}): Record<string, unknown>;
+/**
+ * Create an SQS event producer using ts-cloud configuration
+ *
+ * @example
+ * ```ts
+ * import { createAnalyticsProducer } from 'ts-analytics'
+ *
+ * // Uses queue URL from environment or cloud.config.ts
+ * const producer = await createAnalyticsProducer()
+ *
+ * // Or specify queue URL directly
+ * const producer = await createAnalyticsProducer({
+ *   queueUrl: 'https://sqs.us-east-1.amazonaws.com/123456789/analytics-events',
+ *   region: 'us-east-1',
+ * })
+ *
+ * // Send events
+ * await producer.sendEvent({
+ *   type: 'pageview',
+ *   siteId: 'my-site',
+ *   timestamp: new Date().toISOString(),
+ *   data: pageViewData,
+ * })
+ * ```
+ */
+export declare function createAnalyticsProducer(options?: {
+  queueUrl?: string
+  region?: string
+}): Promise<SQSEventProducer>;
+/**
+ * Check if SQS buffering is enabled based on configuration
+ */
+export declare function isSQSBufferingEnabled(): boolean;
+// ============================================================================
+// Default Configuration
+// ============================================================================
+export declare const defaultSQSConfig: SQSConfig;
+// Re-export ts-cloud compatible types for convenience
+export declare interface SQSRawMessage {
+  MessageId: string
+  ReceiptHandle: string
+  Body: string
+  Attributes?: Record<string, string>
+  MessageAttributes?: Record<string, unknown>
+}
+export declare interface QueueAttributes {
+  QueueUrl: string
+  QueueArn?: string
+  ApproximateNumberOfMessages?: string
+  ApproximateNumberOfMessagesNotVisible?: string
+  VisibilityTimeout?: string
+  MessageRetentionPeriod?: string
+}
+// ============================================================================
+// Types
+// ============================================================================
+export declare interface SQSConfig {
+  queueUrl?: string
+  enabled: boolean
+  batchSize: number
+  maxMessagesPerInvocation: number
+  visibilityTimeout: number
+  messageRetention: number
+  deadLetterQueueUrl?: string
+  maxReceiveCount: number
+}
+export declare interface AnalyticsEvent {
+  type: 'pageview' | 'session' | 'event' | 'realtime'
+  siteId: string
+  timestamp: string
+  data: PageView | Session | CustomEvent | RealtimeUpdate
+}
+export declare interface RealtimeUpdate {
+  siteId: string
+  minute: string
+  path: string
+  visitorId: string
+}
+export declare interface SQSMessage {
+  events: AnalyticsEvent[]
+  batchId: string
+  timestamp: string
+  retryCount?: number
+}
+export declare interface SQSSendResult {
+  successful: number
+  failed: number
+  messageId?: string
+}
+export declare interface SQSClient {
+  sendMessage: (input: SQSSendMessageInput) => Promise<SQSSendMessageOutput>
+  sendMessageBatch: (input: SQSSendMessageBatchInput) => Promise<SQSSendMessageBatchOutput>
+  receiveMessage: (input: SQSReceiveMessageInput) => Promise<SQSReceiveMessageOutput>
+  deleteMessage: (input: SQSDeleteMessageInput) => Promise<void>
+  deleteMessageBatch: (input: SQSDeleteMessageBatchInput) => Promise<SQSDeleteMessageBatchOutput>
+}
+declare interface SQSSendMessageInput {
+  QueueUrl: string
+  MessageBody: string
+  MessageGroupId?: string
+  MessageDeduplicationId?: string
+}
+declare interface SQSSendMessageOutput {
+  MessageId?: string
+}
+declare interface SQSSendMessageBatchInput {
+  QueueUrl: string
+  Entries: Array<{
+    Id: string
+    MessageBody: string
+    MessageGroupId?: string
+    MessageDeduplicationId?: string
+  }>
+}
+declare interface SQSSendMessageBatchOutput {
+  Successful?: Array<{ Id: string, MessageId: string }>
+  Failed?: Array<{ Id: string, Code: string, Message: string }>
+}
+declare interface SQSReceiveMessageInput {
+  QueueUrl: string
+  MaxNumberOfMessages?: number
+  VisibilityTimeout?: number
+  WaitTimeSeconds?: number
+}
+declare interface SQSReceiveMessageOutput {
+  Messages?: Array<{
+    MessageId: string
+    ReceiptHandle: string
+    Body: string
+  }>
+}
+declare interface SQSDeleteMessageInput {
+  QueueUrl: string
+  ReceiptHandle: string
+}
+declare interface SQSDeleteMessageBatchInput {
+  QueueUrl: string
+  Entries: Array<{
+    Id: string
+    ReceiptHandle: string
+  }>
+}
+declare interface SQSDeleteMessageBatchOutput {
+  Successful?: Array<{ Id: string }>
+  Failed?: Array<{ Id: string, Code: string }>
+}
+// ============================================================================
+// Event Processor Interface
+// ============================================================================
+export declare interface EventProcessor {
+  processEvents(events: AnalyticsEvent[]): Promise<void>
+}
+export declare interface SQSLambdaMessage {
+  messageId: string
+  receiptHandle: string
+  body: string
+}
+export declare interface ProcessResult {
+  successful: number
+  failed: number
+  errors: Array<{ messageId: string, error: string }>
+}
+/**
+ * In-memory event buffer for batching before SQS send
+ */
+export declare class EventBuffer {
+  constructor(options: {
+    maxSize?: number
+    flushIntervalMs?: number
+    onFlush: (events: AnalyticsEvent[]) => Promise<void>
+  });
+  add(event: AnalyticsEvent): void;
+  flush(): Promise<void>;
+  get size(): number;
+}
+/**
+ * Sends analytics events to SQS queue
+ */
+export declare class SQSEventProducer {
+  constructor(client: SQSClient, queueUrl: string, batchSize?: number);
+  sendEvent(event: AnalyticsEvent): Promise<SQSSendResult>;
+  sendEvents(events: AnalyticsEvent[]): Promise<SQSSendResult>;
+  sendEventsBatch(events: AnalyticsEvent[]): Promise<SQSSendResult>;
+}
+/**
+ * Processes analytics events from SQS queue
+ */
+export declare class SQSEventConsumer {
+  constructor(client: SQSClient, queueUrl: string, processor: EventProcessor);
+  processBatch(messages: SQSLambdaMessage[]): Promise<ProcessResult>;
+  poll(maxMessages?: number): Promise<ProcessResult>;
+}
+/**
+ * Coalesce multiple writes to the same key within a time window
+ * This reduces write costs and avoids unnecessary overwrites
+ */
+export declare class WriteCoalescer<T> {
+  constructor(options: {
+    windowMs?: number
+    onWrite: (key: string, data: T) => Promise<void>
+  });
+  write(key: string, data: T): void;
+  flush(): Promise<void>;
+  get size(): number;
+}
+// ============================================================================
+// Export Default Config
+// ============================================================================
+export { defaultSQSConfig as sqsConfig };

package/dist/stacks-integration.d.ts

@@ -0,0 +1,159 @@
+import { AggregationPipeline, AnalyticsAPI, AnalyticsQueryAPI, AnalyticsStore } from './index';
+import type { AnalyticsAPIConfig, HandlerContext } from './index';
+// ============================================================================
+// Type Exports for Stacks Integration
+// ============================================================================
+export type {
+  AnalyticsAPIConfig,
+  HandlerContext,
+};
+/**
+ * Create Stacks analytics middleware
+ * Injects tracking script into HTML responses
+ */
+export declare function createAnalyticsMiddleware(driver: DynamoDBAnalyticsDriver): (ctx: {
+  request: Request
+  response?: Response
+  html?: string
+}, next: () => Promise<void>) => Promise<void>;
+/**
+ * Create server-side tracking middleware
+ * Tracks page views automatically for server-rendered pages
+ */
+export declare function createServerTrackingMiddleware(driver: DynamoDBAnalyticsDriver, options?: {
+    excludedPaths?: RegExp[]
+    getVisitorId?: (request: Request) => string
+    getSessionId?: (request: Request) => string
+  }): (ctx: { request: Request, url: URL }, next: () => Promise<void>) => Promise<void>;
+/**
+ * Create Stacks dashboard actions for analytics
+ */
+export declare function createDashboardActions(driver: DynamoDBAnalyticsDriver): {
+  getDashboardStats: (params: { startDate?: string, endDate?: string, compare?: boolean }) => Promise<unknown>
+  getRealtimeStats: (params?: { minutes?: number }) => Promise<unknown>
+  getTopPages: (params?: { startDate?: string, endDate?: string, limit?: number }) => Promise<unknown>
+  runAggregation: (params: { period: 'hour' | 'day' | 'month' }) => Promise<unknown>
+};
+/**
+ * Create a DynamoDB analytics driver from Stacks config
+ *
+ * @example
+ * ```typescript
+ * import { createAnalyticsDriver } from '@stacksjs/dynamodb-tooling'
+ * import config from './config/analytics'
+ * import { DynamoDBClient } from '@aws-sdk/client-dynamodb'
+ *
+ * const client = new DynamoDBClient({ region: 'us-east-1' })
+ * const driver = createAnalyticsDriver(config.drivers.dynamodb!, async (cmd) => {
+ *   // Execute DynamoDB command
+ *   return client.send(new cmd.command(cmd.input))
+ * })
+ * ```
+ */
+export declare function createAnalyticsDriver(config: DynamoDBAnalyticsConfig, executeCommand: HandlerContext['executeCommand']): DynamoDBAnalyticsDriver;
+/**
+ * DynamoDB analytics driver configuration for Stacks
+ */
+export declare interface DynamoDBAnalyticsConfig {
+  tableName: string
+  region?: string
+  siteId: string
+  apiEndpoint?: string
+  useTtl?: boolean
+  rawEventRetentionDays?: number
+  hourlyRetentionDays?: number
+  dailyRetentionYears?: number
+  privacy?: {
+    honorDnt?: boolean
+    hashIps?: boolean
+    collectGeolocation?: boolean
+  }
+  tracking?: {
+    trackHashChanges?: boolean
+    trackOutboundLinks?: boolean
+    excludedPaths?: string[]
+    excludedIps?: string[]
+  }
+}
+/**
+ * Stacks analytics options interface (matches Stacks pattern)
+ */
+export declare interface StacksAnalyticsOptions {
+  driver: 'google-analytics' | 'fathom' | 'dynamodb'
+  drivers: {
+    googleAnalytics?: {
+      trackingId: string
+    }
+    fathom?: {
+      siteId: string
+    }
+    dynamodb?: DynamoDBAnalyticsConfig
+  }
+}
+/**
+ * DynamoDB Analytics Driver for Stacks
+ *
+ * @example
+ * ```typescript
+ * // config/analytics.ts
+ * export default {
+ *   driver: 'dynamodb',
+ *   drivers: {
+ *     dynamodb: {
+ *       tableName: 'analytics',
+ *       siteId: 'my-site-id',
+ *       region: 'us-east-1',
+ *       privacy: {
+ *         honorDnt: true,
+ *         hashIps: true,
+ *       },
+ *     },
+ *   },
+ * } satisfies StacksAnalyticsOptions
+ * ```
+ */
+export declare class DynamoDBAnalyticsDriver {
+  constructor(config: DynamoDBAnalyticsConfig, executeCommand: HandlerContext['executeCommand']);
+  getTrackingScript(): string;
+  trackPageView(options: {
+    path: string
+    title?: string
+    referrer?: string
+    visitorId: string
+    sessionId: string
+    userAgent?: string
+    ip?: string
+  }): Promise<void>;
+  trackEvent(options: {
+    name: string
+    value?: number
+    properties?: Record<string, string | number | boolean>
+    path: string
+    visitorId: string
+    sessionId: string
+  }): Promise<void>;
+  getDashboardStats(options?: {
+    startDate?: Date
+    endDate?: Date
+    includeComparison?: boolean
+  }): Promise<{
+      summary: ReturnType<typeof AnalyticsQueryAPI.processSummary>
+      timeSeries: ReturnType<typeof AnalyticsQueryAPI.processTimeSeries>
+    }>;
+  getRealtimeVisitors(minutes?: number): Promise<{
+    currentVisitors: number
+    pageViewsLastHour: number
+    topActivePages: Array<{ name: string, value: number, percentage: number }>
+  }>;
+  getTopPages(options?: {
+    startDate?: Date
+    endDate?: Date
+    limit?: number
+  }): Promise<unknown[]>;
+  runAggregation(period: 'hour' | 'day' | 'month'): Promise<{
+    success: boolean
+    config: ReturnType<typeof AggregationPipeline.createJobConfig>
+  }>;
+  getAPI(): AnalyticsAPI;
+  getStore(): AnalyticsStore;
+}

package/dist/tracking-script.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Generate a comprehensive tracking script
+ *
+ * @example
+ * ```ts
+ * const script = generateFullTrackingScript({
+ *   siteId: 'my-site',
+ *   apiEndpoint: 'https://analytics.example.com/api/analytics',
+ *   trackScrollDepth: [25, 50, 75, 100],
+ *   trackOutboundLinks: true,
+ * })
+ *
+ * // Add to HTML
+ * res.send(`<script>${script}</script>`)
+ * ```
+ */
+export declare function generateFullTrackingScript(config: TrackingScriptConfig): string;
+/**
+ * Generate just the tracking snippet (loader)
+ */
+export declare function generateTrackingSnippet(config: Pick<TrackingScriptConfig, 'siteId' | 'apiEndpoint'>): string;
+/**
+ * Generate inline tracking script (no external file needed)
+ */
+export declare function generateInlineTrackingScript(config: TrackingScriptConfig): string;
+/**
+ * Generate a minimal tracking script (page views only)
+ */
+export declare function generateMinimalTrackingScript(config: Pick<TrackingScriptConfig, 'siteId' | 'apiEndpoint' | 'honorDnt' | 'stealthMode'>): string;
+/**
+ * Generate a Google Analytics 4-style tracking script
+ */
+export declare function generateGA4StyleScript(config: TrackingScriptConfig): string;
+/* eslint-disable prefer-const */
+/**
+ * Tracking Script Generator
+ *
+ * Generates a comprehensive client-side tracking script for web analytics.
+ * Supports page views, custom events, scroll tracking, outbound links, and more.
+ */
+// ============================================================================
+// Types
+// ============================================================================
+export declare interface TrackingScriptConfig {
+  siteId: string
+  apiEndpoint: string
+  autoPageView?: boolean
+  trackHashChanges?: boolean
+  trackOutboundLinks?: boolean
+  trackScrollDepth?: number[]
+  trackTimeOnPage?: number[]
+  honorDnt?: boolean
+  cookieDomain?: string
+  sessionTimeout?: number
+  dataAttributePrefix?: string
+  debug?: boolean
+  onError?: string
+  excludePaths?: string[]
+  excludeQueryParams?: boolean
+  minify?: boolean
+  heatmap?: HeatmapTrackingConfig
+  stealthMode?: boolean
+}
+export declare interface HeatmapTrackingConfig {
+  trackClicks?: boolean
+  trackMovements?: boolean
+  movementSampleInterval?: number
+  maxMovementPoints?: number
+  trackScrollPositions?: boolean
+  flushInterval?: number
+}

package/dist/tracking.d.ts

@@ -0,0 +1,17 @@
+/*`, which have no imports.
+ */
+export {
+  getBrowserFamily,
+  isBot,
+  type ParsedUserAgent,
+  parseUserAgent,
+} from './utils/user-agent';
+export {
+  anonymizeIp,
+  countryCodeOf,
+  countryFlagEmoji,
+  getCountryFromHeaders,
+  getRegionFromHeaders,
+  isSpamReferrer,
+  parseReferrerSource,
+} from './utils/geolocation';

package/dist/tracking.js

@@ -0,0 +1,26 @@
+// @bun
+import {
+  anonymizeIp,
+  countryCodeOf,
+  countryFlagEmoji,
+  getBrowserFamily,
+  getCountryFromHeaders,
+  getRegionFromHeaders,
+  isBot,
+  isSpamReferrer,
+  parseReferrerSource,
+  parseUserAgent
+} from "./chunk-j261vgyp.js";
+import"./chunk-2mx7fq49.js";
+export {
+  parseUserAgent,
+  parseReferrerSource,
+  isSpamReferrer,
+  isBot,
+  getRegionFromHeaders,
+  getCountryFromHeaders,
+  getBrowserFamily,
+  countryFlagEmoji,
+  countryCodeOf,
+  anonymizeIp
+};