pet.trezy.claimAwards

{
  "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."
            }
          }
        },
        "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"
          ]
        },
        "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."
        }
      }
    }
  },
  "$type": "com.atproto.lexicon.schema",
  "lexicon": 1
}