Release: revenue attribution, users LTV + email lookup, feedback pipeline, slack agent reliability and chart images

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

@@ -37,6 +37,9 @@ Keep additions **minimal**: one bullet, a new `rg` hint, or a routing note—eno
 - 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.
+- Automated insight digests have one organization-wide schedule (`off`, `daily`, or `weekly`) and one organization-wide delivery set; website selection is only for manual runs. Do not reintroduce per-website overrides, hourly/custom cadence, or cron input.
+- Insight run items are execution metadata, not rendered insight content; previews should use run status/counts or query real insights, never infer titles or bodies from run items.
+- Insight Slack delivery must resolve each channel binding to its active same-organization integration; never choose an arbitrary organization bot token.
 - 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.
 - Slack agent expected stops such as exhausted Databunny credits should throw `DatabuddyAgentUserError` from `@databuddy/ai/agent/errors`; Slack surfaces those messages directly and reserves the generic reconnect copy for real infrastructure failures.
@@ -53,6 +56,7 @@ Keep additions **minimal**: one bullet, a new `rg` hint, or a routing note—eno
 - Public status pages render from `apps/status`; `apps/dashboard` owns status-page management/config UI only. When cleaning public status UX, update shared `@databuddy/ui/uptime` pieces or `apps/status` wrappers instead of redesigning dashboard-only route remnants.
 - `packages/db`: Drizzle Postgres schema, client, and ClickHouse helpers
 - `packages/rpc`: shared oRPC router, procedures, auth-aware server context
+- `packages/rpc` must declare `drizzle-orm: "catalog:"` before importing `drizzle-orm/*` helpers such as `drizzle-orm/zod`; otherwise TypeScript can resolve a different Drizzle instance than `@databuddy/db` and reject table-derived schemas.
 - `packages/auth`: Better Auth setup, permissions, organization access
 - `packages/env`: per-app env schemas
 - `packages/shared`: shared types, flags, analytics schemas, utilities
@@ -109,7 +113,7 @@ Read [codebase-map.md](./references/codebase-map.md) when you need deeper routin
 - Funnel rows keep the action menu outside the main toggle button; put row padding on the sibling `Button`, not only on `List.Row`, so the visible row surface is clickable without nesting buttons.
 - Demo website navigation must be public-safe and route-backed; hide sensitive, configuration-heavy, or unavailable website features such as Agent, Feature Flags, Revenue, Users, Realtime, Anomalies, and website Settings instead of inheriting the full website nav. Goals and Funnels may be public demo surfaces, but keep them read-only.
 - Dashboard definitions for feature flags and target groups are admin surfaces; do not expose even sanitized rows to demo-tier/public website access.
-- Insights merged feed (`use-insights-feed`) collapses history + AI by `insightSignalDedupeKey` in `apps/dashboard/lib/insight-signal-key.ts` so the list is one row per signal (latest wins).
+- Insights feed (`use-insights-feed`) collapses persisted history by `insightSignalDedupeKey` in `apps/dashboard/lib/insight-signal-key.ts` so the list is one row per signal (latest wins); reads must not invoke AI generation.
 - Insights page (`app/(main)/insights`) should stay focused on the brief + signal queue; do not add generic global analytics KPI cards or top pages/referrers/countries tables there.
 - Theme: `apps/dashboard/app/globals.css`. **`--border` is intentionally subtle**; do not crank it darker for “contrast” unless **iza** asks—prefer text tokens or layout for readability.
 - Website analytics filters are two-way synced between Jotai and the `filters` URL param in `app/(main)/websites/[id]/layout.tsx`; guard URL-driven atom writes from echoing stale atom state back into `nuqs`, or adding a filter can lock the page during form submit.
@@ -139,6 +143,7 @@ Read [codebase-map.md](./references/codebase-map.md) when you need deeper routin
 
 ## Billing (Autumn)
 
+- Transactional billing email identity has three separate concepts: Autumn customer/billing owner, organization, and actual `to` recipient. Only personalize from the actual recipient record; if it is unavailable, omit the greeting rather than using the owner name. Keep `agent_credits` as an internal feature ID, but describe it to customers as Databunny usage or an AI analysis allowance and explain what it enables.
 - `autumn-js` v1.2.2+ — import `autumnHandler` from `autumn-js/fetch` (NOT `autumn-js/elysia`, that export was removed in v1.0)
 - For Elysia, mount with `.mount(autumnHandler(...))` — NOT `.use()`
 - `identify` callback receives `(request: Request)` directly, not `({ request })`
@@ -168,6 +173,7 @@ 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`
+- When a retryable batch failure restores events to an in-memory queue, it must also restore an automatic retry timer with capped backoff; requeueing alone silently stalls delivery.
 - 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`

.github/workflows/ci.yml

@@ -43,6 +43,8 @@ jobs:
     name: Check Types
     runs-on: blacksmith-4vcpu-ubuntu-2404
     timeout-minutes: 15
+    env:
+      CLICKHOUSE_READONLY_URL: ${{ secrets.CLICKHOUSE_READONLY_URL }}
     steps:
       - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
       - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
@@ -56,6 +58,11 @@ jobs:
       - run: bun install --frozen-lockfile --ignore-scripts
       - run: bun run --cwd apps/docs postinstall
       - run: bun run check-types
+      - name: ClickHouse types match DDL
+        run: bun run --cwd packages/db ch:check
+      - name: ClickHouse schema matches cluster
+        if: env.CLICKHOUSE_READONLY_URL != ''
+        run: bun run --cwd packages/db ch:verify
 
   test:
     name: Test

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

@@ -1,4 +1,5 @@
 import { createError } from "evlog";
+import { t, ValidationError } from "elysia";
 import { afterEach, describe, expect, it } from "vitest";
 import { handleAppError } from "./errors";
 
@@ -16,6 +17,7 @@ describe("handleAppError", () => {
 	it("masks structured 5xx details in production", async () => {
 		process.env.NODE_ENV = "production";
 		const response = handleAppError({
+			requestId: "req_test_5xx",
 			error: createError({
 				code: "api.SECRET_FAILURE",
 				message: "Database password leaked into error",
@@ -27,16 +29,19 @@ describe("handleAppError", () => {
 		});
 
 		expect(response.status).toBe(500);
-		expect(await readPayload(response)).toEqual({
-			success: false,
-			error: "An internal server error occurred",
-			code: "api.SECRET_FAILURE",
-		});
+			expect(await readPayload(response)).toEqual({
+				success: false,
+				error: "An internal server error occurred",
+				code: "api.SECRET_FAILURE",
+				requestId: "req_test_5xx",
+			});
+			expect(response.headers.get("X-Request-ID")).toBe("req_test_5xx");
 	});
 
 	it("keeps structured 4xx details visible in production", async () => {
 		process.env.NODE_ENV = "production";
 		const response = handleAppError({
+			requestId: "req_test_4xx",
 			error: createError({
 				code: "api.BAD_INPUT",
 				message: "Invalid filter",
@@ -47,12 +52,38 @@ describe("handleAppError", () => {
 		});
 
 		expect(response.status).toBe(400);
-		expect(await readPayload(response)).toEqual({
+			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.",
+				fix: "Use one of the documented operators.",
+				requestId: "req_test_4xx",
+			});
+	});
+
+	it("returns safe field details for request validation errors", async () => {
+		process.env.NODE_ENV = "production";
+		const response = handleAppError({
+			code: "VALIDATION",
+			requestId: "req_test_validation",
+			error: new ValidationError(
+				"body",
+				t.Object({ name: t.String({ minLength: 1 }) }),
+				{}
+			),
+		});
+		const payload = await readPayload(response);
+
+		expect(response.status).toBe(422);
+		expect(payload).toMatchObject({
+			success: false,
+			error: "Invalid request",
+			code: "VALIDATION",
+			requestId: "req_test_validation",
 		});
+		expect(payload.details).toEqual([
+			expect.objectContaining({ field: "body.name" }),
+		]);
 	});
 });

apps/api/src/http/errors.ts

@@ -1,16 +1,20 @@
 import { config } from "@databuddy/env/app";
+import { ValidationError } from "elysia";
 import { EvlogError, parseError } from "evlog";
+import { getRequestId } from "./request-id";
 
 interface AppErrorContext {
 	code?: string | number;
 	error: unknown;
+	request?: Request;
+	requestId?: string;
 }
 
 const HTTP_STATUS_BY_ERROR_CODE: Record<string, number> = {
 	AUTH_REQUIRED: 401,
 	BAD_REQUEST: 400,
 	CONFLICT: 409,
-	FEATURE_UNAVAILABLE: 403,
+	FEATURE_UNAVAILABLE: 402,
 	FORBIDDEN: 403,
 	INTERNAL_SERVER_ERROR: 500,
 	INVALID_COOKIE_SIGNATURE: 400,
@@ -25,8 +29,15 @@ const HTTP_STATUS_BY_ERROR_CODE: Record<string, number> = {
 };
 
 const PROTECTED_RESOURCE_METADATA_URL = `${config.urls.api}/.well-known/oauth-protected-resource`;
+const LEADING_SLASH_PATTERN = /^\//;
 
-export function handleAppError({ error, code }: AppErrorContext) {
+export function handleAppError({
+	error,
+	code,
+	request,
+	requestId,
+}: AppErrorContext) {
+	const responseRequestId = requestId ?? getRequestId(request);
 	const parsed = parseError(error);
 	const statusCode = getStatusCode({
 		code,
@@ -48,8 +59,10 @@ export function handleAppError({ error, code }: AppErrorContext) {
 		isClientError,
 		statusCode,
 	});
+	const validationDetails = getValidationDetails(error);
 	const headers: Record<string, string> = {
 		"Content-Type": "application/json",
+		"X-Request-ID": responseRequestId,
 	};
 	if (statusCode === 401) {
 		headers["WWW-Authenticate"] =
@@ -61,16 +74,55 @@ export function handleAppError({ error, code }: AppErrorContext) {
 			success: false,
 			error: safeClientError,
 			code: errorCode,
+			requestId: responseRequestId,
 			...(hasValue(parsed.why) && exposeStructured ? { why: parsed.why } : {}),
 			...(hasValue(parsed.fix) && exposeStructured ? { fix: parsed.fix } : {}),
 			...(hasValue(parsed.link) && exposeStructured
 				? { link: parsed.link }
 				: {}),
+			...(validationDetails.length > 0 ? { details: validationDetails } : {}),
 		}),
 		{ status: statusCode, headers }
 	);
 }
 
+interface ValidationDetail {
+	field: string;
+	message: string;
+}
+
+function getValidationDetails(error: unknown): ValidationDetail[] {
+	if (!(error instanceof ValidationError) || error.type === "response") {
+		return [];
+	}
+
+	const details: ValidationDetail[] = [];
+	const seenFields = new Set<string>();
+	for (const issue of error.all) {
+		const path = issue.path
+			.replace(LEADING_SLASH_PATTERN, "")
+			.split("/")
+			.filter(Boolean)
+			.join(".");
+		const field = path ? `${error.type}.${path}` : error.type;
+		if (seenFields.has(field)) {
+			continue;
+		}
+		seenFields.add(field);
+		details.push({
+			field,
+			message:
+				typeof issue.summary === "string" && issue.summary
+					? issue.summary
+					: issue.message,
+		});
+		if (details.length === 20) {
+			break;
+		}
+	}
+	return details;
+}
+
 function getErrorCode({
 	explicitCode,
 	parsedCode,

apps/api/src/http/request-id.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, it } from "vitest";
+import { getRequestId } from "./request-id";
+
+describe("getRequestId", () => {
+	it("returns a stable generated ID for the same request", () => {
+		const request = new Request("https://api.example.com/test");
+		const requestId = getRequestId(request);
+
+		expect(requestId).toMatch(/^req_[a-f0-9]{16}$/);
+		expect(getRequestId(request)).toBe(requestId);
+	});
+
+	it("preserves a safe caller-supplied ID", () => {
+		const request = new Request("https://api.example.com/test", {
+			headers: { "x-request-id": "trace_partner-123" },
+		});
+
+		expect(getRequestId(request)).toBe("trace_partner-123");
+	});
+
+	it("replaces unsafe caller-supplied IDs", () => {
+		const request = new Request("https://api.example.com/test", {
+			headers: { "x-request-id": "not safe for logs" },
+		});
+
+		expect(getRequestId(request)).toMatch(/^req_[a-f0-9]{16}$/);
+	});
+});

apps/api/src/http/request-id.ts

@@ -0,0 +1,25 @@
+const REQUEST_ID_PATTERN = /^[A-Za-z0-9_-]{1,128}$/;
+const requestIds = new WeakMap<Request, string>();
+
+function createRequestId(): string {
+	return `req_${crypto.randomUUID().replaceAll("-", "").slice(0, 16)}`;
+}
+
+export function getRequestId(request?: Request): string {
+	if (!request) {
+		return createRequestId();
+	}
+
+	const existing = requestIds.get(request);
+	if (existing) {
+		return existing;
+	}
+
+	const supplied = request.headers.get("x-request-id")?.trim();
+	const requestId =
+		supplied && REQUEST_ID_PATTERN.test(supplied)
+			? supplied
+			: createRequestId();
+	requestIds.set(request, requestId);
+	return requestId;
+}

apps/api/src/index.ts

@@ -10,6 +10,7 @@ import { registerProcessErrorHandlers } from "@/bootstrap/process-errors";
 import { registerShutdownHooks, warmPostgresPool } from "@/bootstrap/shutdown";
 import { isAllowedApiOrigin } from "@/http/cors";
 import { handleAppError } from "@/http/errors";
+import { getRequestId } from "@/http/request-id";
 import { AUTUMN_API_PREFIX } from "@/lib/autumn-mount";
 import { enrichApiWideEvent } from "@/lib/evlog-api";
 import { enrichRequestAuthWideEvent } from "@/middleware/auth-wide-event";
@@ -81,10 +82,20 @@ const app = new Elysia({ precompile: true })
 			enrich: enrichApiWideEvent,
 		})
 	)
+	.onBeforeHandle(({ request, set }) => {
+		set.headers["X-Request-ID"] = getRequestId(request);
+	})
 	.onBeforeHandle(({ request }) => enrichRequestAuthWideEvent(request))
 	.use(
 		cors({
 			credentials: true,
+			exposeHeaders: [
+				"X-Request-ID",
+				"Retry-After",
+				"X-RateLimit-Limit",
+				"X-RateLimit-Remaining",
+				"X-RateLimit-Reset",
+			],
 			origin: isAllowedApiOrigin,
 		})
 	)