feat(traffic): persistence + sync API for Cloud Run sources (Phase 2 slice 1)

apps/web/src/App.tsx

@@ -80,6 +80,7 @@ function formatTrackedRunKind(kind: RunKind): string {
     case RunKinds['gsc-sync']: return 'GSC sync'
     case RunKinds['inspect-sitemap']: return 'Sitemap inspection'
     case RunKinds['ga-sync']: return 'GA sync'
+    case RunKinds['traffic-sync']: return 'Traffic sync'
     case RunKinds['bing-inspect']: return 'Bing URL inspection'
     case RunKinds['bing-inspect-sitemap']: return 'Bing sitemap inspection'
     case RunKinds['site-audit']: return 'Site audit'

apps/web/src/build-dashboard.ts

@@ -78,6 +78,7 @@ function kindLabel(kind: RunKind): string {
     case RunKinds['gsc-sync']: return 'GSC sync'
     case RunKinds['inspect-sitemap']: return 'Sitemap inspection'
     case RunKinds['ga-sync']: return 'GA sync'
+    case RunKinds['traffic-sync']: return 'Traffic sync'
     case RunKinds['bing-inspect']: return 'Bing URL inspection'
     case RunKinds['bing-inspect-sitemap']: return 'Bing sitemap inspection'
     case RunKinds['site-audit']: return 'Site audit'

apps/web/src/queries/run-invalidations.ts

@@ -30,6 +30,7 @@ export function invalidateQueriesForRunKind(
       void queryClient.invalidateQueries({ queryKey: queryKeys.gsc.project(projectName) })
       return
     case RunKinds['ga-sync']:
+    case RunKinds['traffic-sync']:
       void queryClient.invalidateQueries({ queryKey: queryKeys.traffic.project(projectName) })
       return
     case RunKinds['bing-inspect']:

docs/data-model.md

@@ -34,6 +34,11 @@ erDiagram
   projects ||--o{ bing_keyword_stats : has
   projects ||--o{ bing_coverage_snapshots : has
 
+  projects ||--o{ traffic_sources : has
+  traffic_sources ||--o{ crawler_events_hourly : "rolls up"
+  traffic_sources ||--o{ ai_referral_events_hourly : "rolls up"
+  traffic_sources ||--o{ raw_event_samples : "samples"
+
   projects ||--o| agent_sessions : "has (1:1)"
   projects ||--o{ agent_memory : has
 ```
@@ -81,6 +86,15 @@ erDiagram
 | **ga_ai_referrals** | AI engine referral tracking. Unique: `(projectId, date, source, medium, sourceDimension)` |
 | **ga_social_referrals** | Social media referral tracking. Unique: `(projectId, date, source, medium, channelGroup)` |
 
+### Server-Side Traffic Ingestion
+
+| Table | Purpose |
+|-------|---------|
+| **traffic_sources** | Per-connection metadata (Cloud Run today; future WordPress / Cloudflare / Vercel). Status `connected` / `paused` / `error` / `archived`. Credentials live in `~/.canonry/config.yaml`, never here. FK: projectId → projects. |
+| **crawler_events_hourly** | Hourly rollup of server-observed AI crawler hits. Composite PK `(projectId, sourceId, tsHour, botId, verificationStatus, pathNormalized, status)` so repeat syncs upsert via `hits + ?`. |
+| **ai_referral_events_hourly** | Hourly rollup of server-observed human AI-referral clicks (UTM or referer evidence). Composite PK matches the crawler bucket pattern. |
+| **raw_event_samples** | Bounded sample tail for classifier debugging (default 30-day retention). FK: sourceId → traffic_sources. |
+
 ### Intelligence
 
 | Table | Purpose |

package.json

@@ -1,7 +1,7 @@
 {
   "name": "canonry",
   "private": true,
-  "version": "4.11.1",
+  "version": "4.12.1",
   "type": "module",
   "packageManager": "[email protected]",
   "scripts": {

packages/api-routes/AGENTS.md

@@ -22,6 +22,7 @@ Shared Fastify route plugins used by both the local server (`packages/canonry`)
 | `src/report.ts` | `GET /projects/:name/report` (JSON DTO) and `GET /projects/:name/report.html` (standalone downloadable HTML) — aggregated client-facing AEO report bundle (13 sections) |
 | `src/report-renderer.ts` | `renderReportHtml(report)` — server-side HTML renderer with inline SVG charts and inline CSS, re-exported from `@ainyc/canonry-api-routes` for the CLI |
 | `src/wordpress.ts` | WordPress integration routes |
+| `src/traffic.ts` | Server-side traffic ingestion routes — `POST /traffic/connect/cloud-run`, `POST /traffic/sources/:id/sync`. Credentials resolved through an injected `cloudRunCredentialStore`; the Cloud Logging pull and access-token resolver are also injectable for tests. |
 | `src/backlinks.ts` | Backlinks (Common Crawl sync + per-project extract/summary/domains/history) routes |
 | `src/doctor.ts` | `GET /doctor` and `GET /projects/:name/doctor` — runs check registry, returns `DoctorReport` |
 | `src/doctor/registry.ts` | `ALL_CHECKS` — single source of truth for the doctor check catalog |

packages/api-routes/package.json

@@ -21,9 +21,11 @@
     "@ainyc/canonry-db": "workspace:*",
     "@ainyc/canonry-intelligence": "workspace:*",
     "@ainyc/canonry-integration-bing": "workspace:*",
+    "@ainyc/canonry-integration-cloud-run": "workspace:*",
     "@ainyc/canonry-integration-google": "workspace:*",
     "@ainyc/canonry-integration-commoncrawl": "workspace:*",
     "@ainyc/canonry-integration-google-analytics": "workspace:*",
+    "@ainyc/canonry-integration-traffic": "workspace:*",
     "@ainyc/canonry-integration-wordpress": "workspace:*",
     "drizzle-orm": "^0.45.1",
     "fastify": "^5.4.0"

packages/api-routes/src/index.ts

@@ -41,6 +41,8 @@ import { wordpressRoutes } from './wordpress.js'
 import type { WordpressRoutesOptions } from './wordpress.js'
 import { backlinksRoutes } from './backlinks.js'
 import type { BacklinksRoutesOptions } from './backlinks.js'
+import { trafficRoutes } from './traffic.js'
+import type { TrafficRoutesOptions, CloudRunCredentialStore } from './traffic.js'
 import { doctorRoutes } from './doctor.js'
 
 declare module 'fastify' {
@@ -105,6 +107,12 @@ export interface ApiRoutesOptions {
   onCdpConfigure?: CDPRoutesOptions['onCdpConfigure']
   /** GA4 credential store — stores service account keys in config, not DB */
   ga4CredentialStore?: Ga4CredentialStore
+  /** Cloud Run credential store — stores SA keys / OAuth tokens in config, not DB */
+  cloudRunCredentialStore?: CloudRunCredentialStore
+  /** Override Cloud Run pull (tests) — see `TrafficRoutesOptions` */
+  pullCloudRunEvents?: TrafficRoutesOptions['pullCloudRunEvents']
+  /** Override Cloud Run access-token resolver (tests) — see `TrafficRoutesOptions` */
+  resolveCloudRunAccessToken?: TrafficRoutesOptions['resolveCloudRunAccessToken']
   /** Backlinks feature callbacks — see `backlinksRoutes` for details. */
   getBacklinksStatus?: BacklinksRoutesOptions['getBacklinksStatus']
   onInstallBacklinks?: BacklinksRoutesOptions['onInstallBacklinks']
@@ -262,6 +270,11 @@ export async function apiRoutes(app: FastifyInstance, opts: ApiRoutesOptions) {
       googleConnectionStore: opts.googleConnectionStore,
       getGoogleAuthConfig: opts.getGoogleAuthConfig,
     } satisfies GA4RoutesOptions)
+    await api.register(trafficRoutes, {
+      cloudRunCredentialStore: opts.cloudRunCredentialStore,
+      pullCloudRunEvents: opts.pullCloudRunEvents,
+      resolveCloudRunAccessToken: opts.resolveCloudRunAccessToken,
+    } satisfies TrafficRoutesOptions)
     // Always mount the backlinks routes so read endpoints (summary, domains,
     // history, sync list) work off the shared DB. Action routes (install,
     // sync, extract, cache prune) throw MISSING_DEPENDENCY when the host

packages/api-routes/src/openapi.ts

@@ -2735,6 +2735,68 @@ const routeCatalog: OpenApiOperation[] = [
       404: { description: 'Project not found.' },
     },
   },
+  {
+    method: 'post',
+    path: '/api/v1/projects/{name}/traffic/connect/cloud-run',
+    summary: 'Connect a Cloud Run traffic source',
+    description:
+      'Stores the service-account JSON in `~/.canonry/config.yaml` and creates a `traffic_sources` row for the project. Reconnecting updates the existing active source rather than creating a duplicate.',
+    tags: ['traffic'],
+    parameters: [nameParameter],
+    requestBody: {
+      required: true,
+      content: {
+        'application/json': {
+          schema: {
+            type: 'object',
+            required: ['gcpProjectId', 'keyJson'],
+            properties: {
+              gcpProjectId: stringSchema,
+              serviceName: stringSchema,
+              location: stringSchema,
+              displayName: stringSchema,
+              keyJson: { ...stringSchema, description: 'Service-account JSON content.' },
+            },
+          },
+        },
+      },
+    },
+    responses: {
+      200: { description: 'Traffic source DTO returned.' },
+      400: { description: 'Invalid Cloud Run connection request.' },
+      404: { description: 'Project not found.' },
+    },
+  },
+  {
+    method: 'post',
+    path: '/api/v1/projects/{name}/traffic/sources/{id}/sync',
+    summary: 'Trigger a sync run for a traffic source',
+    description:
+      'Pulls request logs from the configured Cloud Run service for the lookback window, classifies crawler / AI-referral hits, and upserts hourly buckets and a bounded sample tail.',
+    tags: ['traffic'],
+    parameters: [
+      nameParameter,
+      { name: 'id', in: 'path', required: true, description: 'Traffic source ID.', schema: stringSchema },
+    ],
+    requestBody: {
+      required: false,
+      content: {
+        'application/json': {
+          schema: {
+            type: 'object',
+            properties: {
+              sinceMinutes: { ...integerSchema, description: 'Lookback window in minutes (default 60).' },
+            },
+          },
+        },
+      },
+    },
+    responses: {
+      200: { description: 'Sync summary returned.' },
+      400: { description: 'Invalid sync request, missing credentials, or upstream pull error.' },
+      404: { description: 'Project or traffic source not found.' },
+    },
+  },
 ]
 
 /**