Local Bounty Board - Prompt (Blog Demo)

PROMPT.md

You are an expert full-stack developer and integration engineer.

You are working inside an existing project called:

BountyBoard: Local Bounty Board for Minetest

The project already has:

• a Minetest / Luanti mod written in Lua
• a TypeScript Node.js backend
• local bounty generation
• local leaderboard persistence
• commands:
  • /bounty
  • /bounty status
  • /bounty complete
  • /bounty abandon
  • /bounty leaderboard
• backend endpoints:
  • GET /health
  • POST /api/bounty/generate
  • POST /api/bounty/complete
  • GET /api/leaderboard

Your task is to extend this existing working project with real Composio integration.

Important:

Do not rewrite the whole project. Do not break the existing local bounty flow. Do not change the Minetest gameplay unless absolutely needed. Do not use mock Composio mode. Do not leave fake placeholder functions. Do not add TODO-only integration code. Do not hardcode secrets. Do not use outdated Composio APIs.

Before writing code, read the current Composio documentation carefully:

• https://docs.composio.dev/docs
• https://docs.composio.dev/docs/quickstart
• https://docs.composio.dev/docs/providers
• https://docs.composio.dev/cookbooks/templates

First, inspect the docs and determine the correct current TypeScript SDK/API pattern for:

1. Installing the Composio SDK.
2. Initializing the Composio client.
3. Authenticating or identifying a user.
4. Executing tools or actions.
5. Appending a row to Google Sheets.
6. Handling missing connections or authentication failures.

Only after reviewing the docs, start implementation.

Goal:

When a player completes a bounty in Minetest, the backend should:

1. Validate the completion payload.
2. Update the local leaderboard.
3. Append a real row to Google Sheets through Composio.
4. Return a clear response to the game.

The game should still grant the reward locally once the player completes the bounty, but the backend response should clearly say whether the Composio sync succeeded or failed.

Composio requirements:

Add real Composio support to the backend.

Use environment variables:

COMPOSIO_API_KEY= COMPOSIO_USER_ID= GOOGLE_SHEET_ID=

Add any other environment variables required by the current Composio documentation, but explain them clearly in .env.example and README.

The backend should fail gracefully when Composio is not configured.

For example:

• If COMPOSIO_API_KEY is missing, return a clear backend warning.
• If Google Sheets is not connected, return a clear backend warning.
• If sync fails, report the failure clearly.
• Do not crash the server.
• Do not corrupt the leaderboard.
• Do not remove the player reward from the game.

Implementation details:

Create or update:

backend/src/composio.ts

It should export clean functions like:

• appendBountyCompletionToSheet(payload)
• syncBountyCompletion(payload)

The rest of the backend should call syncBountyCompletion from the completion route.

The Composio implementation must be isolated from the route logic.

Expected Google Sheets row:

Append a real row with:

• completedAt
• player
• bounty id
• bounty title
• bounty type
• current progress
• required progress
• reward points

Backend API changes:

Update POST /api/bounty/complete response.

Current response may be:

{ "ok": true, "message": "Bounty completed.", "leaderboard": { "player": "singleplayer", "points": 10, "completedBounties": 1 } }

Change it to include sync status:

{ "ok": true, "message": "Bounty completed.", "leaderboard": { "player": "singleplayer", "points": 10, "completedBounties": 1 }, "sync": { "googleSheets": { "ok": true, "message": "Google Sheets row appended." } } }

If sync fails, keep ok true for the bounty completion, but include the sync error:

{ "ok": true, "message": "Bounty completed, but external sync failed.", "leaderboard": { "player": "singleplayer", "points": 10, "completedBounties": 1 }, "sync": { "googleSheets": { "ok": false, "message": "Google Sheets sync failed: " } } }

Do not expose API keys, tokens, raw stack traces, or private Composio internals in the response.

Minetest mod changes:

Update the /bounty complete flow so chat output can show:

• reward granted
• backend recorded completion
• Google Sheets sync status

Example:

[ BountyBoard ] Bounty complete! Reward granted. [ BountyBoard ] Backend recorded completion. [ BountyBoard ] Google Sheets sync: success.

If sync fails:

[ BountyBoard ] Bounty complete! Reward granted. [ BountyBoard ] Backend recorded completion. [ BountyBoard ] Google Sheets sync failed. Check backend logs.

Do not make the game crash if the sync object is missing or malformed.

Tests:

Update or add backend tests for:

1. Completion response includes sync status.
2. Completion still succeeds when Composio sync fails.
3. Leaderboard still updates when Composio sync fails.
4. Validation still rejects incomplete bounty completions.

Mock only in tests.

Important distinction:

Runtime Composio integration should be real. Test mocks are allowed for unit tests only.

README updates:

Update README with:

1. What changed from the local-only version.
2. How Composio fits into the architecture.
3. How to install the Composio SDK.
4. How to get and set COMPOSIO_API_KEY.
5. How to set COMPOSIO_USER_ID.
6. How to connect Google Sheets.
7. How to set GOOGLE_SHEET_ID.
8. How to run the full demo.
9. How to troubleshoot:
   • missing COMPOSIO_API_KEY
   • missing connected account
   • Google Sheets sync failed
   • backend completion works but external sync fails

Documentation accuracy matters.

If the current Composio docs require a specific connection flow, CLI command, dashboard step, auth config, user ID, connected account ID, toolkit slug, or tool slug, document it accurately.

If the exact Google Sheets tool/action names are discoverable through the SDK, implement discovery or lookup instead of hardcoding guessed names.

If tool/action names must be configured manually, expose them as environment variables and document how to find them.

Suggested optional environment variable if needed:

COMPOSIO_GOOGLE_SHEETS_TOOL_SLUG=

But only add this if the current docs make it necessary.

Run and verify:

After implementation, run:

• npm install if dependencies changed
• npm run build
• npm test

Fix any failures.

Output format:

Please provide:

1. A short explanation of the Composio architecture you implemented.
2. A list of files changed.
3. Full contents of changed or new files.
4. Environment variable setup.
5. Step-by-step Composio setup instructions.
6. Step-by-step full demo instructions.
7. Test/build commands run and results.
8. Remaining risks or assumptions.

Quality bar:

• The project must still work as a Minetest/Luanti bounty board.
• The backend must compile.
• The TypeScript must be type-safe.
• The Composio code must use the current documented SDK/API.
• The integration must be real, not mocked.
• The code must not leak secrets.
• The game must not break when external sync fails.