@kya-os/checkpoint-shared 1.0.0 → 1.2.0

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.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,53 @@
1
1
  # @kya-os/checkpoint-shared
2
2
 
3
+ ## 1.2.0 — 2026-05-19
4
+
5
+ F-19 vocabulary rename (additive, dual-label deprecation window).
6
+
7
+ ### Added
8
+
9
+ - `'unattributed'` added to the `IdentifiedTier` union as the canonical
10
+ label for the lowest tier (rows with no IP / no upstream identity).
11
+ - `AgentHumansTimeseriesPoint.unattributed: number` added alongside the
12
+ existing `anonymous` numeric field. Services emit the same numeric
13
+ value on both keys during the deprecation window.
14
+ - New `./beacon-types` export subpath (#2913) — the beacon/worker type
15
+ defs + hand-rolled `parse*` validators folded in from the former
16
+ `@kya-os/agentshield-types` leaf package. Isolated tsup entry, so the
17
+ main barrel's tree-shaker can't reach it; only `@kya-os/checkpoint-beacon`
18
+ pulls it in.
19
+
20
+ ### Deprecated
21
+
22
+ - `'anonymous'` on `IdentifiedTier` is now `@deprecated` — kept as an
23
+ alias to avoid breaking external consumers of `1.1.0`. Will be
24
+ removed in `2.0.0`. Match on `'unattributed'` in new code.
25
+ - `AgentHumansTimeseriesPoint.anonymous: number` is now `@deprecated` —
26
+ mirror of `unattributed`. Will be removed in `2.0.0`.
27
+
28
+ ### Notes
29
+
30
+ This release is type-additive. Existing consumers pinning `^1.1.0` keep
31
+ compiling. Internal services in `apps/web/` are migrated to emit
32
+ `'unattributed'` in this release cycle.
33
+
34
+ ## 1.1.0 — 2026-05-18
35
+
36
+ Phase-D.8b engine-surface cleanup.
37
+
38
+ ### Added
39
+
40
+ - `DetectionDetailSchema` / `DetectionDetail`, the canonical rich
41
+ detection payload emitted next to engine `Decision`.
42
+ - Deprecated `DetectionResult` remains as an alias of `DetectionDetail`
43
+ for one minor cycle while downstream packages migrate names.
44
+
45
+ ### Removed
46
+
47
+ - Retired `shouldEnforce` and `evaluateEnforcement`. Host packages now
48
+ read enforcement from `VerifyResult.decision` and keep any compatibility
49
+ policy fallback locally.
50
+
3
51
  ## 1.0.0 — 2026-05-15
4
52
 
5
53
  E-tracks Phase D — package rename. **BREAKING.**
@@ -0,0 +1,427 @@
1
+ type JsonPrimitive = string | number | boolean | null;
2
+ type JsonValue = JsonPrimitive | JsonValue[] | {
3
+ [key: string]: JsonValue | undefined;
4
+ };
5
+ type BeaconPrimitive = JsonPrimitive;
6
+ type BeaconJsonValue = JsonValue;
7
+ type BeaconCustomData = Record<string, JsonValue | undefined>;
8
+ type BeaconPayload = BeaconCollectorData | BeaconCustomData | null;
9
+ type WorkerPayload = unknown;
10
+ interface NetworkInformationLike extends EventTarget {
11
+ type?: string;
12
+ effectiveType?: string;
13
+ downlink?: number;
14
+ rtt?: number;
15
+ saveData?: boolean;
16
+ }
17
+ interface NavigatorWithNetworkInformation extends Navigator {
18
+ connection?: NetworkInformationLike;
19
+ mozConnection?: NetworkInformationLike;
20
+ webkitConnection?: NetworkInformationLike;
21
+ deviceMemory?: number;
22
+ vendorSub: string;
23
+ doNotTrack: string | null;
24
+ msDoNotTrack?: string | null;
25
+ }
26
+ interface WindowWithBeaconMetadata extends Window {
27
+ doNotTrack?: string | null;
28
+ __NEXT_DATA__?: {
29
+ buildId?: string;
30
+ };
31
+ }
32
+ interface TrustedTypePolicyLike {
33
+ createScriptURL(url: string): string;
34
+ createScript(script: string): string;
35
+ }
36
+ interface WindowWithTrustedTypes extends Window {
37
+ trustedTypes?: {
38
+ createPolicy(name: string, rules: {
39
+ createScriptURL?: (url: string) => string;
40
+ createScript?: (script: string) => string;
41
+ }): TrustedTypePolicyLike;
42
+ };
43
+ }
44
+ interface PerformanceMemoryInfo {
45
+ usedJSHeapSize: number;
46
+ totalJSHeapSize: number;
47
+ jsHeapSizeLimit: number;
48
+ }
49
+ interface PerformanceWithMemory extends Performance {
50
+ memory?: PerformanceMemoryInfo;
51
+ measureUserAgentSpecificMemory?: () => Promise<unknown>;
52
+ }
53
+ interface LargestContentfulPaintEntry extends PerformanceEntry {
54
+ renderTime?: number;
55
+ loadTime?: number;
56
+ }
57
+ interface BeaconConfig {
58
+ projectId: string;
59
+ environment?: 'development' | 'staging' | 'production' | string;
60
+ tags?: Record<string, string | number | boolean>;
61
+ enabled?: boolean;
62
+ debug?: boolean;
63
+ logLevel?: 'error' | 'warn' | 'info' | 'debug';
64
+ respectDoNotTrack?: boolean;
65
+ anonymizeIp?: boolean;
66
+ sessionTimeout?: number;
67
+ sessionCookieName?: string;
68
+ batchSize?: number;
69
+ flushInterval?: number;
70
+ maxQueueSize?: number;
71
+ retryAttempts?: number;
72
+ retryDelay?: number;
73
+ useWorker?: boolean;
74
+ workerUrl?: string;
75
+ workerConfig?: WorkerConfig;
76
+ }
77
+ interface BeaconEvent {
78
+ type: BeaconEventType;
79
+ data: BeaconCollectorData;
80
+ metadata: BeaconMetadata;
81
+ }
82
+ interface BeaconMetadata {
83
+ sessionId: string;
84
+ timestamp: number;
85
+ eventName?: string;
86
+ [key: string]: unknown;
87
+ }
88
+ interface IAgentShieldBeacon {
89
+ collect(eventType: string, data?: BeaconPayload): Promise<void>;
90
+ trackEvent(eventName: string, eventData?: BeaconPayload): Promise<void>;
91
+ trackPageview(pageData?: BeaconPayload): Promise<void>;
92
+ trackPageUnload(): Promise<void>;
93
+ updateConfig(updates: Partial<BeaconConfig>): void;
94
+ destroy(): Promise<void>;
95
+ }
96
+ interface BeaconResponse {
97
+ status: 'success' | 'error';
98
+ message?: string;
99
+ error?: {
100
+ code: string;
101
+ message: string;
102
+ };
103
+ }
104
+ interface BrowserContext {
105
+ browser: {
106
+ name: string;
107
+ version: string;
108
+ engine: string;
109
+ };
110
+ os: {
111
+ name: string;
112
+ version: string;
113
+ };
114
+ device: {
115
+ type: 'desktop' | 'mobile' | 'tablet' | 'tv' | 'unknown';
116
+ vendor?: string;
117
+ model?: string;
118
+ };
119
+ screen: {
120
+ width: number;
121
+ height: number;
122
+ pixelRatio: number;
123
+ colorDepth: number;
124
+ };
125
+ connection?: {
126
+ type: 'bluetooth' | 'cellular' | 'ethernet' | 'none' | 'wifi' | 'wimax' | 'other' | 'unknown';
127
+ effectiveType?: '2g' | '3g' | '4g' | '5g';
128
+ downlink?: number;
129
+ rtt?: number;
130
+ saveData?: boolean;
131
+ };
132
+ }
133
+ interface PerformanceMetrics {
134
+ pageLoadTime?: number;
135
+ domContentLoadedTime?: number;
136
+ timeToInteractive?: number;
137
+ firstPaintTime?: number;
138
+ firstContentfulPaintTime?: number;
139
+ largestContentfulPaintTime?: number;
140
+ dnsLookupTime?: number;
141
+ tcpConnectionTime?: number;
142
+ serverResponseTime?: number;
143
+ resources?: {
144
+ scripts: number;
145
+ stylesheets: number;
146
+ images: number;
147
+ fonts: number;
148
+ total: number;
149
+ };
150
+ }
151
+ interface SessionData {
152
+ id: string;
153
+ startTime: number;
154
+ lastActivity: number;
155
+ pageViews: number;
156
+ eventCount: number;
157
+ duration: number;
158
+ isNew: boolean;
159
+ }
160
+ interface TransportConfig {
161
+ batchSize: number;
162
+ flushInterval: number;
163
+ maxRetries: number;
164
+ retryDelayBase: number;
165
+ offlineQueueSize: number;
166
+ useCompression: boolean;
167
+ compressionThreshold: number;
168
+ networkAdaptation: boolean;
169
+ dedupWindow: number;
170
+ }
171
+ interface TransportOptions {
172
+ immediate?: boolean;
173
+ priority?: 'low' | 'normal' | 'high' | 'critical';
174
+ retry?: boolean;
175
+ timeout?: number;
176
+ }
177
+ interface TransportResponse {
178
+ success: boolean;
179
+ timestamp: number;
180
+ batchId?: string;
181
+ error?: string;
182
+ }
183
+ type TransportState = 'idle' | 'sending' | 'offline' | 'paused' | 'error';
184
+ interface TransportMetrics {
185
+ eventsSent: number;
186
+ eventsFailed: number;
187
+ eventsQueued: number;
188
+ batchesSent: number;
189
+ batchesFailed: number;
190
+ bytesTransferred: number;
191
+ compressionRatio?: number;
192
+ averageLatency?: number;
193
+ lastSuccessTimestamp?: number;
194
+ lastErrorTimestamp?: number;
195
+ }
196
+ interface BatchEvent {
197
+ id: string;
198
+ event: BeaconEvent;
199
+ timestamp: number;
200
+ retryCount: number;
201
+ hash: string;
202
+ priority: 'low' | 'normal' | 'high' | 'critical';
203
+ }
204
+ type ConnectionType = 'bluetooth' | 'cellular' | 'ethernet' | 'none' | 'wifi' | 'wimax' | 'other' | 'unknown';
205
+ interface NetworkInfo {
206
+ type?: string;
207
+ effectiveType?: string;
208
+ downlink?: number;
209
+ rtt?: number;
210
+ saveData?: boolean;
211
+ }
212
+ type MessagePriority = 'low' | 'normal' | 'high' | 'critical';
213
+ type WorkerErrorType = 'initialization' | 'runtime' | 'communication' | 'timeout' | 'memory' | 'network' | 'permission' | 'validation' | 'processing' | 'unknown';
214
+ type WorkerAction = 'process' | 'init' | 'terminate' | 'pause' | 'resume' | 'status' | 'health';
215
+ type WorkerMessageType = 'request' | 'response' | 'error' | 'heartbeat' | 'status';
216
+ interface WorkerMessage {
217
+ id: string;
218
+ type: 'request' | 'response' | 'error' | 'heartbeat' | 'status';
219
+ action?: string;
220
+ payload?: WorkerPayload;
221
+ timestamp: number;
222
+ compressed?: boolean;
223
+ priority?: MessagePriority;
224
+ correlationId?: string;
225
+ }
226
+ type WorkerState = 'idle' | 'initializing' | 'ready' | 'processing' | 'busy' | 'error' | 'terminating' | 'terminated';
227
+ type WorkerHealthStatus = 'healthy' | 'degraded' | 'unhealthy' | 'unknown';
228
+ interface WorkerMetrics {
229
+ tasksProcessed: number;
230
+ tasksFailed: number;
231
+ averageProcessingTime?: number;
232
+ memoryUsage?: number;
233
+ cpuUsage?: number;
234
+ healthStatus: WorkerHealthStatus;
235
+ lastHealthCheck: number;
236
+ restartCount: number;
237
+ errorRate?: number;
238
+ errorCount: number;
239
+ messageQueueSize: number;
240
+ startTime: number;
241
+ uptime: number;
242
+ averageTaskTime?: number;
243
+ lastTaskTime?: number;
244
+ }
245
+ interface WorkerError {
246
+ type: WorkerErrorType;
247
+ code?: string;
248
+ message: string;
249
+ stack?: string;
250
+ timestamp: number;
251
+ recoverable: boolean;
252
+ retryAfter?: number;
253
+ context?: Record<string, unknown>;
254
+ }
255
+ interface WorkerCapabilities {
256
+ workerAPI: boolean;
257
+ sharedArrayBuffer: boolean;
258
+ transferableObjects: boolean;
259
+ offscreenCanvas: boolean;
260
+ webAssembly: boolean;
261
+ atomics: boolean;
262
+ bigInt: boolean;
263
+ csp: {
264
+ workerSrc: boolean;
265
+ scriptSrc: boolean;
266
+ blobUrls: boolean;
267
+ inlineWorkers: boolean;
268
+ };
269
+ performance: {
270
+ memory: boolean;
271
+ measureUserAgentSpecificMemory: boolean;
272
+ };
273
+ }
274
+ interface WorkerTask {
275
+ id: string;
276
+ type: string;
277
+ data: WorkerPayload;
278
+ priority: 'low' | 'normal' | 'high' | 'critical';
279
+ createdAt: number;
280
+ startedAt?: number;
281
+ completedAt?: number;
282
+ error?: WorkerError;
283
+ maxRetries?: number;
284
+ retries?: number;
285
+ timeout?: number;
286
+ }
287
+ interface FallbackOptions {
288
+ useRequestIdleCallback: boolean;
289
+ idleTimeout: number;
290
+ chunkSize: number;
291
+ throttleMs: number;
292
+ maxExecutionTime: number;
293
+ }
294
+ interface ResourceUsage {
295
+ memory: {
296
+ used: number;
297
+ limit: number;
298
+ percentage: number;
299
+ };
300
+ cpu: {
301
+ usage: number;
302
+ limit: number;
303
+ };
304
+ tasks: {
305
+ pending: number;
306
+ active: number;
307
+ completed: number;
308
+ failed: number;
309
+ };
310
+ activeWorkers: number;
311
+ }
312
+ interface WorkerPoolConfig {
313
+ maxWorkers: number;
314
+ minWorkers: number;
315
+ workerIdleTimeout: number;
316
+ taskQueueSize: number;
317
+ resourceLimits: Record<string, number>;
318
+ autoScale?: boolean;
319
+ scaleUpThreshold?: number;
320
+ scaleDownThreshold?: number;
321
+ }
322
+ type BeaconWorkerMessageType = 'init' | 'collect' | 'flush' | 'config' | 'status' | 'error';
323
+ type ProtocolVersion = '1.0' | '1.1' | '2.0';
324
+ interface BeaconWorkerMessage {
325
+ type: BeaconWorkerMessageType;
326
+ data?: WorkerPayload;
327
+ payload?: WorkerPayload;
328
+ messageId: string;
329
+ timestamp: number;
330
+ id: string;
331
+ }
332
+ interface WorkerConfig {
333
+ enabled?: boolean;
334
+ url?: string;
335
+ heartbeatInterval?: number;
336
+ maxUnhealthyCount?: number;
337
+ maxRetries?: number;
338
+ retryDelay?: number;
339
+ restartDelay?: number;
340
+ messageTimeout?: number;
341
+ compressionThreshold?: number;
342
+ allowFallback?: boolean;
343
+ crossOriginIsolated?: boolean;
344
+ maxRestartAttempts?: number;
345
+ terminationTimeout?: number;
346
+ taskTimeout?: number;
347
+ fallbackDelay?: number;
348
+ enableFallback?: boolean;
349
+ }
350
+ interface CircuitBreakerConfig {
351
+ threshold: number;
352
+ timeout: number;
353
+ resetTimeout: number;
354
+ }
355
+ type CircuitBreakerState = 'closed' | 'open' | 'half-open';
356
+ interface RetryStrategy {
357
+ maxAttempts: number;
358
+ baseDelay: number;
359
+ maxDelay: number;
360
+ factor: number;
361
+ jitter: boolean;
362
+ }
363
+ interface OfflineQueueEntry {
364
+ id: string;
365
+ events: BeaconEvent[];
366
+ timestamp: number;
367
+ expiresAt: number;
368
+ retryCount: number;
369
+ size: number;
370
+ }
371
+ interface BeaconBatch {
372
+ projectId: string;
373
+ events: BeaconEvent[];
374
+ sessionId: string;
375
+ batchId: string;
376
+ timestamp: number;
377
+ }
378
+ interface BeaconCollectorData {
379
+ userAgent?: string;
380
+ language?: string;
381
+ platform?: string;
382
+ screenResolution?: string;
383
+ viewport?: string;
384
+ cookiesEnabled?: boolean;
385
+ doNotTrack?: boolean;
386
+ timezone?: string;
387
+ referrer?: string;
388
+ url?: string;
389
+ title?: string;
390
+ vendor?: string;
391
+ pageLoadTime?: number;
392
+ domContentLoadedTime?: number;
393
+ firstPaintTime?: number;
394
+ firstContentfulPaintTime?: number;
395
+ connectionType?: string;
396
+ sessionId?: string;
397
+ timestamp?: number;
398
+ [key: string]: unknown;
399
+ }
400
+ type BeaconEventType = 'pageview' | 'pageunload' | 'heartbeat' | 'custom' | 'error' | 'performance';
401
+ declare function parseRetryStrategy(input: unknown): RetryStrategy;
402
+ declare function parseCircuitBreakerConfig(input: unknown): CircuitBreakerConfig;
403
+ declare function parseOfflineQueueEntry(input: unknown): OfflineQueueEntry;
404
+ declare function parseBeaconWorkerMessage(input: unknown): BeaconWorkerMessage;
405
+ declare function parseWorkerMessage(input: unknown): WorkerMessage;
406
+ declare function parseWorkerError(input: unknown): WorkerError;
407
+ declare function parseWorkerPoolConfig(input: unknown): WorkerPoolConfig;
408
+ declare function parseResourceUsage(input: unknown): ResourceUsage;
409
+ declare const ResourceUsageSchema: {
410
+ parse: typeof parseResourceUsage;
411
+ };
412
+ declare const WorkerPoolConfigSchema: {
413
+ parse: typeof parseWorkerPoolConfig;
414
+ };
415
+ declare function parseWorkerCapabilities(input: unknown): WorkerCapabilities;
416
+ declare function parseBeaconConfig(input: unknown): BeaconConfig;
417
+ declare class AgentShieldBeacon implements IAgentShieldBeacon {
418
+ constructor(config: BeaconConfig);
419
+ collect(eventType: string, data?: BeaconPayload): Promise<void>;
420
+ trackEvent(eventName: string, eventData?: BeaconPayload): Promise<void>;
421
+ trackPageview(pageData?: BeaconPayload): Promise<void>;
422
+ trackPageUnload(): Promise<void>;
423
+ updateConfig(updates: Partial<BeaconConfig>): void;
424
+ destroy(): Promise<void>;
425
+ }
426
+
427
+ export { AgentShieldBeacon, type BatchEvent, type BeaconBatch, type BeaconCollectorData, type BeaconConfig, type BeaconCustomData, type BeaconEvent, type BeaconEventType, type BeaconJsonValue, type BeaconMetadata, type BeaconPayload, type BeaconPrimitive, type BeaconResponse, type BeaconWorkerMessage, type BeaconWorkerMessageType, type BrowserContext, type CircuitBreakerConfig, type CircuitBreakerState, type ConnectionType, type FallbackOptions, type IAgentShieldBeacon, type JsonPrimitive, type JsonValue, type LargestContentfulPaintEntry, type MessagePriority, type NavigatorWithNetworkInformation, type NetworkInfo, type NetworkInformationLike, type OfflineQueueEntry, type PerformanceMemoryInfo, type PerformanceMetrics, type PerformanceWithMemory, type ProtocolVersion, type ResourceUsage, ResourceUsageSchema, type RetryStrategy, type SessionData, type TransportConfig, type TransportMetrics, type TransportOptions, type TransportResponse, type TransportState, type TrustedTypePolicyLike, type WindowWithBeaconMetadata, type WindowWithTrustedTypes, type WorkerAction, type WorkerCapabilities, type WorkerConfig, type WorkerError, type WorkerErrorType, type WorkerHealthStatus, type WorkerMessage, type WorkerMessageType, type WorkerMetrics, type WorkerPayload, type WorkerPoolConfig, WorkerPoolConfigSchema, type WorkerState, type WorkerTask, parseBeaconConfig, parseBeaconWorkerMessage, parseCircuitBreakerConfig, parseOfflineQueueEntry, parseResourceUsage, parseRetryStrategy, parseWorkerCapabilities, parseWorkerError, parseWorkerMessage, parseWorkerPoolConfig };