Treasury Commands & Integrations

Treasury Commands & Integrations

Concept Phase

Treasury commands should make reward state understandable. Players need a simple claim center; staff need precise grant, revoke, retry, and audit controls.

---

Player Commands

Command	Purpose
/treasury	Open the claim center.
/treasury claim [grantId]	Claim one reward or open claim UI.
/treasury history	View claimed, expired, revoked, and failed rewards.
/treasury inspect <grantId>	Show reward contents, source, expiry, and delivery state.
/treasury settings	Configure claim notifications if enabled.

---

Admin Commands

Command	Purpose	Risk
/treasury admin catalog reload	Reload safe catalog definitions.	Low
/treasury admin catalog preview <catalogId>	Show resolved bundle contents.	Low
/treasury admin grant <player> <catalogId> [source]	Create a manual grant.	Medium
/treasury admin revoke <grantId> <reason>	Revoke an unclaimed reward.	High
/treasury admin retry <grantId>	Retry failed delivery.	Medium
/treasury admin search <player|source|catalog>	Search grant and claim receipts.	Low
/treasury admin export <player>	Export a player’s reward history.	Medium

---

Permission Nodes

Node	Default	Purpose
treasury.use	true	Open claim center.
treasury.claim	true	Claim rewards.
treasury.history	true	View own reward history.
treasury.admin.catalog	op	Reload/preview catalogs.
treasury.admin.grant	op	Create manual grants.
treasury.admin.revoke	op	Revoke grants.
treasury.admin.audit	op	Search/export receipts.
treasury.admin.retry	op	Retry failed deliveries.

---

Web Claim Center

Claimable Rewards

Players see reward cards with contents, source, expiry, and claim button.

History

Claimed, expired, revoked, and failed rewards remain visible with receipts.

Staff Audit

Search by player, source mod, catalog entry, staff actor, status, and date range.

Catalog Browser

Preview reward bundles, versions, delivery adapters, and policy flags before publishing.

---

Discord Integration

• DM or linked-account notification when a valuable reward becomes claimable.
• Staff alert when a delivery adapter fails.
• Staff alert for high-risk grants/revokes.
• Event/season reward summary embeds triggered by Jubilee or Festival.
• Optional public announcements for major community milestone rewards.

---

Grant API Sketch

{
  "player": "uuid",
  "catalog_id": "festival:moonlit_market_attendee",
  "source": "festival:moonlit_market_2027_04_16:attendance",
  "metadata": {
    "minutes_attended": 84,
    "node": "survival-1"
  },
  "idempotency_key": "uuid:festival:moonlit_market_2027_04_16:attendance"
}

Treasury should return the existing grant if the idempotency key has already been processed.

---

Delivery Adapter Contract

Adapters receive resolved contents and return a receipt:

{
  "adapter": "courier",
  "grant_id": "grant_01HR...",
  "contents": [
    { "type": "item", "item": "minecraft:emerald", "count": 16 }
  ],
  "result": "delivered",
  "delivery_ref": "courier:mail_01HR..."
}

Courier can then manage inbox presentation and attachment pickup, while Treasury retains the claim receipt.

---

Config Shape

treasury {
  claims {
    requireExplicitClaim = true
    expireWarningsDays = [14, 3, 1]
  }

  delivery {
    preferred = "courier"
    fallback = "command"
    retryAttempts = 3
  }

  audit {
    requireReasons = true
    staffWebhook = "env:TREASURY_STAFF_WEBHOOK"
  }
}