feat: add OpenGachaCodes source and Wuthering Waves support

Wire in a self-hosted OpenGachaCodes instance as an optional third
code source, gated on the new `opengachaBaseUrl` config value (empty =
disabled, so existing deploys are unchanged).

- sources.go: add fetchOpengacha (typed client for /games/<slug>/codes;
  404 = no data, not a failure) and generalize fetchCodes to run every
  source that serves a game, skipping empty-slug sources and erroring
  only when all attempted ones fail.
- games.go: add an Opengacha slug per game; add `wuwa` (Wuthering
  Waves) as an OpenGachaCodes-only, non-HoYo game (in-game redemption).
- config.go: add opengachaBaseUrl; fail startup if a watched game has
  no reachable source (OpenGachaCodes-only with no base URL set).
- Docs: update AGENTS.md, README.md, config.example.yaml.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: exec-astraea

AGENTS.md

@@ -1,14 +1,19 @@
 # hoyo-codes — agent guide
 
-A small Go service that watches for new **HoYoverse redemption codes** (Genshin
-Impact, Honkai: Star Rail, Honkai Impact 3rd) and posts them to **Discord
-webhooks** on a cron schedule. Docker-first, no database, no framework.
+A small Go service that watches for new gacha **redemption codes** (Genshin
+Impact, Honkai: Star Rail, Zenless Zone Zero, Honkai Impact 3rd, and Wuthering
+Waves) and posts them to **Discord webhooks** on a cron schedule. Docker-first,
+no database, no framework.
 
-Codes are pulled from two community APIs and merged/de-duplicated, so a hiccup on
-one source doesn't cause a miss:
+Codes are pulled from up to three APIs and merged/de-duplicated, so a hiccup on
+one source doesn't cause a miss. A source is skipped for any game it doesn't
+serve (empty slug), and it only errors when *every* attempted source fails:
 
-- [ennead.cc](https://api.ennead.cc/mihoyo) — `/<game>/codes`
-- [torikushiii/hoyoverse-api](https://github.com/torikushiii/hoyoverse-api) — `hoyo-codes.seria.moe`
+- [ennead.cc](https://api.ennead.cc/mihoyo) — `/<game>/codes` (HoYoverse only)
+- [torikushiii/hoyoverse-api](https://github.com/torikushiii/hoyoverse-api) — `hoyo-codes.seria.moe` (HoYoverse only)
+- **OpenGachaCodes** — self-hosted read-only API (`opengachaBaseUrl` config).
+  Supplements the HoYo games it also serves and is the **sole** source for
+  non-HoYo games like Wuthering Waves. Disabled when `opengachaBaseUrl` is unset.
 
 ## Layout
 
@@ -123,8 +128,9 @@ Advanced → **Developer Mode**, then right-click the role → **Copy ID**).
 
 ## How a check works (`runCheck`)
 
-1. For each watched game, `fetchCodes` queries **both** APIs and merges by
-   upper-cased code. One source failing is tolerated; both failing skips the game.
+1. For each watched game, `fetchCodes` queries **every source that serves it**
+   (empty-slug sources are skipped) and merges by upper-cased code. One source
+   failing is tolerated; only *all* attempted sources failing skips the game.
 2. New codes = fetched codes not in `data/sent.json`. They're marked sent
    immediately.
 3. First time a game is seen (no state), codes are **marked sent silently** when
@@ -169,7 +175,8 @@ are a fatal error, catching typos). `loadConfig` resolves the file into `Config`
 - Each game is self-contained (`GameNotify{Webhook, Message, Username, AvatarURL}`;
   `Username` defaults to `defaultUsername`, `AvatarURL` is optional). `loadConfig`
   collects validation problems and returns them together: fatal if no games are
-  configured, or any listed game is missing `webhook` or `message`.
+  configured, any listed game is missing `webhook` or `message`, or a listed game
+  has no reachable source (OpenGachaCodes-only with no `opengachaBaseUrl`).
 
 When adding a config knob: add it to `fileConf`, resolve/validate it in
 `loadConfig`, and document it in `config.example.yaml` and this file.
@@ -181,11 +188,22 @@ When adding a config knob: add it to `fileConf`, resolve/validate it in
 - **torikushiii** — `https://hoyo-codes.seria.moe/codes?game=<slug>`, slugs
   `genshin`, `hkrpg`, `nap`, `honkai3rd`. Shape: `{"codes":[{"code","rewards":"A*60;B*5"}]}`
   (active only). Rewards get normalized (`A*60;B*5` → `A ×60, B ×5`).
+- **OpenGachaCodes** — `<opengachaBaseUrl>/games/<slug>/codes`, slugs `genshin`,
+  `starrail`, `zenless`, `wuwa` (also endfield/nte, not yet in the registry).
+  Shape: a flat array `[{"code","rewards":["Astrite x50", ...]}]` (active only).
+  Self-hosted, no auth/CORS, GET-only, strict paths (no trailing slash). A `404`
+  is treated as "nothing to contribute" (not a source failure). Reward quantities
+  use ASCII `x`, not `×`; they're joined with `, ` as-is. `fetchOpengacha` lives
+  in `sources.go`; the base URL is `opengachaBaseUrl` in config.
 
 The internal key differs from the torikushiii slug for Star Rail (`hsr`/`hkrpg`)
-and Zenless (`zzz`/`nap`). Both slugs and reward-normalization live in `games.go` /
-`sources.go`. To add another game (e.g. Tears of Themis — ennead `tot` / tori `tot`),
-add one entry to the `games` map **and** to `gameOrder`; nothing else needs to change.
+and Zenless (`zzz`/`nap`). Per-source slugs live in `games.go`; a `Game` sets a
+slug to `""` for any source that doesn't serve it (e.g. `wuwa` has empty
+`Ennead`/`Tori` and is OpenGachaCodes-only), and `fetchCodes` skips empty-slug
+sources. To add another game, add one entry to the `games` map **and** to
+`gameOrder`; nothing else needs to change. A game whose only source is
+OpenGachaCodes **fails startup** if `opengachaBaseUrl` is unset (it could never
+produce codes) — a validation problem in `loadConfig`, like a missing webhook.
 
 ## Conventions
 

README.md

@@ -1,7 +1,10 @@
 # hoyo-codes
 
-Watches for new **HoYoverse redemption codes** (Genshin Impact, Honkai: Star
-Rail, Honkai Impact 3rd) and posts them to **Discord webhooks** on a schedule.
+Watches for new **gacha redemption codes** (Genshin Impact, Honkai: Star Rail,
+Zenless Zone Zero, Honkai Impact 3rd, and Wuthering Waves) and posts them to
+**Discord webhooks** on a schedule. Codes come from community HoYoverse APIs plus
+an optional self-hosted [OpenGachaCodes](config.example.yaml) instance
+(`opengachaBaseUrl`) — the sole source for non-HoYo games like Wuthering Waves.
 
 ## Run
 

config.example.yaml

@@ -29,11 +29,19 @@ httpTimeout: 20
 # (≈5h of retries on the default 30-min schedule).
 maxPostAttempts: 10
 
+# Base URL of a self-hosted OpenGachaCodes instance (read-only HTTP JSON API). It
+# supplements the built-in HoYoverse sources for the games it also serves
+# (genshin, hsr, zzz) and is the SOLE source for non-HoYo games like `wuwa`.
+# Leave empty/omit to disable it entirely. No trailing slash needed (trimmed).
+# It has no CORS/auth and refreshes ~every 30 min; call it server-side only.
+opengachaBaseUrl: "http://localhost:8413"
+
 # Games to watch. ONLY the games listed here are watched — to stop watching one,
 # comment it out or delete it (there's no enable/disable flag). Each listed game
 # REQUIRES both a `webhook` and a `message` (startup fails otherwise). Known keys:
 #   genshin (Genshin Impact), hsr (Honkai: Star Rail), zzz (Zenless Zone Zero),
-#   honkai3rd (Honkai Impact 3rd)
+#   honkai3rd (Honkai Impact 3rd), wuwa (Wuthering Waves)
+# `wuwa` is served ONLY by OpenGachaCodes, so it needs opengachaBaseUrl set above.
 games:
   genshin:
     webhook: "https://discord.com/api/webhooks/xxx/yyy"
@@ -59,3 +67,10 @@ games:
   # honkai3rd:
   #   webhook: "https://discord.com/api/webhooks/ccc/ddd"
   #   message: "{count} new Honkai Impact 3rd {if-singular:code}{if-plural:codes}"
+
+  # Wuthering Waves — codes come only from OpenGachaCodes, so opengachaBaseUrl
+  # (above) must be set for this game to work. Redeemed in-game (no web link).
+  # wuwa:
+  #   webhook: "https://discord.com/api/webhooks/eee/fff"
+  #   message: "<@&222222222222222222> {count} new Wuthering Waves {if-singular:code}{if-plural:codes} 🌊"
+  #   username: "Wuthering Waves Codes"

config.go

@@ -37,6 +37,7 @@ type Config struct {
 	MarkExistingOnFirstRun bool                  // mark active backlog sent on a game's first run
 	HTTPTimeout            int                   // per-request HTTP timeout, seconds
 	MaxPostAttempts        int                   // give up announcing a code after this many failed checks
+	OpengachaBaseURL       string                // self-hosted OpenGachaCodes base URL ("" = source disabled)
 }
 
 // --- on-disk YAML shape ---
@@ -56,6 +57,7 @@ type fileConf struct {
 	MarkExistingOnFirstRun *bool               `yaml:"markExistingOnFirstRun"`
 	HTTPTimeout            int                 `yaml:"httpTimeout"`
 	MaxPostAttempts        int                 `yaml:"maxPostAttempts"`
+	OpengachaBaseURL       string              `yaml:"opengachaBaseUrl"`
 	Games                  map[string]gameConf `yaml:"games"`
 }
 
@@ -103,6 +105,7 @@ func loadConfig(path string) (Config, error) {
 		MarkExistingOnFirstRun: orBool(fc.MarkExistingOnFirstRun, true),
 		HTTPTimeout:            orInt(fc.HTTPTimeout, 20),
 		MaxPostAttempts:        orInt(fc.MaxPostAttempts, 10),
+		OpengachaBaseURL:       strings.TrimRight(strings.TrimSpace(fc.OpengachaBaseURL), "/"),
 		Notify:                 map[string]GameNotify{},
 	}
 	cfg.StateFile = filepath.Join(cfg.DataDir, "sent.json")
@@ -130,6 +133,14 @@ func loadConfig(path string) (Config, error) {
 		if strings.TrimSpace(gc.Message) == "" {
 			problems = append(problems, fmt.Sprintf("games.%s: message is required", key))
 		}
+		// A game with no reachable source (only OpenGachaCodes serves it, but no
+		// opengachaBaseUrl is set) can never produce codes — fail startup so the
+		// misconfiguration is loud rather than a silent no-op every check.
+		g := games[key]
+		opengachaUsable := g.Opengacha != "" && cfg.OpengachaBaseURL != ""
+		if g.Ennead == "" && g.Tori == "" && !opengachaUsable {
+			problems = append(problems, fmt.Sprintf("games.%s: only OpenGachaCodes serves this game — set opengachaBaseUrl to watch it", key))
+		}
 		cfg.Games = append(cfg.Games, key)
 		cfg.Notify[key] = GameNotify{
 			Webhook:   gc.Webhook,

games.go

@@ -3,52 +3,69 @@ package main
 // Game holds the canonical key plus the per-source slugs and display metadata.
 // The Key is what appears in the GAMES env var and the state file.
 type Game struct {
-	Key    string // canonical internal key (GAMES env, state file)
-	Name   string // human display name
-	Ennead string // slug for api.ennead.cc/mihoyo/<slug>/codes
-	Tori   string // slug for hoyo-codes.seria.moe/codes?game=<slug>
-	Color  int    // Discord embed colour
+	Key       string // canonical internal key (GAMES env, state file)
+	Name      string // human display name
+	Ennead    string // slug for api.ennead.cc/mihoyo/<slug>/codes
+	Tori      string // slug for hoyo-codes.seria.moe/codes?game=<slug>
+	Opengacha string // slug for <opengachaBaseUrl>/games/<slug>/codes ("" = not served there)
+	Color     int    // Discord embed colour
 	// Redeem is a web redemption URL template with {code} substituted,
 	// or "" when the game only supports in-game redemption.
 	Redeem string
 }
 
 // gameOrder is the canonical iteration order (the games map is unordered, and
 // config game keys should resolve deterministically).
-var gameOrder = []string{"genshin", "hsr", "zzz", "honkai3rd"}
+var gameOrder = []string{"genshin", "hsr", "zzz", "honkai3rd", "wuwa"}
 
 // games is the registry of everything we know how to watch.
 var games = map[string]Game{
 	"genshin": {
-		Key:    "genshin",
-		Name:   "Genshin Impact",
-		Ennead: "genshin",
-		Tori:   "genshin",
-		Color:  0xF2C94C,
-		Redeem: "https://genshin.hoyoverse.com/en/gift?code={code}",
+		Key:       "genshin",
+		Name:      "Genshin Impact",
+		Ennead:    "genshin",
+		Tori:      "genshin",
+		Opengacha: "genshin",
+		Color:     0xF2C94C,
+		Redeem:    "https://genshin.hoyoverse.com/en/gift?code={code}",
 	},
 	"hsr": {
-		Key:    "hsr",
-		Name:   "Honkai: Star Rail",
-		Ennead: "starrail",
-		Tori:   "hkrpg", // torikushiii's slug for Star Rail
-		Color:  0x9B7BD8,
-		Redeem: "https://hsr.hoyoverse.com/gift?code={code}",
+		Key:       "hsr",
+		Name:      "Honkai: Star Rail",
+		Ennead:    "starrail",
+		Tori:      "hkrpg",    // torikushiii's slug for Star Rail
+		Opengacha: "starrail", // OpenGachaCodes slug for Star Rail
+		Color:     0x9B7BD8,
+		Redeem:    "https://hsr.hoyoverse.com/gift?code={code}",
 	},
 	"zzz": {
-		Key:    "zzz",
-		Name:   "Zenless Zone Zero",
-		Ennead: "zenless",
-		Tori:   "nap", // torikushiii's slug for Zenless Zone Zero
-		Color:  0xFFD400,
-		Redeem: "https://zenless.hoyoverse.com/redemption?code={code}",
+		Key:       "zzz",
+		Name:      "Zenless Zone Zero",
+		Ennead:    "zenless",
+		Tori:      "nap",     // torikushiii's slug for Zenless Zone Zero
+		Opengacha: "zenless", // OpenGachaCodes slug for Zenless Zone Zero
+		Color:     0xFFD400,
+		Redeem:    "https://zenless.hoyoverse.com/redemption?code={code}",
 	},
 	"honkai3rd": {
-		Key:    "honkai3rd",
-		Name:   "Honkai Impact 3rd",
-		Ennead: "honkai",
-		Tori:   "honkai3rd",
-		Color:  0x4A9BE0,
-		Redeem: "", // Honkai Impact 3rd has no public web redemption page.
+		Key:       "honkai3rd",
+		Name:      "Honkai Impact 3rd",
+		Ennead:    "honkai",
+		Tori:      "honkai3rd",
+		Opengacha: "", // OpenGachaCodes doesn't serve Honkai Impact 3rd.
+		Color:     0x4A9BE0,
+		Redeem:    "", // Honkai Impact 3rd has no public web redemption page.
+	},
+	"wuwa": {
+		Key:  "wuwa",
+		Name: "Wuthering Waves",
+		// Not a HoYoverse game — the HoYo-only sources (ennead, tori) don't
+		// serve it, so its codes come solely from OpenGachaCodes. A source with
+		// an empty slug is skipped in fetchCodes.
+		Ennead:    "",
+		Tori:      "",
+		Opengacha: "wuwa",
+		Color:     0x3AC8D4,
+		Redeem:    "", // Wuthering Waves redeems codes in-game (no public web page).
 	},
 }

main.go

@@ -75,7 +75,7 @@ func runCheck(cfg Config, watched []Game, state *State) {
 	dirty := false
 
 	for _, g := range watched {
-		codes, err := fetchCodes(g)
+		codes, err := fetchCodes(g, cfg.OpengachaBaseURL)
 		if err != nil {
 			log.Printf("[%s] fetch failed: %v", g.Key, err)
 			continue