# Marketplace requests, version 1

Sources: `proto/pharos/marketplace/v1/requests.proto` (the envelope),
`commands.proto` (the command inputs), `queries.proto` (the query inputs) and
`replies.proto` (the query results). Commands answer with the shared `Outcome`.
Run `pnpm generate:contracts` after edits. Generated Go bindings live in Beto's
outer contract package, Marketplace's messaging adaptor and the API's messaging
adaptor.

`PlaceOrder` places one Order for a Project. It carries `project_id` and `pack_id`,
both required. The Order ID is the command's target. The buyer is the command's
actor, which the API sets from the session, and the price comes from the
catalogue, so neither is in the payload. The
[Marketplace README](../../../services/beto/contexts/marketplace/README.md) lists
its refusals.

`ListProjectOrders` lists one Project's Orders for one of its buyers. It carries
`project_id` (required), `after_order_id` and `page_size` (default 50, at most
100). The caller is the request's verified actor. The reply's `ProjectOrderPage`
holds each Order as it is stored now, ordered by Order ID, with its version as
`revision`; `next_after_order_id` is set when another page follows. The provider
plan reference is not part of it. A refusal answers with a `RequestError` code.

The envelope follows the new-owner numbering: the request's `command = 10` and
`query = 11`, the command's `place_order = 10`, the query's
`list_project_orders = 10`, and the reply's `outcome = 10`, `error = 11` and
`order_page = 12`.

The contract is declared in `contracts/beto/messaging/catalogue.json` with the API
as its consumer. `broker.json` declares the `query` and `command` requests with the
API as their only caller, allowed to carry the actor.