# Runbook: Google Data Portability YouTube Activity Probe

## Purpose

Test whether Google Data Portability can export `myactivity.youtube` records for the YouTube-to-Obsidian pipeline.

This is a probe only. It should write to server-side/project staging, not Obsidian.

## Required Google Cloud setup

The user must create/provide an OAuth client secret JSON.

Suggested setup:

1. Go to Google Cloud Console.
2. Create or select a project.
3. Enable **Data Portability API**.
4. Configure OAuth consent screen.
5. Add the user's Google account as a test user if the app is in testing mode.
6. Create OAuth client credentials.
   - Try **Desktop app** first.
   - Download the `client_secret_....json` file.
7. Keep this file secret. Do not commit it to git.

Required scope/resource:

```text
scope: https://www.googleapis.com/auth/dataportability.myactivity.youtube
resource: myactivity.youtube
```

Note: this scope is classified as **Restricted**. Testing-mode behavior must be verified.

## Local probe commands

From this repository:

```sh
chmod +x scripts/google_data_portability_probe.py
```

Authorize:

```sh
python3 scripts/google_data_portability_probe.py auth \
  --client-secret /path/to/client_secret.json \
  --token /secure/path/google-dp-token.json
```

Check access type:

```sh
python3 scripts/google_data_portability_probe.py check-access \
  --client-secret /path/to/client_secret.json \
  --token /secure/path/google-dp-token.json
```

Initiate a one-day export:

```sh
python3 scripts/google_data_portability_probe.py initiate \
  --client-secret /path/to/client_secret.json \
  --token /secure/path/google-dp-token.json \
  --start 2026-05-15T00:00:00Z \
  --end 2026-05-16T00:00:00Z \
  --state /secure/path/google-dp-job-state.json
```

Poll and download when complete:

```sh
python3 scripts/google_data_portability_probe.py poll \
  --client-secret /path/to/client_secret.json \
  --token /secure/path/google-dp-token.json \
  --state /secure/path/google-dp-job-state.json \
  --download-dir /secure/path/downloads
```

## Server-side target paths later

If probe works, deploy under:

```text
/opt/youtube-activity-import/
/etc/youtube-activity-import/
/var/lib/youtube-activity-import/
  archives/
  extracted/
  normalized/
  state/
  logs/
```

## Security rules

- Never commit `client_secret.json`, OAuth tokens, or downloaded activity archives.
- Store tokens on the server with restrictive permissions.
- Treat YouTube activity data as private personal data.
- Do not write imported raw archives to Obsidian.

## Success criteria

The probe is successful if:

- OAuth consent succeeds for `dataportability.myactivity.youtube`.
- An archive job can be initiated for a small date range.
- The archive completes and downloads.
- Extracted data contains useful YouTube My Activity records with timestamps and URLs/titles.