Merge pull request #492 from databuddy-analytics/staging

Release: staging -> main (privacy controls, insights, AI investigation pipeline)

Author: izadoesdev

.agents/skills/databuddy-internal/SKILL.md

@@ -15,6 +15,8 @@ When a mistake could have been avoided with better repo context (wrong app, pack
 
 Keep additions **minimal**: one bullet, a new `rg` hint, or a routing note—enough that the next session does not repeat it. If the lesson is for SDK/API customers, add it under `.agents/skills/databuddy/` instead.
 
+- Repo-local `.agents/skills` is versioned project guidance. Put new personal or experimental agent skills under `/Users/iza/.agents/skills` unless the user explicitly wants the skill committed with Databuddy.
+
 ## Quick Map
 
 - Prod infrastructure repo is local at `/Users/iza/Documents/GitHub/databuddy-infra` (`databuddy-analytics/infra`); ClickHouse cluster inventory is `clickhouse/ansible/inventory.yml`, not `/Users/iza/Dev/Databuddy/infra` or `DatabuddyOPS`.
@@ -24,6 +26,7 @@ Keep additions **minimal**: one bullet, a new `rg` hint, or a routing note—eno
 - Local E2E dashboard smokes that need `/api/test/e2e/*` should start the API/dashboard directly (or through Playwright's webServer command), not via `bun run dev:dashboard`; Turbo runs in strict env mode and drops `DATABUDDY_E2E_MODE`/`DATABUDDY_E2E_TEST_KEY` unless they are added to `turbo.json` `globalEnv`.
 - Dashboard Playwright public/demo analytics specs call API `/v1/query` anonymously from the browser; keep `DATABUDDY_E2E_MODE` query behavior isolated from production rate limits so CI retries do not exhaust `anon:unknown`.
 - `apps/api`: Elysia API on port `3001`
+- Public REST docs live in `apps/api/src/rpc/openapi.ts`: `/spec.json` is the generated spec, `/` is the reference UI, and hiding a router there also makes its top-level REST paths return 404 because `/*` uses the same filtered docs router.
 - `apps/slack`: Slack agent adapter; Slack installs must resolve through org-scoped DB integration records, not a single env bot token/default website. Agent calls must use an encrypted per-integration Databuddy API key secret as a normal bearer token, never a global internal secret.
 - Slack OAuth lives in `apps/api`, but slash commands/events require `apps/slack` to be running too; local `bun run dev:dashboard` runs dashboard + API only, so use `bun run dev:slack` when working on Slack. The Slack package scripts read the root `.env`.
 - Slack routing is organization-scoped: OAuth binds a Slack workspace to a Databuddy organization, app mentions from the installed workspace auto-bind channels including Slack Connect, and `/bind` is now a manual fallback for unknown/unapproved channels. DMs/assistant threads work after workspace install. Analytics questions should go through app mentions/DMs using MCP-style website discovery inside the installed organization, never by fanning out across the message sender's user memberships. Slack emits evlog events under `apps/slack/.evlog/logs` in development/`SLACK_EVLOG_FS=1`; Axiom uses `AXIOM_TOKEN` with `SLACK_AXIOM_DATASET` defaulting to `slack`; and reactions need the `reactions:write` bot scope. Remote manifest updates need `SLACK_APP_ID` plus a Slack app configuration token in `SLACK_APP_CONFIG_TOKEN`; trust Slack API errors over token-prefix guesses.
@@ -32,6 +35,7 @@ Keep additions **minimal**: one bullet, a new `rg` hint, or a routing note—eno
 - Slack memory is separate from billing/auth: pass a Slack-scoped `memoryUserId` such as `slack-{team}-{user}` plus current-speaker context so one Slack user's saved name/preferences do not bleed into another user's replies.
 - Slack agent write tools need the integration automation API key to include the matching Databuddy API scopes (currently `read:data`, `read:links`, `write:links`, `manage:websites`, `manage:flags`); older installs may need reconnecting so a new key is minted.
 - Shared agent integrations should call `@databuddy/ai/agent` (`askDatabuddyAgent` / `streamDatabuddyAgent`) instead of importing internal MCP run/history helpers directly.
+- First-party ads attribution work should start by preserving UTMs into registration and signup events only; do not add RPC plumbing, conversion destinations, env hooks, tables, workers, or UI until explicitly needed.
 - Insights generation logic belongs in `apps/insights` and should reuse `@databuddy/ai`; `apps/api` should only read insight data or queue runs, not own prompts, model calls, tool loops, validation, or persistence orchestration.
 - Agent ClickHouse SQL must use the canonical analytics.events schema: `client_id`, `time`, `path`, `event_name`, and pageviews as `event_name = 'screen_view'`; never `website_id`, `created_at`, `page_path`, `event_type`, or `pageview`.
 - Slack agent evals live in `packages/evals`: use `bun run eval --surface slack` for the whole Slack surface. `--tag slack` is only a tiny smoke subset, and `cost_fallback` in agent telemetry is pricing-catalog fallback, not proof the model request fell back.
@@ -159,6 +163,8 @@ Read [codebase-map.md](./references/codebase-map.md) when you need deeper routin
 
 - Published SDK logic: `packages/sdk/src`
 - Browser tracker bundle: `packages/tracker/src`
+- Public SDK/tracker visitor ID privacy is only `anonymizeVisitorIds` (`true`/omitted = anonymized, `false` = raw IDs, `"auto"` = raw only in Databuddy's conservative country allowlist).
+- Keep visitor ID privacy internals small and direct; avoid exported helper stacks or storage/hashing vocabulary for this option.
 - If the user reports missing analytics events, inspect both the producer side and `apps/basket`
 
 ## Verification

.agents/skills/databuddy/SKILL.md

@@ -47,6 +47,7 @@ Read [troubleshooting.md](./references/troubleshooting.md) for CSP, blockers, wr
 - API auth accepts `x-api-key: dbdy_...` or `Authorization: Bearer dbdy_...`; prefer `x-api-key` for examples unless docs for that endpoint use Bearer.
 - `websiteId` in event tracking means the public website client id, the same kind of value used by `data-client-id`; it is not necessarily an internal UUID.
 - For server-side attribution, collect `{ anonId, sessionId }` in the browser with `getTrackingIds()`, pass them to your backend, then map them to Node SDK fields `anonymousId` and `sessionId`.
+- Visitor ID privacy is configured with `anonymizeVisitorIds` (`true`/omitted = anonymized, `false` = keeps raw IDs, `"auto"` = raw only in Databuddy's conservative country allowlist); avoid internal wording like storage or hashing in public examples.
 - Do not invent a Databuddy `identify()` helper or endpoint. If an app has an identify route, treat it as the user's own backend code carrying Databuddy tracking IDs.
 - Feature flag evaluation uses the main API host, not basket. It needs a website `clientId`, not API-key-only auth.
 - Feature flag management uses `manage:flags` with `x-api-key`; do not expose that key in browser source. DevTools accepts it at runtime for local/preview flag management.

.env.example

@@ -27,7 +27,7 @@ OPR_API_KEY=""
 # Not necessary, disabled if node env is development
 AUTUMN_SECRET_KEY="autumn pls sponsor me ily"
 
-# Important for local
+# Local dev default. Root build/start scripts force NODE_ENV=production.
 NODE_ENV=development
 
 # Not necessary, except for github oauth

.github/workflows/dashboard-e2e.yml

@@ -99,7 +99,10 @@ jobs:
       - run: bun install --frozen-lockfile --ignore-scripts
       - name: Build dashboard runtime packages
         run: bunx turbo run build --filter @databuddy/cache --filter @databuddy/devtools --filter @databuddy/sdk
-      - run: bunx playwright install --with-deps chromium
+      - name: Install dashboard Playwright browser
+        run: |
+          bun run --cwd apps/dashboard playwright --version
+          bun run --cwd apps/dashboard playwright install --with-deps chromium
       - name: Run dashboard E2E
         run: |
           if [[ "${{ github.event_name }}" == "pull_request" ]]; then

apps/api/src/bootstrap/logger.ts

@@ -1,9 +1,11 @@
+import { databuddyEvlogRedaction } from "@databuddy/shared/evlog-redaction";
 import { initLogger } from "evlog";
 import { apiLoggerDrain } from "@/lib/evlog-api";
 
 export function configureApiLogger() {
 	initLogger({
 		env: { service: "api" },
+		redact: databuddyEvlogRedaction,
 		drain: apiLoggerDrain,
 		sampling: {
 			rates: { info: 20, warn: 50, debug: 5 },

apps/api/src/http/errors.test.ts

@@ -0,0 +1,58 @@
+import { createError } from "evlog";
+import { afterEach, describe, expect, it } from "vitest";
+import { handleAppError } from "./errors";
+
+const originalNodeEnv = process.env.NODE_ENV;
+
+afterEach(() => {
+	process.env.NODE_ENV = originalNodeEnv;
+});
+
+async function readPayload(response: Response): Promise<Record<string, unknown>> {
+	return response.json() as Promise<Record<string, unknown>>;
+}
+
+describe("handleAppError", () => {
+	it("masks structured 5xx details in production", async () => {
+		process.env.NODE_ENV = "production";
+		const response = handleAppError({
+			error: createError({
+				code: "api.SECRET_FAILURE",
+				message: "Database password leaked into error",
+				status: 500,
+				why: "Internal connection string failed",
+				fix: "Rotate credentials",
+				link: "https://internal.example.com/runbook",
+			}),
+		});
+
+		expect(response.status).toBe(500);
+		expect(await readPayload(response)).toEqual({
+			success: false,
+			error: "An internal server error occurred",
+			code: "api.SECRET_FAILURE",
+		});
+	});
+
+	it("keeps structured 4xx details visible in production", async () => {
+		process.env.NODE_ENV = "production";
+		const response = handleAppError({
+			error: createError({
+				code: "api.BAD_INPUT",
+				message: "Invalid filter",
+				status: 400,
+				why: "The filter operator is unsupported.",
+				fix: "Use one of the documented operators.",
+			}),
+		});
+
+		expect(response.status).toBe(400);
+		expect(await readPayload(response)).toEqual({
+			success: false,
+			error: "Invalid filter",
+			code: "api.BAD_INPUT",
+			why: "The filter operator is unsupported.",
+			fix: "Use one of the documented operators.",
+		});
+	});
+});

apps/api/src/http/errors.ts

@@ -1,4 +1,4 @@
-import { parseError } from "evlog";
+import { EvlogError, parseError } from "evlog";
 
 interface AppErrorContext {
 	code?: string | number;
@@ -30,15 +30,21 @@ export function handleAppError({ error, code }: AppErrorContext) {
 		error,
 		parsedStatus: parsed.status,
 	});
-	const errorCode = code == null ? "INTERNAL_SERVER_ERROR" : String(code);
+	const errorCode = getErrorCode({
+		explicitCode: code,
+		parsedCode: parsed.code,
+	});
 	const isDevelopment = process.env.NODE_ENV === "development";
 	const isClientError = statusCode >= 400 && statusCode < 500;
-	const errorMessage = error instanceof Error ? error.message : String(error);
-	const safeClientError =
-		isDevelopment || isClientError
-			? errorMessage
-			: "An internal server error occurred";
-	const exposeStructured = isDevelopment || isClientError;
+	const exposeStructured =
+		isDevelopment || (isClientError && isStructuredError(error));
+	const safeClientError = getSafeErrorMessage({
+		code: errorCode,
+		error,
+		isDevelopment,
+		isClientError,
+		statusCode,
+	});
 
 	return new Response(
 		JSON.stringify({
@@ -55,6 +61,96 @@ export function handleAppError({ error, code }: AppErrorContext) {
 	);
 }
 
+function getErrorCode({
+	explicitCode,
+	parsedCode,
+}: {
+	explicitCode?: string | number;
+	parsedCode: unknown;
+}): string {
+	if (typeof parsedCode === "string" && parsedCode !== "") {
+		return parsedCode;
+	}
+	return explicitCode == null ? "INTERNAL_SERVER_ERROR" : String(explicitCode);
+}
+
+function getSafeErrorMessage({
+	code,
+	error,
+	isClientError,
+	isDevelopment,
+	statusCode,
+}: {
+	code: string;
+	error: unknown;
+	isClientError: boolean;
+	isDevelopment: boolean;
+	statusCode: number;
+}): string {
+	if (isDevelopment) {
+		return error instanceof Error ? error.message : String(error);
+	}
+
+	if (isClientError && isStructuredError(error) && error instanceof Error) {
+		return error.message;
+	}
+
+	return SAFE_MESSAGE_BY_ERROR_CODE[code] ?? getSafeStatusMessage(statusCode);
+}
+
+function isStructuredError(error: unknown): error is EvlogError {
+	return error instanceof EvlogError;
+}
+
+const SAFE_MESSAGE_BY_ERROR_CODE: Record<string, string> = {
+	AUTH_REQUIRED: "Authentication required",
+	BAD_REQUEST: "Invalid request",
+	CONFLICT: "Conflict",
+	FEATURE_UNAVAILABLE: "Feature unavailable",
+	FORBIDDEN: "Forbidden",
+	INTERNAL_SERVER_ERROR: "An internal server error occurred",
+	INVALID_COOKIE_SIGNATURE: "Invalid request",
+	NOT_FOUND: "Not found",
+	PARSE: "Invalid request body",
+	PLAN_LIMIT_EXCEEDED: "Plan limit exceeded",
+	RATE_LIMITED: "Rate limit exceeded",
+	TOO_MANY_REQUESTS: "Rate limit exceeded",
+	UNAUTHORIZED: "Authentication required",
+	UNKNOWN: "An internal server error occurred",
+	VALIDATION: "Invalid request",
+};
+
+function getSafeStatusMessage(statusCode: number): string {
+	if (statusCode === 401) {
+		return "Authentication required";
+	}
+	if (statusCode === 403) {
+		return "Forbidden";
+	}
+	if (statusCode === 404) {
+		return "Not found";
+	}
+	if (statusCode === 409) {
+		return "Conflict";
+	}
+	if (statusCode === 413) {
+		return "Payload too large";
+	}
+	if (statusCode === 422) {
+		return "Invalid request";
+	}
+	if (statusCode === 429) {
+		return "Rate limit exceeded";
+	}
+	if (statusCode === 503) {
+		return "Service temporarily unavailable";
+	}
+	if (statusCode >= 400 && statusCode < 500) {
+		return "Invalid request";
+	}
+	return "An internal server error occurred";
+}
+
 function getStatusCode({
 	code,
 	error,

apps/api/src/integration/with-workspace.test.ts

@@ -584,6 +584,88 @@ describe("withWorkspace", () => {
 		});
 	});
 
+	describe("monitor resource", () => {
+		iit("allows API key with read:monitors to read monitors", async () => {
+			const org = await insertOrganization();
+
+			const ws = await withWorkspace(apiKeyContext(org.id, ["read:monitors"]), {
+				organizationId: org.id,
+				resource: "monitor",
+				permissions: ["read"],
+			});
+			expect(ws.tier).toBe("authed");
+			expect(ws.user).toBeNull();
+		});
+
+		iit("denies API key with read:data from reading monitors", async () => {
+			const org = await insertOrganization();
+
+			await expectCode(
+				withWorkspace(apiKeyContext(org.id, ["read:data"]), {
+					organizationId: org.id,
+					resource: "monitor",
+					permissions: ["read"],
+				}),
+				"FORBIDDEN",
+			);
+		});
+
+		iit("allows API key with write:monitors to write monitors", async () => {
+			const org = await insertOrganization();
+
+			const ws = await withWorkspace(apiKeyContext(org.id, ["write:monitors"]), {
+				organizationId: org.id,
+				resource: "monitor",
+				permissions: ["update"],
+			});
+			expect(ws.tier).toBe("authed");
+		});
+	});
+
+	describe("status page resource", () => {
+		iit("allows API key with read:status_pages to read status pages", async () => {
+			const org = await insertOrganization();
+
+			const ws = await withWorkspace(
+				apiKeyContext(org.id, ["read:status_pages"]),
+				{
+					organizationId: org.id,
+					resource: "status_page",
+					permissions: ["read"],
+				},
+			);
+			expect(ws.tier).toBe("authed");
+			expect(ws.user).toBeNull();
+		});
+
+		iit("denies API key with read:data from reading status pages", async () => {
+			const org = await insertOrganization();
+
+			await expectCode(
+				withWorkspace(apiKeyContext(org.id, ["read:data"]), {
+					organizationId: org.id,
+					resource: "status_page",
+					permissions: ["read"],
+				}),
+				"FORBIDDEN",
+			);
+		});
+
+		iit("allows API key with write:status_pages to write status pages", async () => {
+			const org = await insertOrganization();
+
+			const ws = await withWorkspace(
+				apiKeyContext(org.id, ["write:status_pages"]),
+				{
+					organizationId: org.id,
+					resource: "status_page",
+					permissions: ["update"],
+				},
+			);
+			expect(ws.tier).toBe("authed");
+		});
+	});
+
 	describe("plan gating", () => {
 		iit("rejects when required plan not met", async () => {
 			const user = await signUp();

apps/api/src/lib/auth-wide-event.ts

@@ -5,6 +5,7 @@ import {
 } from "@databuddy/api-keys/resolve";
 import { auth } from "@databuddy/auth";
 import { mergeWideEvent } from "@databuddy/ai/lib/tracing";
+import type { ApiAuthWideEventFields } from "@databuddy/shared/evlog-fields";
 
 export interface ResolvedAuth {
 	apiKeyResult: ResolveApiKeyResult | null;
@@ -18,7 +19,7 @@ export function getResolvedAuth(headers: Headers): ResolvedAuth | undefined {
 }
 
 export async function applyAuthWideEvent(headers: Headers): Promise<void> {
-	const fields: Record<string, string | number | boolean> = {};
+	const fields: Partial<ApiAuthWideEventFields> = {};
 
 	const hasKey = isApiKeyPresent(headers);
 	const [session, apiKeyResult] = await Promise.all([
@@ -72,5 +73,5 @@ export async function applyAuthWideEvent(headers: Headers): Promise<void> {
 		fields.organization_id = orgId;
 	}
 
-	mergeWideEvent(fields);
+	mergeWideEvent<ApiAuthWideEventFields>(fields);
 }