Products: carry the IMVU parent's image and categories

Revisions with an IMVU parent store its public info (image, category path, gender)
from IMVU's product API, looked up after registering and in a periodic pass.
Product views gain parent, image and categories; GET /products takes category and
limit. The website shows the image on cards and product pages.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

docs/api.md

@@ -49,6 +49,13 @@ is. Codes: `invalid`, `signed_out`, `forbidden`, `not_found`, `no_such_imvu_acco
 | `DELETE /api/v1/account/links/:imvu` | unlink |
 | `POST /api/v1/account/signout-computers` | signs T5DE out on all their computers |
 
+## Products, catalogs and libraries
+
+The routes and tokens are in docs/products.md. Products are `{id, name, description, rating, latest, creator,
+creatorUsername, parent, image, categories, createdAt, updatedAt}`; `parent`, `image` and `categories` come from the
+latest revision (its IMVU parent's public info). `GET /api/v1/products` takes `q`, `creator`, `category` (an IMVU
+category ID) and `limit` (1-200, default 60).
+
 ## Age verification
 
 Vendor-neutral (docs/design.md, "Age"): IMVU's answer is recorded when an account is linked or checked again;

docs/products.md

@@ -59,7 +59,7 @@ registering on the hub), `WEB_ORIGIN` (the hub website, for CORS).
 | `POST /api/v1/catalogs` | register a catalog: `{name, url, contact, visibility ("public"/"private"), membership ("open"/"approval"/"invite")}` → 201 `{catalog, key}` (the key is shown once) |
 | `GET /api/v1/catalogs` | (anyone) approved public catalogs; the person's own, any status |
 | `POST /api/v1/products/upload` | `{catalog, product?}` → `{token, url}`: an upload token and the catalog's upload URL |
-| `GET /api/v1/products?q=&creator=` | (anyone) products, newest first; adult ones only for people with an adult account |
+| `GET /api/v1/products?q=&creator=&category=&limit=` | (anyone) `{products}`, newest first; adult ones only for people with an adult account. `category`: an IMVU category ID; only products whose latest revision's parent has it anywhere in its category path (e.g. 106 Clothing, 128 Tops). `limit`: 1-200, default 60 |
 | `GET /api/v1/products/:id` | (anyone, adult rule as above) `{product, revisions, inLibrary?, mine?}` |
 | `PATCH /api/v1/products/:id` | (creator) `{name?, description?, rating?}`; description is HTML, cleaned by the allowlist; rating may go general → adult |
 | `POST /api/v1/products/:id/revisions/:n/retract` | (creator) |
@@ -72,6 +72,20 @@ registering on the hub), `WEB_ORIGIN` (the hub website, for CORS).
 
 The realtime connection also tells the proxy `{"type": "library"}` when the person's library changes.
 
+A product (in lists, its page, the library) is `{id, name, description, rating, latest, creator, creatorUsername,
+parent, image, categories, createdAt, updatedAt}`. `parent`, `image` and `categories` are the latest revision's:
+`parent` is the IMVU product it derives from (0 if none); `image` (an https address on `*.imvu.com`, or null) and
+`categories` (`[{id, name}]`, outermost first, e.g. Clothing / Clothing for Female / Tops / Coats & Jackets; `[]` if
+unknown) are that IMVU product's, from IMVU's public API (`GET https://api.imvu.com/product/product-<id>`).
+
+### Parent info
+
+The hub looks up a revision's parent when the revision is registered (after it's stored; an upload never waits for or
+fails on it) and stores it with the revision (`product_revision.parent_info`: `{found, image, categories, gender,
+checkedAt}`; `found` is false when IMVU shows no such product publicly). Info another revision got for the same
+parent in the last 7 days is reused. Revisions still without it (IMVU was unavailable) are looked up at startup and
+every 10 minutes, 20 at a time.
+
 ### Console (moderators)
 
 `GET /api/v1/console/catalogs`, `POST /api/v1/console/catalogs/:id/approve`, `.../reject`.