nandi.uk
This repository has no description
1// DTOs for User Statistics
2
3export interface UserGrowthDataPoint {
4 date: string; // ISO date string for chart x-axis
5 totalUsers: number; // Cumulative total users up to this date
6 newUsers: number; // New users added in this period
7}
8
9export interface UserGrowthStatsDTO {
10 dataPoints: UserGrowthDataPoint[];
11 currentTotal: number;
12 periodStart: string;
13 periodEnd: string;
14}
15
16export type TimeInterval = 'day' | 'week' | 'month';
17
18export interface UserGrowthStatsOptions {
19 interval: TimeInterval;
20 limit: number; // Number of intervals to return
21}
22
23// User Engagement Statistics DTOs
24
25export interface UserEngagementDataPoint {
26 date: string;
27 activeUsers: number; // Users who created content in this period
28 newlyActivatedUsers: number; // Previously inactive users who became active
29 cumulativeActiveUsers: number; // Total active users up to this date
30}
31
32export interface UserEngagementStatsDTO {
33 // Snapshot data
34 totalUsers: number;
35 activeUsers: number; // Created any content
36 inactiveUsers: number; // Signed in, no content
37
38 // Activity breakdown
39 usersWithCards: number;
40 usersWithCollections: number;
41 usersWithConnections: number;
42 usersWithFollows: number;
43 usersWithContributions: number; // Added cards to others' collections
44
45 // Engagement metrics
46 activationRate: number; // activeUsers / totalUsers
47 avgActionsPerActiveUser: number;
48
49 // Optional: Time series for trends
50 dataPoints?: UserEngagementDataPoint[];
51}
52
53export interface UserEngagementStatsOptions {
54 interval?: TimeInterval; // For time series
55 limit?: number; // For time series
56 includeTimeSeries?: boolean;
57}
58
59// Daily Activity Statistics DTOs
60
61export interface DailyActivityDataPoint {
62 date: string; // ISO date string
63 cardsCreated: number;
64 collectionsCreated: number;
65 connectionsCreated: number;
66 followsCreated: number;
67 totalActions: number; // Sum of all above
68}
69
70export interface DailyActivityStatsDTO {
71 dataPoints: DailyActivityDataPoint[];
72 totals: {
73 cardsCreated: number;
74 collectionsCreated: number;
75 connectionsCreated: number;
76 followsCreated: number;
77 totalActions: number;
78 };
79 periodStart: string;
80 periodEnd: string;
81}
82
83export interface DailyActivityStatsOptions {
84 interval: TimeInterval; // day, week, month
85 limit: number; // Number of intervals to return
86}
87
88// Content Breakdown Statistics DTOs
89
90export interface ContentBreakdownDataPoint {
91 date: string; // ISO date string
92
93 // URL Cards breakdown
94 urlCards: {
95 total: number;
96 byType: Record<string, number>; // e.g., { "article": 50, "video": 30, "tool": 20 }
97 };
98
99 // Collections breakdown
100 collections: {
101 total: number;
102 byAccessType: Record<string, number>; // e.g., { "OPEN": 80, "CLOSED": 45 }
103 };
104
105 // Connections breakdown
106 connections: {
107 total: number;
108 byType: Record<string, number>; // e.g., { "SUPPORTS": 30, "OPPOSES": 20, null: 15 }
109 };
110}
111
112export interface ContentBreakdownStatsDTO {
113 dataPoints: ContentBreakdownDataPoint[];
114
115 // Current totals (latest snapshot)
116 currentTotals: {
117 urlCards: {
118 total: number;
119 byType: Record<string, number>;
120 };
121 collections: {
122 total: number;
123 byAccessType: Record<string, number>;
124 };
125 connections: {
126 total: number;
127 byType: Record<string, number>;
128 };
129 };
130
131 periodStart: string;
132 periodEnd: string;
133}
134
135export interface ContentBreakdownStatsOptions {
136 interval: TimeInterval; // day, week, month
137 limit: number; // Number of intervals to return
138}
139
140// Future stat types can be added here
141export type UserStatType = 'growth' | 'activity' | 'engagement' | 'breakdown';
142
143/**
144 * Repository interface for user statistics and analytics queries
145 * This is a read-only query repository focused on aggregations and time-series data
146 */
147export interface IUserStatsRepository {
148 /**
149 * Get user growth statistics over time
150 * Returns cumulative user counts with period-over-period growth
151 */
152 getUserGrowthStats(
153 options: UserGrowthStatsOptions,
154 ): Promise<UserGrowthStatsDTO>;
155
156 /**
157 * Get user engagement statistics
158 * Returns active vs inactive users with content breakdown
159 */
160 getUserEngagementStats(
161 options: UserEngagementStatsOptions,
162 ): Promise<UserEngagementStatsDTO>;
163
164 /**
165 * Get daily activity statistics
166 * Returns content creation volume over time periods
167 */
168 getDailyActivityStats(
169 options: DailyActivityStatsOptions,
170 ): Promise<DailyActivityStatsDTO>;
171
172 /**
173 * Get content breakdown statistics
174 * Returns cumulative content totals broken down by subtypes over time
175 */
176 getContentBreakdownStats(
177 options: ContentBreakdownStatsOptions,
178 ): Promise<ContentBreakdownStatsDTO>;
179}