@astralibx/email-analytics 2.0.0

package/README.md

@@ -0,0 +1,133 @@
+# @astralibx/email-analytics
+
+Event-level email tracking with automatic daily aggregation and pre-built query APIs. Record individual send/deliver/bounce/open/click events, aggregate them into daily stats by account, rule, or template, and query time-series data through REST endpoints or the programmatic API.
+
+## Install
+
+```bash
+npm install @astralibx/email-analytics
+```
+
+**Peer dependencies** (install separately):
+
+```bash
+npm install mongoose express
+```
+
+## Quick Start
+
+```typescript
+import mongoose from 'mongoose';
+import express from 'express';
+import { createEmailAnalytics } from '@astralibx/email-analytics';
+
+const conn = mongoose.createConnection('mongodb://localhost:27017/myapp');
+
+const analytics = createEmailAnalytics({
+  db: { connection: conn, collectionPrefix: 'myapp_' },
+  options: {
+    eventTTLDays: 90,
+    timezone: 'Asia/Kolkata',
+  },
+});
+
+// Mount REST routes
+const app = express();
+app.use('/api/analytics', analytics.routes);
+
+// Record an event programmatically
+await analytics.events.record({
+  type: 'sent',
+  accountId: '507f1f77bcf86cd799439011',
+  recipientEmail: 'user@example.com',
+  ruleId: '507f1f77bcf86cd799439012',
+});
+
+// Run daily aggregation
+await analytics.aggregator.aggregateDaily();
+
+// Query overview stats
+const overview = await analytics.query.getOverview(
+  new Date('2025-01-01'),
+  new Date('2025-01-31'),
+);
+```
+
+## Features
+
+- **Event Recording** -- single and batch insert with automatic timestamps ([docs](docs/event-recording.md))
+- **Daily Aggregation** -- rolls up raw events into per-day stats by account, rule, template, and overall ([docs](docs/aggregation.md))
+- **Range Aggregation** -- backfill or re-aggregate any date range ([docs](docs/aggregation.md))
+- **Time-Series Queries** -- overview, timeline (daily/weekly/monthly), per-account, per-rule, per-template ([docs](docs/querying.md))
+- **REST API** -- six endpoints with date-range query params ([docs](docs/api-routes.md))
+- **TTL Cleanup** -- MongoDB TTL index auto-expires old events; manual purge also available ([docs](docs/event-recording.md#ttl-and-cleanup))
+- **Programmatic API** -- use services directly without HTTP ([docs](docs/programmatic-api.md))
+- **Error Handling** -- typed error classes for validation, date range, and aggregation failures ([docs](docs/error-handling.md))
+
+## Integration with Other Packages
+
+Wire hooks from `@astralibx/email-account-manager` and `@astralibx/email-rule-engine` to automatically record analytics events. See the [integration guide](docs/integration.md) for full examples.
+
+```typescript
+import { createEmailAccountManager } from '@astralibx/email-account-manager';
+import { createEmailRuleEngine } from '@astralibx/email-rule-engine';
+import { createEmailAnalytics } from '@astralibx/email-analytics';
+
+const analytics = createEmailAnalytics({ db: { connection: conn } });
+const accountManager = createEmailAccountManager({ db: { connection: conn } });
+const ruleEngine = createEmailRuleEngine({ db: { connection: conn } });
+
+// Record events from rule engine execution
+ruleEngine.on('emailSent', async (detail) => {
+  await analytics.events.record({
+    type: 'sent',
+    accountId: detail.accountId,
+    ruleId: detail.ruleId,
+    templateId: detail.templateId,
+    recipientEmail: detail.recipientEmail,
+  });
+});
+
+ruleEngine.on('emailFailed', async (detail) => {
+  await analytics.events.record({
+    type: 'failed',
+    accountId: detail.accountId,
+    ruleId: detail.ruleId,
+    recipientEmail: detail.recipientEmail,
+    metadata: { error: detail.error },
+  });
+});
+```
+
+## Documentation
+
+| Guide | Description |
+|-------|-------------|
+| [Configuration](docs/configuration.md) | Full config reference |
+| [Event Recording](docs/event-recording.md) | Recording events, batch insert, TTL |
+| [Aggregation](docs/aggregation.md) | Daily aggregation, range backfill |
+| [Querying](docs/querying.md) | Overview, timeline, grouped stats |
+| [API Routes](docs/api-routes.md) | REST endpoints reference |
+| [Programmatic API](docs/programmatic-api.md) | Using services directly |
+| [Integration](docs/integration.md) | Wiring with account-manager and rule-engine |
+| [Error Handling](docs/error-handling.md) | Error classes and codes |
+
+## Exported Types
+
+```typescript
+// Core types
+export type { EmailAnalyticsConfig } from './types/config.types';
+export type { EmailEvent, CreateEventInput } from './types/event.types';
+export type { DailyStats, AccountStats, RuleStats, TemplateStats, OverviewStats, TimelineEntry } from './types/stats.types';
+
+// Constants
+export { EVENT_TYPE, AGGREGATION_INTERVAL, STATS_GROUP_BY } from './constants';
+export type { EventType, AggregationInterval, StatsGroupBy } from './constants';
+
+// Errors
+export { AlxAnalyticsError, ConfigValidationError, InvalidDateRangeError, AggregationError } from './errors';
+```
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,267 @@
+import { Request, Response, Router } from 'express';
+import * as mongoose from 'mongoose';
+import { Connection, Model, Types, HydratedDocument, Schema } from 'mongoose';
+import { LogAdapter, AlxError } from '@astralibx/core';
+export { ConfigValidationError } from '@astralibx/core';
+
+declare const EVENT_TYPE: {
+    readonly Sent: "sent";
+    readonly Delivered: "delivered";
+    readonly Bounced: "bounced";
+    readonly Complained: "complained";
+    readonly Opened: "opened";
+    readonly Clicked: "clicked";
+    readonly Unsubscribed: "unsubscribed";
+    readonly Failed: "failed";
+};
+type EventType = (typeof EVENT_TYPE)[keyof typeof EVENT_TYPE];
+declare const AGGREGATION_INTERVAL: {
+    readonly Daily: "daily";
+    readonly Weekly: "weekly";
+    readonly Monthly: "monthly";
+};
+type AggregationInterval = (typeof AGGREGATION_INTERVAL)[keyof typeof AGGREGATION_INTERVAL];
+declare const STATS_GROUP_BY: {
+    readonly Account: "account";
+    readonly Rule: "rule";
+    readonly Template: "template";
+};
+type StatsGroupBy = (typeof STATS_GROUP_BY)[keyof typeof STATS_GROUP_BY];
+
+interface EmailAnalyticsConfig {
+    db: {
+        connection: Connection;
+        collectionPrefix?: string;
+    };
+    logger?: LogAdapter;
+    options?: {
+        eventTTLDays?: number;
+        timezone?: string;
+        aggregationSchedule?: AggregationInterval[];
+    };
+}
+
+interface IEmailEvent {
+    type: EventType;
+    accountId: Types.ObjectId;
+    ruleId?: Types.ObjectId;
+    templateId?: Types.ObjectId;
+    recipientEmail: string;
+    identifierId?: Types.ObjectId;
+    metadata?: Record<string, unknown>;
+    timestamp: Date;
+    createdAt: Date;
+    updatedAt: Date;
+}
+type EmailEventDocument = HydratedDocument<IEmailEvent>;
+interface EmailEventStatics {
+    record(event: {
+        type: EventType;
+        accountId: string;
+        ruleId?: string;
+        templateId?: string;
+        recipientEmail: string;
+        identifierId?: string;
+        metadata?: Record<string, unknown>;
+        timestamp?: Date;
+    }): Promise<EmailEventDocument>;
+    findByDateRange(start: Date, end: Date, filters?: {
+        type?: EventType;
+        accountId?: string;
+        ruleId?: string;
+        templateId?: string;
+    }): Promise<EmailEventDocument[]>;
+}
+type EmailEventModel = Model<IEmailEvent> & EmailEventStatics;
+interface CreateEmailEventSchemaOptions {
+    collectionName?: string;
+    eventTTLDays?: number;
+}
+declare function createEmailEventSchema(options?: CreateEmailEventSchemaOptions): Schema<IEmailEvent, Model<IEmailEvent, any, any, any, mongoose.Document<unknown, any, IEmailEvent, any, {}> & IEmailEvent & {
+    _id: Types.ObjectId;
+} & {
+    __v: number;
+}, any>, {}, {}, {}, {}, mongoose.DefaultSchemaOptions, IEmailEvent, mongoose.Document<unknown, {}, mongoose.FlatRecord<IEmailEvent>, {}, mongoose.DefaultSchemaOptions> & mongoose.FlatRecord<IEmailEvent> & {
+    _id: Types.ObjectId;
+} & {
+    __v: number;
+}>;
+
+interface IAnalyticsStats {
+    date: string;
+    interval: AggregationInterval;
+    accountId: Types.ObjectId | null;
+    ruleId: Types.ObjectId | null;
+    templateId: Types.ObjectId | null;
+    sent: number;
+    delivered: number;
+    bounced: number;
+    complained: number;
+    opened: number;
+    clicked: number;
+    unsubscribed: number;
+    failed: number;
+    createdAt: Date;
+    updatedAt: Date;
+}
+type AnalyticsStatsDocument = HydratedDocument<IAnalyticsStats>;
+interface AnalyticsStatsStatics {
+    upsertStats(date: string, interval: AggregationInterval, dimensions: {
+        accountId?: string;
+        ruleId?: string;
+        templateId?: string;
+    }, increments: Partial<Record<'sent' | 'delivered' | 'bounced' | 'complained' | 'opened' | 'clicked' | 'unsubscribed' | 'failed', number>>): Promise<AnalyticsStatsDocument>;
+}
+type AnalyticsStatsModel = Model<IAnalyticsStats> & AnalyticsStatsStatics;
+interface CreateAnalyticsStatsSchemaOptions {
+    collectionName?: string;
+}
+declare function createAnalyticsStatsSchema(options?: CreateAnalyticsStatsSchemaOptions): Schema<IAnalyticsStats, Model<IAnalyticsStats, any, any, any, mongoose.Document<unknown, any, IAnalyticsStats, any, {}> & IAnalyticsStats & {
+    _id: Types.ObjectId;
+} & {
+    __v: number;
+}, any>, {}, {}, {}, {}, mongoose.DefaultSchemaOptions, IAnalyticsStats, mongoose.Document<unknown, {}, mongoose.FlatRecord<IAnalyticsStats>, {}, mongoose.DefaultSchemaOptions> & mongoose.FlatRecord<IAnalyticsStats> & {
+    _id: Types.ObjectId;
+} & {
+    __v: number;
+}>;
+
+type EmailEvent = IEmailEvent;
+interface CreateEventInput {
+    type: EventType;
+    accountId: string;
+    ruleId?: string;
+    templateId?: string;
+    recipientEmail: string;
+    identifierId?: string;
+    metadata?: Record<string, unknown>;
+    timestamp?: Date;
+}
+
+interface EventQueryFilters {
+    dateFrom: Date;
+    dateTo: Date;
+    type?: string;
+    accountId?: string;
+    ruleId?: string;
+    recipientEmail?: string;
+}
+interface PaginatedEvents {
+    events: EmailEvent[];
+    total: number;
+}
+declare class EventRecorderService {
+    private EmailEvent;
+    private logger;
+    constructor(EmailEvent: EmailEventModel, logger: LogAdapter);
+    record(event: CreateEventInput): Promise<void>;
+    recordBatch(events: CreateEventInput[]): Promise<void>;
+    getEvents(filters: EventQueryFilters, page?: number, limit?: number): Promise<PaginatedEvents>;
+    purgeOldEvents(olderThanDays: number): Promise<number>;
+}
+
+declare class AggregatorService {
+    private EmailEvent;
+    private AnalyticsStats;
+    private timezone;
+    private logger;
+    constructor(EmailEvent: EmailEventModel, AnalyticsStats: AnalyticsStatsModel, timezone: string, logger: LogAdapter);
+    aggregateDaily(date?: Date): Promise<void>;
+    aggregateRange(from: Date, to: Date): Promise<void>;
+    private aggregateByAccount;
+    private aggregateByRule;
+    private aggregateByTemplate;
+    private aggregateOverall;
+    private getDayStart;
+    private getDayEnd;
+    private getTimezoneOffsetMs;
+    private toDateKey;
+}
+
+interface BaseMetrics {
+    sent: number;
+    delivered: number;
+    bounced: number;
+    complained: number;
+    opened: number;
+    clicked: number;
+    unsubscribed: number;
+    failed: number;
+}
+interface DailyStats extends BaseMetrics {
+    date: string;
+}
+interface AccountStats extends BaseMetrics {
+    accountId: string;
+}
+interface RuleStats extends BaseMetrics {
+    ruleId: string;
+}
+interface TemplateStats extends BaseMetrics {
+    templateId: string;
+}
+interface OverviewStats extends BaseMetrics {
+    startDate: string;
+    endDate: string;
+}
+interface TimelineEntry extends BaseMetrics {
+    date: string;
+    interval: AggregationInterval;
+}
+
+declare class QueryService {
+    private AnalyticsStats;
+    private logger;
+    constructor(AnalyticsStats: AnalyticsStatsModel, logger: LogAdapter);
+    getOverview(dateFrom: Date, dateTo: Date): Promise<OverviewStats>;
+    getTimeline(dateFrom: Date, dateTo: Date, interval?: AggregationInterval): Promise<TimelineEntry[]>;
+    getAccountStats(dateFrom: Date, dateTo: Date): Promise<AccountStats[]>;
+    getRuleStats(dateFrom: Date, dateTo: Date): Promise<RuleStats[]>;
+    getTemplateStats(dateFrom: Date, dateTo: Date): Promise<TemplateStats[]>;
+    private buildTimeGroupId;
+    private toDateKey;
+}
+
+declare class AlxAnalyticsError extends AlxError {
+    readonly code: string;
+    constructor(message: string, code: string);
+}
+
+declare class InvalidDateRangeError extends AlxAnalyticsError {
+    readonly startDate: string;
+    readonly endDate: string;
+    constructor(startDate: string, endDate: string);
+}
+declare class AggregationError extends AlxAnalyticsError {
+    readonly pipeline: string;
+    readonly originalError: Error;
+    constructor(pipeline: string, originalError: Error);
+}
+
+declare function validateConfig(raw: unknown): void;
+
+declare function createAnalyticsController(eventRecorder: EventRecorderService, aggregator: AggregatorService, queryService: QueryService): {
+    getOverview(req: Request, res: Response): Promise<Response<any, Record<string, any>> | undefined>;
+    getTimeline(req: Request, res: Response): Promise<Response<any, Record<string, any>> | undefined>;
+    getAccountStats(req: Request, res: Response): Promise<Response<any, Record<string, any>> | undefined>;
+    getRuleStats(req: Request, res: Response): Promise<Response<any, Record<string, any>> | undefined>;
+    getTemplateStats(req: Request, res: Response): Promise<Response<any, Record<string, any>> | undefined>;
+    triggerAggregation(req: Request, res: Response): Promise<Response<any, Record<string, any>> | undefined>;
+};
+
+type AnalyticsController = ReturnType<typeof createAnalyticsController>;
+declare function createAnalyticsRoutes(controller: AnalyticsController): Router;
+
+interface EmailAnalytics {
+    routes: Router;
+    events: EventRecorderService;
+    aggregator: AggregatorService;
+    query: QueryService;
+    models: {
+        EmailEvent: EmailEventModel;
+        AnalyticsStats: AnalyticsStatsModel;
+    };
+}
+declare function createEmailAnalytics(config: EmailAnalyticsConfig): EmailAnalytics;
+
+export { AGGREGATION_INTERVAL, type AccountStats, AggregationError, type AggregationInterval, AggregatorService, AlxAnalyticsError, type AnalyticsStatsDocument, type AnalyticsStatsModel, type AnalyticsStatsStatics, type BaseMetrics, type CreateAnalyticsStatsSchemaOptions, type CreateEmailEventSchemaOptions, type CreateEventInput, type DailyStats, EVENT_TYPE, type EmailAnalytics, type EmailAnalyticsConfig, type EmailEvent, type EmailEventDocument, type EmailEventModel, type EmailEventStatics, type EventQueryFilters, EventRecorderService, type EventType, type IAnalyticsStats, type IEmailEvent, InvalidDateRangeError, type OverviewStats, type PaginatedEvents, QueryService, type RuleStats, STATS_GROUP_BY, type StatsGroupBy, type TemplateStats, type TimelineEntry, createAnalyticsController, createAnalyticsRoutes, createAnalyticsStatsSchema, createEmailAnalytics, createEmailEventSchema, validateConfig };

package/dist/index.d.ts

@@ -0,0 +1,267 @@
+import { Request, Response, Router } from 'express';
+import * as mongoose from 'mongoose';
+import { Connection, Model, Types, HydratedDocument, Schema } from 'mongoose';
+import { LogAdapter, AlxError } from '@astralibx/core';
+export { ConfigValidationError } from '@astralibx/core';
+
+declare const EVENT_TYPE: {
+    readonly Sent: "sent";
+    readonly Delivered: "delivered";
+    readonly Bounced: "bounced";
+    readonly Complained: "complained";
+    readonly Opened: "opened";
+    readonly Clicked: "clicked";
+    readonly Unsubscribed: "unsubscribed";
+    readonly Failed: "failed";
+};
+type EventType = (typeof EVENT_TYPE)[keyof typeof EVENT_TYPE];
+declare const AGGREGATION_INTERVAL: {
+    readonly Daily: "daily";
+    readonly Weekly: "weekly";
+    readonly Monthly: "monthly";
+};
+type AggregationInterval = (typeof AGGREGATION_INTERVAL)[keyof typeof AGGREGATION_INTERVAL];
+declare const STATS_GROUP_BY: {
+    readonly Account: "account";
+    readonly Rule: "rule";
+    readonly Template: "template";
+};
+type StatsGroupBy = (typeof STATS_GROUP_BY)[keyof typeof STATS_GROUP_BY];
+
+interface EmailAnalyticsConfig {
+    db: {
+        connection: Connection;
+        collectionPrefix?: string;
+    };
+    logger?: LogAdapter;
+    options?: {
+        eventTTLDays?: number;
+        timezone?: string;
+        aggregationSchedule?: AggregationInterval[];
+    };
+}
+
+interface IEmailEvent {
+    type: EventType;
+    accountId: Types.ObjectId;
+    ruleId?: Types.ObjectId;
+    templateId?: Types.ObjectId;
+    recipientEmail: string;
+    identifierId?: Types.ObjectId;
+    metadata?: Record<string, unknown>;
+    timestamp: Date;
+    createdAt: Date;
+    updatedAt: Date;
+}
+type EmailEventDocument = HydratedDocument<IEmailEvent>;
+interface EmailEventStatics {
+    record(event: {
+        type: EventType;
+        accountId: string;
+        ruleId?: string;
+        templateId?: string;
+        recipientEmail: string;
+        identifierId?: string;
+        metadata?: Record<string, unknown>;
+        timestamp?: Date;
+    }): Promise<EmailEventDocument>;
+    findByDateRange(start: Date, end: Date, filters?: {
+        type?: EventType;
+        accountId?: string;
+        ruleId?: string;
+        templateId?: string;
+    }): Promise<EmailEventDocument[]>;
+}
+type EmailEventModel = Model<IEmailEvent> & EmailEventStatics;
+interface CreateEmailEventSchemaOptions {
+    collectionName?: string;
+    eventTTLDays?: number;
+}
+declare function createEmailEventSchema(options?: CreateEmailEventSchemaOptions): Schema<IEmailEvent, Model<IEmailEvent, any, any, any, mongoose.Document<unknown, any, IEmailEvent, any, {}> & IEmailEvent & {
+    _id: Types.ObjectId;
+} & {
+    __v: number;
+}, any>, {}, {}, {}, {}, mongoose.DefaultSchemaOptions, IEmailEvent, mongoose.Document<unknown, {}, mongoose.FlatRecord<IEmailEvent>, {}, mongoose.DefaultSchemaOptions> & mongoose.FlatRecord<IEmailEvent> & {
+    _id: Types.ObjectId;
+} & {
+    __v: number;
+}>;
+
+interface IAnalyticsStats {
+    date: string;
+    interval: AggregationInterval;
+    accountId: Types.ObjectId | null;
+    ruleId: Types.ObjectId | null;
+    templateId: Types.ObjectId | null;
+    sent: number;
+    delivered: number;
+    bounced: number;
+    complained: number;
+    opened: number;
+    clicked: number;
+    unsubscribed: number;
+    failed: number;
+    createdAt: Date;
+    updatedAt: Date;
+}
+type AnalyticsStatsDocument = HydratedDocument<IAnalyticsStats>;
+interface AnalyticsStatsStatics {
+    upsertStats(date: string, interval: AggregationInterval, dimensions: {
+        accountId?: string;
+        ruleId?: string;
+        templateId?: string;
+    }, increments: Partial<Record<'sent' | 'delivered' | 'bounced' | 'complained' | 'opened' | 'clicked' | 'unsubscribed' | 'failed', number>>): Promise<AnalyticsStatsDocument>;
+}
+type AnalyticsStatsModel = Model<IAnalyticsStats> & AnalyticsStatsStatics;
+interface CreateAnalyticsStatsSchemaOptions {
+    collectionName?: string;
+}
+declare function createAnalyticsStatsSchema(options?: CreateAnalyticsStatsSchemaOptions): Schema<IAnalyticsStats, Model<IAnalyticsStats, any, any, any, mongoose.Document<unknown, any, IAnalyticsStats, any, {}> & IAnalyticsStats & {
+    _id: Types.ObjectId;
+} & {
+    __v: number;
+}, any>, {}, {}, {}, {}, mongoose.DefaultSchemaOptions, IAnalyticsStats, mongoose.Document<unknown, {}, mongoose.FlatRecord<IAnalyticsStats>, {}, mongoose.DefaultSchemaOptions> & mongoose.FlatRecord<IAnalyticsStats> & {
+    _id: Types.ObjectId;
+} & {
+    __v: number;
+}>;
+
+type EmailEvent = IEmailEvent;
+interface CreateEventInput {
+    type: EventType;
+    accountId: string;
+    ruleId?: string;
+    templateId?: string;
+    recipientEmail: string;
+    identifierId?: string;
+    metadata?: Record<string, unknown>;
+    timestamp?: Date;
+}
+
+interface EventQueryFilters {
+    dateFrom: Date;
+    dateTo: Date;
+    type?: string;
+    accountId?: string;
+    ruleId?: string;
+    recipientEmail?: string;
+}
+interface PaginatedEvents {
+    events: EmailEvent[];
+    total: number;
+}
+declare class EventRecorderService {
+    private EmailEvent;
+    private logger;
+    constructor(EmailEvent: EmailEventModel, logger: LogAdapter);
+    record(event: CreateEventInput): Promise<void>;
+    recordBatch(events: CreateEventInput[]): Promise<void>;
+    getEvents(filters: EventQueryFilters, page?: number, limit?: number): Promise<PaginatedEvents>;
+    purgeOldEvents(olderThanDays: number): Promise<number>;
+}
+
+declare class AggregatorService {
+    private EmailEvent;
+    private AnalyticsStats;
+    private timezone;
+    private logger;
+    constructor(EmailEvent: EmailEventModel, AnalyticsStats: AnalyticsStatsModel, timezone: string, logger: LogAdapter);
+    aggregateDaily(date?: Date): Promise<void>;
+    aggregateRange(from: Date, to: Date): Promise<void>;
+    private aggregateByAccount;
+    private aggregateByRule;
+    private aggregateByTemplate;
+    private aggregateOverall;
+    private getDayStart;
+    private getDayEnd;
+    private getTimezoneOffsetMs;
+    private toDateKey;
+}
+
+interface BaseMetrics {
+    sent: number;
+    delivered: number;
+    bounced: number;
+    complained: number;
+    opened: number;
+    clicked: number;
+    unsubscribed: number;
+    failed: number;
+}
+interface DailyStats extends BaseMetrics {
+    date: string;
+}
+interface AccountStats extends BaseMetrics {
+    accountId: string;
+}
+interface RuleStats extends BaseMetrics {
+    ruleId: string;
+}
+interface TemplateStats extends BaseMetrics {
+    templateId: string;
+}
+interface OverviewStats extends BaseMetrics {
+    startDate: string;
+    endDate: string;
+}
+interface TimelineEntry extends BaseMetrics {
+    date: string;
+    interval: AggregationInterval;
+}
+
+declare class QueryService {
+    private AnalyticsStats;
+    private logger;
+    constructor(AnalyticsStats: AnalyticsStatsModel, logger: LogAdapter);
+    getOverview(dateFrom: Date, dateTo: Date): Promise<OverviewStats>;
+    getTimeline(dateFrom: Date, dateTo: Date, interval?: AggregationInterval): Promise<TimelineEntry[]>;
+    getAccountStats(dateFrom: Date, dateTo: Date): Promise<AccountStats[]>;
+    getRuleStats(dateFrom: Date, dateTo: Date): Promise<RuleStats[]>;
+    getTemplateStats(dateFrom: Date, dateTo: Date): Promise<TemplateStats[]>;
+    private buildTimeGroupId;
+    private toDateKey;
+}
+
+declare class AlxAnalyticsError extends AlxError {
+    readonly code: string;
+    constructor(message: string, code: string);
+}
+
+declare class InvalidDateRangeError extends AlxAnalyticsError {
+    readonly startDate: string;
+    readonly endDate: string;
+    constructor(startDate: string, endDate: string);
+}
+declare class AggregationError extends AlxAnalyticsError {
+    readonly pipeline: string;
+    readonly originalError: Error;
+    constructor(pipeline: string, originalError: Error);
+}
+
+declare function validateConfig(raw: unknown): void;
+
+declare function createAnalyticsController(eventRecorder: EventRecorderService, aggregator: AggregatorService, queryService: QueryService): {
+    getOverview(req: Request, res: Response): Promise<Response<any, Record<string, any>> | undefined>;
+    getTimeline(req: Request, res: Response): Promise<Response<any, Record<string, any>> | undefined>;
+    getAccountStats(req: Request, res: Response): Promise<Response<any, Record<string, any>> | undefined>;
+    getRuleStats(req: Request, res: Response): Promise<Response<any, Record<string, any>> | undefined>;
+    getTemplateStats(req: Request, res: Response): Promise<Response<any, Record<string, any>> | undefined>;
+    triggerAggregation(req: Request, res: Response): Promise<Response<any, Record<string, any>> | undefined>;
+};
+
+type AnalyticsController = ReturnType<typeof createAnalyticsController>;
+declare function createAnalyticsRoutes(controller: AnalyticsController): Router;
+
+interface EmailAnalytics {
+    routes: Router;
+    events: EventRecorderService;
+    aggregator: AggregatorService;
+    query: QueryService;
+    models: {
+        EmailEvent: EmailEventModel;
+        AnalyticsStats: AnalyticsStatsModel;
+    };
+}
+declare function createEmailAnalytics(config: EmailAnalyticsConfig): EmailAnalytics;
+
+export { AGGREGATION_INTERVAL, type AccountStats, AggregationError, type AggregationInterval, AggregatorService, AlxAnalyticsError, type AnalyticsStatsDocument, type AnalyticsStatsModel, type AnalyticsStatsStatics, type BaseMetrics, type CreateAnalyticsStatsSchemaOptions, type CreateEmailEventSchemaOptions, type CreateEventInput, type DailyStats, EVENT_TYPE, type EmailAnalytics, type EmailAnalyticsConfig, type EmailEvent, type EmailEventDocument, type EmailEventModel, type EmailEventStatics, type EventQueryFilters, EventRecorderService, type EventType, type IAnalyticsStats, type IEmailEvent, InvalidDateRangeError, type OverviewStats, type PaginatedEvents, QueryService, type RuleStats, STATS_GROUP_BY, type StatsGroupBy, type TemplateStats, type TimelineEntry, createAnalyticsController, createAnalyticsRoutes, createAnalyticsStatsSchema, createEmailAnalytics, createEmailEventSchema, validateConfig };