{
"id": "pet.trezy.claimAwards",
"defs": {
"main": {
"type": "procedure",
"output": {
"schema": {
"type": "object",
"required": [
"awards"
],
"properties": {
"error": {
"type": "string",
"description": "Present instead of a result. `awards-unavailable` means the ledger could not be read, which must NOT be shown as an empty shelf — a caller that took it that way would tell somebody they had earned nothing.",
"knownValues": [
"awards-unavailable",
"no-caller"
]
},
"awards": {
"type": "array",
"items": {
"ref": "#award",
"type": "ref"
},
"description": "Every badge the caller has earned, oldest first. Present whether or not the repo copy could be written — the ledger is the truth and the record is a publication of it."
},
"message": {
"type": "string"
},
"written": {
"type": "integer",
"minimum": 0,
"description": "How many repo copies this call wrote. Zero is the ordinary answer on a return visit."
},
"progress": {
"type": "array",
"items": {
"ref": "#progress",
"type": "ref"
},
"description": "How far along the badges the caller has NOT earned are, one entry each. Earned ones carry the same two numbers on their own entry in `awards` instead, so nothing appears twice. ⚠ MEASURED BY `job.run:games.achievements` IN THE SAME PASS THAT DECIDES WHETHER A BADGE IS MET — earned is `current >= target` and nothing else — so a bar can never disagree with the badge beside it. Absent or empty when the job has not run for this caller yet, which a client must draw as a badge with no bar rather than as zero."
}
}
},
"encoding": "application/json"
},
"description": "Publishes the badges the awards ledger says the caller has earned into the caller's own repo, as `community.lexicon.badge.award` records, and answers with everything they hold. Called on sign-in and after anything that might have earned one. It decides nothing: `job.run:games.achievements` owns that, and this only copies what is already recorded — so calling it twice writes nothing the second time, and calling it can never award anything."
},
"award": {
"type": "object",
"required": [
"badge",
"earnedAt"
],
"properties": {
"badge": {
"type": "string",
"description": "The achievement's stable id — `first-pet`, `group-bats`. The same string is the `name` on the badge definition and the rkey of both the definition and the award."
},
"state": {
"type": "string",
"description": "Where the repo copy stands. `written` was published by this call, `held` was already published, `unpublished` could not be written — usually because the caller has not granted the collection, which costs them nothing but the portable copy.",
"knownValues": [
"written",
"held",
"unpublished"
]
},
"target": {
"type": "integer",
"minimum": 0,
"description": "See `current`. Absent on both when the job has not measured this badge."
},
"current": {
"type": "integer",
"minimum": 0,
"description": "Progress toward this badge, for a caller that wants to show a completed set as “6 of 6”. Same numbers as `#progress`, carried here so an earned badge is described in one place."
},
"earnedAt": {
"type": "string",
"format": "datetime",
"description": "The FIRST moment the ledger saw this as true, not the moment it was published. A badge is a record of a moment; re-running the evaluation never moves this."
}
}
},
"progress": {
"type": "object",
"required": [
"badge",
"current",
"target"
],
"properties": {
"badge": {
"type": "string",
"description": "The achievement's stable id."
},
"target": {
"type": "integer",
"minimum": 0,
"description": "What `current` has to reach. ⚠ ZERO MEANS UNMEASURABLE, NOT COMPLETE — a group whose members failed to load measures `0 of 0`, and a reader treating that as done would show every set finished the moment the catalogue hiccuped."
},
"current": {
"type": "integer",
"minimum": 0,
"description": "The real quantity, uncapped: coin badges routinely exceed their threshold, and a client that wants a bar clamps it rather than the server lying about the number."
}
}
}
},
"$type": "com.atproto.lexicon.schema",
"lexicon": 1
}