213 lines
6.4 KiB
Markdown
213 lines
6.4 KiB
Markdown
# Dune API Skill For OpenClaw Agents
|
|
|
|
You are working with the Dune API, a Node.js Express service that imports Dune: Awakening data from Questlog into MongoDB and exposes it through REST endpoints for OpenClaw.
|
|
|
|
## Primary Goal
|
|
|
|
Help OpenClaw retrieve complete Dune: Awakening records with the least guesswork. Prefer the detailed singular datasets for client-facing lookups and search.
|
|
|
|
## Public Base URL
|
|
|
|
Use this production API base URL:
|
|
|
|
```text
|
|
https://dune.api.coppnic.cc
|
|
```
|
|
|
|
Swagger/OpenAPI is available here:
|
|
|
|
```text
|
|
https://dune.api.coppnic.cc/openapi.json
|
|
https://ui.dune.api.coppnic.cc/docs
|
|
```
|
|
|
|
## Best Endpoints For OpenClaw
|
|
|
|
Prefer singular datasets because they contain full Questlog single-record payloads in `raw`:
|
|
|
|
```text
|
|
GET /api/item
|
|
GET /api/item/{id}
|
|
GET /api/skill
|
|
GET /api/skill/{id}
|
|
GET /api/recipe
|
|
GET /api/recipe/{id}
|
|
GET /api/placeable
|
|
GET /api/placeable/{id}
|
|
GET /api/npc
|
|
GET /api/npc/{id}
|
|
```
|
|
|
|
Useful examples:
|
|
|
|
```text
|
|
GET /api/item/LongRifle_Unique_Poison_03?language=en
|
|
GET /api/item/Bloodsack_02?language=en
|
|
GET /api/skill/skills_ability_poisonmine?language=en
|
|
GET /api/recipe/Bloodsack_2_Recipe?language=en
|
|
GET /api/placeable/Atre_Banner_Placeable?language=en
|
|
GET /api/npc/bs43q?language=en
|
|
```
|
|
|
|
For text search:
|
|
|
|
```text
|
|
GET /api/search?q=rifle&datasets=item&language=en
|
|
GET /api/search?q=poison&datasets=item,skill,recipe&language=en
|
|
```
|
|
|
|
Supported languages are `en` and `de`.
|
|
|
|
## Dataset Rules
|
|
|
|
Detailed singular datasets:
|
|
|
|
| Dataset | Mongo collection | Questlog detail method |
|
|
| ----------- | ---------------- | ----------------------- |
|
|
| `item` | `item` | `database.getItem` |
|
|
| `skill` | `skill` | `database.getSkill` |
|
|
| `recipe` | `recipe` | `database.getRecipe` |
|
|
| `placeable` | `placeable` | `database.getPlaceable` |
|
|
| `npc` | `npc` | `database.getNpc` |
|
|
|
|
Summary plural datasets:
|
|
|
|
| Dataset | Mongo collection | Questlog page method |
|
|
| ------------ | ---------------- | ------------------------ |
|
|
| `items` | `items` | `database.getItems` |
|
|
| `skills` | `skills` | `database.getSkills` |
|
|
| `recipes` | `recipes` | `database.getRecipes` |
|
|
| `placeables` | `placeables` | `database.getPlaceables` |
|
|
| `npcs` | `npcs` | `database.getNpcs` |
|
|
|
|
Use plural datasets only when a compact Questlog page-summary record is enough. If a plural lookup includes an id, for example `/api/items/LongRifle_Unique_Poison_03`, the API checks the matching singular collection first and falls back to the plural summary collection.
|
|
|
|
## Response Shape
|
|
|
|
Stored documents have normalized metadata and the original Questlog payload:
|
|
|
|
```json
|
|
{
|
|
"dataset": "item",
|
|
"language": "en",
|
|
"source": "questlog.gg",
|
|
"sourceMethod": "database.getItem",
|
|
"sourceId": "LongRifle_Unique_Poison_03",
|
|
"name": "Assassin's Rifle",
|
|
"raw": {}
|
|
}
|
|
```
|
|
|
|
For OpenClaw, inspect `raw` for domain-specific fields:
|
|
|
|
- Items: `raw.stats`, `raw.mainCategory`, `raw.subCategory`, recipe relationships, wearable/equip fields.
|
|
- Skills: `raw.levels`, `raw.connections`, grid position, bonuses.
|
|
- Recipes: `raw.recipeInputItems`, `raw.recipeOutputItems`, crafting requirements, crafting stations.
|
|
- Placeables: production types, power/water fields, craftable recipe relationships.
|
|
- NPCs: `raw.description`, `raw.npcTags`, category metadata.
|
|
|
|
## Discord Output Contract
|
|
|
|
When OpenClaw asks for an answer intended for Discord, return Discord embed JSON instead of plain text. The bot should be able to send the returned payload directly.
|
|
|
|
Use this shape:
|
|
|
|
```json
|
|
{
|
|
"embeds": [
|
|
{
|
|
"title": "Assassin's Rifle",
|
|
"url": "https://dune.api.coppnic.cc/api/item/LongRifle_Unique_Poison_03?language=en",
|
|
"description": "Short useful summary for Discord.",
|
|
"color": 15198183,
|
|
"fields": [
|
|
{ "name": "Dataset", "value": "item", "inline": true },
|
|
{ "name": "Language", "value": "en", "inline": true },
|
|
{ "name": "Source ID", "value": "LongRifle_Unique_Poison_03", "inline": false }
|
|
],
|
|
"footer": { "text": "Dune API" }
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
Embed rules:
|
|
|
|
- Use `name` or `raw.name` as the embed title.
|
|
- Use the matching Dune API URL as the embed URL.
|
|
- Keep descriptions short; do not dump the full `raw` object.
|
|
- Put compact facts in fields and omit empty fields.
|
|
- Return at most 5 embeds for search results.
|
|
- Keep field values below Discord limits.
|
|
- Use decimal colors: item `15198183`, skill `3447003`, recipe `5763719`, placeable `15844367`, npc `10181046`.
|
|
|
|
Dataset field ideas:
|
|
|
|
- `item`: grade, category, subcategory, weapon stats, armor stats, fillable stats.
|
|
- `skill`: category, subcategory, max skill level, level bonuses.
|
|
- `recipe`: output items, input items, crafting time, required stations.
|
|
- `placeable`: category, power, water, supported production types.
|
|
- `npc`: category, tags, description.
|
|
|
|
## Repository Map
|
|
|
|
Look here when changing behavior:
|
|
|
|
```text
|
|
src/datasets.js Dataset keys, collections, Questlog methods, API allowlists.
|
|
src/importer/questlogClient.js Questlog URL building and TRPC response extraction.
|
|
src/importer/importer.js Import orchestration, detail fetches, Mongo upserts.
|
|
src/db/indexes.js Mongo indexes for summary and singular collections.
|
|
src/routes/api.js REST API routes, search, dataset lookup behavior.
|
|
src/swagger/openapi.js OpenAPI/Swagger documentation.
|
|
src/app.js Express middleware and public top-level routes.
|
|
scripts/import.js CLI import entry point.
|
|
```
|
|
|
|
## Import Commands
|
|
|
|
Run all imports:
|
|
|
|
```powershell
|
|
npm run import
|
|
```
|
|
|
|
Run a safe smoke import:
|
|
|
|
```powershell
|
|
npm run import:smoke
|
|
```
|
|
|
|
Import selected datasets:
|
|
|
|
```powershell
|
|
node scripts/import.js --datasets=items,skills,recipes,placeables,npcs --languages=en,de
|
|
```
|
|
|
|
The importer writes both plural summaries and singular detailed records when a dataset has a detail endpoint.
|
|
|
|
## Validation
|
|
|
|
Use the existing syntax check:
|
|
|
|
```powershell
|
|
npm run check
|
|
```
|
|
|
|
Useful endpoint checks:
|
|
|
|
```text
|
|
GET /health
|
|
GET /api/datasets
|
|
GET /api/item/LongRifle_Unique_Poison_03?language=en
|
|
GET /api/search?q=poison&datasets=item,skill,recipe&language=en
|
|
GET /SKILL.md
|
|
```
|
|
|
|
## Important Constraints
|
|
|
|
- Do not expose secrets in public documentation or API responses.
|
|
- Keep `.env` values private; production configuration comes from environment variables.
|
|
- Keep the singular datasets first-class for OpenClaw.
|
|
- Keep changes small and consistent with the existing CommonJS/Express style.
|