Documentation
¶
Overview ¶
Package catalog is the HTTP surface for the platform product catalog — the CMS source-of-truth for a brand's OWN products (Models, Vector, KMS, …) that docs.<brand>, the console sidebar, and pricing derive from.
Two audiences, two auth models:
- PUBLIC read: GET /catalog returns the brand-scoped projection with no auth (it is public presentation + pricing data). Wired on the commerce public group so it serves the exact path GET /v1/commerce/catalog.
- PLATFORM-ADMIN write: create/update/delete/seed mutate the platform-global catalog (the "system" namespace, NOT a per-tenant org), so they gate on auth.IAMClaims.IsSuperAdmin() — a Hanzo platform admin, never an org-level admin. Wired on the /v1 bundle under /catalog/entries.
The catalog is platform-global: one store in the "system" namespace, scoped per requesting brand BY CATEGORY at projection time (matching @hanzo/products catalogForBrand). Entries are keyed by their globally-unique slug.
Index ¶
- func AdminCatalog(c *zip.Ctx) error
- func AdminCatalogRoute(r zip.Router)
- func AdminRoute(r zip.Router, args ...zip.Handler)
- func CreateEntry(c *zip.Ctx) error
- func DeleteEntry(c *zip.Ctx) error
- func ListEntries(c *zip.Ctx) error
- func Public(c *zip.Ctx) error
- func PublicRoute(r zip.Router)
- func RefreshModels(c *zip.Ctx) error
- func SeedCatalog(c *zip.Ctx) error
- func SyncModels(c *zip.Ctx) error
- func UpdateEntry(c *zip.Ctx) error
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AdminCatalog ¶ added in v1.49.7
AdminCatalog returns the brand-scoped catalog projection WITH the administrative economics (costCents + marginPct) the public projection withholds — the margin surface admin.hanzo.ai administrates. owner=="admin" only (IsSuperAdmin); an org-level admin is refused 403, so upstream cost and margin never leak to a tenant. Brand from ?brand (default hanzo).
func AdminCatalogRoute ¶ added in v1.49.7
AdminCatalogRoute wires the owner=="admin" margin projection. Mount on an IAM-gated commerce group so it serves GET /v1/commerce/admin/catalog; the handler ALSO enforces IsSuperAdmin() (defense in depth).
func AdminRoute ¶
AdminRoute wires the platform-admin catalog CRUD + seed on the /v1 bundle.
func CreateEntry ¶
CreateEntry adds a catalog entry (platform admin).
func DeleteEntry ¶
DeleteEntry removes a catalog entry by slug (platform admin).
func ListEntries ¶
ListEntries returns the raw catalog entries (admin view — includes unpublished). Optional ?brand filter.
func Public ¶
Public returns the brand-scoped catalog projection. Public + cacheable. Brand from ?brand (default hanzo).
func PublicRoute ¶
PublicRoute wires the public, unauthenticated catalog projection. Mount on the commerce public group so it serves GET /v1/commerce/catalog.
func RefreshModels ¶ added in v1.49.26
RefreshModels PULLS the upstream catalog and lands it. POST /catalog/models is the PUSH of already-decided rows; this is the same landing, for an upstream that has to be read rather than told. Both funnel through catalogentry.UpsertModels, so the rule that a sync owns cost and admin owns price is enforced in one place regardless of which door a row came through.
Scheduling is a cron entry poking this with the service token, the same shape billing-autorecharge uses, so there is one way to run a periodic job. That is why the gate is requirePlatform and not requireSuperAdmin: the service token is a platform principal but carries no SuperAdmin claim, so under the narrower gate every scheduled run 403'd and the model catalog was never populated at all.
It is deliberately NOT run at boot: a boot-time call to a third party is a boot hazard, and the catalog that is already stored is the one to serve until a scheduled run says otherwise.
func SeedCatalog ¶
SeedCatalog upserts the embedded Hanzo catalog seed (idempotent, non-destructive — never overwrites CMS edits). Platform admin only.
func SyncModels ¶ added in v1.49.25
SyncModels lands a syncer's view of the model catalog: it refreshes each model's upstream COST and machine-observable facts and touches nothing a human owns — not the retail price, not the markup, not the entitlement tier (catalogentry.UpsertModels enforces that, so the rule holds no matter which syncer calls). This is the ONE write seam between the model families / upstream and the catalog: they own the structure and publish it, commerce holds the numbers, admin.hanzo.ai edits them.
Platform principal, like its sibling RefreshModels — the two sync doors land through the same UpsertModels, so gating them differently would only decide which syncer has to be a human.
func UpdateEntry ¶
UpdateEntry edits a catalog entry by slug (platform admin). The slug identity is preserved; other fields are replaced from the body.
Types ¶
This section is empty.
Source Files