{
"id": "pet.trezy.getDefinitions",
"defs": {
"main": {
"type": "query",
"output": {
"schema": {
"type": "object",
"required": [],
"properties": {
"error": {
"type": "string",
"description": "Present instead of the catalogue when there is no catalogue to send. A stable machine code the client branches on — add codes, never rename them. `definitions-unavailable` means the read failed and the answer is unknown; `definitions-empty` means the read succeeded and there is genuinely nothing published. They are different operator problems — a broken index versus an unpublished catalogue — and they were once the same 200 with two empty arrays, which rendered an empty shop that looked like the game rather than like a fault.",
"knownValues": [
"definitions-unavailable",
"definitions-empty"
]
},
"tiers": {
"type": "array",
"items": {
"ref": "#definition",
"type": "ref"
},
"description": "Tier definitions, shaped as com.atproto.repo.listRecords returns them so the client parse is the same either way."
},
"groups": {
"type": "array",
"items": {
"ref": "#definition",
"type": "ref"
},
"description": "Group definitions, shaped like the others. ⚠ ABSENT OR EMPTY IS NOT A FAULT, unlike an empty `species` or `tiers`. A species without its groups is still priceable, buyable and drawable — it is only unlabelled — so the Lua sends an empty list rather than refusing the catalogue, and a client must render the pets it has with no group chips instead of treating this as an outage."
},
"message": {
"type": "string",
"description": "A sentence to show the player, accompanying `error`."
},
"species": {
"type": "array",
"items": {
"ref": "#definition",
"type": "ref"
}
},
"activePetCap": {
"type": "integer",
"minimum": 0,
"description": "How many pets may be on the stage at once, from pet.trezy.gameConfig. A DISPLAY hint: the corral draws this many slots so a player can see the room they have, rather than discovering the ceiling by being refused. swapPets remains the only authority on whether a pet may actually come on. ABSENT when the config could not be read — a client must then draw the pets it has and no empty slots, never substitute a number of its own, because a compiled-in cap is exactly the drift that put four copies of the decay curve in this directory."
},
"starterGrantCap": {
"type": "integer",
"description": "The most createPet will grant a player for their very first pet, from pet.trezy.gameConfig/self. Onboarding offers a choice of starters and every one of them must be a pet the grant actually covers, so the number that decides that has to come from the same record the server enforces it from — a client-side copy would offer pets nobody can buy the moment it is repriced. Absent when the config record could not be read, which a client must treat as 'unknown' and NOT as zero: zero would empty the starter choice, and an instance that cannot read its config also cannot sell anything, so the honest reading is that the catalogue is unusable rather than that everything is too dear."
}
}
},
"encoding": "application/json"
},
"description": "Every species and tier definition the game will actually price from. Reads the INDEX, not the publisher's PDS, and filters to the publisher DID. The store must price from the same rows createPet charges from: definitions can be published and not yet indexed, and reading the PDS in that state renders a full catalogue at correct prices where every purchase refuses. Returns both collections in one answer so a species can never be shown without its tier."
},
"definition": {
"type": "object",
"required": [
"uri",
"value"
],
"properties": {
"uri": {
"type": "string",
"format": "at-uri"
},
"value": {
"type": "unknown",
"description": "The record body verbatim. Unknown rather than typed: the client already parses this shape, and a schema here would have to be kept in step with pet.trezy.species and pet.trezy.tier for no gain."
}
}
}
},
"$type": "com.atproto.lexicon.schema",
"lexicon": 1
}