Module commerce 

In-world commerce — the “buy” side of the Thread.

A world’s buy behavior returns Action::CommerceBuy; the browser performs it here. The flow is deliberately server-authoritative (Theme B): the client sends only { worldId, itemStructuredId, priceRef } to POST <base>/thread/purchase with the traveler’s Passport as the bearer — the server resolves the price from its own catalog (client-set prices are dead on arrival), records the charge idempotently, and returns a grant.

Entitlements — “what does this traveler already hold?” — come from GET <base>/entitlements/:projectId with the same bearer.

All network runs on background threads and lands via CommerceClient::poll once per frame; failures degrade to a message, never a stall (super-stable tenet). The base URL comes from INFINITE_COMMERCE_BASE (default https://api.pixygon.io/v1 — same origin as the Codex).

Structs

Charge

CommerceClient

The browser’s commerce client — one purchase in flight at a time (buying is a deliberate act, not a queue), plus an independent entitlements read.

Entitlement

What the traveler already holds against a project, shaped to GET /entitlements/:projectId (tolerant to extras).

Grant

Offer

What’s on the counter — everything the purchase confirm dialog shows and everything the wire call needs. Built from the behavior’s commerce.buy action plus the placement’s data block via offer_from.

Receipt

The settled purchase, shaped to POST /thread/purchase (tolerant to extras).

Functions

offer_from

Build an Offer from a commerce.buy action + the focused placement’s data block. price_ref resolution order: the action’s value (string, or an object’s priceRef/productKey/key) → data.priceRef → the item id.