@beesolve/analytics-processor 0.2.6 → 0.4.0

package/dist/index.d.ts

@@ -39,81 +39,6 @@ declare class AppliedMarkers {
 	}) => TransactPutItem;
 }
 import { AthenaClient } from "@aws-sdk/client-athena";
-import { DynamoDBDocumentClient as DynamoDBDocumentClient2, TransactWriteCommandInput as TransactWriteCommandInput2 } from "@aws-sdk/lib-dynamodb";
-import * as v2 from "valibot";
-type TransactWriteItem2 = NonNullable<TransactWriteCommandInput2["TransactItems"]>[number];
-type UpdateMembers = NonNullable<TransactWriteItem2["Update"]>;
-interface TransactUpdateItem {
-	readonly Update: UpdateMembers;
-}
-interface TotalsInput {
-	readonly timeKey: string;
-	readonly hits: number;
-	readonly success: number;
-	readonly errors: number;
-	readonly errors4xx: number;
-	readonly errors5xx: number;
-	readonly bytesSent: number;
-	readonly bytesReceived: number;
-	readonly p50TimeTaken?: number;
-	readonly p95TimeTaken?: number;
-	readonly cacheHitRatio?: number;
-	readonly uniqueIpCount?: number;
-}
-declare const totalsSchema: v2.ObjectSchema<{
-	readonly pk: v2.StringSchema<undefined>;
-	readonly sk: v2.StringSchema<undefined>;
-	readonly grain: v2.PicklistSchema<readonly ["hour", "day", "month"], undefined>;
-	readonly timeKey: v2.StringSchema<undefined>;
-	readonly hits: v2.NumberSchema<undefined>;
-	readonly success: v2.NumberSchema<undefined>;
-	readonly errors: v2.NumberSchema<undefined>;
-	readonly errors4xx: v2.NumberSchema<undefined>;
-	readonly errors5xx: v2.NumberSchema<undefined>;
-	readonly bytesSent: v2.NumberSchema<undefined>;
-	readonly bytesReceived: v2.NumberSchema<undefined>;
-	readonly p50TimeTaken: v2.OptionalSchema<v2.NumberSchema<undefined>, undefined>;
-	readonly p95TimeTaken: v2.OptionalSchema<v2.NumberSchema<undefined>, undefined>;
-	readonly cacheHitRatio: v2.OptionalSchema<v2.NumberSchema<undefined>, undefined>;
-	readonly uniqueIpCount: v2.OptionalSchema<v2.NumberSchema<undefined>, undefined>;
-	readonly ttl: v2.OptionalSchema<v2.NumberSchema<undefined>, undefined>;
-}, undefined>;
-type TotalsItem = v2.InferOutput<typeof totalsSchema>;
-declare class Totals {
-	private readonly props;
-	constructor(props: {
-		readonly dynamo: Pick<DynamoDBDocumentClient2, "send">;
-		readonly tableName: string;
-		readonly reverseIndexName?: string;
-	});
-	readonly addHourly: (props: {
-		readonly item: TotalsInput;
-		readonly ttl: number;
-	}) => Promise<void>;
-	readonly addAggregate: (props: {
-		readonly grain: "day" | "month";
-		readonly item: TotalsInput;
-	}) => Promise<void>;
-	readonly buildHourlyUpdate: (props: {
-		readonly item: TotalsInput;
-		readonly ttl: number;
-	}) => TransactUpdateItem;
-	readonly buildAggregateUpdate: (props: {
-		readonly grain: "day" | "month";
-		readonly item: TotalsInput;
-	}) => TransactUpdateItem;
-	readonly queryWindow: (props: {
-		readonly grain: Grain;
-		readonly startKey: string;
-		readonly endKey: string;
-	}) => Promise<Array<TotalsItem>>;
-	readonly getOne: (props: {
-		readonly grain: Grain;
-		readonly timeKey: string;
-	}) => Promise<TotalsItem | undefined>;
-	private readonly buildUpdateMembers;
-	private readonly parseOne;
-}
 interface BreakdownRow {
 	readonly value: string;
 	readonly hits: number;
@@ -128,7 +53,7 @@ interface SummedTotals {
 	readonly bytesSent: number;
 	readonly bytesReceived: number;
 }
-declare function sumTotals(items: Array<TotalsInput>): SummedTotals;
+declare function sumTotals(items: Array<SummedTotals>): SummedTotals;
 declare function sumBreakdown(items: Array<BreakdownRow>): Array<BreakdownRow>;
 declare function topNWithOther({ items, n, otherValue }: {
 	items: Array<BreakdownRow>;
@@ -227,34 +152,34 @@ declare function runHourlyAthenaQuery({ athena, database, table, workgroup, outp
 	hourKey: string;
 	topPaths: number;
 }): Promise<HourlyAthenaResult>;
-import { DynamoDBDocumentClient as DynamoDBDocumentClient3, TransactWriteCommandInput as TransactWriteCommandInput3 } from "@aws-sdk/lib-dynamodb";
-import * as v3 from "valibot";
-type TransactWriteItem3 = NonNullable<TransactWriteCommandInput3["TransactItems"]>[number];
-type UpdateMembers2 = NonNullable<TransactWriteItem3["Update"]>;
-interface TransactUpdateItem2 {
-	readonly Update: UpdateMembers2;
+import { DynamoDBDocumentClient as DynamoDBDocumentClient2, TransactWriteCommandInput as TransactWriteCommandInput2 } from "@aws-sdk/lib-dynamodb";
+import * as v2 from "valibot";
+type TransactWriteItem2 = NonNullable<TransactWriteCommandInput2["TransactItems"]>[number];
+type UpdateMembers = NonNullable<TransactWriteItem2["Update"]>;
+interface TransactUpdateItem {
+	readonly Update: UpdateMembers;
 }
 interface BreakdownInput {
 	readonly value: string;
 	readonly hits: number;
 	readonly bytes: number;
 }
-declare const breakdownSchema: v3.ObjectSchema<{
-	readonly pk: v3.StringSchema<undefined>;
-	readonly sk: v3.StringSchema<undefined>;
-	readonly dimension: v3.PicklistSchema<readonly ["status", "country", "device", "path"], undefined>;
-	readonly grain: v3.PicklistSchema<readonly ["hour", "day", "month"], undefined>;
-	readonly periodKey: v3.StringSchema<undefined>;
-	readonly value: v3.StringSchema<undefined>;
-	readonly hits: v3.NumberSchema<undefined>;
-	readonly bytes: v3.NumberSchema<undefined>;
-	readonly ttl: v3.OptionalSchema<v3.NumberSchema<undefined>, undefined>;
+declare const breakdownSchema: v2.ObjectSchema<{
+	readonly pk: v2.StringSchema<undefined>;
+	readonly sk: v2.StringSchema<undefined>;
+	readonly dimension: v2.PicklistSchema<readonly ["status", "country", "device", "path"], undefined>;
+	readonly grain: v2.PicklistSchema<readonly ["hour", "day", "month"], undefined>;
+	readonly periodKey: v2.StringSchema<undefined>;
+	readonly value: v2.StringSchema<undefined>;
+	readonly hits: v2.NumberSchema<undefined>;
+	readonly bytes: v2.NumberSchema<undefined>;
+	readonly ttl: v2.OptionalSchema<v2.NumberSchema<undefined>, undefined>;
 }, undefined>;
-type BreakdownItem = v3.InferOutput<typeof breakdownSchema>;
+type BreakdownItem = v2.InferOutput<typeof breakdownSchema>;
 declare class Breakdowns {
 	private readonly props;
 	constructor(props: {
-		readonly dynamo: Pick<DynamoDBDocumentClient3, "send">;
+		readonly dynamo: Pick<DynamoDBDocumentClient2, "send">;
 		readonly tableName: string;
 		readonly reverseIndexName?: string;
 	});
@@ -271,7 +196,7 @@ declare class Breakdowns {
 		readonly periodKey: string;
 		readonly items: Array<BreakdownInput>;
 		readonly ttl?: number;
-	}) => Array<TransactUpdateItem2>;
+	}) => Array<TransactUpdateItem>;
 	readonly getForPeriod: (props: {
 		readonly dimension: Dimension;
 		readonly grain: Grain;
@@ -280,17 +205,119 @@ declare class Breakdowns {
 	private readonly buildUpdateMembers;
 	private readonly parseOne;
 }
+import { DynamoDBDocumentClient as DynamoDBDocumentClient3 } from "@aws-sdk/lib-dynamodb";
+import * as v3 from "valibot";
+declare const configSchema: v3.ObjectSchema<{
+	readonly pk: v3.LiteralSchema<"system#config", undefined>;
+	readonly sk: v3.LiteralSchema<"analytics", undefined>;
+	readonly startKey: v3.StringSchema<undefined>;
+	readonly startedAt: v3.StringSchema<undefined>;
+}, undefined>;
+type AnalyticsConfig = v3.InferOutput<typeof configSchema>;
+declare class Config {
+	private readonly props;
+	constructor(props: {
+		readonly dynamo: Pick<DynamoDBDocumentClient3, "send">;
+		readonly tableName: string;
+	});
+	readonly get: () => Promise<AnalyticsConfig | null>;
+	/**
+	* Records the earliest ingested hour the first time any data lands, so the UI
+	* can clamp navigation to [startKey, now]. Idempotent: once `startKey` exists
+	* it is never moved forward, and a conditional guard lets it move earlier only
+	* when a backfill ingests an hour older than the stored boundary.
+	*/
+	readonly ensureStart: (props: {
+		readonly hourKey: string;
+	}) => Promise<void>;
+}
 type DeviceBucket = "mobile" | "desktop" | "bot" | "other";
 declare function classifyDevice(userAgent: string): DeviceBucket;
 import { AthenaClient as AthenaClient2 } from "@aws-sdk/client-athena";
-import { DynamoDBDocumentClient as DynamoDBDocumentClient4, TransactWriteCommandInput as TransactWriteCommandInput4 } from "@aws-sdk/lib-dynamodb";
+import { DynamoDBDocumentClient as DynamoDBDocumentClient5, TransactWriteCommandInput as TransactWriteCommandInput4 } from "@aws-sdk/lib-dynamodb";
 import { IpInfoCache } from "@beesolve/ip-info";
+import { DynamoDBDocumentClient as DynamoDBDocumentClient4, TransactWriteCommandInput as TransactWriteCommandInput3 } from "@aws-sdk/lib-dynamodb";
+import * as v4 from "valibot";
+type TransactWriteItem3 = NonNullable<TransactWriteCommandInput3["TransactItems"]>[number];
+type UpdateMembers2 = NonNullable<TransactWriteItem3["Update"]>;
+interface TransactUpdateItem2 {
+	readonly Update: UpdateMembers2;
+}
+interface TotalsInput {
+	readonly timeKey: string;
+	readonly hits: number;
+	readonly success: number;
+	readonly errors: number;
+	readonly errors4xx: number;
+	readonly errors5xx: number;
+	readonly bytesSent: number;
+	readonly bytesReceived: number;
+	readonly p50TimeTaken?: number;
+	readonly p95TimeTaken?: number;
+	readonly cacheHitRatio?: number;
+	readonly uniqueIpCount?: number;
+}
+declare const totalsSchema: v4.ObjectSchema<{
+	readonly pk: v4.StringSchema<undefined>;
+	readonly sk: v4.StringSchema<undefined>;
+	readonly grain: v4.PicklistSchema<readonly ["hour", "day", "month"], undefined>;
+	readonly timeKey: v4.StringSchema<undefined>;
+	readonly hits: v4.NumberSchema<undefined>;
+	readonly success: v4.NumberSchema<undefined>;
+	readonly errors: v4.NumberSchema<undefined>;
+	readonly errors4xx: v4.NumberSchema<undefined>;
+	readonly errors5xx: v4.NumberSchema<undefined>;
+	readonly bytesSent: v4.NumberSchema<undefined>;
+	readonly bytesReceived: v4.NumberSchema<undefined>;
+	readonly p50TimeTaken: v4.OptionalSchema<v4.NumberSchema<undefined>, undefined>;
+	readonly p95TimeTaken: v4.OptionalSchema<v4.NumberSchema<undefined>, undefined>;
+	readonly cacheHitRatio: v4.OptionalSchema<v4.NumberSchema<undefined>, undefined>;
+	readonly uniqueIpCount: v4.OptionalSchema<v4.NumberSchema<undefined>, undefined>;
+	readonly ttl: v4.OptionalSchema<v4.NumberSchema<undefined>, undefined>;
+}, undefined>;
+type TotalsItem = v4.InferOutput<typeof totalsSchema>;
+declare class Totals {
+	private readonly props;
+	constructor(props: {
+		readonly dynamo: Pick<DynamoDBDocumentClient4, "send">;
+		readonly tableName: string;
+		readonly reverseIndexName?: string;
+	});
+	readonly addHourly: (props: {
+		readonly item: TotalsInput;
+		readonly ttl: number;
+	}) => Promise<void>;
+	readonly addAggregate: (props: {
+		readonly grain: "day" | "month";
+		readonly item: TotalsInput;
+	}) => Promise<void>;
+	readonly buildHourlyUpdate: (props: {
+		readonly item: TotalsInput;
+		readonly ttl: number;
+	}) => TransactUpdateItem2;
+	readonly buildAggregateUpdate: (props: {
+		readonly grain: "day" | "month";
+		readonly item: TotalsInput;
+	}) => TransactUpdateItem2;
+	readonly queryWindow: (props: {
+		readonly grain: Grain;
+		readonly startKey: string;
+		readonly endKey: string;
+	}) => Promise<Array<TotalsItem>>;
+	readonly getOne: (props: {
+		readonly grain: Grain;
+		readonly timeKey: string;
+	}) => Promise<TotalsItem | undefined>;
+	private readonly buildUpdateMembers;
+	private readonly parseOne;
+}
 type TransactItem = NonNullable<TransactWriteCommandInput4["TransactItems"]>[number];
 interface ProcessHourModels {
 	readonly totals: Pick<Totals, "buildHourlyUpdate">;
 	readonly breakdowns: Pick<Breakdowns, "buildUpdates">;
 	readonly markers: Pick<AppliedMarkers, "isApplied" | "buildMarkerPut">;
 	readonly ipCache: Pick<IpInfoCache, "enrichMany">;
+	readonly config?: Pick<Config, "ensureStart">;
 }
 interface ProcessHourAthena {
 	readonly client: Pick<AthenaClient2, "send">;
@@ -313,17 +340,17 @@ declare function processHour({ hourKey, source, models, athena, options, dynamo
 	models: ProcessHourModels;
 	athena: ProcessHourAthena;
 	options: ProcessHourOptions;
-	dynamo: Pick<DynamoDBDocumentClient4, "send">;
+	dynamo: Pick<DynamoDBDocumentClient5, "send">;
 }): Promise<ProcessHourResult>;
 declare function applyDailyRollup({ dayKey, models, dynamo }: {
 	dayKey: string;
 	models: RollupModels;
-	dynamo: Pick<DynamoDBDocumentClient4, "send">;
+	dynamo: Pick<DynamoDBDocumentClient5, "send">;
 }): Promise<ProcessHourResult>;
 declare function applyMonthlyRollup({ monthKey, models, dynamo }: {
 	monthKey: string;
 	models: RollupModels;
-	dynamo: Pick<DynamoDBDocumentClient4, "send">;
+	dynamo: Pick<DynamoDBDocumentClient5, "send">;
 }): Promise<ProcessHourResult>;
 declare function chunkTransactItems({ leading, rest, limit }: {
 	leading: Array<TransactItem>;
@@ -335,10 +362,80 @@ interface RollupModels {
 	readonly breakdowns: Pick<Breakdowns, "buildUpdates" | "getForPeriod">;
 	readonly markers: Pick<AppliedMarkers, "isApplied" | "buildMarkerPut">;
 }
+type View = Grain | "year";
+/**
+* How a bucket's value was obtained, so the UI can tell "no traffic" apart from
+* "not calculated yet":
+* - `sealed`: a finalized, rolled-up period read from its stored aggregate. A
+*   zero-hit sealed bucket is genuine "no traffic".
+* - `partial`: an in-progress period computed live from the finer grain; the
+*   value is real but may still grow.
+* - `pending`: a period past its expected processing time with no stored data
+*   and nothing computable yet — awaiting processing.
+*/
+declare const bucketStates: readonly ["sealed", "partial", "pending"];
+type BucketState = (typeof bucketStates)[number];
+interface ResolveModels {
+	readonly totals: Pick<Totals, "queryWindow" | "getOne">;
+	readonly breakdowns: Pick<Breakdowns, "getForPeriod">;
+	readonly markers: Pick<AppliedMarkers, "isApplied">;
+}
+/**
+* Resolves one bucket's totals, computing an in-progress period on the fly from
+* exactly one grain finer, following only the current edge deeper.
+*
+* A sealed period (strictly past, rollup marker applied) is read from its stored
+* aggregate. Otherwise the period is the sum of its children at the next finer
+* grain, where every already-complete child is taken from its stored aggregate
+* and only the single in-progress child is resolved recursively:
+*
+* - partial day   = stored/queried hours `00..currentHour`
+* - partial month = stored days `01..currentDay-1` + the partial current day
+* - partial year  = stored months `01..currentMonth-1` + the partial current month
+*
+* So a partial month never fans out to hours for its finished days (it trusts
+* their day aggregate) — only the one current day drills into hours. Each level
+* is one ranged query, keeping the read count bounded (a year touches ~12
+* months + ~31 days + ~24 hours) and the request sub-second.
+*/
+declare function resolveTotalsLive({ models, grain, periodKey, now }: {
+	readonly models: ResolveModels;
+	readonly grain: Grain;
+	readonly periodKey: string;
+	readonly now: Date;
+}): Promise<SummedTotals>;
+declare function resolveBreakdownLive({ models, dimension, grain, periodKey, now }: {
+	readonly models: ResolveModels;
+	readonly dimension: Dimension;
+	readonly grain: Grain;
+	readonly periodKey: string;
+	readonly now: Date;
+}): Promise<Array<BreakdownRow>>;
+/**
+* Classifies a bucket as sealed / partial / pending without recomputing its
+* value. A sealed bucket is a finalized rollup (its marker is applied), so a
+* zero-hit sealed bucket is genuine "no traffic". A non-sealed bucket that
+* yielded data is in-progress (`partial`); one with nothing to show is awaiting
+* processing (`pending`).
+*/
+declare function classifyBucketState({ models, grain, periodKey, now, hasData }: {
+	readonly models: ResolveModels;
+	readonly grain: Grain;
+	readonly periodKey: string;
+	readonly now: Date;
+	readonly hasData: boolean;
+}): Promise<BucketState>;
 declare function yearKey(date: Date): string;
 declare function monthKey2(date: Date): string;
 declare function dayKey2(date: Date): string;
 declare function hourKey2(date: Date): string;
+/**
+* Parses a period key (any grain) back to the UTC Date at the start of that
+* bucket. `YYYY` → Jan 1 00:00, `YYYY-MM` → 1st 00:00, `YYYY-MM-DD` → 00:00,
+* `YYYY-MM-DD-HH` → that hour. Throws on a malformed key.
+*/
+declare function parsePeriodKey(periodKey: string): Date;
+declare function grainForPeriodKey(periodKey: string): Grain | "year";
 declare function maxWindowFor(grain: Grain): number;
 declare function shiftAnchor({ grain, anchor, size, direction }: {
 	grain: Grain;
@@ -358,4 +455,4 @@ declare function hoursBetween({ from, to }: {
 	from: Date;
 	to: Date;
 }): Array<string>;
-export { AppliedMarker, AppliedMarkers, AppliedSource, AthenaColumnMap, BreakdownInput, BreakdownItem, BreakdownRow, Breakdowns, DeviceBucket, Dimension, Grain, HourlyAthenaResult, HourlyAthenaTotals, ProcessHourAthena, ProcessHourModels, ProcessHourOptions, ProcessHourResult, SummedTotals, Totals, TotalsInput, TotalsItem, TransactItem, appliedMarkerSchema, appliedSources, applyDailyRollup, applyMonthlyRollup, breakdownSchema, buildHourlyQuery, chunkTransactItems, classifyDevice, columnMaps, dayKey2 as dayKey, dimensions, grains, hourKey2 as hourKey, hourKeyParts, hoursBetween, maxWindowFor, monthKey2 as monthKey, processHour, requiredRecordFields, runHourlyAthenaQuery, shiftAnchor, sumBreakdown, sumTotals, topNWithOther, totalsSchema, windowKeys, yearKey };
+export { AnalyticsConfig, AppliedMarker, AppliedMarkers, AppliedSource, AthenaColumnMap, BreakdownInput, BreakdownItem, BreakdownRow, Breakdowns, BucketState, Config, DeviceBucket, Dimension, Grain, HourlyAthenaResult, HourlyAthenaTotals, ProcessHourAthena, ProcessHourModels, ProcessHourOptions, ProcessHourResult, ResolveModels, SummedTotals, Totals, TotalsInput, TotalsItem, TransactItem, View, appliedMarkerSchema, appliedSources, applyDailyRollup, applyMonthlyRollup, breakdownSchema, bucketStates, buildHourlyQuery, chunkTransactItems, classifyBucketState, classifyDevice, columnMaps, configSchema, dayKey2 as dayKey, dimensions, grainForPeriodKey, grains, hourKey2 as hourKey, hourKeyParts, hoursBetween, maxWindowFor, monthKey2 as monthKey, parsePeriodKey, processHour, requiredRecordFields, resolveBreakdownLive, resolveTotalsLive, runHourlyAthenaQuery, shiftAnchor, sumBreakdown, sumTotals, topNWithOther, totalsSchema, windowKeys, yearKey };