# Product analytics gate

Product analytics stores events about the **people who use your product**: who signed up, which
step they stopped at. That is a different kind of data from a crash report, so Bucker keeps it
behind a gate that is **off for every project** and that nothing opens by default: no SDK
setting, no plan and no upgrade.

> **Status: built, and shut.** The amended data processing terms that cover this kind of data
> have not been published yet. Until they are, the gate cannot be opened for any project, and an
> attempt to open it answers `dpa_amendment_pending`. Bucker stores no event about your users today.

## What opens the gate

Three things, in this order, and each is a person's act. An organization **owner** does all of
them, from **Settings, Projects, Product analytics**. An agent, a service account, a personal
access token or an OAuth client cannot.

1. **The organization accepts the amended terms.** One acceptance per version, by an owner. It is
   recorded with who accepted it and when, and it appears in the audit log as `org.dpa.accept`.
2. **The project records its lawful basis.** One of consent, contract, legitimate interest, or
   exempt (aggregate data only). This is a record of the basis you rely on; Bucker does not
   decide it for you. Changing it is audited as `analytics_basis.update`.
3. **The owner turns product analytics on for that project.** Audited as `analytics.enable`, and
   the other owners of the organization are told.

If a newer version of the terms is published later, every project that was on under the older
version closes until an owner accepts the new one. A gate is open only for the version that is
current.

## What a closed gate does

A product event sent for a project whose gate is closed is **refused when it arrives**:

- it is recorded in the project's drops as **invalid**, with the reason `product_category_disabled`
  and a sentence saying the project has not enabled product analytics;
- it is not stored, not queued and **not billed**;
- if it arrived in the same envelope as an error, only the product event is removed; the error
  is kept;
- nothing was wrong with what was sent, so there is nothing to fix in the SDK. The cure is the
  setting.

The setting is read through a short cache, so a change takes effect on the machine that made it
at once and on the others within about ten seconds.

Every other read of product analytics, once those reads exist, answers `analytics_not_enabled`
with the same next step: accept the terms, record the basis, enable the project.

## Turning it off

An owner can turn product analytics off for a project at any time. The basis stays on record, and
turning it on again is a fresh `analytics.enable` by a person.

An agent holding the `analytics:write` scope may **ask** for a project to be turned off: the
request waits for a human approval, expires after at most seven days, and the agent then repeats
the call naming the approved request. It cannot turn anything **on**, and there is no MCP tool
for either direction.

## API

| Route | Who | What |
| --- | --- | --- |
| `GET /orgs/{org}/projects/{project}/analytics-setting` | any member who can read the project | The gate, the organization's terms status, and what blocks enabling |
| `PUT /orgs/{org}/projects/{project}/analytics-setting` | owner (a person's session); agents may only send `enabled: false` | `{ "enabled": true }` turns it on, `{ "enabled": false }` turns it off, `{ "basis": "contract" }` records the basis |
| `GET /orgs/{org}/dpa` | any member | `requiredVersion`, `acceptedVersion`, `acceptedAt` and a `status` of `amendment_pending`, `acceptance_needed` or `accepted` |
| `POST /orgs/{org}/dpa/accept` | owner (a person's session) | `{ "version": "…" }`; must be the version currently required |

Refusals carry `details.reason`: `dpa_amendment_pending`, `dpa_not_accepted`, `basis_required` or
`dpa_version_mismatch`.

## Audit

| Action | Written when |
| --- | --- |
| `org.dpa.accept` | An owner accepted the terms |
| `analytics_basis.update` | A project's basis was recorded or changed |
| `analytics.enable` | A project was turned on, or an attempt was refused (result `DENIED`, with the reason) |
| `analytics.disable` | A project was turned off, by an owner or by an approved agent request |

Each entry carries the before and after.
