@iann29/rastro 0.1.0-alpha.1 → 0.1.0-alpha.11

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (179) hide show
  1. package/README.md +693 -69
  2. package/agent/integration.md +801 -0
  3. package/agent/manifest.json +205 -0
  4. package/agent/manifest.schema.json +444 -0
  5. package/dist/client/federation.d.ts +381 -0
  6. package/dist/client/federation.d.ts.map +1 -0
  7. package/dist/client/federation.js +274 -0
  8. package/dist/client/federation.js.map +1 -0
  9. package/dist/client/index.d.ts +2673 -15
  10. package/dist/client/index.d.ts.map +1 -1
  11. package/dist/client/index.js +565 -33
  12. package/dist/client/index.js.map +1 -1
  13. package/dist/component/_generated/api.d.ts +22 -0
  14. package/dist/component/_generated/api.d.ts.map +1 -1
  15. package/dist/component/_generated/api.js.map +1 -1
  16. package/dist/component/_generated/component.d.ts +315 -4
  17. package/dist/component/_generated/component.d.ts.map +1 -1
  18. package/dist/component/_generated/server.d.ts +4 -0
  19. package/dist/component/_generated/server.d.ts.map +1 -1
  20. package/dist/component/_generated/server.js.map +1 -1
  21. package/dist/component/affiliates.d.ts.map +1 -1
  22. package/dist/component/affiliates.js +6 -2
  23. package/dist/component/affiliates.js.map +1 -1
  24. package/dist/component/cardinality.d.ts +12 -0
  25. package/dist/component/cardinality.d.ts.map +1 -0
  26. package/dist/component/cardinality.js +94 -0
  27. package/dist/component/cardinality.js.map +1 -0
  28. package/dist/component/constants.d.ts +28 -1
  29. package/dist/component/constants.d.ts.map +1 -1
  30. package/dist/component/constants.js +44 -1
  31. package/dist/component/constants.js.map +1 -1
  32. package/dist/component/convex.config.d.ts +6 -1
  33. package/dist/component/convex.config.js +9 -1
  34. package/dist/component/convex.config.js.map +1 -1
  35. package/dist/component/coverage.d.ts +27 -0
  36. package/dist/component/coverage.d.ts.map +1 -0
  37. package/dist/component/coverage.js +56 -0
  38. package/dist/component/coverage.js.map +1 -0
  39. package/dist/component/diagnostics.d.ts +9 -0
  40. package/dist/component/diagnostics.d.ts.map +1 -0
  41. package/dist/component/diagnostics.js +47 -0
  42. package/dist/component/diagnostics.js.map +1 -0
  43. package/dist/component/errors.d.ts +1 -1
  44. package/dist/component/errors.d.ts.map +1 -1
  45. package/dist/component/errors.js.map +1 -1
  46. package/dist/component/eventStore.d.ts +21 -9
  47. package/dist/component/eventStore.d.ts.map +1 -1
  48. package/dist/component/eventStore.js +142 -152
  49. package/dist/component/eventStore.js.map +1 -1
  50. package/dist/component/funnels.d.ts.map +1 -1
  51. package/dist/component/funnels.js +5 -3
  52. package/dist/component/funnels.js.map +1 -1
  53. package/dist/component/geo.d.ts +73 -0
  54. package/dist/component/geo.d.ts.map +1 -0
  55. package/dist/component/geo.js +648 -0
  56. package/dist/component/geo.js.map +1 -0
  57. package/dist/component/goals.d.ts.map +1 -1
  58. package/dist/component/goals.js +8 -5
  59. package/dist/component/goals.js.map +1 -1
  60. package/dist/component/guards.d.ts.map +1 -1
  61. package/dist/component/guards.js.map +1 -1
  62. package/dist/component/http.d.ts.map +1 -1
  63. package/dist/component/http.js +281 -62
  64. package/dist/component/http.js.map +1 -1
  65. package/dist/component/identity.d.ts +13 -0
  66. package/dist/component/identity.d.ts.map +1 -0
  67. package/dist/component/identity.js +58 -0
  68. package/dist/component/identity.js.map +1 -0
  69. package/dist/component/ingest.d.ts +3 -1
  70. package/dist/component/ingest.d.ts.map +1 -1
  71. package/dist/component/ingest.js +498 -95
  72. package/dist/component/ingest.js.map +1 -1
  73. package/dist/component/live.d.ts.map +1 -1
  74. package/dist/component/live.js +7 -6
  75. package/dist/component/live.js.map +1 -1
  76. package/dist/component/localTime.d.ts +25 -0
  77. package/dist/component/localTime.d.ts.map +1 -0
  78. package/dist/component/localTime.js +126 -0
  79. package/dist/component/localTime.js.map +1 -0
  80. package/dist/component/reports.d.ts +266 -10
  81. package/dist/component/reports.d.ts.map +1 -1
  82. package/dist/component/reports.js +1243 -137
  83. package/dist/component/reports.js.map +1 -1
  84. package/dist/component/retention.d.ts +75 -1
  85. package/dist/component/retention.d.ts.map +1 -1
  86. package/dist/component/retention.js +561 -38
  87. package/dist/component/retention.js.map +1 -1
  88. package/dist/component/rollupStore.d.ts +320 -0
  89. package/dist/component/rollupStore.d.ts.map +1 -0
  90. package/dist/component/rollupStore.js +596 -0
  91. package/dist/component/rollupStore.js.map +1 -0
  92. package/dist/component/rollups.d.ts +20 -0
  93. package/dist/component/rollups.d.ts.map +1 -0
  94. package/dist/component/rollups.js +73 -0
  95. package/dist/component/rollups.js.map +1 -0
  96. package/dist/component/sanitize.d.ts +24 -1
  97. package/dist/component/sanitize.d.ts.map +1 -1
  98. package/dist/component/sanitize.js +96 -16
  99. package/dist/component/sanitize.js.map +1 -1
  100. package/dist/component/schema.d.ts +687 -65
  101. package/dist/component/schema.js +187 -20
  102. package/dist/component/schema.js.map +1 -1
  103. package/dist/component/sites.d.ts +12 -0
  104. package/dist/component/sites.d.ts.map +1 -1
  105. package/dist/component/sites.js +41 -7
  106. package/dist/component/sites.js.map +1 -1
  107. package/dist/component/useragent.d.ts +9 -0
  108. package/dist/component/useragent.d.ts.map +1 -0
  109. package/dist/component/useragent.js +152 -0
  110. package/dist/component/useragent.js.map +1 -0
  111. package/dist/component/validators.d.ts +124 -69
  112. package/dist/component/validators.d.ts.map +1 -1
  113. package/dist/component/validators.js +35 -14
  114. package/dist/component/validators.js.map +1 -1
  115. package/dist/component/visitors.d.ts +19 -0
  116. package/dist/component/visitors.d.ts.map +1 -0
  117. package/dist/component/visitors.js +86 -0
  118. package/dist/component/visitors.js.map +1 -0
  119. package/dist/component/vitals.d.ts +41 -0
  120. package/dist/component/vitals.d.ts.map +1 -0
  121. package/dist/component/vitals.js +115 -0
  122. package/dist/component/vitals.js.map +1 -0
  123. package/dist/react/index.d.ts.map +1 -1
  124. package/dist/react/index.js.map +1 -1
  125. package/dist/tracker/generated.d.ts +11 -4
  126. package/dist/tracker/generated.d.ts.map +1 -1
  127. package/dist/tracker/generated.js +11 -4
  128. package/dist/tracker/generated.js.map +1 -1
  129. package/dist/tracker/tracker.d.ts +1 -1
  130. package/dist/tracker/tracker.d.ts.map +1 -1
  131. package/dist/tracker/tracker.js +57 -20
  132. package/dist/tracker/tracker.js.map +1 -1
  133. package/dist/tracker/vitals.d.ts +10 -0
  134. package/dist/tracker/vitals.d.ts.map +1 -0
  135. package/dist/tracker/vitals.js +140 -0
  136. package/dist/tracker/vitals.js.map +1 -0
  137. package/dist/tracker.min.js +1 -1
  138. package/dist/vitals.min.js +1 -0
  139. package/docs/benchmarks/2026-08-20-realistic.md +76 -76
  140. package/docs/benchmarks/2026-08-21-formal-certification.md +353 -0
  141. package/docs/benchmarks/2026-08-30-alpha6-recertification.md +206 -0
  142. package/docs/federation-setup.md +464 -0
  143. package/docs/federation.md +352 -0
  144. package/docs/upgrading.md +344 -0
  145. package/llms.txt +72 -0
  146. package/package.json +55 -11
  147. package/scripts/benchmark-ingest.mjs +175 -73
  148. package/scripts/generate-federation-keys.mjs +20 -0
  149. package/src/component/_generated/api.ts +22 -0
  150. package/src/component/_generated/component.ts +381 -4
  151. package/src/component/_generated/server.ts +4 -0
  152. package/src/component/affiliates.ts +20 -5
  153. package/src/component/cardinality.ts +117 -0
  154. package/src/component/constants.ts +44 -1
  155. package/src/component/convex.config.ts +11 -1
  156. package/src/component/coverage.ts +71 -0
  157. package/src/component/diagnostics.ts +65 -0
  158. package/src/component/errors.ts +2 -1
  159. package/src/component/eventStore.ts +217 -193
  160. package/src/component/funnels.ts +19 -16
  161. package/src/component/geo.ts +835 -0
  162. package/src/component/goals.ts +29 -21
  163. package/src/component/guards.ts +3 -1
  164. package/src/component/http.ts +404 -70
  165. package/src/component/identity.ts +74 -0
  166. package/src/component/ingest.ts +894 -188
  167. package/src/component/live.ts +13 -7
  168. package/src/component/localTime.ts +167 -0
  169. package/src/component/reports.ts +1872 -197
  170. package/src/component/retention.ts +788 -96
  171. package/src/component/rollupStore.ts +799 -0
  172. package/src/component/rollups.ts +82 -0
  173. package/src/component/sanitize.ts +144 -29
  174. package/src/component/schema.ts +217 -21
  175. package/src/component/sites.ts +59 -12
  176. package/src/component/useragent.ts +171 -0
  177. package/src/component/validators.ts +49 -14
  178. package/src/component/visitors.ts +116 -0
  179. package/src/component/vitals.ts +146 -0
@@ -1,9 +1,16 @@
1
1
  import { v } from "convex/values";
2
- import { mutation } from "./_generated/server.js";
3
- import { MAX_RETENTION_BATCH } from "./constants.js";
2
+ import { internal } from "./_generated/api.js";
3
+ import { internalMutation, mutation, query } from "./_generated/server.js";
4
+ import { DAY_MS, HOUR_MS, MAX_RETENTION_BATCH, MINUTE_MS, RATE_LIMIT_WINDOW_MS, RETENTION_LEASE_MS, RETENTION_POLICY_INTERVAL_MS, } from "./constants.js";
5
+ import { ensureAnalyticsControl } from "./coverage.js";
4
6
  import { fail } from "./errors.js";
5
7
  import { deleteTelemetryBefore } from "./eventStore.js";
6
- const cleanupKindValidator = v.union(v.literal("events"), v.literal("sessions"), v.literal("conversions"), v.literal("goalCompletions"), v.literal("aggregateHour"), v.literal("aggregateDay"), v.literal("funnelProgress"), v.literal("funnelSteps"), v.literal("affiliateStats"), v.literal("attributions"), v.literal("liveSessions"), v.literal("ingestWindows"), v.literal("siteIngestWindows"));
8
+ export const cleanupKindValidator = v.union(v.literal("events"), v.literal("sessions"), v.literal("conversions"), v.literal("goalCompletions"), v.literal("aggregateHour"), v.literal("aggregateDay"), v.literal("funnelProgress"), v.literal("funnelSteps"), v.literal("affiliateStats"), v.literal("goalRollups"), v.literal("funnelRollups"), v.literal("affiliateRollups"), v.literal("vitalRollups"), v.literal("siteMapRollups"), v.literal("attributions"), v.literal("liveSessions"), v.literal("ingestWindows"), v.literal("siteIngestWindows"));
9
+ const cleanupResultValidator = v.object({
10
+ deleted: v.number(),
11
+ hasMore: v.boolean(),
12
+ before: v.number(),
13
+ });
7
14
  export const cleanup = mutation({
8
15
  args: {
9
16
  siteId: v.id("sites"),
@@ -11,102 +18,618 @@ export const cleanup = mutation({
11
18
  before: v.number(),
12
19
  batchSize: v.optional(v.number()),
13
20
  },
14
- returns: v.object({ deleted: v.number(), hasMore: v.boolean() }),
21
+ returns: cleanupResultValidator,
22
+ handler: async (ctx, args) => {
23
+ const policy = await ctx.db
24
+ .query("retentionPolicies")
25
+ .withIndex("by_siteId", (range) => range.eq("siteId", args.siteId))
26
+ .unique();
27
+ if (policy) {
28
+ fail("CONFLICT", "disable the retention policy before running manual cleanup");
29
+ }
30
+ const before = safeCleanupBoundary(args.kind, args.before, Date.now());
31
+ const result = await executeCleanupBatch(ctx, { ...args, before });
32
+ await persistDirectState(ctx, { ...args, before }, result);
33
+ await recordRetentionBoundary(ctx, args.siteId, args.kind, before);
34
+ return { ...result, before };
35
+ },
36
+ });
37
+ const policyValidator = v.object({
38
+ eventsDays: v.number(),
39
+ sessionsDays: v.number(),
40
+ conversionsDays: v.number(),
41
+ aggregatesDays: v.number(),
42
+ reportsDays: v.number(),
43
+ });
44
+ export const setPolicy = mutation({
45
+ args: { siteId: v.id("sites"), ...policyValidator.fields },
46
+ returns: v.null(),
15
47
  handler: async (ctx, args) => {
16
- if (!Number.isFinite(args.before) || args.before < 0) {
17
- fail("INVALID_ARGUMENT", "before must be a positive timestamp");
48
+ validatePolicy(args);
49
+ const now = Date.now();
50
+ const existingPolicy = await ctx.db
51
+ .query("retentionPolicies")
52
+ .withIndex("by_siteId", (range) => range.eq("siteId", args.siteId))
53
+ .unique();
54
+ const policy = { ...args, updatedAt: now };
55
+ if (existingPolicy) {
56
+ await ctx.db.replace("retentionPolicies", existingPolicy._id, policy);
18
57
  }
19
- const batchSize = args.batchSize ?? 100;
20
- if (!Number.isSafeInteger(batchSize) || batchSize < 1 || batchSize > MAX_RETENTION_BATCH) {
21
- fail("INVALID_ARGUMENT", `batchSize must be an integer between 1 and ${MAX_RETENTION_BATCH}`);
58
+ else {
59
+ await ctx.db.insert("retentionPolicies", policy);
22
60
  }
23
- const effectiveBatchSize = args.kind === "events"
24
- ? Math.min(batchSize, 32)
25
- : batchSize;
26
- if (args.kind === "events") {
27
- return await deleteTelemetryBefore(ctx, {
61
+ for (const kind of POLICY_CLEANUP_KINDS) {
62
+ const requestedBefore = now - retentionDaysForKind(policy, kind) * DAY_MS;
63
+ const before = safeCleanupBoundary(kind, requestedBefore, now);
64
+ const existing = await loadState(ctx, args.siteId, kind);
65
+ const generation = (existing?.generation ?? 0) + 1;
66
+ const fields = {
28
67
  siteId: args.siteId,
29
- before: args.before,
30
- batchSize: effectiveBatchSize,
68
+ kind,
69
+ before,
70
+ status: "pending",
71
+ generation,
72
+ attempt: 0,
73
+ scheduledAt: now,
74
+ deleted: 0,
75
+ updatedAt: now,
76
+ };
77
+ const stateId = existing
78
+ ? (await ctx.db.replace("retentionStates", existing._id, fields),
79
+ existing._id)
80
+ : await ctx.db.insert("retentionStates", fields);
81
+ await ctx.scheduler.runAfter(0, internal.retention.runScheduled, {
82
+ stateId,
83
+ generation,
84
+ });
85
+ }
86
+ return null;
87
+ },
88
+ });
89
+ export const disablePolicy = mutation({
90
+ args: { siteId: v.id("sites") },
91
+ returns: v.null(),
92
+ handler: async (ctx, args) => {
93
+ const policy = await ctx.db
94
+ .query("retentionPolicies")
95
+ .withIndex("by_siteId", (range) => range.eq("siteId", args.siteId))
96
+ .unique();
97
+ if (policy)
98
+ await ctx.db.delete("retentionPolicies", policy._id);
99
+ const now = Date.now();
100
+ const states = await ctx.db
101
+ .query("retentionStates")
102
+ .withIndex("by_siteId_and_kind", (range) => range.eq("siteId", args.siteId))
103
+ .take(POLICY_CLEANUP_KINDS.length + 1);
104
+ for (const state of states) {
105
+ await ctx.db.patch("retentionStates", state._id, {
106
+ status: "complete",
107
+ generation: state.generation + 1,
108
+ leaseExpiresAt: undefined,
109
+ scheduledAt: undefined,
110
+ updatedAt: now,
31
111
  });
32
112
  }
33
- const deletions = await deletionsForCleanup(ctx, args.siteId, args.kind, args.before, effectiveBatchSize + 1);
34
- for (const remove of deletions.slice(0, effectiveBatchSize)) {
35
- await remove();
113
+ return null;
114
+ },
115
+ });
116
+ export const runPolicy = mutation({
117
+ args: {
118
+ siteId: v.id("sites"),
119
+ kind: cleanupKindValidator,
120
+ batchSize: v.optional(v.number()),
121
+ },
122
+ returns: cleanupResultValidator,
123
+ handler: async (ctx, args) => {
124
+ const policy = await ctx.db
125
+ .query("retentionPolicies")
126
+ .withIndex("by_siteId", (range) => range.eq("siteId", args.siteId))
127
+ .unique();
128
+ if (!policy)
129
+ fail("NOT_FOUND", "retention policy not found");
130
+ const now = Date.now();
131
+ const existing = await loadState(ctx, args.siteId, args.kind);
132
+ if (existing?.status === "running" &&
133
+ existing.leaseExpiresAt !== undefined &&
134
+ existing.leaseExpiresAt > now) {
135
+ return { deleted: 0, hasMore: true, before: existing.before };
36
136
  }
137
+ const before = existing && existing.status !== "complete"
138
+ ? existing.before
139
+ : safeCleanupBoundary(args.kind, now - retentionDaysForKind(policy, args.kind) * DAY_MS, now);
140
+ const result = await executeCleanupBatch(ctx, { ...args, before });
141
+ const generation = existing?.generation ?? 1;
142
+ const fields = {
143
+ siteId: args.siteId,
144
+ kind: args.kind,
145
+ before,
146
+ status: result.hasMore ? "pending" : "complete",
147
+ generation,
148
+ attempt: existing?.attempt ?? 0,
149
+ scheduledAt: result.hasMore ? now : now + RETENTION_POLICY_INTERVAL_MS,
150
+ deleted: existing?.before === before
151
+ ? existing.deleted + result.deleted
152
+ : result.deleted,
153
+ updatedAt: now,
154
+ };
155
+ const stateId = existing
156
+ ? (await ctx.db.replace("retentionStates", existing._id, fields),
157
+ existing._id)
158
+ : await ctx.db.insert("retentionStates", fields);
159
+ await recordRetentionBoundary(ctx, args.siteId, args.kind, before);
160
+ if (result.hasMore) {
161
+ await ctx.scheduler.runAfter(0, internal.retention.runScheduled, {
162
+ stateId,
163
+ generation,
164
+ });
165
+ }
166
+ else {
167
+ await ctx.scheduler.runAt(now + RETENTION_POLICY_INTERVAL_MS, internal.retention.startScheduledCycle, { stateId, generation });
168
+ }
169
+ return { ...result, before };
170
+ },
171
+ });
172
+ export const runScheduled = internalMutation({
173
+ args: { stateId: v.id("retentionStates"), generation: v.number() },
174
+ returns: v.object({
175
+ claimed: v.boolean(),
176
+ stale: v.boolean(),
177
+ attempt: v.number(),
178
+ }),
179
+ handler: async (ctx, args) => {
180
+ const state = await ctx.db.get("retentionStates", args.stateId);
181
+ const now = Date.now();
182
+ if (!state ||
183
+ state.generation !== args.generation ||
184
+ state.status === "complete" ||
185
+ (state.status === "running" &&
186
+ state.leaseExpiresAt !== undefined &&
187
+ state.leaseExpiresAt > now)) {
188
+ return { claimed: false, stale: true, attempt: state?.attempt ?? 0 };
189
+ }
190
+ const attempt = state.attempt + 1;
191
+ const leaseExpiresAt = now + RETENTION_LEASE_MS;
192
+ await ctx.db.patch("retentionStates", state._id, {
193
+ status: "running",
194
+ attempt,
195
+ leaseExpiresAt,
196
+ scheduledAt: now,
197
+ updatedAt: now,
198
+ });
199
+ await ctx.scheduler.runAfter(0, internal.retention.executeScheduled, {
200
+ stateId: state._id,
201
+ generation: state.generation,
202
+ attempt,
203
+ });
204
+ await ctx.scheduler.runAt(leaseExpiresAt, internal.retention.runScheduled, {
205
+ stateId: state._id,
206
+ generation: state.generation,
207
+ });
208
+ return { claimed: true, stale: false, attempt };
209
+ },
210
+ });
211
+ export const executeScheduled = internalMutation({
212
+ args: {
213
+ stateId: v.id("retentionStates"),
214
+ generation: v.number(),
215
+ attempt: v.number(),
216
+ },
217
+ returns: v.object({
218
+ deleted: v.number(),
219
+ hasMore: v.boolean(),
220
+ stale: v.boolean(),
221
+ }),
222
+ handler: async (ctx, args) => {
223
+ const state = await ctx.db.get("retentionStates", args.stateId);
224
+ if (!state ||
225
+ state.generation !== args.generation ||
226
+ state.attempt !== args.attempt ||
227
+ state.status !== "running") {
228
+ return { deleted: 0, hasMore: false, stale: true };
229
+ }
230
+ const result = await executeCleanupBatch(ctx, {
231
+ siteId: state.siteId,
232
+ kind: state.kind,
233
+ before: state.before,
234
+ batchSize: 100,
235
+ });
236
+ const now = Date.now();
237
+ const policy = result.hasMore
238
+ ? null
239
+ : await ctx.db
240
+ .query("retentionPolicies")
241
+ .withIndex("by_siteId", (range) => range.eq("siteId", state.siteId))
242
+ .unique();
243
+ const nextCycleAt = policy ? now + RETENTION_POLICY_INTERVAL_MS : undefined;
244
+ await ctx.db.patch("retentionStates", state._id, {
245
+ status: result.hasMore ? "pending" : "complete",
246
+ leaseExpiresAt: undefined,
247
+ scheduledAt: result.hasMore ? now : nextCycleAt,
248
+ deleted: state.deleted + result.deleted,
249
+ updatedAt: now,
250
+ });
251
+ await recordRetentionBoundary(ctx, state.siteId, state.kind, state.before);
252
+ if (result.hasMore) {
253
+ await ctx.scheduler.runAfter(0, internal.retention.runScheduled, {
254
+ stateId: state._id,
255
+ generation: state.generation,
256
+ });
257
+ }
258
+ else if (nextCycleAt !== undefined) {
259
+ await ctx.scheduler.runAt(nextCycleAt, internal.retention.startScheduledCycle, { stateId: state._id, generation: state.generation });
260
+ }
261
+ return { ...result, stale: false };
262
+ },
263
+ });
264
+ export const startScheduledCycle = internalMutation({
265
+ args: { stateId: v.id("retentionStates"), generation: v.number() },
266
+ returns: v.object({
267
+ started: v.boolean(),
268
+ stale: v.boolean(),
269
+ before: v.union(v.number(), v.null()),
270
+ }),
271
+ handler: async (ctx, args) => {
272
+ const state = await ctx.db.get("retentionStates", args.stateId);
273
+ const now = Date.now();
274
+ if (!state ||
275
+ state.generation !== args.generation ||
276
+ state.status !== "complete" ||
277
+ (state.scheduledAt !== undefined && state.scheduledAt > now)) {
278
+ return { started: false, stale: true, before: null };
279
+ }
280
+ const policy = await ctx.db
281
+ .query("retentionPolicies")
282
+ .withIndex("by_siteId", (range) => range.eq("siteId", state.siteId))
283
+ .unique();
284
+ if (!policy)
285
+ return { started: false, stale: true, before: null };
286
+ const kind = state.kind;
287
+ const before = safeCleanupBoundary(kind, now - retentionDaysForKind(policy, kind) * DAY_MS, now);
288
+ await ctx.db.patch("retentionStates", state._id, {
289
+ before,
290
+ status: "pending",
291
+ attempt: 0,
292
+ leaseExpiresAt: undefined,
293
+ scheduledAt: now,
294
+ deleted: 0,
295
+ updatedAt: now,
296
+ });
297
+ await ctx.scheduler.runAfter(0, internal.retention.runScheduled, {
298
+ stateId: state._id,
299
+ generation: state.generation,
300
+ });
301
+ return { started: true, stale: false, before };
302
+ },
303
+ });
304
+ export const status = query({
305
+ args: { siteId: v.id("sites") },
306
+ returns: v.object({
307
+ policy: v.union(policyValidator.extend({ updatedAt: v.number() }), v.null()),
308
+ jobs: v.array(v.object({
309
+ kind: cleanupKindValidator,
310
+ before: v.number(),
311
+ status: v.union(v.literal("pending"), v.literal("running"), v.literal("complete")),
312
+ deleted: v.number(),
313
+ scheduledAt: v.union(v.number(), v.null()),
314
+ updatedAt: v.number(),
315
+ })),
316
+ backlog: v.number(),
317
+ }),
318
+ handler: async (ctx, args) => {
319
+ const policy = await ctx.db
320
+ .query("retentionPolicies")
321
+ .withIndex("by_siteId", (range) => range.eq("siteId", args.siteId))
322
+ .unique();
323
+ const jobs = await ctx.db
324
+ .query("retentionStates")
325
+ .withIndex("by_siteId_and_kind", (range) => range.eq("siteId", args.siteId))
326
+ .take(POLICY_CLEANUP_KINDS.length + 1);
327
+ const publicJobs = jobs.map(({ kind, before, status, deleted, scheduledAt, updatedAt }) => ({
328
+ kind: kind,
329
+ before,
330
+ status,
331
+ deleted,
332
+ scheduledAt: scheduledAt ?? null,
333
+ updatedAt,
334
+ }));
37
335
  return {
38
- deleted: Math.min(deletions.length, effectiveBatchSize),
39
- hasMore: deletions.length > effectiveBatchSize,
336
+ policy: policy
337
+ ? {
338
+ eventsDays: policy.eventsDays,
339
+ sessionsDays: policy.sessionsDays,
340
+ conversionsDays: policy.conversionsDays,
341
+ aggregatesDays: policy.aggregatesDays,
342
+ reportsDays: policy.reportsDays,
343
+ updatedAt: policy.updatedAt,
344
+ }
345
+ : null,
346
+ jobs: publicJobs,
347
+ backlog: publicJobs.filter((job) => job.status !== "complete").length,
40
348
  };
41
349
  },
42
350
  });
351
+ const POLICY_CLEANUP_KINDS = [
352
+ "events",
353
+ "sessions",
354
+ "conversions",
355
+ "aggregateHour",
356
+ "aggregateDay",
357
+ "goalCompletions",
358
+ "funnelProgress",
359
+ "funnelSteps",
360
+ "affiliateStats",
361
+ "goalRollups",
362
+ "funnelRollups",
363
+ "affiliateRollups",
364
+ "vitalRollups",
365
+ "siteMapRollups",
366
+ "attributions",
367
+ "ingestWindows",
368
+ "siteIngestWindows",
369
+ ];
370
+ function validatePolicy(policy) {
371
+ for (const [name, days] of Object.entries(policy)) {
372
+ if (!name.endsWith("Days"))
373
+ continue;
374
+ if (!Number.isSafeInteger(days) || days < 1 || days > 3_650) {
375
+ fail("INVALID_ARGUMENT", `${name} must be an integer between 1 and 3650`);
376
+ }
377
+ }
378
+ }
379
+ function retentionDaysForKind(policy, kind) {
380
+ if (kind === "events")
381
+ return policy.eventsDays;
382
+ if (kind === "sessions")
383
+ return policy.sessionsDays;
384
+ if (kind === "conversions")
385
+ return policy.conversionsDays;
386
+ if (kind === "aggregateHour" || kind === "aggregateDay") {
387
+ return policy.aggregatesDays;
388
+ }
389
+ return policy.reportsDays;
390
+ }
391
+ function safeCleanupBoundary(kind, requested, now) {
392
+ if (!Number.isFinite(requested) || requested < 0) {
393
+ fail("INVALID_ARGUMENT", "before must be a positive timestamp");
394
+ }
395
+ if (kind === "events")
396
+ return safeBucketBoundary(requested, now, MINUTE_MS);
397
+ if (kind === "aggregateHour")
398
+ return safeBucketBoundary(requested, now, HOUR_MS);
399
+ if (kind === "aggregateDay" ||
400
+ kind === "funnelSteps" ||
401
+ kind === "affiliateStats" ||
402
+ kind === "goalRollups" ||
403
+ kind === "funnelRollups" ||
404
+ kind === "affiliateRollups" ||
405
+ kind === "vitalRollups" ||
406
+ kind === "siteMapRollups") {
407
+ return safeBucketBoundary(requested, now, DAY_MS);
408
+ }
409
+ if (kind === "ingestWindows" || kind === "siteIngestWindows") {
410
+ return Math.min(Math.floor(requested / RATE_LIMIT_WINDOW_MS) * RATE_LIMIT_WINDOW_MS, Math.floor(now / RATE_LIMIT_WINDOW_MS) * RATE_LIMIT_WINDOW_MS);
411
+ }
412
+ return Math.trunc(requested);
413
+ }
414
+ function safeBucketBoundary(requested, now, intervalMs) {
415
+ return Math.min(Math.floor(requested / intervalMs) * intervalMs, Math.floor(now / intervalMs) * intervalMs);
416
+ }
417
+ async function loadState(ctx, siteId, kind) {
418
+ return ctx.db
419
+ .query("retentionStates")
420
+ .withIndex("by_siteId_and_kind", (range) => range.eq("siteId", siteId).eq("kind", kind))
421
+ .unique();
422
+ }
423
+ async function persistDirectState(ctx, args, result) {
424
+ const now = Date.now();
425
+ const existing = await loadState(ctx, args.siteId, args.kind);
426
+ const fields = {
427
+ siteId: args.siteId,
428
+ kind: args.kind,
429
+ before: args.before,
430
+ status: result.hasMore ? "pending" : "complete",
431
+ generation: (existing?.generation ?? 0) + 1,
432
+ attempt: 0,
433
+ deleted: existing?.before === args.before
434
+ ? existing.deleted + result.deleted
435
+ : result.deleted,
436
+ updatedAt: now,
437
+ };
438
+ if (existing) {
439
+ await ctx.db.replace("retentionStates", existing._id, fields);
440
+ }
441
+ else {
442
+ await ctx.db.insert("retentionStates", fields);
443
+ }
444
+ }
445
+ async function recordRetentionBoundary(ctx, siteId, kind, before) {
446
+ const datasets = coverageDatasetsForKind(kind);
447
+ if (datasets.length === 0)
448
+ return;
449
+ const now = Date.now();
450
+ const coverage = await ensureAnalyticsControl(ctx, siteId, now, datasets.map((dataset) => ({ dataset, before })));
451
+ const retained = coverage.retained.filter((item) => !datasets.includes(item.dataset));
452
+ let changed = retained.length !== coverage.retained.length;
453
+ for (const dataset of datasets) {
454
+ const prior = coverage.retained.find((item) => item.dataset === dataset)?.before ?? 0;
455
+ const next = Math.max(prior, before);
456
+ retained.push({ dataset, before: next });
457
+ changed ||= next !== prior;
458
+ }
459
+ if (changed) {
460
+ await ctx.db.patch("analyticsCoverage", coverage._id, {
461
+ retained,
462
+ updatedAt: now,
463
+ });
464
+ }
465
+ }
466
+ function coverageDatasetsForKind(kind) {
467
+ if (kind === "events")
468
+ return ["events"];
469
+ if (kind === "sessions")
470
+ return ["sessions"];
471
+ if (kind === "conversions")
472
+ return ["conversions"];
473
+ if (kind === "aggregateHour")
474
+ return ["overviewHour"];
475
+ if (kind === "aggregateDay")
476
+ return ["overviewDay", "overviewLocalDay"];
477
+ if (kind === "goalCompletions")
478
+ return ["goalCompletions"];
479
+ if (kind === "funnelSteps")
480
+ return ["funnelSteps"];
481
+ if (kind === "affiliateStats")
482
+ return ["affiliateStats"];
483
+ if (kind === "goalRollups")
484
+ return ["goalRollups"];
485
+ if (kind === "funnelRollups")
486
+ return ["funnelRollups"];
487
+ if (kind === "affiliateRollups")
488
+ return ["affiliateRollups"];
489
+ if (kind === "vitalRollups")
490
+ return ["vitalRollups"];
491
+ if (kind === "siteMapRollups")
492
+ return ["siteMapRollups"];
493
+ return [];
494
+ }
495
+ async function executeCleanupBatch(ctx, args) {
496
+ const batchSize = args.batchSize ?? 100;
497
+ if (!Number.isSafeInteger(batchSize) ||
498
+ batchSize < 1 ||
499
+ batchSize > MAX_RETENTION_BATCH) {
500
+ fail("INVALID_ARGUMENT", `batchSize must be an integer between 1 and ${MAX_RETENTION_BATCH}`);
501
+ }
502
+ const effectiveBatchSize = args.kind === "events" ? Math.min(batchSize, 32) : batchSize;
503
+ if (args.kind === "events") {
504
+ return deleteTelemetryBefore(ctx, {
505
+ siteId: args.siteId,
506
+ before: args.before,
507
+ batchSize: effectiveBatchSize,
508
+ });
509
+ }
510
+ const deletions = await deletionsForCleanup(ctx, args.siteId, args.kind, args.before, effectiveBatchSize + 1);
511
+ for (const remove of deletions.slice(0, effectiveBatchSize))
512
+ await remove();
513
+ return {
514
+ deleted: Math.min(deletions.length, effectiveBatchSize),
515
+ hasMore: deletions.length > effectiveBatchSize,
516
+ };
517
+ }
43
518
  async function deletionsForCleanup(ctx, siteId, kind, before, limit) {
44
519
  if (kind === "sessions") {
45
520
  return (await ctx.db
46
521
  .query("sessions")
47
- .withIndex("by_siteId_and_lastSeenAt", (range) => range.eq("siteId", siteId).lt("lastSeenAt", before))
522
+ .withIndex("by_siteId_and_lastSeenAt", (q) => q.eq("siteId", siteId).lt("lastSeenAt", before))
48
523
  .take(limit)).map((row) => () => ctx.db.delete("sessions", row._id));
49
524
  }
50
525
  if (kind === "conversions") {
51
526
  return (await ctx.db
52
527
  .query("conversions")
53
- .withIndex("by_siteId_and_timestamp", (range) => range.eq("siteId", siteId).lt("timestamp", before))
528
+ .withIndex("by_siteId_and_timestamp", (q) => q.eq("siteId", siteId).lt("timestamp", before))
54
529
  .take(limit)).map((row) => () => ctx.db.delete("conversions", row._id));
55
530
  }
56
531
  if (kind === "goalCompletions") {
57
532
  return (await ctx.db
58
533
  .query("goalCompletions")
59
- .withIndex("by_siteId_and_timestamp", (range) => range.eq("siteId", siteId).lt("timestamp", before))
534
+ .withIndex("by_siteId_and_timestamp", (q) => q.eq("siteId", siteId).lt("timestamp", before))
60
535
  .take(limit)).map((row) => () => ctx.db.delete("goalCompletions", row._id));
61
536
  }
62
537
  if (kind === "aggregateHour" || kind === "aggregateDay") {
63
- return (await ctx.db
64
- .query("aggregateBuckets")
65
- .withIndex("by_siteId_and_granularity_and_bucketStart", (range) => range
66
- .eq("siteId", siteId)
67
- .eq("granularity", kind === "aggregateHour" ? "hour" : "day")
68
- .lt("bucketStart", before))
69
- .take(limit)).map((row) => () => ctx.db.delete("aggregateBuckets", row._id));
538
+ // The daily kind also retires the site's local-day buckets. Their cutoff
539
+ // sits a day and an hour earlier than the UTC-aligned one: a local day
540
+ // may begin almost a day before its UTC counterpart and, across a
541
+ // fall-back transition, last 25 hours, so this keeps every bucket that
542
+ // could still contain the cutoff instant.
543
+ const granularities = kind === "aggregateHour"
544
+ ? [["hour", before]]
545
+ : [
546
+ ["day", before],
547
+ ["localDay", before - DAY_MS - HOUR_MS],
548
+ ];
549
+ const deletions = [];
550
+ for (const [granularity, cutoff] of granularities) {
551
+ if (deletions.length >= limit)
552
+ break;
553
+ const rows = await ctx.db
554
+ .query("aggregateBuckets")
555
+ .withIndex("by_siteId_and_granularity_and_bucketStart", (q) => q
556
+ .eq("siteId", siteId)
557
+ .eq("granularity", granularity)
558
+ .lt("bucketStart", cutoff))
559
+ .take(limit - deletions.length);
560
+ deletions.push(...rows.map((row) => () => ctx.db.delete("aggregateBuckets", row._id)));
561
+ }
562
+ return deletions;
70
563
  }
71
564
  if (kind === "funnelProgress") {
72
565
  return (await ctx.db
73
566
  .query("funnelProgress")
74
- .withIndex("by_siteId_and_lastStepAt", (range) => range.eq("siteId", siteId).lt("lastStepAt", before))
567
+ .withIndex("by_siteId_and_lastStepAt", (q) => q.eq("siteId", siteId).lt("lastStepAt", before))
75
568
  .take(limit)).map((row) => () => ctx.db.delete("funnelProgress", row._id));
76
569
  }
77
570
  if (kind === "funnelSteps") {
78
571
  return (await ctx.db
79
572
  .query("funnelStepBuckets")
80
- .withIndex("by_siteId_and_bucketStart", (range) => range.eq("siteId", siteId).lt("bucketStart", before))
573
+ .withIndex("by_siteId_and_bucketStart", (q) => q.eq("siteId", siteId).lt("bucketStart", before))
81
574
  .take(limit)).map((row) => () => ctx.db.delete("funnelStepBuckets", row._id));
82
575
  }
83
576
  if (kind === "affiliateStats") {
84
577
  return (await ctx.db
85
578
  .query("affiliateDailyStats")
86
- .withIndex("by_siteId_and_bucketStart", (range) => range.eq("siteId", siteId).lt("bucketStart", before))
579
+ .withIndex("by_siteId_and_bucketStart", (q) => q.eq("siteId", siteId).lt("bucketStart", before))
87
580
  .take(limit)).map((row) => () => ctx.db.delete("affiliateDailyStats", row._id));
88
581
  }
582
+ if (kind === "goalRollups") {
583
+ return (await ctx.db
584
+ .query("goalDailyRollups")
585
+ .withIndex("by_siteId_and_bucketStart", (q) => q.eq("siteId", siteId).lt("bucketStart", before))
586
+ .take(limit)).map((row) => () => ctx.db.delete("goalDailyRollups", row._id));
587
+ }
588
+ if (kind === "funnelRollups") {
589
+ return (await ctx.db
590
+ .query("funnelDailyRollups")
591
+ .withIndex("by_siteId_and_bucketStart", (q) => q.eq("siteId", siteId).lt("bucketStart", before))
592
+ .take(limit)).map((row) => () => ctx.db.delete("funnelDailyRollups", row._id));
593
+ }
594
+ if (kind === "affiliateRollups") {
595
+ return (await ctx.db
596
+ .query("affiliateDailyRollups")
597
+ .withIndex("by_siteId_and_bucketStart", (q) => q.eq("siteId", siteId).lt("bucketStart", before))
598
+ .take(limit)).map((row) => () => ctx.db.delete("affiliateDailyRollups", row._id));
599
+ }
600
+ if (kind === "vitalRollups") {
601
+ return (await ctx.db
602
+ .query("vitalRollups")
603
+ .withIndex("by_siteId_and_bucketStart", (q) => q.eq("siteId", siteId).lt("bucketStart", before))
604
+ .take(limit)).map((row) => () => ctx.db.delete("vitalRollups", row._id));
605
+ }
606
+ if (kind === "siteMapRollups") {
607
+ return (await ctx.db
608
+ .query("routeDailyRollups")
609
+ .withIndex("by_siteId_and_bucketStart", (q) => q.eq("siteId", siteId).lt("bucketStart", before))
610
+ .take(limit)).map((row) => () => ctx.db.delete("routeDailyRollups", row._id));
611
+ }
89
612
  if (kind === "attributions") {
90
613
  return (await ctx.db
91
614
  .query("visitorAttributions")
92
- .withIndex("by_siteId_and_expiresAt", (range) => range.eq("siteId", siteId).lt("expiresAt", before))
615
+ .withIndex("by_siteId_and_expiresAt", (q) => q.eq("siteId", siteId).lt("expiresAt", before))
93
616
  .take(limit)).map((row) => () => ctx.db.delete("visitorAttributions", row._id));
94
617
  }
95
618
  if (kind === "liveSessions") {
96
619
  return (await ctx.db
97
620
  .query("liveSessions")
98
- .withIndex("by_siteId_and_expiresAt", (range) => range.eq("siteId", siteId).lt("expiresAt", before))
621
+ .withIndex("by_siteId_and_expiresAt", (q) => q.eq("siteId", siteId).lt("expiresAt", before))
99
622
  .take(limit)).map((row) => () => ctx.db.delete("liveSessions", row._id));
100
623
  }
101
624
  if (kind === "siteIngestWindows") {
102
625
  return (await ctx.db
103
626
  .query("siteIngestWindows")
104
- .withIndex("by_siteId_and_updatedAt", (range) => range.eq("siteId", siteId).lt("updatedAt", before))
627
+ .withIndex("by_siteId_and_updatedAt", (q) => q.eq("siteId", siteId).lt("updatedAt", before))
105
628
  .take(limit)).map((row) => () => ctx.db.delete("siteIngestWindows", row._id));
106
629
  }
107
630
  return (await ctx.db
108
631
  .query("ingestWindows")
109
- .withIndex("by_siteId_and_updatedAt", (range) => range.eq("siteId", siteId).lt("updatedAt", before))
632
+ .withIndex("by_siteId_and_updatedAt", (q) => q.eq("siteId", siteId).lt("updatedAt", before))
110
633
  .take(limit)).map((row) => () => ctx.db.delete("ingestWindows", row._id));
111
634
  }
112
635
  //# sourceMappingURL=retention.js.map