@beesolve/analytics-processor 0.2.5 → 0.3.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>;
@@ -158,8 +83,10 @@ interface AthenaColumnMap {
 * logical field is addressed in each table.
 *
 * v2 is the Parquet Glue table: Athena normalizes Parquet column names to
-* lowercase with hyphens folded to underscores, and numeric columns are already
-* typed, so no casting is needed.
+* lowercase with hyphens folded to underscores. CloudFront standard-logging-v2
+* stores every Parquet field as BINARY/string, so the Glue schema types every
+* column as string and numeric references must cast explicitly — just like v1,
+* but on the normalized (unquoted) column names.
 *
 * v1 is the legacy tab-delimited LazySimpleSerDe table: its column names contain
 * hyphens and parentheses, so they must be double-quoted, and every numeric
@@ -225,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;
 	});
@@ -269,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;
@@ -278,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">;
@@ -311,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>;
@@ -333,10 +362,48 @@ interface RollupModels {
 	readonly breakdowns: Pick<Breakdowns, "buildUpdates" | "getForPeriod">;
 	readonly markers: Pick<AppliedMarkers, "isApplied" | "buildMarkerPut">;
 }
+type View = Grain | "year";
+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
+* the grain below it. A past period whose rollup marker is applied is read
+* directly from the stored aggregate ("sealed"); the current period, and any
+* past period still missing its marker, is summed from its children — the
+* current month folds down through the current day to the hours ingested so far.
+*
+* Each level reads its children with a single ranged query (never a get per
+* child): a day sums its hours via one hourly `queryWindow`; a month sums its
+* days, and the one in-progress day among them is resolved from hours. `hour`
+* is terminal.
+*/
+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>>;
 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;
@@ -356,4 +423,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, Config, DeviceBucket, Dimension, Grain, HourlyAthenaResult, HourlyAthenaTotals, ProcessHourAthena, ProcessHourModels, ProcessHourOptions, ProcessHourResult, ResolveModels, SummedTotals, Totals, TotalsInput, TotalsItem, TransactItem, View, appliedMarkerSchema, appliedSources, applyDailyRollup, applyMonthlyRollup, breakdownSchema, buildHourlyQuery, chunkTransactItems, 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 };