|
| 1 | +# hoyo-codes — agent guide |
| 2 | + |
| 3 | +A small Go service that watches for new **HoYoverse redemption codes** (Genshin |
| 4 | +Impact, Honkai: Star Rail, Honkai Impact 3rd) and posts them to **Discord |
| 5 | +webhooks** on a cron schedule. Docker-first, no database, no framework. |
| 6 | + |
| 7 | +Codes are pulled from two community APIs and merged/de-duplicated, so a hiccup on |
| 8 | +one source doesn't cause a miss: |
| 9 | + |
| 10 | +- [ennead.cc](https://api.ennead.cc/mihoyo) — `/<game>/codes` |
| 11 | +- [torikushiii/hoyoverse-api](https://github.com/torikushiii/hoyoverse-api) — `hoyo-codes.seria.moe` |
| 12 | + |
| 13 | +## Layout |
| 14 | + |
| 15 | +This directory is the whole, self-contained project (Go code, `Dockerfile`, |
| 16 | +docs, config). It knows nothing about how it's deployed — a separate |
| 17 | +`docker-compose.yaml` outside this dir builds the image and supplies its own |
| 18 | +config file and data volume; treat that as external. |
| 19 | + |
| 20 | +``` |
| 21 | +config.yaml live config (gitignored — holds webhook URLs) |
| 22 | +config.example.yaml committed, fully-commented template |
| 23 | +data/ runtime state (sent.json), gitignored |
| 24 | +Dockerfile |
| 25 | +README.md dry, user-facing |
| 26 | +AGENTS.md this file |
| 27 | +*.go the service (flat package main) |
| 28 | +``` |
| 29 | + |
| 30 | +This is a flat `package main`, one concern per file: |
| 31 | + |
| 32 | +| File | Responsibility | |
| 33 | +| --------------- | ----------------------------------------------------------------------- | |
| 34 | +| `main.go` | Startup, config load, cron loop, the per-check diff/announce. | |
| 35 | +| `config.go` | YAML config load (`gopkg.in/yaml.v3`) + resolution/validation. | |
| 36 | +| `games.go` | `games` registry: canonical key → per-source slugs, colour, redeem URL. | |
| 37 | +| `sources.go` | Fetch + normalize from both upstream APIs, merge/de-dupe. | |
| 38 | +| `discord.go` | Build embeds, chunk to Discord limits, POST the webhook. | |
| 39 | +| `state.go` | `data/sent.json` load/save (atomic write). | |
| 40 | +| `util.go` | Tiny shared helpers. | |
| 41 | +| `discord_test.go` | Unit test for `buildContent` (placeholder/plural expansion). | |
| 42 | + |
| 43 | +## Build / run / verify |
| 44 | + |
| 45 | +All commands run from this directory. |
| 46 | + |
| 47 | +```sh |
| 48 | +go build ./... && go vet ./... && go test ./... && gofmt -l . # compile + vet + test + fmt gate |
| 49 | +docker build -t hoyo-codes . # build the image |
| 50 | +``` |
| 51 | + |
| 52 | +Quick local run without Docker. Config path comes from `CONFIG_FILE` (default |
| 53 | +`/app/config.yaml`); point it at a scratch file: |
| 54 | + |
| 55 | +```sh |
| 56 | +CONFIG_FILE=/path/to/test-config.yaml go run . |
| 57 | +``` |
| 58 | + |
| 59 | +For a one-shot test, set `schedule: "0 0 1 1 *"` (parks cron far in the future so |
| 60 | +only the immediate `runOnStart` check fires) and `markExistingOnFirstRun: false` |
| 61 | +(forces the active backlog to post; by default the first run marks it sent silently). |
| 62 | + |
| 63 | +After a `go build .` here, delete the stray `hoyo-codes` binary it drops |
| 64 | +(already gitignored). |
| 65 | + |
| 66 | +## Configuration reference |
| 67 | + |
| 68 | +All config lives in `config.yaml` (gitignored — it holds webhook URLs). See |
| 69 | +`config.example.yaml` for the fully-commented template. |
| 70 | + |
| 71 | +```yaml |
| 72 | +schedule: "*/30 * * * *" # 5-field cron |
| 73 | +timezone: "Europe/Amsterdam" # optional; when the schedule runs |
| 74 | +markExistingOnFirstRun: true # suppress the old-code backlog on first run |
| 75 | +runOnStart: true |
| 76 | +httpTimeout: 20 |
| 77 | +maxPostAttempts: 10 # give up announcing a code after N failed checks |
| 78 | + |
| 79 | +games: # only games listed here are watched |
| 80 | + genshin: |
| 81 | + webhook: "https://discord.com/api/webhooks/..." |
| 82 | + message: "<@&ROLE_ID> {count} new {if-singular:code}{if-plural:codes} 🎁" |
| 83 | + username: "Genshin Codes" # optional sender name override |
| 84 | + avatarUrl: "https://…/pic.png" # optional sender avatar (public image URL) |
| 85 | + hsr: |
| 86 | + webhook: "https://discord.com/api/webhooks/..." # its own channel |
| 87 | + message: "<@&ROLE_ID> Trailblazers — {count} new {if-singular:code}{if-plural:codes}!" |
| 88 | +# honkai3rd: # comment a game out (or delete it) to stop watching |
| 89 | +# webhook: "…" |
| 90 | +# message: "…" |
| 91 | +``` |
| 92 | + |
| 93 | +- **Which games run** = the keys under `games:` (known keys: `genshin`, `hsr`, |
| 94 | + `zzz`, `honkai3rd`). There is no enable/disable flag — comment a game out or |
| 95 | + delete it to stop watching it. |
| 96 | +- **Every listed game requires `webhook` and `message`.** There is no shared |
| 97 | + default block — each game is self-contained. Startup fails with a clear error if |
| 98 | + a game is missing either, if no games are configured, or on any unknown key (typos). |
| 99 | +- **Optional per-game sender identity** (both fall back if omitted): |
| 100 | + - `username` — the Discord sender name; defaults to `defaultUsername` |
| 101 | + (`"Hoyo Codes"`) in `config.go`. |
| 102 | + - `avatarUrl` — a public image URL (PNG/JPG/GIF) Discord fetches as the sender |
| 103 | + avatar; omit to keep the webhook's own configured avatar. Both map onto the |
| 104 | + webhook payload's `username` / `avatar_url` fields. |
| 105 | +- **Message placeholders**: |
| 106 | + - `{count}` — number of new codes. |
| 107 | + - `{if-singular:X}` / `{if-plural:X}` — `X` is kept only when the count is 1 |
| 108 | + (singular) or not 1 (plural); the other is dropped. Handles irregular plurals |
| 109 | + and other languages. The text inside must not contain a `}`. |
| 110 | + |
| 111 | +### Pinging a role |
| 112 | + |
| 113 | +To ping a role, put its mention token **in the game's `message`** — the message is |
| 114 | +the Discord message body, and mentions only ping from there (never from an embed): |
| 115 | + |
| 116 | +```yaml |
| 117 | +message: "<@&123456789012345678> {count} new codes!" # pings a role |
| 118 | +message: "@everyone {count} new codes!" # literal |
| 119 | +``` |
| 120 | +
|
| 121 | +Role mentions need the role's **numeric ID**, not its name (Discord → Settings → |
| 122 | +Advanced → **Developer Mode**, then right-click the role → **Copy ID**). |
| 123 | +
|
| 124 | +## How a check works (`runCheck`) |
| 125 | + |
| 126 | +1. For each watched game, `fetchCodes` queries **both** APIs and merges by |
| 127 | + upper-cased code. One source failing is tolerated; both failing skips the game. |
| 128 | +2. New codes = fetched codes not in `data/sent.json`. They're marked sent |
| 129 | + immediately. |
| 130 | +3. First time a game is seen (no state), codes are **marked sent silently** when |
| 131 | + `markExistingOnFirstRun: true` (the default) — avoids dumping the whole |
| 132 | + backlog on boot. Set it false to announce the backlog instead. A game with |
| 133 | + **no** active codes on its first fetch is still seeded (`state.seed`) so the |
| 134 | + next fetch that finds codes is announced as new rather than re-treated as |
| 135 | + first-run backlog. |
| 136 | +4. New codes become one Discord embed (with a one-click **Redeem** link where the |
| 137 | + game supports web redemption), posted to **that game's** webhook |
| 138 | + (`cfg.Notify[key]`). `buildContent` expands `{count}` and resolves the |
| 139 | + `{if-singular:X}`/`{if-plural:X}` blocks in the game's `message`, then sends it |
| 140 | + as the message `content`; a `<@&ROLE_ID>` token pings from there. |
| 141 | +5. Codes are marked sent **only after their announce post succeeds** (state is |
| 142 | + saved once at the end of the check). A failed post leaves its codes unmarked, |
| 143 | + so the next check retries them — nothing reached Discord, so this re-tries |
| 144 | + rather than double-posts, and a broken webhook self-heals once fixed instead |
| 145 | + of silently dropping codes. A transient `429` is first retried in-place per |
| 146 | + its `Retry-After` header (`postPayload`, bounded to 3). Force a re-announce of |
| 147 | + already-sent codes by deleting `data/sent.json`. |
| 148 | + - **Retry cap:** each failed check bumps a per-code counter in `state.Attempts` |
| 149 | + (`recordAttempt`). Once a code reaches `maxPostAttempts` (config, default 10) |
| 150 | + it's marked done and **given up on** (never announced) so a persistently |
| 151 | + failing post can't retry/log forever. The counter is per-code, so a genuinely |
| 152 | + new code arriving mid-retry gets its own fresh budget; `mark` clears a code's |
| 153 | + counter on success or give-up. |
| 154 | + - **Edge case:** if one check yields enough new codes to span multiple Discord |
| 155 | + messages (>25 at once) and an early message succeeds but a later one fails, |
| 156 | + the successful ones can repost on retry. HoYo drops codes a few at a time, so |
| 157 | + in practice it's one message per game and this can't arise. |
| 158 | + |
| 159 | +## Config internals (`config.go`) |
| 160 | + |
| 161 | +Parsed with `gopkg.in/yaml.v3` in strict mode (`KnownFields(true)` — unknown keys |
| 162 | +are a fatal error, catching typos). `loadConfig` resolves the file into `Config`: |
| 163 | + |
| 164 | +- Top-level scalars (`schedule`, `timezone`, `markExistingOnFirstRun`, |
| 165 | + `runOnStart`, `httpTimeout`, `maxPostAttempts`, `dataDir`) have defaults via |
| 166 | + `orString/orBool/orInt`. |
| 167 | +- Watched games = the keys present under `games:` (iterated in `gameOrder` for |
| 168 | + stable order). Unknown keys warn and are skipped; there is no disable flag. |
| 169 | +- Each game is self-contained (`GameNotify{Webhook, Message, Username, AvatarURL}`; |
| 170 | + `Username` defaults to `defaultUsername`, `AvatarURL` is optional). `loadConfig` |
| 171 | + collects validation problems and returns them together: fatal if no games are |
| 172 | + configured, or any listed game is missing `webhook` or `message`. |
| 173 | + |
| 174 | +When adding a config knob: add it to `fileConf`, resolve/validate it in |
| 175 | +`loadConfig`, and document it in `config.example.yaml` and this file. |
| 176 | + |
| 177 | +## Upstream APIs |
| 178 | + |
| 179 | +- **ennead** — `https://api.ennead.cc/mihoyo/<slug>/codes`, slugs `genshin`, |
| 180 | + `starrail`, `zenless`, `honkai`. Shape: `{"active":[{"code","rewards":[...]}],"inactive":[...]}`. |
| 181 | +- **torikushiii** — `https://hoyo-codes.seria.moe/codes?game=<slug>`, slugs |
| 182 | + `genshin`, `hkrpg`, `nap`, `honkai3rd`. Shape: `{"codes":[{"code","rewards":"A*60;B*5"}]}` |
| 183 | + (active only). Rewards get normalized (`A*60;B*5` → `A ×60, B ×5`). |
| 184 | + |
| 185 | +The internal key differs from the torikushiii slug for Star Rail (`hsr`/`hkrpg`) |
| 186 | +and Zenless (`zzz`/`nap`). Both slugs and reward-normalization live in `games.go` / |
| 187 | +`sources.go`. To add another game (e.g. Tears of Themis — ennead `tot` / tori `tot`), |
| 188 | +add one entry to the `games` map **and** to `gameOrder`; nothing else needs to change. |
| 189 | + |
| 190 | +## Conventions |
| 191 | + |
| 192 | +- **Config is a YAML file.** Add new knobs to `fileConf`/`Config` in `config.go` |
| 193 | + and document them in `config.example.yaml` and this file. Every listed game |
| 194 | + must define its own `webhook` and `message` (validated in `loadConfig`). |
| 195 | +- **Keep it dependency-light.** Stdlib plus `robfig/cron` and `yaml.v3` only. |
| 196 | + Don't pull in an HTTP or Discord SDK. |
| 197 | +- **Discord facts worth remembering:** mentions only ping from `content`, never |
| 198 | + from an embed; limits are 25 fields/embed and 10 embeds/message — `discord.go` |
| 199 | + chunks for both. Preserve that when editing. |
| 200 | +- **Runtime state** (`data/`) and the live `config.yaml` (holds webhooks) are |
| 201 | + gitignored; committed: source, `Dockerfile`, docs, and `config.example.yaml`. |
| 202 | +- **Container runs as uid/gid 1000** and writes only `/app/data`. Keep it non-root. |
| 203 | +- **Honkai Impact 3rd** has no public web-redemption page, so its codes post |
| 204 | + without a Redeem link (redeem in-game). |
0 commit comments