@beesolve/analytics-processor 0.4.0 → 0.5.0

package/DOCS.md

@@ -1,18 +1,38 @@
 # @beesolve/analytics-processor - Documentation
 
-**Keywords:** CloudFront analytics, Athena, DynamoDB totals, breakdowns, rollups, AnalyticsProcessor construct, grantRead, processHour, hourKey, windowKeys, Grain, Dimension, backfill
+**Keywords:** CloudFront analytics, Athena, DynamoDB totals, breakdowns, rollups, AnalyticsProcessor construct, grantRead, processHour, hourKey, windowKeys, Grain, Dimension, backfill, sitemap URL stats, SitemapUrlStats, getForUrl, getForMonth, canonicalPath
 
 > This documentation is published inside the installed package and matches the installed version. Prefer it over prior knowledge or older examples found online.
 
 > Full source and ADRs: https://github.com/BeeSolve/packages/tree/main/packages/analytics-processor
 
-This package does not ship how-to guides. See the [README](./README.md) for the API
-reference and usage, and the GitHub repository for source and examples.
+See the [README](./README.md) for the API reference and usage, the how-to guides below for
+task-focused walkthroughs, and the GitHub repository for source and examples.
+
+## Sitemap URL stats
+
+The hourly breakdown keeps only a top-100-by-hits `path` list per hour; everything else
+collapses into `__other__`, so genuine articles are lost under bot traffic. Sitemap URL stats
+are a separate, parallel model that accumulates per-day hit counts for a known set of URLs
+(the site's sitemap) and stores one item per `(path, year-month)`.
+
+- **Config**: set `sitemapUrl` on the shared config item (`Config.setSitemapUrl`); the hourly
+  sitemap processor fetches and resolves it to a path set.
+- **Processor**: an hourly Lambda scans one lagged hour and `ADD`s each sitemap path's hits
+  into that day's `dNN` + the `hits` month rollup, guarded by a per-hour applied-marker so the
+  hour counts exactly once.
+- **Read model**: `SitemapUrlStats` with `getForUrl` (one URL across months) and
+  `getForMonth` (all URLs in a month, for month-over-month comparison).
+
+See [the how-to guide](./docs/how-to/sitemap-url-stats.md) and
+[ADR-007](./docs/adr-007-sitemap-url-stats.md) for details.
 
 ## How-To Guides
 
 - [Reduce Athena cost](./docs/how-to/reduce-athena-cost.md) - deliver only the 10 fields
   the processor needs via the exported `requiredRecordFields`
+- [Track per-article hits with sitemap URL stats](./docs/how-to/sitemap-url-stats.md) - the
+  `sitemapUrl` config, the hourly sitemap processor, and the `SitemapUrlStats` read model
 
 ## Further Reading
 

package/dist/cdk.js

@@ -85,6 +85,48 @@ class AnalyticsProcessor extends Construct {
         resources: [props.athenaResultsBucketArn, `${props.athenaResultsBucketArn}/*`]
       }));
     }
+    const sitemap = new Nodejs24Function(this, "Sitemap", {
+      description: "CloudFront analytics sitemap processor — fetches sitemap, recomputes per-URL monthly hits",
+      entry: `${builtDir}sitemap/`,
+      handler: "sitemap.handler",
+      memorySize,
+      timeout,
+      environment: {
+        ...sharedEnvironment,
+        ATHENA_DATABASE: props.athenaDatabase,
+        ATHENA_V2_TABLE: props.athenaV2Table,
+        ATHENA_WORKGROUP: props.athenaWorkgroup,
+        ...props.athenaOutputLocation != null ? { ATHENA_OUTPUT_LOCATION: props.athenaOutputLocation } : {}
+      }
+    });
+    this.table.grantReadWriteData(sitemap);
+    sitemap.addToRolePolicy(new PolicyStatement({
+      effect: Effect.ALLOW,
+      actions: [
+        "athena:StartQueryExecution",
+        "athena:GetQueryExecution",
+        "athena:GetQueryResults",
+        "athena:StopQueryExecution"
+      ],
+      resources: ["*"]
+    }));
+    sitemap.addToRolePolicy(new PolicyStatement({
+      effect: Effect.ALLOW,
+      actions: ["glue:GetTable", "glue:GetDatabase", "glue:GetPartitions"],
+      resources: ["*"]
+    }));
+    sitemap.addToRolePolicy(new PolicyStatement({
+      effect: Effect.ALLOW,
+      actions: ["s3:GetObject", "s3:ListBucket", "s3:GetBucketLocation"],
+      resources: [props.logBucketArn, `${props.logBucketArn}/*`]
+    }));
+    if (props.athenaResultsBucketArn != null) {
+      sitemap.addToRolePolicy(new PolicyStatement({
+        effect: Effect.ALLOW,
+        actions: ["s3:PutObject", "s3:GetObject", "s3:GetBucketLocation", "s3:ListBucket"],
+        resources: [props.athenaResultsBucketArn, `${props.athenaResultsBucketArn}/*`]
+      }));
+    }
     const dailyRollup = new Nodejs24Function(this, "DailyRollup", {
       description: "CloudFront analytics daily rollup — sums hourly DynamoDB items",
       entry: `${builtDir}dailyRollup/`,
@@ -107,6 +149,10 @@ class AnalyticsProcessor extends Construct {
       schedule: Schedule.rate(Duration.hours(1)),
       targets: [new LambdaFunctionTarget(hourly)]
     });
+    new Rule(this, "SitemapSchedule", {
+      schedule: Schedule.rate(Duration.hours(1)),
+      targets: [new LambdaFunctionTarget(sitemap)]
+    });
     new Rule(this, "DailyRollupSchedule", {
       schedule: Schedule.cron({ minute: "15", hour: "0" }),
       targets: [new LambdaFunctionTarget(dailyRollup)]