@stacksjs/ts-analytics 0.1.6

package/dist/chunk-xga17tz7.js

@@ -0,0 +1,207 @@
+// @bun
+import"./chunk-3z29508k.js";
+import"./chunk-2mx7fq49.js";
+
+// src/models/orm/index.ts
+import { Model, configureModels, DynamoDBClient, createClient } from "bun-query-builder/dynamodb";
+
+// src/lib/ddb-errors.ts
+function isConditionalCheckFailed(e) {
+  const err = e;
+  return !!err && (String(err.name || "").includes("ConditionalCheckFailed") || /conditional request failed/i.test(String(err.message || err)));
+}
+
+// src/lib/site-retention.ts
+var CACHE_MS = 5 * 60 * 1000;
+var cache = new Map;
+
+// src/models/orm/index.ts
+var analyticsConfig = {
+  tableName: process.env.ANALYTICS_TABLE_NAME || "ts-analytics"
+};
+function configureAnalytics(config) {
+  if (config.tableName) {
+    analyticsConfig.tableName = config.tableName;
+    console.log("[ORM] Configured tableName:", analyticsConfig.tableName);
+  }
+  configureModels({
+    region: config.region,
+    endpoint: config.endpoint,
+    credentials: config.credentials
+  });
+}
+function marshall(obj) {
+  const result = {};
+  for (const [key, value] of Object.entries(obj)) {
+    result[key] = marshallValue(value);
+  }
+  return result;
+}
+function marshallValue(value) {
+  if (value === null || value === undefined) {
+    return { NULL: true };
+  }
+  if (typeof value === "string") {
+    return { S: value };
+  }
+  if (typeof value === "number") {
+    return { N: String(value) };
+  }
+  if (typeof value === "boolean") {
+    return { BOOL: value };
+  }
+  if (Array.isArray(value)) {
+    return { L: value.map(marshallValue) };
+  }
+  if (typeof value === "object") {
+    const m = {};
+    for (const [k, v] of Object.entries(value)) {
+      m[k] = marshallValue(v);
+    }
+    return { M: m };
+  }
+  return { S: String(value) };
+}
+function unmarshall(item) {
+  const result = {};
+  for (const [key, value] of Object.entries(item)) {
+    result[key] = unmarshallValue(value);
+  }
+  return result;
+}
+function unmarshallValue(value) {
+  if ("S" in value)
+    return value.S;
+  if ("N" in value)
+    return Number(value.N);
+  if ("BOOL" in value)
+    return value.BOOL;
+  if ("NULL" in value)
+    return null;
+  if ("SS" in value)
+    return [...value.SS];
+  if ("NS" in value)
+    return value.NS.map(Number);
+  if ("L" in value)
+    return value.L.map(unmarshallValue);
+  if ("M" in value)
+    return unmarshall(value.M);
+  return value;
+}
+
+// src/lib/dynamodb.ts
+var TABLE_NAME = process.env.ANALYTICS_TABLE_NAME || "ts-analytics";
+var REGION = process.env.AWS_REGION || "us-east-1";
+var DYNAMODB_ENDPOINT = process.env.ANALYTICS_DYNAMODB_ENDPOINT || undefined;
+configureAnalytics({
+  tableName: TABLE_NAME,
+  region: REGION,
+  ...DYNAMODB_ENDPOINT ? { endpoint: DYNAMODB_ENDPOINT } : {}
+});
+var dynamodb = createClient({ region: REGION, ...DYNAMODB_ENDPOINT ? { endpoint: DYNAMODB_ENDPOINT } : {} });
+function buildDateRangeExpression(startDate, endDate, timestampField = "timestamp") {
+  return {
+    expression: `#${timestampField} BETWEEN :startDate AND :endDate`,
+    names: { [`#${timestampField}`]: timestampField },
+    values: {
+      ":startDate": { S: startDate.toISOString() },
+      ":endDate": { S: endDate.toISOString() }
+    }
+  };
+}
+function buildSiteKeyCondition(siteId) {
+  return {
+    expression: "pk = :pk",
+    values: { ":pk": { S: `SITE#${siteId}` } }
+  };
+}
+async function paginatedQuery(params, maxItems = 1000) {
+  const items = [];
+  let lastKey;
+  do {
+    const response = await dynamodb.query({
+      ...params,
+      ExclusiveStartKey: lastKey
+    });
+    if (response.Items) {
+      for (const item of response.Items) {
+        items.push(unmarshall(item));
+        if (items.length >= maxItems) {
+          return items;
+        }
+      }
+    }
+    lastKey = response.LastEvaluatedKey;
+  } while (lastKey);
+  return items;
+}
+async function querySessionItemsInRange(siteId, startDate, endDate) {
+  return queryAllItems({
+    TableName: TABLE_NAME,
+    IndexName: "GSI1",
+    KeyConditionExpression: "gsi1pk = :pk AND gsi1sk BETWEEN :start AND :end",
+    ExpressionAttributeValues: {
+      ":pk": { S: `SITE#${siteId}#SESSIONS` },
+      ":start": { S: startDate.toISOString() },
+      ":end": { S: `${endDate.toISOString()}~` }
+    }
+  });
+}
+async function queryAllItems(params, cap = 1e5) {
+  const items = [];
+  let lastKey;
+  do {
+    const page = await dynamodb.query({ ...params, ExclusiveStartKey: lastKey });
+    if (page.Items)
+      items.push(...page.Items);
+    lastKey = page.LastEvaluatedKey;
+    if (items.length >= cap) {
+      console.warn(`[queryAllItems] hit ${cap}-item cap (table ${String(params.TableName)}) \u2014 results truncated; counts may undercount`);
+      break;
+    }
+  } while (lastKey);
+  return { Items: items, Count: items.length };
+}
+async function batchGet(keys) {
+  if (keys.length === 0)
+    return [];
+  const items = [];
+  const batches = [];
+  for (let i = 0;i < keys.length; i += 100) {
+    batches.push(keys.slice(i, i + 100));
+  }
+  for (const batch of batches) {
+    const response = await dynamodb.batchGetItem({
+      RequestItems: {
+        [TABLE_NAME]: {
+          Keys: batch.map((key) => ({
+            pk: { S: key.pk },
+            sk: { S: key.sk }
+          }))
+        }
+      }
+    });
+    const tableItems = response.Responses?.[TABLE_NAME];
+    if (tableItems) {
+      for (const item of tableItems) {
+        items.push(unmarshall(item));
+      }
+    }
+  }
+  return items;
+}
+export {
+  unmarshall,
+  querySessionItemsInRange,
+  queryAllItems,
+  paginatedQuery,
+  marshall,
+  isConditionalCheckFailed,
+  dynamodb,
+  buildSiteKeyCondition,
+  buildDateRangeExpression,
+  batchGet,
+  TABLE_NAME,
+  REGION,
+  DYNAMODB_ENDPOINT
+};

package/dist/config.d.ts

@@ -0,0 +1,132 @@
+import type { AnalyticsTableConfig, BillingMode, GSIDefinition, SingleTableDesignConfig } from './types';
+/**
+ * Merge user config with defaults
+ */
+export declare function defineConfig(userConfig?: UserAnalyticsConfig): AnalyticsConfig;
+/**
+ * Create table configuration from analytics config
+ */
+export declare function getTableConfig(config: AnalyticsConfig): {
+  tableName: string
+  billingMode: BillingMode
+  partitionKey: string
+  sortKey: string
+  gsis: GSIDefinition[]
+  ttlAttribute?: string
+};
+/**
+ * Get TTL value for a given entity type
+ */
+export declare function getTtlForEntity(config: AnalyticsConfig, entityType: 'raw' | 'hourly' | 'daily' | 'monthly'): number | undefined;
+/**
+ * Set global analytics configuration
+ */
+export declare function setConfig(config: UserAnalyticsConfig): AnalyticsConfig;
+/**
+ * Get current analytics configuration
+ */
+export declare function getConfig(): AnalyticsConfig;
+/**
+ * Reset configuration to defaults
+ */
+export declare function resetConfig(): void;
+/**
+ * Default single-table design configuration
+ */
+export declare const defaultSingleTableConfig: SingleTableDesignConfig;
+/**
+ * Default GSI definitions for analytics
+ */
+export declare const defaultGSIs: GSIDefinition[];
+/**
+ * Default analytics table configuration
+ */
+export declare const defaultAnalyticsConfig: AnalyticsTableConfig;
+/**
+ * Complete default configuration
+ */
+export declare const defaultConfig: AnalyticsConfig;
+/**
+ * Analytics configuration options
+ */
+export declare interface AnalyticsConfig {
+  table: AnalyticsTableConfig
+  region: string
+  endpoint?: string
+  retention: {
+    rawEventTtl: number
+    hourlyAggregateTtl: number
+    dailyAggregateTtl: number
+    monthlyAggregateTtl?: number
+  }
+  privacy: {
+    hashVisitorIds: boolean
+    collectGeolocation: boolean
+    honorDnt: boolean
+    ipAnonymization: 'none' | 'partial' | 'full'
+  }
+  tracking: {
+    trackReferrers: boolean
+    trackUtmParams: boolean
+    trackDeviceType: boolean
+    trackHashChanges: boolean
+    trackOutboundLinks: boolean
+    excludedIps?: string[]
+    excludedPaths?: string[]
+  }
+  api: {
+    basePath: string
+    corsOrigins: string[]
+  }
+  aggregation: {
+    batchSize: number
+    hourlyEnabled: boolean
+    dailyEnabled: boolean
+    monthlyEnabled: boolean
+  }
+  scale: {
+    sqsBuffering: {
+      enabled: boolean
+      queueUrl?: string
+      deadLetterQueueUrl?: string
+      maxRetries: number
+    }
+    daxCaching: {
+      enabled: boolean
+      endpoint?: string
+      ttlSeconds: number
+    }
+    partitionSharding: {
+      enabled: boolean
+      shardCount: number
+      enabledSiteIds: string[]
+    }
+    writeCoalescing: {
+      enabled: boolean
+      windowMs: number
+    }
+    batchWrites: {
+      enabled: boolean
+      maxBatchSize: number
+      flushIntervalMs: number
+    }
+  }
+}
+/**
+ * Partial configuration for user overrides
+ */
+export type UserAnalyticsConfig = {
+  [K in keyof AnalyticsConfig]?: K extends 'table'
+    ? Partial<AnalyticsTableConfig>
+    : K extends 'retention' | 'privacy' | 'tracking' | 'api' | 'aggregation'
+      ? Partial<AnalyticsConfig[K]>
+      : K extends 'scale'
+        ? {
+            sqsBuffering?: Partial<AnalyticsConfig['scale']['sqsBuffering']>
+            daxCaching?: Partial<AnalyticsConfig['scale']['daxCaching']>
+            partitionSharding?: Partial<AnalyticsConfig['scale']['partitionSharding']>
+            writeCoalescing?: Partial<AnalyticsConfig['scale']['writeCoalescing']>
+            batchWrites?: Partial<AnalyticsConfig['scale']['batchWrites']>
+          }
+        : AnalyticsConfig[K]
+}

package/dist/dashboard/components/index.d.ts

@@ -0,0 +1,80 @@
+// Function to get component file path
+export declare function getComponentPath(name: string): string | undefined;
+/**
+ * Analytics Dashboard Components
+ *
+ * stx components for displaying analytics data.
+ * These are .stx files that need to be processed by the stx framework.
+ * Total: 31 components
+ *
+ * Components are exported as string identifiers pointing to the component files.
+ * The stx framework uses these to resolve and render the components at runtime.
+ */
+// Component name constants - use these when referencing components in stx templates
+export declare const AlertCard: 'AlertCard';
+export declare const AnalyticsDashboard: 'AnalyticsDashboard';
+export declare const AnimatedNumber: 'AnimatedNumber';
+export declare const BarChart: 'BarChart';
+export declare const BrowserBreakdown: 'BrowserBreakdown';
+export declare const CampaignBreakdown: 'CampaignBreakdown';
+export declare const CountryList: 'CountryList';
+export declare const DataTable: 'DataTable';
+export declare const DateRangePicker: 'DateRangePicker';
+export declare const DeviceBreakdown: 'DeviceBreakdown';
+export declare const DonutChart: 'DonutChart';
+export declare const EmptyState: 'EmptyState';
+export declare const EngagementMetrics: 'EngagementMetrics';
+export declare const FilterBar: 'FilterBar';
+export declare const FullAnalyticsDashboard: 'FullAnalyticsDashboard';
+export declare const FunnelChart: 'FunnelChart';
+export declare const GoalsPanel: 'GoalsPanel';
+export declare const HeatmapChart: 'HeatmapChart';
+export declare const LiveActivityFeed: 'LiveActivityFeed';
+export declare const MetricComparison: 'MetricComparison';
+export declare const MiniStats: 'MiniStats';
+export declare const OSBreakdown: 'OSBreakdown';
+export declare const PageDetailCard: 'PageDetailCard';
+export declare const ProgressRing: 'ProgressRing';
+export declare const RealtimeCounter: 'RealtimeCounter';
+export declare const SparklineChart: 'SparklineChart';
+export declare const StatCard: 'StatCard';
+export declare const ThemeSwitcher: 'ThemeSwitcher';
+export declare const TimeSeriesChart: 'TimeSeriesChart';
+export declare const TopList: 'TopList';
+export declare const TrendIndicator: 'TrendIndicator';
+// Component registry for dynamic component resolution
+export declare const componentRegistry: {
+  AlertCard: './AlertCard.stx';
+  AnalyticsDashboard: './AnalyticsDashboard.stx';
+  AnimatedNumber: './AnimatedNumber.stx';
+  BarChart: './BarChart.stx';
+  BrowserBreakdown: './BrowserBreakdown.stx';
+  CampaignBreakdown: './CampaignBreakdown.stx';
+  CountryList: './CountryList.stx';
+  DataTable: './DataTable.stx';
+  DateRangePicker: './DateRangePicker.stx';
+  DeviceBreakdown: './DeviceBreakdown.stx';
+  DonutChart: './DonutChart.stx';
+  EmptyState: './EmptyState.stx';
+  EngagementMetrics: './EngagementMetrics.stx';
+  FilterBar: './FilterBar.stx';
+  FullAnalyticsDashboard: './FullAnalyticsDashboard.stx';
+  FunnelChart: './FunnelChart.stx';
+  GoalsPanel: './GoalsPanel.stx';
+  HeatmapChart: './HeatmapChart.stx';
+  LiveActivityFeed: './LiveActivityFeed.stx';
+  MetricComparison: './MetricComparison.stx';
+  MiniStats: './MiniStats.stx';
+  OSBreakdown: './OSBreakdown.stx';
+  PageDetailCard: './PageDetailCard.stx';
+  ProgressRing: './ProgressRing.stx';
+  RealtimeCounter: './RealtimeCounter.stx';
+  SparklineChart: './SparklineChart.stx';
+  StatCard: './StatCard.stx';
+  ThemeSwitcher: './ThemeSwitcher.stx';
+  TimeSeriesChart: './TimeSeriesChart.stx';
+  TopList: './TopList.stx';
+  TrendIndicator: './TrendIndicator.stx'
+};
+// List of all component names
+export declare const allComponents: string[];

package/dist/dashboard/composables/useAnalytics.d.ts

@@ -0,0 +1,99 @@
+import type { AnalyticsApiConfig, DashboardSummary, FetchOptions, GoalConversion, RealtimeData, TimeSeriesDataPoint, TopItem } from '../types/index';
+/**
+ * Create analytics composable
+ * Note: This returns a factory function that works with Vue's reactivity system
+ */
+export declare function createAnalyticsComposable(options: UseAnalyticsOptions): {
+  client: AnalyticsClient
+  getInitialDateRange: () => { start: Date, end: Date }
+  fetchStats: (dateRange: { start: Date, end: Date }) => Promise<DashboardSummary>
+  fetchRealtime: () => Promise<RealtimeData>
+  fetchTopPages: (dateRange: { start: Date, end: Date }, limit?: number) => Promise<unknown[]>
+  fetchTopReferrers: (dateRange: { start: Date, end: Date }, limit?: number) => Promise<unknown[]>
+  fetchDevices: (dateRange: { start: Date, end: Date }) => Promise<unknown>
+  fetchBrowsers: (dateRange: { start: Date, end: Date }, limit?: number) => Promise<unknown[]>
+  fetchCountries: (dateRange: { start: Date, end: Date }, limit?: number) => Promise<unknown[]>
+  fetchRegions: (dateRange: { start: Date, end: Date }, country?: string, limit?: number) => Promise<unknown[]>
+  fetchCities: (dateRange: { start: Date, end: Date }, country?: string, region?: string, limit?: number) => Promise<unknown[]>
+  fetchTimeSeries: (dateRange: { start: Date, end: Date }) => Promise<unknown[]>
+  fetchGoals: (dateRange: { start: Date, end: Date }) => Promise<unknown[]>
+};
+/**
+ * Fetch all dashboard data at once
+ */
+// eslint-disable-next-line pickier/no-unused-vars
+export declare function fetchDashboardData(config: AnalyticsApiConfig, options?: FetchOptions): Promise<{
+    stats: DashboardSummary
+    realtime: RealtimeData
+    topPages: TopItem[]
+    topReferrers: TopItem[]
+    devices: TopItem[]
+    timeSeries: TimeSeriesDataPoint[]
+  }>;
+/**
+ * Create a polling function for realtime data
+ */
+export declare function createRealtimePoller(config: AnalyticsApiConfig, callback: (data: RealtimeData) => void, interval?: number): { start: () => void, stop: () => void };
+/**
+ * Create analytics composable for Vue 3
+ *
+ * @example
+ * ```vue
+ * <script setup>
+ * import { useAnalytics } from 'dynamodb-tooling/analytics/dashboard'
+ *
+ * const {
+ *   stats,
+ *   realtime,
+ *   topPages,
+ *   loading,
+ *   error,
+ *   refresh,
+ *   setDateRange
+ * } = useAnalytics({
+ *   baseUrl: '/api',
+ *   siteId: 'my-site'
+ * })
+ * </script>
+ * ```
+ */
+export declare interface UseAnalyticsOptions extends AnalyticsApiConfig {
+  refreshInterval?: number
+  initialDateRange?: '7d' | '30d' | '90d' | 'today' | 'yesterday'
+  fetchRealtime?: boolean
+  realtimeInterval?: number
+}
+export declare interface UseAnalyticsReturn {
+  stats: { value: DashboardSummary | null }
+  realtime: { value: RealtimeData | null }
+  topPages: { value: TopItem[] }
+  topReferrers: { value: TopItem[] }
+  devices: { value: TopItem[] }
+  browsers: { value: TopItem[] }
+  countries: { value: TopItem[] }
+  timeSeries: { value: TimeSeriesDataPoint[] }
+  goals: { value: GoalConversion[] }
+  loading: { value: boolean }
+  error: { value: Error | null }
+  dateRange: { value: { start: Date, end: Date } }
+  refresh: () => Promise<void>
+  setDateRange: (start: Date, end: Date) => void
+  setDatePreset: (preset: string) => void
+}
+// ============================================================================
+// API Client
+// ============================================================================
+export declare class AnalyticsClient {
+  constructor(config: AnalyticsApiConfig);
+  getStats(options?: FetchOptions): Promise<DashboardSummary>;
+  getRealtime(minutes?: number): Promise<RealtimeData>;
+  getTopPages(options?: FetchOptions): Promise<TopItem[]>;
+  getTopReferrers(options?: FetchOptions): Promise<TopItem[]>;
+  getDevices(options?: FetchOptions): Promise<TopItem[]>;
+  getBrowsers(options?: FetchOptions): Promise<TopItem[]>;
+  getCountries(options?: FetchOptions): Promise<TopItem[]>;
+  getRegions(options?: FetchOptions & { country?: string }): Promise<TopItem[]>;
+  getCities(options?: FetchOptions & { country?: string, region?: string }): Promise<TopItem[]>;
+  getTimeSeries(options?: FetchOptions): Promise<TimeSeriesDataPoint[]>;
+  getGoals(options?: FetchOptions): Promise<GoalConversion[]>;
+}

package/dist/dashboard/index.d.ts

@@ -0,0 +1,110 @@
+// Types
+export type {
+  AnalyticsApiConfig,
+  ChartProps,
+  DashboardSummary,
+  DashboardTheme,
+  DateRange,
+  RealtimeCounterProps,
+  RealtimeData,
+  StatCardProps,
+  TimeSeriesDataPoint,
+  TopItem,
+  TopListProps,
+} from './types/index';
+/**
+ * Analytics Dashboard Module
+ *
+ * Vue 3 dashboard components and utilities for displaying
+ * privacy-focused analytics data.
+ *
+ * @example
+ * ```vue
+ * <script setup lang="ts">
+ * import { AnalyticsDashboard } from '@stacksjs/dynamodb-tooling/analytics/dashboard'
+ *
+ * const config = {
+ *   baseUrl: '/api/analytics',
+ *   siteId: 'my-site',
+ * }
+ * </script>
+ *
+ * <template>
+ *   <AnalyticsDashboard :config="config" />
+ * </template>
+ * ```
+ */
+// Components - All 31 dashboard components
+// These are string identifiers that reference .stx component files
+export {
+  // Alert & activity
+  AlertCard,
+  // Main dashboards
+  AnalyticsDashboard,
+  AnimatedNumber,
+  BarChart,
+  BrowserBreakdown,
+  CampaignBreakdown,
+  CountryList,
+  DataTable,
+  DateRangePicker,
+  // Breakdown components
+  DeviceBreakdown,
+  DonutChart,
+  EmptyState,
+  EngagementMetrics,
+  FilterBar,
+  FullAnalyticsDashboard,
+  FunnelChart,
+  // Conversion & engagement
+  GoalsPanel,
+  HeatmapChart,
+  LiveActivityFeed,
+  MetricComparison,
+  MiniStats,
+  OSBreakdown,
+  PageDetailCard,
+  ProgressRing,
+  RealtimeCounter,
+  SparklineChart,
+  // Core components
+  StatCard,
+  ThemeSwitcher,
+  // Chart components
+  TimeSeriesChart,
+  // List & table components
+  TopList,
+  TrendIndicator,
+  // Utilities for component resolution
+  allComponents,
+  componentRegistry,
+  getComponentPath,
+} from './components/index';
+// Composables
+export {
+  AnalyticsClient,
+  createAnalyticsComposable,
+  createRealtimePoller,
+  fetchDashboardData,
+} from './composables/useAnalytics';
+// Re-export as useAnalytics alias for convenience
+export { createAnalyticsComposable as useAnalytics } from './composables/useAnalytics';
+// Theme
+export { darkTheme, defaultTheme } from './types/index';
+// Utilities
+export {
+  calculateAxisTicks,
+  calculateChange,
+  type DateRangePreset,
+  dateRangePresets,
+  formatCompact,
+  formatDate,
+  formatDateRange,
+  formatDuration,
+  formatNumber,
+  formatPercentage,
+  getDateRangeFromPreset,
+} from './utils/index';
+// Re-export with common alias names
+export { calculateChange as calculatePercentageChange } from './utils/index';
+export { getDateRangeFromPreset as getDateRangePreset } from './utils/index';