ytstats 0.1.0

package/docs/output-contract.md

@@ -0,0 +1,214 @@
+---
+description: The JSON envelope, the diagnostic schema, the full failure-code catalog, and exit-code derivation.
+tags: [output, envelope, diagnostics, error-codes, agents]
+source:
+  - src/output.js
+  - src/diagnostics.js
+  - src/errors.js
+---
+
+# Output Contract
+
+`ytstats` is designed for a program — often an LLM in a retry loop — rather than a human at a terminal. Everything here follows from that. For why the implementation looks the way it does, see [gotchas/cli-output.md](gotchas/cli-output.md).
+
+## The two rules
+
+**1. stdout is exactly one JSON document, always.** Every code path: success, failure, bad flag, unknown command, crash. There is no path that writes nothing.
+
+**2. stderr is everything a human reads**, and is safe to discard entirely.
+
+```bash
+ytstats fetch --days 30 2>/dev/null | jq '.data.channel.subscriberCount'
+```
+
+Commander's default behaviour violates rule 1 — it prints prose to stderr and calls `process.exit`, leaving stdout empty. `exitOverride()` and `configureOutput()` exist precisely to prevent that.
+
+## The envelope
+
+Shape-invariant: **every key is present on every response**, so a consumer never branches on whether a field exists.
+
+```jsonc
+{
+  "ok": true,
+  "command": "channel",
+  "fetchedAt": "2026-07-27T10:00:00.000Z",
+  "data": { },            // null whenever ok is false — never partial
+  "errors": [],           // non-empty iff ok is false
+  "warnings": [],         // non-fatal; never affects ok or the exit code
+  "nextSteps": [],        // ordered, deduplicated, ready-to-run commands
+  "meta": {
+    "version": "0.1.0",
+    "exitCode": 0,
+    "helpCommand": "ytstats --help",
+    "docs": "https://www.npmjs.com/package/ytstats"
+  }
+}
+```
+
+| Field | Type | Contract |
+|---|---|---|
+| `ok` | boolean | True iff `errors` is empty |
+| `command` | string \| null | The command that ran; best-effort from argv when parsing failed early |
+| `fetchedAt` | ISO 8601 string | When the envelope was rendered |
+| `data` | object \| array \| null | The payload. **`null` whenever `ok` is false** — never partial |
+| `errors` | array | Error-severity diagnostics. Non-empty exactly when `ok` is false |
+| `warnings` | array | Warning-severity diagnostics. Never affect `ok` or the exit code |
+| `nextSteps` | string[] | Flattened remediation, errors before warnings, deduplicated |
+| `meta.version` | string | The `ytstats` version, read from `package.json` |
+| `meta.exitCode` | number | The process exit code, duplicated for stdout-only consumers |
+| `meta.helpCommand` | string | Always `ytstats --help` |
+| `meta.docs` | string | Package documentation URL |
+
+`data` being `null` on failure is load-bearing: a consumer that reads `data` without checking `ok` would otherwise act on half a dataset and never know.
+
+`--compact` emits the same document on a single line.
+
+## Diagnostics
+
+Each entry in `errors` and `warnings` answers four questions — what happened, why, can it be fixed, and what to run next:
+
+```jsonc
+{
+  "code": "AUTH_TOKEN_EXPIRED",        // stable API — branch on this, never on prose
+  "severity": "error",                 // "error" | "warning"
+  "title": "Stored refresh token is no longer valid",
+  "detail": "Google rejected the stored refresh token (invalid_grant)…",
+  "cause": "Most commonly the OAuth consent screen is still in Testing mode…",
+  "recoverable": true,                 // can this be fixed and retried at all?
+  "retryable": false,                  // would re-running the SAME command help?
+  "remediation": {
+    "summary": "Sign in again, then publish your consent screen to Production.",
+    "steps": ["Run: ytstats login", "…"],
+    "commands": [{ "run": "ytstats login", "description": "Re-authorize this machine" }],
+    "docs": ["https://console.cloud.google.com/apis/credentials/consent"]
+  },
+  "context": { "flag": "--start", "value": "01/01/2026", "expected": "YYYY-MM-DD" }
+}
+```
+
+### recoverable vs retryable
+
+These are the anti-loop signals, and they are not the same question:
+
+- **`recoverable`** — can this be fixed at all? `AUTH_SERVICE_ACCOUNT` is `recoverable: false`: no configuration will ever make a service account work with YouTube APIs.
+- **`retryable`** — would re-running the *identical* command help? `AUTH_TIMEOUT` is `retryable: false` because the usual cause is a browser-side rejection that a retry cannot change. `API_RATE_LIMITED` is `retryable: true`.
+
+An agent that respects both never loops pointlessly.
+
+### context
+
+Whatever the call site supplied: `flag`, `value`, `expected`, `allowed`, `step`, `account`, `detail`. `diagnose()` also folds these into the `detail` prose (`Option: --start. Received: "01/01/2026". Expected: YYYY-MM-DD.`) so a consumer reading only `detail` still learns what was wrong. Stack-like lines are stripped — diagnostics are prose, never traces.
+
+### nextSteps
+
+Every diagnostic's `remediation.commands` flattened into one ordered, deduplicated list of `"<command>  # <description>"` strings, errors before warnings. A diagnostic with no commands contributes its `remediation.summary` instead.
+
+```bash
+ytstats fetch 2>/dev/null | jq -r 'if .ok then "fine" else .nextSteps[0] end'
+```
+
+## Diagnostic catalog
+
+`code` values are **public API**. New ones may be added freely; existing ones are never repurposed or deleted without a major version bump.
+
+### Authentication — exit 2
+
+| Code | Recoverable | Retryable | Meaning |
+|---|---|---|---|
+| `AUTH_NO_CREDENTIALS` | yes | no | No OAuth client found in any of the four sources |
+| `AUTH_NO_TOKENS` | yes | no | Client exists, but no channel has been authorized here |
+| `AUTH_TOKEN_EXPIRED` | yes | no | Refresh token rejected (`invalid_grant`) — usually the 7-day Testing trap |
+| `AUTH_TOKEN_REVOKED` | yes | no | Access explicitly revoked, by logout elsewhere or in Google account settings |
+| `AUTH_ACCOUNT_UNKNOWN` | yes | no | `--account` matched no signed-in channel |
+| `AUTH_CONSENT_DECLINED` | yes | **yes** | Google returned `access_denied` — consent dismissed or a scope refused |
+| `AUTH_TIMEOUT` | yes | no | Callback never arrived; usually "Access blocked" in the browser |
+| `AUTH_CLIENT_ID_INVALID` | yes | no | Client ID does not end in `.apps.googleusercontent.com` |
+| `AUTH_STATE_MISMATCH` | yes | **yes** | OAuth state check failed — stale tab or another process on the port |
+| `AUTH_SERVICE_ACCOUNT` | **no** | no | Service account key supplied. No workaround exists |
+| `AUTH_NO_CHANNEL` | yes | no | Authorization succeeded but the account owns no YouTube channel |
+| `AUTH_CREDENTIALS_MALFORMED` | yes | no | File is not the JSON Google produces for an OAuth client |
+| `AUTH_CREDENTIALS_NOT_FOUND` | yes | no | `--client-secret` path could not be opened |
+
+### Google APIs — exit 4
+
+| Code | Recoverable | Retryable | Meaning |
+|---|---|---|---|
+| `API_NOT_ENABLED` | yes | yes | One of the three YouTube APIs is not enabled in the project |
+| `API_QUOTA_EXCEEDED` | yes | yes | Daily quota spent; resets at midnight Pacific |
+| `API_RATE_LIMITED` | yes | yes | Transient rate limit, unlike a daily quota exhaustion |
+| `API_QUERY_NOT_SUPPORTED` | yes | no | YouTube rejected this metric/dimension combination |
+| `API_FORBIDDEN` | yes | no | Authenticated but not permitted to read this resource |
+| `API_NOT_FOUND` | yes | no | 404 for the requested id |
+| `API_UNAVAILABLE` | yes | yes | Google 5xx; nothing wrong with the request |
+| `NETWORK_UNREACHABLE` | yes | yes | Request failed before a response — DNS, TLS, proxy, or no connectivity |
+
+### Input — exit 3
+
+| Code | Recoverable | Retryable | Meaning |
+|---|---|---|---|
+| `INPUT_UNKNOWN_COMMAND` | yes | no | No such command; `context.allowed` lists the valid set |
+| `INPUT_UNKNOWN_OPTION` | yes | no | Flag not recognised by this command |
+| `INPUT_MISSING_REQUIRED` | yes | no | A mandatory option was not supplied |
+| `INPUT_INVALID_CHOICE` | yes | no | Value outside the enumerated set; see `context.allowed` |
+| `INPUT_INVALID_DATE` | yes | no | Not `YYYY-MM-DD`, or not a real calendar date |
+| `INPUT_INVALID_RANGE` | yes | no | Inverted range, or a non-positive `--days` |
+| `INPUT_INVALID_VALUE` | yes | no | Value could not be interpreted for this flag |
+
+### Data and config
+
+| Code | Severity | Exit | Meaning |
+|---|---|---|---|
+| `AUTH_CLIENT_ID_SUSPICIOUS` | warning | 0 | Client ID has the right suffix but an unusual shape; proceeding |
+| `DATA_PARTIAL` | warning | 0 | Some datasets failed while others succeeded — empty means "not fetched", not "zero" |
+| `DATA_EMPTY` | warning | 0 | Query succeeded and returned zero rows — genuinely no data |
+| `REACH_PENDING` | warning | 0 | Reporting job created; YouTube has not generated reports yet |
+| `CONFIG_UNWRITABLE` | error | 1 | Config directory not writable, so authentication cannot persist |
+| `UNEXPECTED` | error | 1 | Unrecognised condition. A bug worth reporting |
+
+## Exit codes
+
+| Code | Class |
+|---|---|
+| `0` | Success |
+| `1` | General or unexpected |
+| `2` | Authentication |
+| `3` | Bad input |
+| `4` | API error |
+
+`exitCodeFor()` returns the **worst** exit code across all error-severity diagnostics, and `EXIT.OK` when there are none — which is why warnings never change it. The result is duplicated at `meta.exitCode`.
+
+`EXIT` in `src/diagnostics.js` also defines `PARTIAL: 5`, which no diagnostic currently uses; partial results are reported as warnings on a successful run instead.
+
+## Two code vocabularies
+
+Reading the source, you will meet two sets of codes:
+
+- **`DIAGNOSTICS` codes** (`src/diagnostics.js`) — the fine-grained catalog above. This is the public contract, surfaced in the envelope.
+- **`ERROR_CODES`** (`src/errors.js`) — a coarser internal vocabulary on `YtStatsError.code`: `MISSING_CREDENTIALS`, `INVALID_CREDENTIALS`, `NOT_AUTHENTICATED`, `AUTH_FAILED`, `AUTH_TIMEOUT`, `ACCESS_DENIED`, `API_NOT_ENABLED`, `NO_YOUTUBE_CHANNEL`, `QUOTA_EXCEEDED`, `QUERY_NOT_SUPPORTED`, `NOT_FOUND`, `INVALID_INPUT`, `API_ERROR`, `UNKNOWN`. Used for internal control flow, such as `FATAL_CODES` in `fetch-all.js`.
+
+`legacyCodeFor()` maps the first onto the second when `mapGoogleError()` constructs an error. Consumers should read the envelope's `code`, which is always the `DIAGNOSTICS` vocabulary.
+
+## Error classification
+
+`diagnoseGoogleError()` turns a Google API failure into a precise diagnostic by checking, **in this order**: network-level error codes, then reason strings (`accessNotConfigured`, `NoLinkedYouTubeAccount`, `quotaExceeded`, `rateLimitExceeded`), then message fingerprints (`query is not supported`, `invalid_grant`, revocation phrasing), and only then generic HTTP statuses.
+
+The order matters: a bare 403 can mean four unrelated things, so reordering silently degrades precise diagnostics into `API_FORBIDDEN`.
+
+## Redaction
+
+`redact()` strips anything resembling a secret from text bound for stdout or stderr:
+
+- Google client secrets (`GOCSPX-…`)
+- Access tokens (`ya29.…`), refresh tokens (`1//…`), authorization codes (`4/…`)
+- JSON fields named `client_secret`, `clientSecret`, `refresh_token`, `access_token`, `code_verifier`, `codeVerifier`, `authorization_code`
+- Query parameters `code`, `code_verifier`, `client_secret`
+
+It runs on the **serialized** JSON, after `JSON.stringify`, so a secret embedded in prose is caught too. It deliberately does *not* match a bare `"code"` field, because every diagnostic carries `"code": "AUTH_NO_TOKENS"` — public API that must survive redaction.
+
+Redaction is belt-and-braces: these values are never deliberately logged in the first place.
+
+## Failures are differentiated
+
+There is no single "not authenticated" bucket. A generic error would force the caller to guess between six unrelated problems, each with a different fix. The design assumption is an agent that reads `code`, checks `recoverable`/`retryable`, and runs `nextSteps[0]` — so every anticipated failure earns its own code and its own recovery path.
+
+Input problems are additionally reported **all at once, before authentication**, so one loop iteration fixes everything rather than discovering a bad date only after fixing auth.

package/docs/testing.md

@@ -0,0 +1,93 @@
+---
+description: How ytstats is tested — injection seams, temp config dirs, real-HTTP loopback tests, subprocess end-to-end runs, and what coverage numbers actually mean.
+tags: [testing, vitest, coverage, injection]
+source:
+  - test/**
+  - vitest.config.js
+---
+
+# Testing
+
+316 tests across 13 files. **None of them requires network access**, and none opens a browser.
+
+## Running
+
+```bash
+npm test          # vitest run
+npm run test:watch
+npm run coverage  # vitest run --coverage
+```
+
+`vitest.config.js` sets a Node environment, matches `test/**/*.test.js`, and allows a 15-second timeout — long enough for the end-to-end tests, which spawn real subprocesses.
+
+`prepublishOnly` runs `npm test`, so a failing suite blocks publication.
+
+## Injection is the strategy
+
+The suite runs offline because every effect is a parameter with a real default. `buildProgram()` takes `stdout`, `stderr`, `exit`, `session`, and `now`; `login()` takes `OAuth2`, `startLoopbackServer`, `openBrowser`, `fetchIdentity`, `promptForRedirectUrl`, and `log`; `fetchAll()` takes a `fetchers` bundle; every API fetcher takes `apis` as its first argument.
+
+Nothing is mocked at the module level. Tests hand in plain objects, which means a test breaks when a *contract* changes rather than when an implementation detail moves.
+
+## Test files
+
+| File | Tests | Covers |
+|---|---|---|
+| `test/envelope.test.js` | 96 | Envelope shape, the diagnostic catalog, severity routing, `nextSteps`, redaction |
+| `test/api/transforms.test.js` | 33 | Duration parsing, content classification, CSV, date normalization, row zipping |
+| `test/cli.e2e.test.js` | 30 | The real binary, spawned as a subprocess |
+| `test/api/fetchers.test.js` | 27 | Exact query parameters sent by every Data, Analytics, and Reporting fetcher |
+| `test/auth/credentials.test.js` | 20 | Resolution precedence, file shapes, service-account rejection, discovery |
+| `test/auth/oauth.test.js` | 18 | PKCE, auth URL construction, and the loopback server over real HTTP |
+| `test/auth/session.test.js` | 18 | `login`, `logout`, `getAuthenticatedClient`, refresh persistence |
+| `test/auth/tokens.test.js` | 18 | Multi-account store, merging, default promotion, legacy import |
+| `test/config/store.test.js` | 14 | Atomic writes, permissions, traversal rejection |
+| `test/fetch-all.test.js` | 13 | Orchestration, per-step degradation, fatal codes, retention capping |
+| `test/dates.test.js` | 11 | Window resolution, calendar validation, bounds |
+| `test/client-id.test.js` | 10 | Client ID pre-flight validation, both tiers |
+| `test/config/paths.test.js` | 8 | Per-OS directory resolution, including Windows and Linux from any host |
+
+`envelope.test.js` dominates the count because it parameterizes with `it.each` over the entire `DIAGNOSTICS` catalog — every code is asserted to be fully specified, and every recoverable one to carry remediation. Adding a diagnostic adds tests automatically.
+
+## Isolation
+
+`test/helpers/tmp.js` provides `useTempConfigDir()`, which creates a fresh temp directory, points `YTSTATS_CONFIG_DIR` at it, and returns a `cleanup()` that restores the previous value and removes the directory.
+
+Every test touching the config store uses it, so there is no shared global state and no risk of a test reading the developer's real credentials.
+
+The helper also exports `mode(path)` — an octal permission string for asserting `0600`/`0700` — and `isWindows`, used to skip POSIX-mode assertions where they are meaningless.
+
+## What each layer proves
+
+**Pure functions are tested directly.** `transforms.js`, `dates.js`, `config/paths.js`, and `diagnostics.js` have no effects to arrange.
+
+**Fetchers assert the exact query parameters**, not merely the return shape. This is the mechanism that pins the undocumented API limits — `MAX_VIDEO_ROWS` at 200, `MAX_DETAIL_ROWS` at 25, the `views`-only metric list on `insightTrafficSourceDetail`, and the absence of `videoThumbnailImpressions`. A test that only checked the returned rows would let someone raise a limit and reintroduce an opaque failure.
+
+There is also a test asserting `search.list` is never called, protecting the 100× quota difference against a plausible-looking refactor.
+
+**The session layer injects `OAuth2`, the loopback server, the browser opener, and the identity lookup**, so `login` and `logout` are covered end to end without Google.
+
+**The loopback server is tested over real HTTP** on `127.0.0.1` — the test makes actual `fetch` calls against a listening server. It covers state mismatch, user denial, timeout, favicon noise, and the guarantee that the success page never contains the authorization code.
+
+**The CLI is tested by spawning the actual binary.** `test/cli.e2e.test.js` runs `node bin/ytstats.js …` with `execFile`, a temp `YTSTATS_CONFIG_DIR`, and `NO_COLOR=1`, and never throws on a non-zero exit — the exit code is part of what it asserts. This is what proves the output contract holds on paths that are hard to reach in-process: unknown commands, invalid flags, `--help`, `--version`.
+
+## Coverage numbers
+
+`npm run coverage` currently reports about 71% overall, and two figures need explaining:
+
+**`src/cli.js` reports 0%.** Its 30 end-to-end tests run the file as a **subprocess**, which v8 coverage cannot instrument from the parent process. The file is well covered; the number is a measurement artifact, not a gap. Do not chase it by converting the e2e tests to in-process calls — running the real binary is the point.
+
+**`src/api/client.js` reports about 33%.** The uncovered lines are `createApis()` and `downloadCsv()`, which construct live googleapis clients and perform real HTTP. Fetchers take the resulting bundle as a parameter, so the tests hand in plain objects and never execute the constructor.
+
+## What is not covered
+
+**No test performs a live call against Google.** Request shapes are asserted against the documented contract, not the live service. If YouTube changes a limit or starts rejecting a combination that works today, the suite will not notice — that class of failure surfaces as a `API_QUERY_NOT_SUPPORTED` diagnostic at runtime, which is why per-step degradation exists.
+
+The browser is never opened, and no real OAuth consent is exercised.
+
+## Adding tests
+
+For a new fetcher, assert the exact parameters passed to the injected API bundle — see [contributing.md](contributing.md#adding-a-new-dataset).
+
+For a new diagnostic, the catalog test fails unless the entry has a title, detail, cause, and at least one remediation step.
+
+For anything touching the config store, use `useTempConfigDir()` rather than writing to the real directory.

package/docs/youtube-apis.md

@@ -0,0 +1,180 @@
+---
+description: How ytstats calls the YouTube Data, Analytics, and Reporting APIs — exact queries, encoded limits, quota costs, and transforms.
+tags: [youtube-api, analytics, reporting, quota, fetchers]
+source:
+  - src/api/**
+  - src/fetch-all.js
+---
+
+# YouTube APIs
+
+`ytstats` reads from three separate Google APIs. This is the request-level reference; for the traps each one hides, see [gotchas/youtube-api.md](gotchas/youtube-api.md).
+
+## The three surfaces
+
+`createApis(authClient)` bundles them, plus a CSV downloader:
+
+```js
+{
+  youtube:   google.youtube({ version: 'v3', auth }),           // Data API v3
+  analytics: google.youtubeAnalytics({ version: 'v2', auth }),  // Analytics API v2
+  reporting: google.youtubereporting({ version: 'v1', auth }),  // Reporting API v1
+  downloadCsv(url),                                             // OAuth-authenticated fetch
+}
+```
+
+Every fetcher takes this bundle as its first argument. That is the injection seam: tests hand in plain objects and never touch the network. All three APIs must be enabled in the same Google Cloud project that issued the OAuth client, or requests fail with `API_NOT_ENABLED`.
+
+`call(fn)` wraps each request and converts Google's error shapes into typed `YtStatsError`s via `mapGoogleError()`.
+
+## Data API v3
+
+Three fetchers in `src/api/data.js`.
+
+### fetchChannel
+
+```js
+youtube.channels.list({
+  part: 'snippet,contentDetails,statistics,status,topicDetails',
+  mine: true,
+})
+```
+
+Returns the normalized channel, or `null` when the account owns none. `uploadsPlaylistId` comes from `contentDetails.relatedPlaylists.uploads` and is what every video enumeration keys off.
+
+### fetchAllVideoIds
+
+Pages `playlistItems.list` over the uploads playlist at `maxResults: 50`, following `nextPageToken` until exhausted.
+
+**This must not be swapped for `search.list`.** `playlistItems.list` costs 1 quota unit per page of 50; `search.list` costs 100 per call — a 100× difference. A test asserts `search.list` is never called.
+
+### fetchVideos
+
+Batches ids 50 at a time into `videos.list`:
+
+```js
+youtube.videos.list({
+  part: 'snippet,contentDetails,statistics,status,liveStreamingDetails,topicDetails',
+  id: batch.join(','),
+})
+```
+
+1 quota unit per batch. `liveStreamingDetails` is requested because `classifyContent()` uses its presence to identify live streams.
+
+### Quota costs
+
+| Operation | Cost |
+|---|---|
+| `channels.list` | 1 |
+| `playlistItems.list` | 1 per page of 50 |
+| `videos.list` | 1 per batch of 50 |
+| `search.list` | **100** — never used |
+
+The Data API grants 10,000 units/day per project. A full fetch for a 100-video channel costs roughly 5 units. The Analytics and Reporting APIs have separate quotas.
+
+## Analytics API v2
+
+Every fetcher in `src/api/analytics.js` funnels through one private `query()` helper that always sets `ids: 'channel==MINE'` and includes `dimensions`, `filters`, `sort`, and `maxResults` only when supplied.
+
+Two undocumented limits are encoded as constants rather than left to callers, because exceeding either produces an opaque failure:
+
+```js
+const MAX_VIDEO_ROWS = 200;   // dimensions=video rejects maxResults above this
+const MAX_DETAIL_ROWS = 25;   // insightTrafficSourceDetail errors above ~25
+```
+
+Both are applied with `Math.min`, so a caller cannot exceed them.
+
+### Fetchers
+
+| Fetcher | Metrics | Dimensions | Sort | maxResults |
+|---|---|---|---|---|
+| `fetchDailyAnalytics` | `views`, `estimatedMinutesWatched`, `averageViewDuration`, `likes`, `dislikes`, `comments`, `shares`, `subscribersGained`, `subscribersLost` | `day` | `day` | — |
+| `fetchCardMetrics` | `views`, `annotationClickThroughRate`, `cardClicks`, `cardImpressions` | `day` | `day` | — |
+| `fetchVideoAnalytics` | `views`, `estimatedMinutesWatched`, `averageViewDuration`, `averageViewPercentage`, `likes`, `comments`, `shares`, `subscribersGained`, `subscribersLost` | `video` | `-views` | ≤ 200 |
+| `fetchTrafficSources` | `views`, `estimatedMinutesWatched` | `insightTrafficSourceType` | `-views` | — |
+| `fetchDemographics` | `viewerPercentage` | `ageGroup,gender` | — | — |
+| `fetchDeviceTypes` | `views`, `estimatedMinutesWatched` | `deviceType` | `-views` | — |
+| `fetchContentTypes` | `views`, `estimatedMinutesWatched`, `likes`, `shares`, `subscribersGained`, `subscribersLost` | `creatorContentType` | `-views` | — |
+| `fetchSearchTerms` | `views` | `insightTrafficSourceDetail` | `-views` | ≤ 25 |
+| `fetchGeography` | `views`, `estimatedMinutesWatched`, `subscribersGained`, `subscribersLost` | `country` | `-views` | 50 |
+| `fetchPlaybackLocations` | `views`, `estimatedMinutesWatched` | `insightPlaybackLocationType` | `-views` | — |
+| `fetchTrafficSourceDetails` | `views` | `insightTrafficSourceDetail` | `-views` | ≤ 25 |
+| `fetchAudienceRetention` | `audienceWatchRatio` | `elapsedVideoTimeRatio` | — | — |
+| `runCustomReport` | caller-supplied | caller-supplied | caller-supplied | caller-supplied |
+
+`fetchSearchTerms` filters with `insightTrafficSourceType==YT_SEARCH`; `fetchTrafficSourceDetails` filters on whichever source type it is given. `fetchAudienceRetention` filters `video==<videoId>`.
+
+The `views`-only metric lists on the two detail fetchers are not an oversight: adding `estimatedMinutesWatched` to `insightTrafficSourceDetail` triggers an internal server error.
+
+Tests assert the **exact query parameters** each fetcher sends. That is what pins these limits rather than merely documenting them.
+
+### Notable omission
+
+`videoThumbnailImpressions` and `videoThumbnailImpressionsClickRate` appear nowhere in this file. They are documented by Google but never work; a test asserts their absence. Impressions and CTR come from the Reporting API instead.
+
+### fetchCardMetrics degrades silently
+
+It is the one fetcher with its own `try`/`catch` returning `[]`, because some channels never have card data and the query fails outright. Unlike every other step, a failure here produces **no warning** — treat empty card fields as unknown rather than zero.
+
+### runCustomReport
+
+The escape hatch behind `ytstats query`. Returns `{ columns, rows }`, where `columns` is derived from the response's `columnHeaders` as `[{ name, type }]`.
+
+## Reporting API v1
+
+The only source of thumbnail impressions and CTR, and asynchronous by design. `src/api/reporting.js` uses one report type:
+
+```js
+export const REACH_REPORT_TYPE = 'channel_reach_basic_a1';
+```
+
+The lifecycle:
+
+1. **`ensureReachJob()`** lists jobs and returns the existing one with a matching `reportTypeId`, creating it only if absent. Safe to call on every run — it never creates a duplicate.
+2. **`listReports()`** pages `jobs.reports.list` for that job.
+3. **Zero reports** → return `pending: true` with an explanatory `message`. The CLI surfaces this as the `REACH_PENDING` warning. Google generates the first reports within 24-48 hours, including a 30-day backfill.
+4. **Download and merge.** Each report's `downloadUrl` is fetched through `apis.downloadCsv`, parsed, and folded into a `Map` keyed `` `${date}|${videoId}` ``. Reports overlap, so last write wins — later reports carry corrected figures for the same day.
+5. **Sort** by date, then video id.
+
+Rows are `{ date, channelId, videoId, impressions, impressionsCtr }`. **`impressionsCtr` is a decimal fraction, not a percentage**: `0.0561` means 5.61%.
+
+Report data is permanently 1-2 days behind — the same lag YouTube Studio shows — because it covers midnight-to-midnight Pacific periods generated after the period closes.
+
+### downloadCsv
+
+Report bodies are plain CSV behind an OAuth-protected URL that the googleapis client does not handle, so `createApis` provides a `fetch` wrapper that attaches `Authorization: Bearer <token>` from `authClient.getAccessToken()` and requests gzip. A non-2xx response throws.
+
+## Transforms
+
+`src/api/transforms.js` is pure — no network, no auth, deterministic, directly tested.
+
+| Function | Purpose |
+|---|---|
+| `parseDuration(iso)` | ISO 8601 duration (`PT15M33S`, `P1DT2H`) to whole seconds; `0` when absent or unparseable |
+| `classifyContent(video)` | `LIVE_STREAM` if `liveStreamingDetails` is present, `SHORTS` if duration is 1-60s, else `VIDEO_ON_DEMAND` |
+| `parseCsv(text)` | RFC 4180 subset: quoted fields, embedded commas and newlines, `""` escapes |
+| `normalizeReportingDate(v)` | `20260328.0` → `2026-03-28`; ISO passes through; unrecognised values are returned unchanged |
+| `rowsFromAnalytics(data)` | Zips `columnHeaders` + positional `rows` into objects |
+| `normalizeChannel(ch)` | Flattens the channel resource into camelCase |
+| `normalizeVideo(v)` | Flattens the video resource, adding `durationSeconds` and `contentType` |
+
+Output is idiomatic camelCase JSON. Mapping it onto a particular database schema is the consumer's job.
+
+A naive `split(',')` would corrupt report rows silently, because video titles and search terms routinely contain commas — hence the real parser. Its `coerce()` helper converts numeric-looking cells to numbers but leaves anything with a leading zero as a string, so zero-padded identifiers survive.
+
+## Orchestration
+
+`fetchAll()` in `src/fetch-all.js` runs every dataset in one pass. Order and concurrency:
+
+1. **`fetchChannel`** — outside `step()`. A missing channel throws `NO_YOUTUBE_CHANNEL`; everything downstream needs `uploadsPlaylistId`.
+2. **`fetchAllVideoIds`** then **`fetchVideos`** — sequential, the second needs the first.
+3. **`fetchDailyAnalytics` + `fetchCardMetrics`** — concurrent; the results are merged by date.
+4. **Eight analytics fetchers** — concurrent: video analytics, traffic sources, demographics, device types, content types, search terms, geography, playback locations.
+5. **Traffic source details** — one call per source type the channel actually returned, concurrent.
+6. **Retention** — sequential, one API call per video, capped at `retentionLimit` (default 50) with the newest videos first.
+7. **Reach** — only with `reach: true`.
+
+Every step after the channel runs inside `step(name, fn, fallback)`, which catches, records a warning, and returns the fallback — except for `FATAL_CODES` (`NOT_AUTHENTICATED`, `MISSING_CREDENTIALS`, `INVALID_CREDENTIALS`, `NO_YOUTUBE_CHANNEL`, `QUOTA_EXCEEDED`), which rethrow.
+
+Returns `{ period: { startDate, endDate, days }, warnings, notes, data }`. When retention is truncated, `notes` says so explicitly.

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "ytstats",
+  "version": "0.1.0",
+  "description": "Pull your YouTube channel stats and analytics as JSON. Bring your own Google Cloud credentials, no server, no data leaves your machine.",
+  "type": "module",
+  "bin": {
+    "ytstats": "./bin/ytstats.js"
+  },
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md",
+    "CHANGELOG.md",
+    "docs/",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "coverage": "vitest run --coverage",
+    "prepublishOnly": "npm test"
+  },
+  "keywords": [
+    "youtube",
+    "analytics",
+    "youtube-api",
+    "youtube-analytics",
+    "cli",
+    "json",
+    "statistics",
+    "creator",
+    "agent",
+    "agentic"
+  ],
+  "author": "Nicolas Dao",
+  "license": "BSD-3-Clause",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nicolasdao/ytstats.git"
+  },
+  "homepage": "https://github.com/nicolasdao/ytstats#readme",
+  "bugs": {
+    "url": "https://github.com/nicolasdao/ytstats/issues"
+  },
+  "dependencies": {
+    "commander": "^14.0.3",
+    "googleapis": "^171.4.0",
+    "open": "^9.1.0"
+  },
+  "overridesRationale": {
+    "gaxios": "googleapis-common pins gaxios 7.1.3, which drags in rimraf > glob > minimatch > brace-expansion and a high-severity DoS advisory (GHSA-mh99-v99m-4gvg). gaxios 7.1.4+ dropped that chain. Same major version, so this is a patch-level floor, not a compatibility risk. Remove once googleapis-common raises its own floor."
+  },
+  "overrides": {
+    "gaxios": "^7.1.4"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^4.1.10",
+    "vitest": "^4.1.10"
+  }
+}