api-duneawa/.idea/SKILL.md

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:

https://dune.api.coppnic.cc

Swagger/OpenAPI is available here:

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:

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:

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:

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:

{
	"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:

{
	"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:

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:

npm run import

Run a safe smoke import:

npm run import:smoke

Import selected datasets:

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:

npm run check

Useful endpoint checks:

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.