Bambuddy sync: match the real spools API

Checked against Greg's Bambuddy: the key goes in X-API-Key, colors are
color_name (often null on RFID spools) and rgba, grams left is
label_weight minus weight_used, and archived spools carry archived_at.
Unnamed spools get the nearest plain color name.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012aSbo2D1qP8cMFQCykf7kx

docs/content-service.md

@@ -148,7 +148,7 @@ being down never takes a page down. Code: [`services/content/src/sync/`](../serv
 | `covers` | 15 min | Library items with no `cover`: Open Library (books), TMDB (film, TV; needs `TMDB_API_KEY`), AniList (anime, manga, manhwa, light novels, webnovels; by `anilistId` when set) | `cover` |
 | `suwayomi` | hour | PersonalReader's manga and manhwa: Suwayomi's GraphQL library (category, furthest chapter read and when, AniList tracker id), matched to Library items by `anilistId`; AniList for covers | `chapterProgress` (`title`, `status`, `chapter`, `readAt`), `cover` (AniList); changes `state` (below) |
 | `kavita` | day | PersonalReader's light novels and books: Kavita's API, matched by `kavitaSeriesId`, or by `anilistId` against an anilist.co link in the series' metadata | `bookProgress` (`title`, `percent`, `readAt`); changes `state` (below) |
-| `bambuddy` | hour | Filament spools in stock (**unverified API**, below) | `filamentStock` on product lines with a Filament option |
+| `bambuddy` | hour | Filament spools in stock | `filamentStock` on product lines with a Filament option |
 | `homebox` | hour | Homebox items with the labels or locations in `HOMEBOX_LABELS` / `HOMEBOX_LOCATIONS` | `materialStock` on product lines with a Leather or Paper option |
 
 The covers job looks every 15 minutes, so a new Library item gets a cover
@@ -227,15 +227,15 @@ stock when the source does not have it; in-stock colors the note does not
 list are added after the note's own. With nothing synced, options show
 exactly as the note says (a missing `inStock` counts as in stock).
 
-- **Bambuddy: unverified.** Its API is not documented anywhere this project
-  has, and no request has been made to one. The endpoint is
-  `BAMBUDDY_SPOOLS_PATH` (default `/api/v1/inventory/spools`, a guess), and all
-  knowledge of the response is in `mapBambuddySpools` in
-  `sync/jobs/bambuddy.ts`: it accepts a list (or one under `items`, `spools`,
-  `data`, `results`) and reads color name, hex, material and grams left under
-  common spellings. Check it against Greg's Bambuddy and fix that one function
-  before relying on it. A color is in stock when some spool of it has at least
-  `BAMBUDDY_MIN_GRAMS` (default 50) left, or does not say.
+- **Bambuddy** reads `GET /api/v1/inventory/spools` (`BAMBUDDY_SPOOLS_PATH`)
+  with an API key made in Bambuddy's Settings, sent in the `X-API-Key` header.
+  Field names were checked against Greg's Bambuddy (2026-10-12) and are all in
+  `mapBambuddySpools` in `sync/jobs/bambuddy.ts`. Grams left is `label_weight`
+  minus `weight_used`; archived spools are skipped. A spool with no
+  `color_name` (RFID spools) is named by its nearest plain color (Black,
+  Blue...); setting a color name in Bambuddy overrides that. A color is in
+  stock when some spool of it has at least `BAMBUDDY_MIN_GRAMS` (default 50)
+  left.
 - **Homebox** logs in at `POST /api/v1/users/login`, looks up the label and
   location ids, and lists `GET /api/v1/items?labels=<id>` (or
   `locations=<id>`). Each `HOMEBOX_LABELS` / `HOMEBOX_LOCATIONS` entry is
@@ -250,8 +250,8 @@ exactly as the note says (a missing `inStock` counts as in stock).
 | `SUWAYOMI_AUTH` | `ui_login` (default with a user), `basic`, or `none`. |
 | `KAVITA_URL`, `KAVITA_API_KEY` | Enable `kavita`, like `http://kavita:5000`; the key of a Kavita user that can see the libraries. |
 | `BAMBUDDY_URL` | Enables `bambuddy`. |
-| `BAMBUDDY_SPOOLS_PATH` | Endpoint path (default `/api/v1/inventory/spools`, unverified). |
-| `BAMBUDDY_API_KEY`, `BAMBUDDY_AUTH_HEADER` | Sent as `Authorization: Bearer <key>`, or as the raw key in the named header. |
+| `BAMBUDDY_SPOOLS_PATH` | Endpoint path (default `/api/v1/inventory/spools`). |
+| `BAMBUDDY_API_KEY`, `BAMBUDDY_AUTH_HEADER` | The API key from Bambuddy's Settings, sent in `X-API-Key` (or in the named header). |
 | `BAMBUDDY_GROUP`, `BAMBUDDY_MATERIALS`, `BAMBUDDY_MIN_GRAMS` | Option group (Filament), materials to include (like `PLA,PETG`; all when empty), grams that count as in stock (50). |
 | `HOMEBOX_URL`, `HOMEBOX_USER`, `HOMEBOX_PASS` | Enable `homebox`, with a read-only Homebox user. |
 | `HOMEBOX_LABELS`, `HOMEBOX_LOCATIONS` | Which items count, `name` or `name=Group`, comma separated. Labels default to `leather,paper`. |