ytstats 0.1.0

package/docs/gotchas/auth.md

@@ -0,0 +1,121 @@
+---
+description: Credential and OAuth traps — service accounts, weekly token expiry, silent browser failures, and refresh-token preservation.
+tags: [auth, oauth, credentials, tokens, gotchas]
+source:
+  - src/auth/**
+---
+
+# Authentication Gotchas
+
+Traps in the bring-your-own-credentials OAuth model, and where `ytstats` defends against them.
+
+Related: [auth.md](../auth.md) for the full flow, [config-storage.md](config-storage.md) for how the resulting tokens are written.
+
+## Service accounts can never be used
+
+A platform limitation with no workaround. A service account owns no YouTube channel and there is no way to link one, so Google rejects the flow with `NoLinkedYouTubeAccount`. Domain-wide delegation does not help — it is itself a service-account mechanism.
+
+> "the YouTube Reporting API and YouTube Analytics API do not support this flow.
+> Since there is no way to link a Service Account to a YouTube account, attempts to
+> authorize requests with this flow will generate an error."
+> — [Google's authorization guide](https://developers.google.com/youtube/reporting/guides/authorization)
+
+The only service-account-based YouTube API is the Content ID API, which is partner-only and does not cover single-channel analytics.
+
+**Where handled:** `parseClientSecret()` in `src/auth/credentials.js` detects `type: 'service_account'` and fails with `AUTH_SERVICE_ACCOUNT`, marked `recoverable: false` so an agent stops instead of retrying forever.
+
+## Testing-mode consent screens expire tokens weekly
+
+While an OAuth consent screen is in **Testing** status, Google expires refresh tokens after **7 days**. The symptom is re-authenticating every week, surfacing as `invalid_grant`.
+
+Publishing the consent screen to Production removes the expiry. Verification is not required for personal use — the user clicks past a one-time "unverified app" warning.
+
+**Where handled:** `invalid_grant` maps to `AUTH_TOKEN_EXPIRED` in `diagnoseGoogleError()` (`src/errors.js`), whose `cause` names Testing mode as the likely root cause rather than saying "log in again".
+
+## A bad client ID fails in the browser, not the API
+
+An invalid or malformed client ID produces **no API error**. Google renders "Access blocked: Authorization Error" in the browser and never redirects, so the loopback listener waits until it times out. The resulting `AUTH_TIMEOUT` is misleading: retrying can never help.
+
+**Where handled:** `validateClientId()` in `src/auth/credentials.js` runs before any browser opens, turning a five-minute hang into an instant `AUTH_CLIENT_ID_INVALID`. `AUTH_TIMEOUT` also names "Access blocked" as the leading cause and is marked `retryable: false`.
+
+## A merely unusual client ID must not lock anyone out
+
+`validateClientId()` has two tiers, deliberately. An ID that does not end in `.apps.googleusercontent.com` **throws** — it cannot possibly work. An ID with the right suffix but not the canonical `<project-number>-<hash>` shape only **returns a warning diagnostic** (`AUTH_CLIENT_ID_SUSPICIOUS`), because legacy clients occasionally deviate and a false positive here would block a working setup.
+
+Do not tighten the regex into a hard failure without evidence that the deviant shape is genuinely unusable.
+
+**Where handled:** `CANONICAL_CLIENT_ID` and the two-tier return in `src/auth/credentials.js`.
+
+## Google omits refresh_token on refresh, so saving must merge
+
+A refresh response contains a new `access_token` but **no** `refresh_token`. Writing the response over the stored tokens would therefore destroy the long-lived credential and force a re-login on the next run.
+
+`saveAccount()` merges instead of replacing: `tokens: { ...(existing?.tokens ?? {}), ...tokens }`. The `tokens` event handler registered in `getAuthenticatedClient()` relies on this, since it fires with exactly those partial refresh payloads.
+
+**Where handled:** `saveAccount()` in `src/auth/tokens.js`; the `client.on('tokens', …)` handler in `src/auth/session.js`.
+
+## The client secret must be stored, not discarded after login
+
+Google's token endpoint requires the client secret on **every** refresh, not just the initial code exchange. Treating it as single-use — a reasonable instinct for a secret — breaks every subsequent command.
+
+**Where handled:** `login()` calls `saveCredentials()` alongside `saveAccount()` in `src/auth/session.js`, and `getAuthenticatedClient()` resolves credentials before loading tokens.
+
+## Channel identity is fetched before anything is persisted
+
+If the identity lookup were done after saving, a failed lookup would leave a half-written account with tokens but no channel id — and `saveAccount()` throws on a missing channel id, so the failure mode is a corrupt store rather than a clean error.
+
+`login()` exchanges the code, fetches identity, and only then calls `saveCredentials()` + `saveAccount()`. Keep that ordering.
+
+**Where handled:** `login()` in `src/auth/session.js`.
+
+## Credentials are diagnosed before tokens
+
+`getAuthenticatedClient()` resolves credentials *first*, then loads the account. The ordering is deliberate: telling someone who has not yet created a Google Cloud project to "run `ytstats login`" sends them down a path that cannot succeed. They need `AUTH_NO_CREDENTIALS`, not `AUTH_NO_TOKENS`.
+
+**Where handled:** `getAuthenticatedClient()` in `src/auth/session.js`.
+
+## An unknown --account never falls back to the default
+
+`loadAccount(selector)` returns `null` for an unrecognised selector rather than quietly returning the default account. A silent fallback would answer a question about channel A with channel B's data — wrong numbers presented as correct ones.
+
+The caller turns that `null` into `AUTH_ACCOUNT_UNKNOWN`, listing the channels that *are* signed in.
+
+**Where handled:** `loadAccount()` in `src/auth/tokens.js`; the `AUTH_ACCOUNT_UNKNOWN` branch in `getAuthenticatedClient()`.
+
+## The loopback server binds 127.0.0.1, never 0.0.0.0
+
+Binding `0.0.0.0` would expose the callback listener — and therefore the authorization code — to anything on the local network. The server binds `127.0.0.1` on an ephemeral port (`server.listen(0, '127.0.0.1')`).
+
+The state comparison is constant-time (`crypto.timingSafeEqual`) so the value cannot be probed byte by byte, and the success page deliberately contains no code or token material. A test asserts the success page never contains the authorization code.
+
+**Where handled:** `startLoopbackServer()` in `src/auth/oauth.js`.
+
+## The favicon request is not the callback
+
+Browsers request `/favicon.ico` unprompted when the callback page loads. Treating any request as the callback would settle the promise on the wrong one.
+
+The handler 404s `/favicon.ico` and anything that is not `/` or `/callback` before inspecting query parameters. A test covers this.
+
+**Where handled:** the pathname guards in `startLoopbackServer()`, `src/auth/oauth.js`.
+
+## --no-browser uses a deliberately dead redirect URI
+
+The paste flow sets `redirectUri` to `http://127.0.0.1:1` and starts **no** listener. Port 1 is chosen so the browser's redirect fails immediately and visibly, leaving the URL — including `?code=…` — in the address bar for the user to copy.
+
+The same `redirect_uri` must then be sent to the token exchange, since Google validates that it matches the one used in the authorization request.
+
+**Where handled:** `pasteFlow()` in `src/auth/session.js`.
+
+## Logout removes local tokens even when revocation fails
+
+Revoking with Google is best-effort: it is wrapped in `try`/`catch` and the loop continues. If the machine is offline or the token is already invalid, revocation fails but the local removal still happens — otherwise `logout` would leave credentials on disk while reporting an error, which is the worst of both outcomes.
+
+Resolving credentials for the revocation call is likewise optional; without them `ytstats` cannot revoke, but it can still forget.
+
+**Where handled:** `logout()` in `src/auth/session.js`.
+
+## A read-only config dir must not break a working command
+
+The `tokens` event handler that persists refreshed tokens swallows its errors. If the config directory has become unwritable, the in-memory client still holds a valid access token and the command can complete — failing the whole run over a cache write would be a worse outcome than losing the refreshed token.
+
+**Where handled:** the empty `catch` in the `client.on('tokens', …)` handler, `src/auth/session.js`.

package/docs/gotchas/cli-output.md

@@ -0,0 +1,155 @@
+---
+description: Traps in the CLI wiring and the output envelope — Commander overrides, severity forcing, validation ordering, and redaction.
+tags: [cli, output, diagnostics, commander, gotchas]
+source:
+  - src/cli.js
+  - src/output.js
+  - src/errors.js
+  - src/diagnostics.js
+---
+
+# CLI and Output Gotchas
+
+Why the CLI wiring and the envelope look the way they do. Most entries here exist because the obvious implementation violates the output contract.
+
+Related: [output-contract.md](../output-contract.md) for the envelope schema, [cli.md](../cli.md) for the command surface.
+
+## Commander's default behaviour writes nothing to stdout
+
+On a usage error Commander prints prose to stderr and calls `process.exit`, leaving stdout **empty**. An agent parsing stdout gets nothing at all — which breaks the contract's central promise that every code path emits one JSON document.
+
+Two overrides fix this and both are load-bearing:
+
+```js
+program.exitOverride();          // throw instead of process.exit
+program.configureOutput({
+  writeErr: () => {},            // suppressed; re-emitted as a diagnostic
+  writeOut: s => stdout(s.replace(/\n$/, '')),
+});
+```
+
+`exitOverride()` converts the exit into a throw that `main()` catches and routes through `diagnoseCommanderError()`. Removing either override silently reintroduces the empty-stdout failure.
+
+**Where handled:** `buildProgram()` in `src/cli.js`.
+
+## --help and --version arrive as thrown errors
+
+Because of `exitOverride()`, a successful `--help` or `--version` reaches `main()`'s `catch` block like any failure. Treating everything caught there as an error would make help exit non-zero and emit an error envelope.
+
+`main()` checks for `commander.helpDisplayed`, `commander.help`, and `commander.version` first and returns `EXIT.OK`.
+
+**Where handled:** `main()` in `src/cli.js`.
+
+## Global flags are not known when the reporter is first built
+
+`createReporter()` is called once at build time, before `--compact` and `--quiet` have been parsed. Using that first reporter for output would ignore both flags.
+
+A `preAction` hook rebuilds the reporter once global options are available. In `main()`'s error path — where parsing may never have reached the hook — the flags are instead sniffed directly out of `argv`.
+
+**Where handled:** the `preAction` hook in `buildProgram()`, and the `argv.includes('--compact')` sniffing in `main()`.
+
+## warn() forces severity to warning, and must
+
+`reporter.warn()` overwrites the diagnostic's `severity` with `SEVERITY.WARNING`. Routing a diagnostic through `warn()` *is* the decision that it is non-fatal, so the definition's own severity is not authoritative there.
+
+Without this, `doctor` — whose entire job is to report the auth problems it found — would emit `ok: true` while exiting 2, because `exitCodeFor()` reads severity. That combination is incoherent for a consumer.
+
+**Where handled:** `warn()` in `createReporter()`, `src/output.js`.
+
+## data is null on failure, never partial
+
+When `ok` is false, `data` is set to `null` — not to whatever was collected before the failure. A consumer that reads `data` without checking `ok` would otherwise act on half a dataset and never know.
+
+```js
+data: ok ? (data ?? null) : null,
+```
+
+**Where handled:** `renderEnvelope()` in `src/output.js`.
+
+## Errors carrying warning severity are re-sorted into warnings
+
+`renderEnvelope()` does not trust the caller's error/warning split. It partitions both input lists by each diagnostic's actual `severity`, so a warning-severity diagnostic passed in `errors` lands in `warnings` and does not make `ok` false.
+
+This is why `reporter.fail()` can pass `[...list, ...warningsBuffer]` as one array without corrupting `ok`.
+
+**Where handled:** `errorList` / `warningList` construction in `renderEnvelope()`, `src/output.js`.
+
+## Input is validated before authentication
+
+Every `run()` wrapper executes its `validate` callback before touching the network. Checking auth first would hide a malformed date behind a login error, costing an agent an extra round trip to discover the second problem.
+
+`validateRange()` also collects *every* problem rather than throwing on the first, so `--start 01/01/2026 --end yesterday --days -3` reports three diagnostics in one envelope.
+
+**Where handled:** the `run()` wrapper and `validateRange()` in `src/cli.js`.
+
+## The range check is skipped when a date is already invalid
+
+`validateRange()` only compares `start > end` when `problems` is still empty. Comparing an unparseable date string would produce a second, misleading `INPUT_INVALID_RANGE` on top of the real `INPUT_INVALID_DATE` — two diagnostics for one mistake.
+
+**Where handled:** the `if (!problems.length && …)` guard in `validateRange()`, `src/cli.js`.
+
+## Date validation exists in two places, deliberately
+
+`validateRange()` in `src/cli.js` collects problems as diagnostics without throwing; `assertIsoDate()` in `src/dates.js` throws `YtStatsError`. They overlap on purpose — the CLI needs to report all problems at once, while `resolveDateRange()` must stay safe for library callers who never went through the CLI.
+
+Changing one without the other lets a bad date through one entry point. `src/dates.js` additionally enforces `MAX_DAYS` (3650), which the CLI validator does not check.
+
+**Where handled:** `validateRange()` in `src/cli.js`, `assertIsoDate()` and `resolveDateRange()` in `src/dates.js`.
+
+## Redaction deliberately spares the "code" field
+
+The redaction patterns strip Google client secrets, access tokens, refresh tokens, and authorization codes. They deliberately do **not** match a bare `"code"` JSON field, because every diagnostic carries `"code": "AUTH_NO_TOKENS"` — public API that must survive redaction.
+
+Broadening the pattern to catch `"code"` generically would blank out the one field consumers branch on.
+
+**Where handled:** `SECRET_PATTERNS` in `src/errors.js`, with a comment marking the exclusion.
+
+## Redaction runs on the serialized JSON, not the object
+
+`renderEnvelope()` calls `redact(json)` after `JSON.stringify`, so redaction sees the final text including any secret that leaked into a nested `detail` string. Redacting the object first would miss anything embedded in prose.
+
+The reporter applies `redact()` to every stderr write for the same reason.
+
+**Where handled:** `renderEnvelope()` and `createReporter()` in `src/output.js`.
+
+## Google error classification is order-dependent
+
+`diagnoseGoogleError()` checks specific signals — network error codes, reason strings, message fingerprints — **before** generic HTTP status buckets. A 403 alone can mean four unrelated things (`accessNotConfigured`, `quotaExceeded`, `NoLinkedYouTubeAccount`, plain forbidden), so reordering the checks silently degrades precise diagnostics into `API_FORBIDDEN`.
+
+`invalid_grant` is checked before the generic 401 branch for the same reason: it has a specific, actionable cause that "token expired" alone does not convey.
+
+**Where handled:** the ordered `if` chain in `diagnoseGoogleError()`, `src/errors.js`.
+
+## An empty result set is reported explicitly
+
+An empty `rows` array is ambiguous — it could mean the query failed silently or that the channel genuinely had no activity. Every `simple()` command emits a `DATA_EMPTY` warning when the query succeeds with zero rows, so the caller can tell the two apart.
+
+**Where handled:** the `rows.length === 0` branch in `simple()`, `src/cli.js`.
+
+## --no-retention is Commander's negation, so the option reads as `retention`
+
+`.option('--no-retention', …)` makes Commander expose `cmdOpts.retention`, defaulting to `true` and becoming `false` when the flag is passed. There is no `cmdOpts.noRetention`. The same applies to `--no-browser`, read as `!cmdOpts.browser` in the `login` action.
+
+**Where handled:** the `fetch` and `login` command definitions in `src/cli.js`.
+
+## Exit codes are also in the envelope
+
+A consumer that can only see stdout — piped, captured, or read by an agent that never observed the process status — still needs the exit code. It is duplicated at `meta.exitCode`.
+
+`exitCodeFor()` returns the **worst** code across all error-severity diagnostics, and `EXIT.OK` when there are none, which is why warnings never affect it.
+
+**Where handled:** `exitCodeFor()` in `src/diagnostics.js`, surfaced via `meta.exitCode` in `renderEnvelope()`.
+
+## The bin shim is the last line of defence
+
+`bin/ytstats.js` wraps `main()` in a final `.catch()` that writes to stderr and sets exit code 1. Its only job is to guarantee that an unanticipated throw never puts a stack trace on stdout, which is reserved for the JSON document.
+
+**Where handled:** `bin/ytstats.js`.
+
+## Diagnostic detail is folded from context, so callers need not format it
+
+`diagnose()` appends `Option: …`, `Received: …`, `Expected: …`, `Allowed: …`, `Step: …`, `Account: …`, and `Underlying: …` onto `detail` from whatever context keys were supplied. A caller reading only `detail` still learns exactly what was wrong.
+
+Stack-like lines are stripped from context strings by `clean()` — diagnostics are prose, never traces.
+
+**Where handled:** `diagnose()` and `clean()` in `src/diagnostics.js`.

package/docs/gotchas/config-storage.md

@@ -0,0 +1,98 @@
+---
+description: Traps in the per-user config store — atomic writes, permission windows, path traversal, and platform differences.
+tags: [config, storage, permissions, security, gotchas]
+source:
+  - src/config/**
+---
+
+# Config and Storage Gotchas
+
+Everything the config store holds is a secret — the OAuth client secret and refresh tokens. These entries explain why the write path is more careful than a `writeFileSync` would be.
+
+Related: [configuration.md](../configuration.md) for the directory layout and env vars, [auth gotchas](auth.md) for what is stored.
+
+## The temp file is created *at* 0600, not chmod'd afterwards
+
+`writeJson()` passes `{ mode: FILE_MODE }` to `fs.writeFileSync` rather than writing first and fixing permissions after. Between those two operations the secret would be briefly world-readable, and a concurrent reader can hit exactly that window.
+
+```js
+fs.writeFileSync(tmp, JSON.stringify(value, null, 2) + '\n', { mode: FILE_MODE });
+```
+
+**Where handled:** `writeJson()` in `src/config/store.js`.
+
+## The write is atomic via rename, so a crash never truncates tokens
+
+Writing in place means a crash mid-write leaves a half-written token file that parses as invalid JSON — and the user is silently logged out. `writeJson()` writes to a unique temp file in the same directory and then `renameSync`s it over the target, which is atomic on POSIX filesystems.
+
+The temp name includes the pid and six random bytes so two concurrent processes cannot collide. On failure the temp file is unlinked best-effort before the error is rethrown.
+
+**Where handled:** `writeJson()` in `src/config/store.js`.
+
+## chmod runs again after the rename
+
+`rename` preserves the temp file's mode, so the final file is already `0600`. The extra `chmodSync(target, FILE_MODE)` afterwards guards the case where the target pre-existed with looser permissions on a filesystem that does not behave as expected. It is belt-and-braces, not redundancy to remove.
+
+Every `chmod` call in this file is wrapped in `try`/`catch` because Windows ignores POSIX modes and would otherwise throw.
+
+**Where handled:** `writeJson()` in `src/config/store.js`.
+
+## The directory mode is asserted, not assumed
+
+`fs.mkdirSync(dir, { recursive: true, mode: DIR_MODE })` does not reliably produce `0700`: the mode is masked by the process umask, and the directory may already exist from an earlier run with different permissions.
+
+`ensureDir()` therefore follows the mkdir with an explicit `chmodSync(dir, DIR_MODE)`.
+
+**Where handled:** `ensureDir()` in `src/config/store.js`.
+
+## Unsafe filenames are rejected, not sanitised
+
+`assertSafeName()` throws for anything that is not a flat basename — path separators, `.`, `..`, absolute paths, and embedded NUL. It does not strip or rewrite them.
+
+Silently sanitising would hide a caller bug: code that passes `../../.ssh/id_rsa` has a defect, and rewriting it into `id_rsa` lets the defect ship. The throw is the point.
+
+**Where handled:** `assertSafeName()` in `src/config/store.js`.
+
+## Windows relies on directory location, not file modes
+
+POSIX modes are meaningless on Windows, so `0600` provides no protection there. The security property comes from the storage location instead: `%APPDATA%` is already per-user and roaming.
+
+Do not "fix" the Windows path to a shared location on the assumption that the file modes are doing the work.
+
+**Where handled:** the comment on `FILE_MODE` / `DIR_MODE` in `src/config/store.js`; the `win32` branch of `resolveConfigDir()` in `src/config/paths.js`.
+
+## readJson returns null for a corrupt file, not an error
+
+Both the read and the `JSON.parse` are wrapped, and either failure yields `null`. A corrupt `tokens.json` therefore reads as "not signed in" rather than crashing the command.
+
+The trade-off is deliberate but worth knowing: a truncated token file is indistinguishable from an absent one, so the user sees `AUTH_NO_TOKENS` and re-runs `login`, which repairs it. Callers must not treat `null` as proof the file does not exist.
+
+**Where handled:** `readJson()` in `src/config/store.js`.
+
+## A relative XDG_CONFIG_HOME is ignored, per spec
+
+The XDG Base Directory specification requires a relative `XDG_CONFIG_HOME` to be treated as unset. `resolveConfigDir()` implements this with `path.isAbsolute(xdg)` and falls back to `~/.config`.
+
+`YTSTATS_CONFIG_DIR` behaves the *opposite* way: a relative value is accepted and resolved to absolute against the current working directory, since it is an explicit override rather than an environment convention.
+
+**Where handled:** `resolveConfigDir()` in `src/config/paths.js`.
+
+## Config path resolution is pure so every OS can be tested from any OS
+
+`resolveConfigDir({ platform, env, home })` takes all three inputs as parameters; only `configDir()` reads `process.platform`, `process.env`, and `os.homedir()`. This is what lets the test suite assert Windows and Linux behaviour while running on macOS.
+
+Reading `process.*` directly inside `resolveConfigDir()` would make two thirds of that coverage impossible.
+
+**Where handled:** `resolveConfigDir()` versus `configDir()` in `src/config/paths.js`.
+
+## listFiles filters in-flight temp files
+
+`listFiles()` excludes names containing `.tmp-` so a concurrent write in progress is not reported as a stored file. Anything enumerating the config directory should apply the same filter rather than reading the raw directory listing.
+
+**Where handled:** `listFiles()` in `src/config/store.js`.
+
+## removeAccount deletes the file when the last account goes
+
+Leaving an empty `{ accounts: {} }` store behind would make `listAccounts()` cheap but leave a stale file implying state that no longer exists. `removeAccount()` unlinks `tokens.json` entirely once the last account is removed, and otherwise promotes an arbitrary remaining account to default.
+
+**Where handled:** `removeAccount()` in `src/auth/tokens.js`.

package/docs/gotchas/youtube-api.md

@@ -0,0 +1,132 @@
+---
+description: Non-obvious behaviour of the three YouTube APIs — metrics that never work, undocumented limits, and lag that cannot be removed.
+tags: [youtube-api, analytics, reporting, quota, gotchas]
+source:
+  - src/api/**
+---
+
+# YouTube API Gotchas
+
+What breaks in the YouTube Data, Analytics, and Reporting APIs, why, and where `ytstats` handles it. Each entry names the handling site so a future change does not silently undo a workaround.
+
+Related: [auth gotchas](auth.md) for credential and token traps, [youtube-apis.md](../youtube-apis.md) for the full request reference.
+
+## CTR and impressions do not work on the Analytics API
+
+The Analytics API documents `videoThumbnailImpressions` and `videoThumbnailImpressionsClickRate` as valid channel-report metrics. They do not work — every combination returns `The query is not supported.`
+
+This is a [known Google issue](https://issuetracker.google.com/issues/254665034) affecting all channels regardless of size. The only working source is the Reporting API's `channel_reach_basic_a1` report, which is why `ytstats reach` exists at all and why it behaves unlike every other command.
+
+**Where handled:** `src/api/reporting.js`. Never add these metrics to `src/api/analytics.js` — a test asserts they are absent.
+
+## Reporting API data is always 1-2 days behind
+
+Reports cover midnight-to-midnight Pacific Time and are generated 1-2 days after the period closes, so `ytstats reach` never returns data for today or yesterday.
+
+This is not a `ytstats` limitation. YouTube Studio shows the same lag, because real-time impression data does not exist anywhere.
+
+## The first reach run returns nothing for 24-48 hours
+
+The first `ytstats reach` only *creates* the reporting job. Google then generates reports within 24-48 hours, including a 30-day backfill. Until then there is genuinely nothing to download.
+
+This surfaces as the `REACH_PENDING` **warning**, not an error — the command succeeded, the data does not exist yet. Re-running is harmless and does not create a duplicate job, because `ensureReachJob()` looks for an existing job with the same `reportTypeId` before creating one.
+
+**Where handled:** `fetchReach()` and `ensureReachJob()` in `src/api/reporting.js`.
+
+## Reach reports overlap, so rows must be deduped
+
+Successive report files cover overlapping periods, and later files carry corrected figures for days already reported. Concatenating rows produces duplicates and stale numbers.
+
+`fetchReach()` keys rows on `` `${date}|${videoId}` `` in a `Map` and lets the last write win, so corrections from later reports replace earlier figures.
+
+**Where handled:** the `deduped` map in `fetchReach()`, `src/api/reporting.js`.
+
+## Per-video analytics rejects maxResults above 200
+
+Queries with `dimensions=video` fail if `maxResults` exceeds 200. Channels with more than 200 videos get only the top 200 by the sort field (`-views`).
+
+**Where handled:** `MAX_VIDEO_ROWS` in `src/api/analytics.js`, applied with `Math.min` so a caller cannot exceed it. A test asserts the clamp.
+
+## Traffic source detail queries are fragile in three separate ways
+
+The `insightTrafficSourceDetail` dimension has three distinct traps:
+
+1. It **requires** both `sort` and `maxResults`. Without `maxResults` the query returns `The query is not supported.`
+2. With `maxResults` too high (50+) it returns `Internal error encountered.` The safe ceiling is **25**.
+3. Combining it with `estimatedMinutesWatched` also triggers an internal error. Only `views` is reliable.
+
+**Where handled:** `MAX_DETAIL_ROWS` and the hard-coded `metrics: 'views'` in `fetchSearchTerms()` and `fetchTrafficSourceDetails()`, `src/api/analytics.js`. Tests assert all three.
+
+## Retention ratios legitimately exceed 1.0
+
+`audienceWatchRatio` returns values above 1.0 for Shorts that viewers loop. A 25-second Short showing `1.54` at position 0 means 54% more viewing than the number of initial viewers.
+
+This is a strong engagement signal, not a data error. `ytstats` never clamps it, and a test pins that behaviour so nobody "fixes" it later.
+
+**Where handled:** `fetchAudienceRetention()` in `src/api/analytics.js` — note the deliberate absence of clamping.
+
+## Two content-type vocabularies disagree
+
+| Source | Values |
+|---|---|
+| `classifyContent()`, duration-based | `SHORTS`, `VIDEO_ON_DEMAND`, `LIVE_STREAM` |
+| YouTube's `creatorContentType` dimension | `shorts`, `videoOnDemand`, `creatorContentTypeUnspecified` |
+
+Different casing *and* different semantics. The `ytstats` classifier uses duration alone (`<= 60s` is a Short), so a 62-second video intended as a Short reads as `VIDEO_ON_DEMAND`. YouTube uses additional signals and may disagree.
+
+Consumers wanting YouTube's own opinion should read the `contentTypes` dataset rather than the `contentType` field on a video.
+
+**Where handled:** `classifyContent()` in `src/api/transforms.js` (duration-based) versus `fetchContentTypes()` in `src/api/analytics.js` (YouTube's own).
+
+## Subscriber counts are rounded
+
+Above 1,000 subscribers the Data API returns counts rounded to 3 significant figures — expect `1,020` or `10,400`, never exact values. Below 1,000 the count is exact. Week-over-week deltas smaller than the rounding step are invisible.
+
+**Where handled:** nothing to handle, but `normalizeChannel()` in `src/api/transforms.js` carries a comment so the rounding is not mistaken for a bug.
+
+## Reporting API CSVs need a real CSV parser
+
+Report bodies contain video titles and search terms, which routinely include commas and quotes. Splitting on `,` silently corrupts rows, and the corruption is quiet — it produces plausible-looking wrong data rather than an error.
+
+**Where handled:** `parseCsv()` in `src/api/transforms.js` implements the RFC 4180 subset that matters: quoted fields, embedded commas and newlines, and `""` escapes.
+
+## Reporting API dates arrive in a different format
+
+Report dates arrive as `20260328.0` while every other surface uses ISO `YYYY-MM-DD`. Passing them through unchanged would give consumers two date formats in one document.
+
+`normalizeReportingDate()` unifies them. It passes ISO dates through untouched and returns the original value when it recognises neither form, so an unexpected format is visible rather than silently mangled.
+
+**Where handled:** `normalizeReportingDate()` in `src/api/transforms.js`.
+
+## CSV cells with a leading zero must stay strings
+
+Numeric-looking cells are coerced to numbers, but identifiers such as zero-padded codes would lose their leading zero and become the wrong value.
+
+`coerce()` only converts values matching `/^-?(0|[1-9]\d*)(\.\d+)?$/` — a pattern that admits a bare `0` and `0.5` but rejects `007`, leaving it a string.
+
+**Where handled:** `coerce()` in `src/api/transforms.js`.
+
+## search.list costs 100x what playlistItems.list costs
+
+The Data API allows 10,000 quota units per project per day.
+
+| Operation | Cost |
+|---|---|
+| `channels.list` | 1 |
+| `playlistItems.list` | 1 per page of 50 |
+| `videos.list` | 1 per batch of 50 |
+| `search.list` | **100** |
+
+`ytstats` enumerates videos through the channel's uploads playlist, never `search.list`. A full fetch for a 100-video channel costs roughly 5 units. A test asserts `search.list` is never called.
+
+The expensive operation is retention: one Analytics call **per video**, which is why `fetch` caps it at 50 videos by default (`--retention-limit`) and offers `--no-retention`.
+
+**Where handled:** `fetchAllVideoIds()` in `src/api/data.js`, and the retention cap in `src/fetch-all.js`.
+
+## Card metrics fail on some channels and are swallowed
+
+`fetchCardMetrics()` is the one fetcher with its own `try`/`catch` returning `[]`. Some channels never have card/annotation data and the query fails outright rather than returning zero rows.
+
+Because it degrades inside the fetcher, a card-metrics failure produces **no warning** in the envelope — unlike every other step, which degrades through `fetch-all.js`'s `step()` and is reported. Treat empty `annotationClickThroughRate` / `cardClicks` / `cardImpressions` fields as "unknown", not "zero".
+
+**Where handled:** `fetchCardMetrics()` in `src/api/analytics.js`.

package/docs/gotchas.md

@@ -0,0 +1,10 @@
+# Gotchas
+
+Lessons learned the hard way so we don't repeat them.
+
+Each domain file explains what breaks, why, and where `ytstats` handles it — so a future change does not silently undo a workaround.
+
+- [YouTube API](gotchas/youtube-api.md) — metrics that never work, undocumented `maxResults` ceilings, reporting lag, quota traps, and vocabulary mismatches across the three APIs.
+- [Authentication](gotchas/auth.md) — service accounts, weekly token expiry in Testing mode, client IDs that fail silently in the browser, and refresh-token preservation.
+- [CLI and output](gotchas/cli-output.md) — Commander overrides that keep stdout parseable, severity forcing, validation ordering, and what redaction must not eat.
+- [Config and storage](gotchas/config-storage.md) — atomic writes, permission windows, path-traversal rejection, and platform differences.