Comp AI CRM is an open source, CRM designed for AI agents. Agentic-first CRM.
TypeScript
Add anonymous usage telemetry documentation and enhance currency handling in DealSheet
Lewis Carhart82ee80d002d9
diff --git a/adrs/usage.md b/adrs/usage.mdnew file mode 100644index 00000000..57595051--- /dev/null+++ b/adrs/usage.md@@ -0,0 +1,189 @@+# Task: anonymous usage telemetry for trycompai/crm++Read `AGENTS.md` first and follow it. In particular: no code comments, one root `.env` with+`.env.example` as its documentation, anything a self-hoster might not have is optional and its+absence removes a capability rather than throwing, and no coauthored commits.++**Before writing any implementation code, write an ADR** at `adrs/telemetry.md` following the+format in `adrs/README.md`: what you want to change, why the current behaviour is a problem, what+you'd do instead and what it would break. Then stop and wait for review. `CONTRIBUTING.md` is+explicit that a paragraph someone wrote beats a PR full of generated code, and this is a change+where the reasoning matters more than the diff.++## Why++This repo is MIT and cloned rather than installed, so there is no download signal and no runtime+signal. We cannot tell which of the 20 agent tools earn their place, whether the evidence ledger+actually holds up in the wild, or where people give up during setup. We want anonymous,+aggregate usage data — enabled by default, trivially disabled, and auditable in one file.++## Non-negotiable constraints++1. **Server-side only.** `posthog-node` in `apps/api` and `apps/agent`. No `posthog-js`, no+ autocapture, no session replay, nothing in `apps/app`. Autocapture on a CRM would pull contact+ names, email addresses, company domains and deal amounts out of other people's databases. We+ do not want that data and would have to deal with it if we had it.++2. **The install ID lives in Postgres, not the filesystem.** All three processes deploy to Vercel+ with an ephemeral filesystem, so the usual `~/.app/telemetry-id` pattern would mint a new ID+ on every cold start. Add a table with a single row holding a UUID, created in a migration.+ All three processes read it. Never call `identify()`, never attach an email, never attach+ `ALLOWED_SIGN_IN`.++3. **Never instrument inside the sandbox.** `apps/agent/agent/sandbox` runs `deny-all` egress by+ design. A telemetry call in there will hang and then fail, and someone will spend a day+ debugging it. Emit from the agent runtime after the tool returns.++4. **Never block, never throw.** Fire-and-forget with a swallowed error handler. `posthog.on('error')`+ logs at debug and nothing else. A telemetry failure must be invisible to the user and must not+ surface in a request path or an agent session.++5. **Allowlist, not blocklist.** A single exported const listing every permitted property name.+ Anything not on the list is dropped before send, in code, not by convention.++## Opt-out++`CRM_TELEMETRY_DISABLED="1"` disables everything. Also honour `DO_NOT_TRACK=1`. Add both to+`.env.example` with a note, and declare `CRM_TELEMETRY_DISABLED` in+`apps/api/src/config/env.validation.ts` as optional.++When disabled, call `posthog.disable()` at init so every subsequent `capture()` is a silent no-op.+Do not scatter conditional guards through the codebase.++Add a **Settings → Telemetry** page under `apps/app/app/(app)/[slug]/settings/` matching the+existing pages there. It shows the current state, the exact JSON of the most recent payload, and+a link to `docs/telemetry.md`. Reading it should take thirty seconds and answer every question+someone would have.++## What to send++One `install_daily` rollup event per install per day, emitted from the API. Do **not** emit one+event per tool call — the agent runs continuously and it would be noise and volume for no extra+signal. Plus discrete events only for the setup funnel and errors, below.++Derive everything from the schema in `packages/db/prisma/schema.prisma`. Counts and enum+distributions only — never a value from a row.++### Install shape++- Install UUID, days since install, git commit or version+- Deployment target: `VERCEL` set or not, Node version, Postgres major version+- Capability booleans, mirroring `apps/agent/agent/lib/capabilities.ts` exactly: `RAPIDAPI_KEY`,+ `PERPLEXITY_API_KEY`, `CONTEXT_DEV` (the DB setting, not the key), `BLOB_READ_WRITE_TOKEN`.+ Extend with `GITHUB_TOKEN`, `REDIS_URL`, `AGENT_BRIDGE_SECRET`, `CRON_SECRET`,+ `AI_GATEWAY_API_KEY`, `IS_MARKETING`, whether Google OAuth is configured, whether an SSO+ provider row exists. Booleans only — never the values.+- Configured agent model id from `AppSetting.agentModelId`, and its context window+- Member count, bucketed++### The agent++This is the product, so it gets the most detail.++- Tool invocation counts keyed by tool name, from the 20 files in `apps/agent/agent/tools/`.+ The open question is which four do 90% of the work.+- Sessions started, sessions completed, mean tools per session+- `AgentTask` counts by `kind` from `TASK_KINDS` (`brand`, `portrait`, `meeting-prep`, `identify`,+ `profile`, `recheck`, `company-profile`, `workspace-profile`): claimed, completed, and retired.+ A task retired by `retireExhausted()` hit `MAX_ATTEMPTS` and the session never reported back —+ that is a pure failure signal and should be its own counter per kind.+- Mean and max `attempts` per kind+- Budget exhaustion rate: how often a session stops because the budget ran out rather than+ because it finished+- `schedule_recheck` calls, and the distribution of recheck intervals in day buckets+- Whether the sandbox is enabled, and `AgentConversation` count — how many installs actually+ configure `AGENT_BRIDGE_SECRET` and talk to the agent from the Agent tab++### The evidence ledger++The core product claim is that nothing about a person is guessed. Telemetry can test it.++- `ContactFact` counts by `status` (`APPLIED` / `PROPOSED` / `DISMISSED` / `SUPERSEDED`) and by+ `band` (`VERIFIED` / `PROBABLE` / `POSSIBLE`)+- The dismissal rate on `PROPOSED` facts — the share a human looked at and rejected. This is the+ agent's precision as measured by users rather than by us.+- Median time from `observedAt` to `decidedAt` — how long suggestions sit unsettled+- Counts by `method`, and by evidence kind from the `WEIGHTS` map in+ `apps/agent/agent/lib/evidence.ts`. We assert that `crm.signature-block` and `crm.thread-reply`+ are the best evidence and that they are free. Measure whether installs with no API keys at all+ actually produce applied facts.+- Facts superseded within N days of being applied — churn, meaning the agent changed its mind++### CRM usage++- `Contact`, `Company`, `Deal`, `Activity` counts, bucketed not exact+- `Contact` and `Company` counts by `RecordSource` (`MANUAL` / `IMPORT` / `EMAIL` / `CALENDAR`).+ The README claims most contacts arrive from the mailbox sync rather than being typed. This+ measures it.+- `Deal` counts by `DealStage`, to tell an install running a real pipeline from one only+ enriching contacts+- `Activity` counts by `ActivityType`+- Mailbox sync configured, last sync status from `MailboxSync`, threads and messages ingested in+ the period as counts+- `CompanyEnrichment` counts by `EnrichmentStatus`+- `SuppressedDomain` and `SuppressedContact` counts — people actively curating what the agent+ touches is a strong engagement signal+- Whether `WorkspaceProfile` has been written++### Setup funnel++Discrete one-shot events, each fired once per install. This is the number nobody else instruments+and probably the most valuable thing here.++`migrations_applied` → `first_sign_in` → `google_oauth_configured` → `first_mailbox_sync` →+`first_non_seed_contact` → `first_agent_task_claimed` → `first_agent_task_completed` →+`first_fact_applied`++Include a `seed_only` boolean on the daily rollup. `bun run db:seed` writes a known fixture set;+an install whose data is only seed rows is someone who ran it once, not a user. Without this the+numbers are meaningless.++### Errors++Error **class** plus the module or tool that threw. No messages, no stack traces, no payloads —+unlike n8n, which does send error messages, our errors will contain contact fields.++- Failed agent sessions by tool and error class+- Failed Google sync by error class+- API 5xx by route pattern and error class+- Model or AI Gateway failures by class++## What must never be sent++Grounded in the actual schema. Put this list in `docs/telemetry.md` verbatim.++- Any `Contact` or `User` name, email, title or photo+- Any `Company` name, domain, industry or location+- `ContactFact.value`, `.sourceUrl`, `.evidence`, `.field`+- `AgentTask.reason` and `AgentTask.outcome` — both free text the agent wrote about a named person+- `ContactBrief` content, `WorkspaceProfile.website`, `.narrative`, `.sections`+- `EmailThread` and `EmailMessage` subjects or bodies, `CalendarEvent` titles, `CalendarAttendee` rows+- `Deal` names and amounts. Stage distribution is fine; amounts are not.+- `AgentEvent.data`, `AgentConversation` content, prompts, completions, reasoning traces+- `ALLOWED_SIGN_IN`, `AppSetting.contextDevApiKey`, any key, secret, token or connection string+- `SuppressedDomain` and `SuppressedContact` values — counts only+- **IP address.** Set `$ip: null` and disable geoip. n8n collects IP and has to caveat their+ anonymity claim because of it. We do not need it and we would rather the claim be unqualified.++## Deliverables++1. `adrs/telemetry.md` — write this first, then stop for review+2. `packages/telemetry` — one module, allowlist const, install-ID accessor, disabled-check,+ typed event builders+3. A Prisma migration adding the install-ID table+4. Wiring in `apps/api` (daily rollup, funnel events, API errors) and `apps/agent` (tool counters,+ session outcomes, agent errors)+5. Settings → Telemetry page+6. `docs/telemetry.md` — every event, every property, in plain English, plus the never-sent list+7. `.env.example` entries and the `env.validation.ts` declaration+8. A README line in the env table matching the style of the existing rows+9. Tests: allowlist drops unknown properties, disabled flag produces zero network calls,+ `DO_NOT_TRACK` honoured, install ID stable across processes++## Notes++The PostHog project key (`phc_...`) is write-only and belongs in the committed `.env.example`+alongside a PostHog EU host. It is public by design.++Do not aggregate by querying every table on every request. The daily rollup should be one+scheduled job doing grouped counts, reusing the pattern in `apps/api/src/dashboard` where it fits.\ No newline at end of filediff --git a/apps/app/components/crm/record-sheet/deal-sheet.tsx b/apps/app/components/crm/record-sheet/deal-sheet.tsxindex f44a71d9..8d30e100 100644--- a/apps/app/components/crm/record-sheet/deal-sheet.tsx+++ b/apps/app/components/crm/record-sheet/deal-sheet.tsx@@ -1,7 +1,7 @@"use client";import UserMultiple from "@carbon/icons-react/es/UserMultiple";-import { CURRENCIES } from "@crm/db/currency";+import { CURRENCIES, normalizeCurrency } from "@crm/db/currency";import { EmptyCellValue } from "@crm/ui/components/empty-cell";import {EntityLogo,@@ -54,6 +54,10 @@ const CURRENCY_OPTIONS = CURRENCIES.map((entry) => ({label: `${entry.code} · ${entry.name}`,}));+function dealCurrency(currency: string) {+ return normalizeCurrency(currency) || currency;+}+function currencyOptions(currency: string) {if (CURRENCY_OPTIONS.some((option) => option.value === currency)) {return CURRENCY_OPTIONS;@@ -66,14 +70,16 @@ function currencyOptions(currency: string) {}function ReportedValue({ deal }: { deal: Deal }) {- if (deal.currency === deal.reportingCurrency) return null;+ const currency = dealCurrency(deal.currency);++ if (currency === deal.reportingCurrency) return null;if (deal.amountCents === null) return null;return (<DetailSheetProperty label={`In ${deal.reportingCurrency}`}>{deal.baseAmountCents === null ? (<span className="text-muted-foreground">- No {deal.currency} rate — left out of totals+ No {currency} rate — left out of totals</span>) : (<span className="tabular-nums text-muted-foreground">@@ -183,7 +189,7 @@ export function DealSheet({ dealId }: { dealId: string }) {<EmptyCellValue />) : (<span className="tabular-nums">- {formatMoney(deal.amountCents, deal.currency)}+ {formatMoney(deal.amountCents, dealCurrency(deal.currency))}</span>)}</DetailSheetStat>@@ -227,6 +233,8 @@ function DealOverview({ deal }: { deal: Deal }) {const save = (data: Parameters<typeof update.mutate>[0]["data"]) =>update.mutate({ id: deal.id, data });+ const currency = dealCurrency(deal.currency);+const isSaving = savingField(update);return (@@ -260,13 +268,13 @@ function DealOverview({ deal }: { deal: Deal }) {save({ amountCents: Math.round(parsed * 100) });}}render={(value) =>- formatMoney(Math.round(Number(value) * 100), deal.currency)+ formatMoney(Math.round(Number(value) * 100), currency)}/><InlineSelectFieldlabel="Currency"- value={deal.currency}- options={currencyOptions(deal.currency)}+ value={currency}+ options={currencyOptions(currency)}onSave={(currency) => save({ currency })}/><ReportedValue deal={deal} />