ytstats 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,40 @@
+# Changelog
+
+All notable changes to this project are documented here.
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-07-27
+
+Initial release.
+
+### Added
+
+- `login` / `logout` / `status` / `use` — bring-your-own-credentials OAuth. No shared
+  client ID: each user supplies their own Google Cloud OAuth client, so quota and
+  verification are their own.
+- Loopback OAuth flow with PKCE (S256) and a constant-time CSRF state check, bound to
+  `127.0.0.1` on an ephemeral port. `--no-browser` fallback for headless machines.
+- Multi-account token storage in a per-user config directory (macOS, Windows, Linux),
+  written atomically at `0600` inside a `0700` directory.
+- `fetch` — every dimension in one JSON document: channel, videos, daily metrics,
+  per-video analytics, traffic sources and details, demographics, devices, content
+  types, search terms, geography, playback locations, retention curves, optional reach.
+- Individual dataset commands: `channel`, `videos`, `daily`, `traffic`, `demographics`,
+  `devices`, `content-types`, `search-terms`, `geography`, `playback-locations`,
+  `video-analytics`, `retention`, `reach`, `reach-jobs`, `query`.
+- `doctor` — checks config writability, credentials, sign-in state and live API
+  reachability independently, and reports the exact blocking diagnostics.
+- `import-legacy` — import tokens from a pre-ytstats project-local `tokens.json`.
+- Agent-first output contract: stdout is always exactly one shape-invariant envelope
+  (`ok`, `command`, `fetchedAt`, `data`, `errors`, `warnings`, `nextSteps`, `meta`),
+  including for unknown commands and invalid flags. Every diagnostic carries a stable
+  code, cause, `recoverable`/`retryable` flags, and runnable remediation commands.
+- Input validation runs before authentication and reports every problem at once.
+- Client ID pre-flight validation, so a malformed OAuth client fails immediately
+  instead of hanging until the browser callback times out.
+
+[Unreleased]: https://github.com/nicolasdao/ytstats/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/nicolasdao/ytstats/releases/tag/v0.1.0

package/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Nicolas Dao
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -0,0 +1,256 @@
+# ytstats
+
+Pull your YouTube channel's stats and analytics as JSON, from the command line.
+
+```bash
+npx ytstats login
+npx ytstats fetch --days 90 > snapshot.json
+```
+
+No install. No server. No shared API key. Your data and your credentials never leave your machine.
+
+## Table of Contents
+
+<!-- BEGIN toc -->
+- [Overview](#overview)
+  - [Why bring your own credentials](#why-bring-your-own-credentials)
+- [Getting Started](#getting-started)
+  - [Prerequisites](#prerequisites)
+  - [1. Create a Google Cloud project](#1-create-a-google-cloud-project)
+  - [2. Enable the three APIs](#2-enable-the-three-apis)
+  - [3. Configure the OAuth consent screen](#3-configure-the-oauth-consent-screen)
+  - [4. Create the OAuth client](#4-create-the-oauth-client)
+  - [5. Log in](#5-log-in)
+  - [Where credentials are stored](#where-credentials-are-stored)
+- [Commands](#commands)
+  - [Self-diagnosis](#self-diagnosis)
+- [Output](#output)
+- [Use as a library](#use-as-a-library)
+- [Things worth knowing](#things-worth-knowing)
+- [Quota](#quota)
+- [Project Structure](#project-structure)
+- [Documentation](#documentation)
+- [Requirements](#requirements)
+- [License](#license)
+<!-- END toc -->
+
+## Overview
+
+`ytstats` reads a channel you own — metadata, videos, daily metrics, traffic sources, demographics, devices, content types, search terms, geography, playback locations, retention curves, and thumbnail CTR — and prints it as one JSON document.
+
+It is built for programs first. **stdout is exactly one JSON document, always** — success, failure, bad flag, unknown command, crash. Progress goes to stderr and is safe to discard. Every failure carries a stable code, a cause, `recoverable`/`retryable` flags, and runnable next steps, so an agent in a retry loop knows whether to retry, fix something, or stop.
+
+### Why bring your own credentials
+
+`ytstats` has **no built-in Google client ID**, by design. You create a Google Cloud project, generate an OAuth client, and the CLI uses yours. This means:
+
+- **Your quota is yours.** The YouTube Data API gives every project 10,000 units/day. A shared client ID would make everyone compete for one pool.
+- **No verification bottleneck.** Apps using YouTube scopes need Google's OAuth verification to serve strangers. You're not a stranger to yourself.
+- **Nothing to trust.** There is no backend to send your data to, because there is no backend.
+
+The cost is about five minutes of setup, once.
+
+## Getting Started
+
+### Prerequisites
+
+Node.js 18+. No native dependencies, so `npx` is instant.
+
+### 1. Create a Google Cloud project
+
+<https://console.cloud.google.com/projectcreate>
+
+### 2. Enable the three APIs
+
+| API | Link |
+|---|---|
+| YouTube Data API v3 | [enable](https://console.cloud.google.com/apis/library/youtube.googleapis.com) |
+| YouTube Analytics API | [enable](https://console.cloud.google.com/apis/library/youtubeanalytics.googleapis.com) |
+| YouTube Reporting API | [enable](https://console.cloud.google.com/apis/library/youtubereporting.googleapis.com) |
+
+All three must be enabled in the **same project** that issues your OAuth client.
+
+### 3. Configure the OAuth consent screen
+
+<https://console.cloud.google.com/apis/credentials/consent> — choose **External**, fill in the app name and your email, and add your own Google account as a **test user**.
+
+> **Publish it to Production when you're done.** While the consent screen is in *Testing*, Google expires refresh tokens after **7 days** and you'll be logging in every week. Publishing (you'll click past an "unverified app" warning once) stops that.
+
+### 4. Create the OAuth client
+
+<https://console.cloud.google.com/apis/credentials> → **Create credentials → OAuth client ID → Application type: Desktop app**. Download the JSON.
+
+> A **service account will not work** — not with any amount of configuration. Service accounts have no YouTube channel, so Google rejects them with `NoLinkedYouTubeAccount`. This is [documented](https://developers.google.com/youtube/v3/guides/authentication) and there is no workaround. You need an OAuth client ID.
+
+### 5. Log in
+
+```bash
+npx ytstats login --client-secret ~/Downloads/client_secret_1234.json
+```
+
+Your browser opens, you approve, and you're done. Every later command needs no flags:
+
+```bash
+npx ytstats channel
+```
+
+`--no-browser` prints a URL and reads the pasted redirect back, for SSH and headless machines.
+
+### Where credentials are stored
+
+Both the OAuth client and your tokens are written to a per-user directory, `0600`, readable only by you:
+
+| OS | Location |
+|---|---|
+| macOS | `~/Library/Application Support/ytstats/` |
+| Linux | `$XDG_CONFIG_HOME/ytstats/` (default `~/.config/ytstats/`) |
+| Windows | `%APPDATA%\ytstats\` |
+
+Override with `YTSTATS_CONFIG_DIR`. For CI, set `YTSTATS_CLIENT_ID` and `YTSTATS_CLIENT_SECRET` instead of a file. These are plaintext files, like `gcloud`, `gh`, and `aws` use. `ytstats logout` revokes the token with Google and deletes them.
+
+## Commands
+
+The one you'll actually use:
+
+```bash
+ytstats fetch [--days 90] [--no-retention] [--retention-limit 50] [--reach]
+```
+
+Every dimension in a single JSON document. Individual analytics steps degrade rather than abort — YouTube rejects some metric combinations for some channels, and losing demographics shouldn't cost you the other twelve datasets. Anything that failed appears in `warnings`.
+
+Individual datasets and account management:
+
+```bash
+ytstats channel                       # metadata and lifetime stats
+ytstats videos [-n 10] [-t SHORTS] [-s viewCount]
+ytstats daily [-d 30]                 # day-by-day metrics
+ytstats traffic                       # where views come from
+ytstats demographics                  # age and gender
+ytstats devices
+ytstats content-types                 # Shorts vs long-form vs live
+ytstats search-terms                  # what people search to find you
+ytstats geography [-n 50]
+ytstats playback-locations
+ytstats video-analytics               # per-video, top 200 by views
+ytstats retention <videoId>           # where viewers drop off
+ytstats reach                         # thumbnail impressions and CTR
+ytstats query -m views,likes --dimensions day
+
+ytstats login | logout | status | doctor | use <channel> | import-legacy <file>
+```
+
+All analytics commands accept `--days N`, or `--start YYYY-MM-DD --end YYYY-MM-DD`. Global flags: `-a, --account <channel>`, `--compact`, `-q, --quiet`.
+
+Full reference with every flag and default: [docs/cli.md](docs/cli.md).
+
+### Self-diagnosis
+
+When something is wrong and you don't know what:
+
+```bash
+ytstats doctor
+```
+
+It checks config writability, credentials, sign-in state, and live API reachability independently, and returns a pass/fail list plus the exact blocking diagnostics. `doctor` itself always succeeds (`ok: true`); the verdict is in `data.healthy`.
+
+## Output
+
+Every response is the same shape — every key present, every time, 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" }
+}
+```
+
+Exit codes: `0` success · `2` authentication · `3` bad input · `4` API error · `1` anything else. Also available as `meta.exitCode`, so a consumer that can only see stdout still knows.
+
+```bash
+ytstats fetch --days 30 2>/dev/null | jq '.data.channel.subscriberCount'
+ytstats fetch 2>/dev/null | jq -r 'if .ok then "fine" else .nextSteps[0] end'
+```
+
+Input is validated **before** authentication, and every input problem is reported together — so one loop iteration fixes everything rather than discovering a bad date only after fixing auth.
+
+The envelope, the diagnostic schema, and the full failure-code catalog are in [docs/output-contract.md](docs/output-contract.md).
+
+## Use as a library
+
+```js
+import { getAuthenticatedClient, createApis, fetchAll, resolveDateRange } from 'ytstats';
+
+const { client } = getAuthenticatedClient();
+const result = await fetchAll(createApis(client), { range: resolveDateRange({ days: 90 }) });
+```
+
+Library callers get no envelope: `fetchAll` returns its result object directly and fetchers throw `YtStatsError`. The full export surface is listed in [docs/architecture.md](docs/architecture.md#programmatic-api).
+
+## Things worth knowing
+
+**CTR only comes from `ytstats reach`.** The Analytics API documents `videoThumbnailImpressions` but it has never worked ([issue 254665034](https://issuetracker.google.com/issues/254665034)). CTR is served asynchronously by the Reporting API instead: the first `reach` run only creates a job, and data appears **24-48 hours later** with a 30-day backfill. It's also permanently 1-2 days behind — the same lag YouTube Studio shows.
+
+**Retention ratios above 1.0 are correct.** A Short showing `1.54` means viewers looped it. Not a bug, and never clamped.
+
+**Shorts detection is duration-based.** ≤60s is `SHORTS`. A 62-second video meant as a Short will read `VIDEO_ON_DEMAND`. YouTube's own classification uses extra signals — read `content-types` for its opinion.
+
+**Per-video analytics caps at 200 videos**, sorted by views. An API limit, not ours.
+
+**Subscriber counts are rounded** to 3 significant figures above 1,000. Small week-over-week changes are invisible.
+
+**`fetch --reach` and retention cost extra calls.** Retention is one API call per video, hence `--retention-limit` (default 50, newest first).
+
+The rest, with the handling sites named, is in [docs/gotchas.md](docs/gotchas.md).
+
+## Quota
+
+The Data API allows 10,000 units/day per project. `ytstats` uses the uploads playlist (1 unit per 50 videos) rather than `search.list` (100 units per call), so a full fetch for a 100-video channel costs about 5 units. The Analytics and Reporting APIs have separate quotas.
+
+## Project Structure
+
+```
+bin/ytstats.js       thin shim; guards stdout against stack traces
+src/
+  cli.js             command definitions, validation ordering, error capture
+  index.js           the library entry point
+  auth/              credentials, OAuth loopback flow, token store, session
+  api/               Data v3, Analytics v2, Reporting v1, pure transforms
+  config/            per-user config dir, atomic 0600 store
+  fetch-all.js       one-document orchestrator with per-step degradation
+  output.js          the envelope; stdout/stderr discipline
+  diagnostics.js     the failure catalog
+  errors.js          YtStatsError, Google error classification, redaction
+  dates.js           reporting window resolution and validation
+test/                316 tests, none requiring network access
+docs/                topic documentation, indexed below
+```
+
+## Documentation
+
+<!-- BEGIN doc-index -->
+- [Architecture](docs/architecture.md) — How ytstats is put together — module layout, design principles, request flow, and the programmatic API surface.
+- [Authentication](docs/auth.md) — The bring-your-own-credentials OAuth model — credential resolution, the PKCE loopback flow, token storage, and multi-account handling.
+- [CLI Reference](docs/cli.md) — Complete ytstats command reference — every command, flag, default, and exit code.
+- [Configuration](docs/configuration.md) — Environment variables, the per-user config directory, stored file formats, and CI setup.
+- [Contributing](docs/contributing.md) — How to extend ytstats — adding datasets, commands, and diagnostics; the dependency policy; and the release process.
+- [Gotchas](docs/gotchas.md)
+- [Output Contract](docs/output-contract.md) — The JSON envelope, the diagnostic schema, the full failure-code catalog, and exit-code derivation.
+- [Testing](docs/testing.md) — How ytstats is tested — injection seams, temp config dirs, real-HTTP loopback tests, subprocess end-to-end runs, and what coverage numbers actually mean.
+- [YouTube APIs](docs/youtube-apis.md) — How ytstats calls the YouTube Data, Analytics, and Reporting APIs — exact queries, encoded limits, quota costs, and transforms.
+<!-- END doc-index -->
+
+Also: [CHANGELOG.md](CHANGELOG.md).
+
+## Requirements
+
+Node.js 18+. No native dependencies.
+
+## License
+
+BSD-3-Clause

package/bin/ytstats.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import { main } from '../src/cli.js';
+
+main().catch(err => {
+  // Last-resort guard: never let a stack trace land on stdout, which is reserved
+  // for the JSON document.
+  process.stderr.write(`ytstats: ${err?.message ?? err}\n`);
+  process.exitCode = 1;
+});

package/docs/architecture.md

@@ -0,0 +1,128 @@
+---
+description: How ytstats is put together — module layout, design principles, request flow, and the programmatic API surface.
+tags: [architecture, design, modules, orchestration]
+source:
+  - bin/ytstats.js
+  - src/index.js
+  - src/cli.js
+  - src/fetch-all.js
+---
+
+# Architecture
+
+Contributor-facing notes on how `ytstats` is built and why. For the command surface see [cli.md](cli.md); for how to change it see [contributing.md](contributing.md).
+
+## Shape
+
+```
+bin/ytstats.js          thin shim; last-resort guard against stdout pollution
+  └─ src/cli.js         command definitions, validation ordering, error capture
+       ├─ src/auth/     credentials, OAuth, token store, session
+       ├─ src/api/      Data v3, Analytics v2, Reporting v1, pure transforms
+       ├─ src/fetch-all.js   one-document orchestrator with per-step degradation
+       ├─ src/output.js      the envelope; stdout/stderr discipline
+       ├─ src/diagnostics.js the failure catalog
+       ├─ src/errors.js      YtStatsError, Google error classification, redaction
+       ├─ src/dates.js       reporting window resolution and validation
+       └─ src/config/   per-user config dir, atomic 0600 store
+```
+
+`src/index.js` is a separate entry point — the library surface — and imports the same modules the CLI does.
+
+## Design principles
+
+**Everything I/O is injected.** API clients, the OAuth2 constructor, the loopback server, the browser opener, the identity lookup, the output sinks, and even `now()` are parameters with real defaults. This is why 316 tests run without a network connection and without opening a browser.
+
+**Pure logic is separated from effects.** `api/transforms.js`, `dates.js`, `config/paths.js` and `diagnostics.js` are pure and directly tested. Everything awkward to test is pushed to the edges.
+
+**No native dependencies.** `npx ytstats` must start instantly, which rules out anything requiring a prebuild download or a node-gyp compile. Runtime dependencies are `commander`, `googleapis`, and `open` — all pure JS. Think hard before adding a fourth.
+
+**Read-only by design.** Only three read-only scopes are ever requested (`SCOPES` in `src/auth/oauth.js`). `ytstats` has no code path that modifies a channel.
+
+**The consumer is assumed to be a program.** stdout carries exactly one JSON document on every code path; diagnostics are structured, coded, and carry runnable remediation. See [output-contract.md](output-contract.md).
+
+## Module responsibilities
+
+| Module | Responsibility |
+|---|---|
+| `config/paths.js` | Per-OS config dir. Pure — platform, env, and home are injected, so Windows and Linux behaviour is asserted from any machine. |
+| `config/store.js` | Atomic `0600` JSON read/write, traversal-safe filenames. |
+| `auth/credentials.js` | BYO credential resolution and validation. Rejects service accounts and malformed client IDs before they cost a browser round trip. |
+| `auth/oauth.js` | PKCE pair, CSRF state, loopback callback server, auth URL builder, scope list. |
+| `auth/tokens.js` | Multi-account token store keyed by channel; legacy import. |
+| `auth/session.js` | Ties the above together: `login`, `logout`, `getAuthenticatedClient` with refresh persistence. |
+| `api/client.js` | Builds the three API surfaces plus an authenticated CSV downloader; wraps calls in error mapping. |
+| `api/transforms.js` | Pure shaping: duration parsing, content classification, CSV, date normalization, row zipping. |
+| `api/data.js` | Data API v3 fetchers — channel, video ids, video resources. |
+| `api/analytics.js` | Analytics API v2 fetchers, with the undocumented limits encoded as constants. |
+| `api/reporting.js` | Reporting API v1 job lifecycle and reach download. |
+| `fetch-all.js` | Orchestrates every dataset into one document, degrading per step. |
+| `dates.js` | Reporting window resolution and validation. |
+| `output.js` | The envelope and the stdout/stderr split. |
+| `diagnostics.js` | The failure catalog and exit-code derivation. |
+| `errors.js` | `YtStatsError`, Google error classification, secret redaction. |
+| `cli.js` | Commander wiring, validation-before-auth ordering, Commander error capture. |
+
+## Request flow
+
+A data command travels the same path every time:
+
+1. **`bin/ytstats.js`** calls `main(process.argv)`, with a final `catch` that guarantees no stack trace ever reaches stdout.
+2. **`main()`** builds the program and calls `parseAsync`. Commander errors are thrown rather than exited (`exitOverride()`) and converted by `diagnoseCommanderError()`.
+3. **The `run()` wrapper** executes the command's `validate` callback first, collecting *every* input problem into one envelope before any network call. See [validation ordering](gotchas/cli-output.md#input-is-validated-before-authentication).
+4. **`withApis()`** calls `getAuthenticatedClient()` — which resolves credentials, loads the stored account, and registers a `tokens` listener so refreshed tokens are written back — then `createApis()` bundles the three API surfaces.
+5. **The command body** calls one or more fetchers, passing the `apis` bundle as the first argument.
+6. **`reporter.succeed()` / `reporter.fail()`** renders the single JSON envelope to stdout and returns the exit code.
+
+Progress messages go to stderr throughout via `reporter.progress()` and are safe to discard.
+
+## fetch-all orchestration
+
+`fetchAll()` is the one place that runs every dataset in a single pass. Three properties matter:
+
+**Channel identity is the only hard requirement.** It is fetched outside `step()`, and a missing channel throws `NO_YOUTUBE_CHANNEL` — everything downstream keys off `channel.uploadsPlaylistId`.
+
+**Individual steps degrade rather than abort.** Each dataset runs inside `step(name, fn, fallback)`, which catches, records `{ step, code, message }` in `warnings`, and returns the fallback. YouTube rejects certain metric/dimension combinations for certain channels, and losing demographics should not cost you the other twelve datasets.
+
+**Auth and quota failures are fatal anyway.** `FATAL_CODES` — `NOT_AUTHENTICATED`, `MISSING_CREDENTIALS`, `INVALID_CREDENTIALS`, `NO_YOUTUBE_CHANNEL`, `QUOTA_EXCEEDED` — rethrow instead of degrading, because continuing past them yields a document that is empty for reasons the caller cannot act on step by step.
+
+Independent steps run concurrently in two `Promise.all` batches (daily + cards, then the eight analytics datasets). Traffic-source details are then fetched only for the source types the channel actually has, and retention runs sequentially because it costs one API call per video.
+
+The return value is `{ period, warnings, notes, data }`. `notes` carries non-diagnostic information such as "retention fetched for 50 of 120 videos".
+
+## Programmatic API
+
+`src/index.js` re-exports the module surface so a Node caller can skip the process spawn and the JSON round-trip:
+
+```js
+import { getAuthenticatedClient, createApis, fetchAll, resolveDateRange } from 'ytstats';
+
+const { client } = getAuthenticatedClient();
+const result = await fetchAll(createApis(client), { range: resolveDateRange({ days: 90 }) });
+```
+
+The exported surface, grouped:
+
+| Group | Exports |
+|---|---|
+| Session | `getAuthenticatedClient`, `login`, `logout` |
+| Credentials | `resolveCredentials`, `saveCredentials`, `clearCredentials`, `loadStoredCredentials`, `discoverClientSecretFile`, `parseClientSecret` |
+| Accounts | `loadAccount`, `listAccounts`, `saveAccount`, `removeAccount`, `setDefaultAccount`, `clearAllAccounts`, `migrateLegacyTokens` |
+| APIs | `createApis`, `data`, `analytics`, `reporting` (namespace exports), plus everything in `api/transforms.js` |
+| Orchestration | `fetchAll` |
+| Dates | `resolveDateRange`, `daysBetween`, `toIsoDate` |
+| Output | `renderEnvelope`, `createReporter` |
+| Errors | `YtStatsError`, `ERROR_CODES`, `EXIT_CODES`, `mapGoogleError`, `diagnoseGoogleError`, `fail`, `redact` |
+| Diagnostics | `DIAGNOSTICS`, `diagnose`, `isDiagnostic`, `SEVERITY`, `EXIT` |
+| CLI | `buildProgram`, `main`, `SCOPES`, `configDir` |
+
+Library callers get no envelope: `fetchAll` returns its result object directly and fetchers throw `YtStatsError`. Use `renderEnvelope()` if you want the CLI's output shape.
+
+## Two error vocabularies
+
+`ytstats` carries two code sets, and the distinction matters when reading the source:
+
+- **`DIAGNOSTICS` codes** (`src/diagnostics.js`) — the fine-grained public catalog surfaced in the envelope: `AUTH_TOKEN_EXPIRED`, `API_QUOTA_EXCEEDED`, `INPUT_INVALID_DATE`, and so on. This is what consumers branch on.
+- **`ERROR_CODES`** (`src/errors.js`) — the coarser internal vocabulary carried on `YtStatsError.code`: `NOT_AUTHENTICATED`, `QUOTA_EXCEEDED`, `INVALID_INPUT`. Used for control flow such as `FATAL_CODES` in `fetch-all.js`.
+
+`legacyCodeFor()` bridges the first onto the second when `mapGoogleError()` builds an error. Both are documented in [output-contract.md](output-contract.md).

package/docs/auth.md

@@ -0,0 +1,186 @@
+---
+description: The bring-your-own-credentials OAuth model — credential resolution, the PKCE loopback flow, token storage, and multi-account handling.
+tags: [auth, oauth, pkce, credentials, tokens, security]
+source:
+  - src/auth/**
+---
+
+# Authentication
+
+`ytstats` has **no built-in Google client ID**. Each user supplies their own Google Cloud OAuth client, and the CLI uses it. This document covers how that works internally; for the traps, see [gotchas/auth.md](gotchas/auth.md).
+
+## Why bring your own credentials
+
+Three consequences follow from having no shared client:
+
+- **Quota is per-project.** The YouTube Data API grants every Google Cloud project 10,000 units/day. A shared client ID would make every user compete for one pool.
+- **No verification bottleneck.** Apps requesting YouTube scopes need Google's OAuth verification to serve strangers. You are not a stranger to yourself, so the unverified-app warning is a one-time click rather than a blocker.
+- **Nothing to trust.** There is no backend to send data to, because there is no backend.
+
+The cost is roughly five minutes of one-time Google Cloud setup, walked through in the [README](../README.md#getting-started) and reproduced in the `SETUP_GUIDE` constant (`src/errors.js`) that ships inside diagnostics.
+
+## Scopes
+
+Three, all read-only, frozen in `src/auth/oauth.js`:
+
+```js
+export const SCOPES = Object.freeze([
+  'https://www.googleapis.com/auth/youtube.readonly',
+  'https://www.googleapis.com/auth/yt-analytics.readonly',
+  'https://www.googleapis.com/auth/yt-analytics-monetary.readonly',
+]);
+```
+
+There is no code path that writes to a channel.
+
+## Credential resolution
+
+`resolveCredentials()` returns `{ clientId, clientSecret, source }`, checking four sources in order and taking the first that yields a complete pair:
+
+| Order | Source | `source` value |
+|---|---|---|
+| 1 | `--client-secret <file>` | the path given |
+| 2 | `YTSTATS_CLIENT_ID` **and** `YTSTATS_CLIENT_SECRET` (both required) | `environment` |
+| 3 | `credentials.json` saved by a previous `ytstats login` | `stored` |
+| 4 | `client_secret*.json` auto-discovered in the working directory | the discovered path |
+
+If none match, it throws `AUTH_NO_CREDENTIALS` with a `detail` naming everything it searched.
+
+`source` is for display only and never contains the secret — it is what `ytstats status` reports as `credentialSource` and what `login` prints to stderr.
+
+### File shapes accepted
+
+`parseClientSecret()` normalises the shapes Google hands out. It reads `raw.installed` (Desktop app), `raw.web`, or an already-flat object, and accepts both `client_id`/`client_secret` and `clientId`/`clientSecret` casings.
+
+It rejects two things outright:
+
+- `type: 'service_account'` → `AUTH_SERVICE_ACCOUNT`, marked `recoverable: false`. Service accounts can never work with YouTube APIs; see [the gotcha](gotchas/auth.md#service-accounts-can-never-be-used).
+- A missing `client_id` or `client_secret` → `AUTH_CREDENTIALS_MALFORMED`.
+
+### Auto-discovery
+
+`discoverClientSecretFile(dir)` scans a directory for files starting with `client_secret` and ending in `.json` — the shape of Google's downloads, `client_secret_<numbers>-<hash>.apps.googleusercontent.com.json`. An exact `client_secret.json` wins; otherwise candidates are sorted for determinism so the same directory always yields the same file.
+
+### Client ID pre-flight validation
+
+`validateClientId()` runs before a browser is ever opened, because Google does not reject a bad client ID through the API — it renders "Access blocked" in the browser and never redirects, so the CLI would hang until its timeout.
+
+Two tiers:
+
+- Does not end in `.apps.googleusercontent.com` → **throws** `AUTH_CLIENT_ID_INVALID`.
+- Right suffix, but not the canonical `<project-number>-<hash>` shape → **returns a warning diagnostic**, `AUTH_CLIENT_ID_SUSPICIOUS`, and the flow proceeds. Legacy clients occasionally deviate, and being wrong here must not lock anyone out.
+
+`login` surfaces the warning in the envelope as well as on stderr, since it is the leading cause of a subsequent timeout.
+
+## The login flow
+
+`login()` in `src/auth/session.js` runs the loopback flow Google recommends for desktop apps:
+
+1. **Resolve and validate credentials** — as above, before anything else happens.
+2. **Generate a PKCE pair (S256) and an unguessable `state`.** The verifier is 64 random bytes base64url-encoded (86 characters, within RFC 7636's 43-128 range — the `slice(0, 128)` is a ceiling that never triggers at this size); the challenge is its base64url SHA-256 digest, 43 characters. The state is 24 random bytes, 32 characters. PKCE protects the authorization code against interception by another local process racing on the loopback port.
+3. **Bind an HTTP server to `127.0.0.1` on an ephemeral port** — `server.listen(0, '127.0.0.1')`, never `0.0.0.0`.
+4. **Open the browser** at Google's authorization endpoint with `access_type=offline&prompt=consent` (what makes Google return a refresh token) and `include_granted_scopes=true`.
+5. **Capture the callback.** The handler 404s `/favicon.ico` and any path other than `/` or `/callback`, then compares the returned `state` in constant time via `crypto.timingSafeEqual`. A mismatch, a Google `error` parameter, or a missing code each rejects with its own diagnostic.
+6. **Exchange the code** with the PKCE verifier and the same `redirect_uri` used in the authorization request.
+7. **Fetch the channel identity** via `channels.list({ part: 'snippet,contentDetails', mine: true })` — *before* persisting, so a failed lookup cannot leave a half-written account behind.
+8. **Persist** the credentials and the account.
+
+The success page served to the browser contains no token material and never echoes the authorization code. A test asserts this.
+
+### Timeout
+
+The loopback server takes a `timeoutMs` (default 300 seconds, set via `login --timeout`). On expiry it rejects with `AUTH_TIMEOUT`, which is marked `retryable: false` — the usual cause is Google refusing the request in the browser and never redirecting at all, which a plain retry cannot fix.
+
+### The --no-browser flow
+
+`pasteFlow()` starts **no** listener. It sets `redirectUri` to `http://127.0.0.1:1` so the browser's redirect fails immediately and visibly, leaving the full URL — including `?code=…` — in the address bar. The user pastes it back, and `extractCode()` pulls the `code` parameter out (or accepts a bare code if that is what was pasted).
+
+The same dead `redirect_uri` must be sent to the token exchange, because Google validates that it matches the authorization request.
+
+## Token storage
+
+Tokens live in `tokens.json` inside the per-user config directory (see [configuration.md](configuration.md)):
+
+```jsonc
+{
+  "version": 1,
+  "default": "UC...",
+  "accounts": {
+    "UC...": {
+      "channelId": "UC...",
+      "channelTitle": "…",
+      "customUrl": "@…",
+      "tokens": { "access_token": "…", "refresh_token": "…", "expiry_date": 0 },
+      "savedAt": "2026-07-27T10:00:00.000Z"
+    }
+  }
+}
+```
+
+Keyed by channel, so one machine can hold several. The first account logged in wins `default`; `ytstats use` changes it.
+
+**Saving merges rather than replaces.** A refresh response from Google contains a new `access_token` but no `refresh_token`, so `saveAccount()` spreads the existing tokens under the new ones. Overwriting would destroy the long-lived credential.
+
+### Refresh persistence
+
+`getAuthenticatedClient()` registers a `tokens` listener on the OAuth2 client:
+
+```js
+client.on('tokens', tokens => {
+  try { saveAccount({ …account, tokens }); } catch { /* read-only dir must not break the command */ }
+});
+```
+
+Any token the googleapis client rotates during the process lifetime is written back to disk. The error is swallowed deliberately: if the config directory has become unwritable, the in-memory access token is still valid and the command can complete.
+
+The client secret is required on every refresh, not only the initial exchange — which is why `saveCredentials()` runs at login and `getAuthenticatedClient()` resolves credentials before loading tokens.
+
+### Account selection
+
+`loadAccount(selector)` resolves in this order:
+
+1. No selector → the `default` account, or `null` if none.
+2. Exact match on the `accounts` key (the channel id).
+3. Case-insensitive match against `customUrl` or `channelTitle`.
+
+An unrecognised selector returns `null` — never a silent fallback to the default, which would answer a question about one channel with another channel's data. The caller turns that into `AUTH_ACCOUNT_UNKNOWN`, listing the channels that are available.
+
+`listAccounts()` returns summaries without token material, safe to print.
+
+## Failure diagnosis order
+
+`getAuthenticatedClient()` resolves credentials **before** loading tokens. There is no single "not authenticated" bucket, because each cause needs a different fix:
+
+| Situation | Diagnostic |
+|---|---|
+| No OAuth client anywhere | `AUTH_NO_CREDENTIALS` |
+| Client exists, never logged in | `AUTH_NO_TOKENS` |
+| `--account` names an unknown channel | `AUTH_ACCOUNT_UNKNOWN` |
+| Refresh token rejected (`invalid_grant`) | `AUTH_TOKEN_EXPIRED` |
+| Access explicitly revoked | `AUTH_TOKEN_REVOKED` |
+| Consent screen dismissed | `AUTH_CONSENT_DECLINED` |
+| Callback never arrived | `AUTH_TIMEOUT` |
+| State check failed | `AUTH_STATE_MISMATCH` |
+| Service account key supplied | `AUTH_SERVICE_ACCOUNT` |
+| Client ID malformed | `AUTH_CLIENT_ID_INVALID` |
+| Google account owns no channel | `AUTH_NO_CHANNEL` |
+
+Telling someone who has not yet created a Google Cloud project to "run login" sends them down a path that cannot succeed — hence the ordering. Full catalog in [output-contract.md](output-contract.md#diagnostic-catalog).
+
+## Logout
+
+`logout()` revokes with Google and forgets locally:
+
+1. Collect the target accounts — all of them with `--all`, otherwise the selected or default one.
+2. Resolve credentials if possible. Without them revocation is impossible, but local removal still proceeds.
+3. For each account, call `client.revokeToken()` on the refresh token (falling back to the access token), wrapped in `try`/`catch`.
+4. Remove the account locally regardless of whether revocation succeeded.
+5. With `--forget-credentials`, delete `credentials.json` too.
+
+Returns `{ loggedOut, revoked, accounts }`. `revoked` is false when the machine was offline or the token was already invalid — the local state is still clean.
+
+## Legacy import
+
+`migrateLegacyTokens()` performs a one-time import of a pre-`ytstats` per-project token file. It never overwrites an existing account, returning `{ migrated: false, reason }` for `no-legacy-file`, `no-refresh-token`, `unknown-channel`, or `already-logged-in`.
+
+Because the legacy file carries no channel identity, `import-legacy` in `src/cli.js` exchanges the tokens for one via `channels.list` before calling it.