[bruel-gabrielsson]

Ranks several catalogs together, on unbox-api's new x-catalog-ids (unbox-api#594).

complete, sections and similar_items, sync and async, take catalog_ids=[...] in place of catalog_id. The first catalog is the request's own.

items = client.complete(history, catalog_ids=["shop", "outlet"])
for item in items:
    print(item.catalog_id, item.id)

• Item.catalog_id is always filled: the catalog the item comes from, also with a single catalog.
• Events name their catalog: View("a0", catalog_id="outlet"), CartItem("a0", 1, catalog_id="outlet"). They also accept an Item, which brings its catalog along, so a result can go straight back into a history. An event without one is in the first catalog.
• An order whose items span catalogs is sent as one order per catalog.
• similar_items(item, catalog_id=..., catalog_ids=[...]) finds products like one catalog's item across all of them. similar_items also takes filters now.
• A catalog_id filter picks one catalog's products.
• CartItem is exported at the top level, so an order line can name its catalog.
• UNBOXAI_CATALOG_ID sets the default catalog, so calls need no catalog_id. An explicit default_catalog_id= still wins, and without either it stays retail_catalog.

Passing both catalog_id and catalog_ids (except for similar_items), an empty list, or a plain string is a ValueError that says what to pass instead.

The README and docs/catalogs.md ("Several catalogs at once") document it. Tests: tests/test_multi_catalog.py, 14 tests; 188 passed in all. Ruff is clean and mypy is at its baseline.

Insights needs this released (behaviorgpt-insights-app#1); the version is not bumped here.