horizon-mcp 0.0.0-development

package/src/resources/docs/gift-codes.md

@@ -0,0 +1,153 @@
+# Gift Codes
+
+## Overview
+
+Gift Codes allow you to create promotional codes that players can redeem for in-game rewards. Codes are created in the horizOn Dashboard with associated reward data. Each code can be single-use or multi-use, and can optionally have an expiration date.
+
+The typical flow is:
+
+1. **Validate** (optional) — Check if a code is valid before redeeming
+2. **Redeem** — Redeem the code to receive the reward data
+
+## Endpoints
+
+### Validate Gift Code
+
+**`POST /api/v1/app/gift-codes/validate`**
+
+Checks if a gift code is valid and can be redeemed by the user, without consuming it.
+
+**Request Body:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `code` | string | Yes | The gift code to validate |
+| `userId` | string | Yes | The user's ID |
+
+**Response (200):**
+
+```json
+{
+  "valid": true
+}
+```
+
+`valid` is `false` if the code does not exist, is expired, or has already been redeemed by this user.
+
+---
+
+### Redeem Gift Code
+
+**`POST /api/v1/app/gift-codes/redeem`**
+
+Redeems a gift code and returns the associated reward data.
+
+**Request Body:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `code` | string | Yes | The gift code to redeem |
+| `userId` | string | Yes | The user's ID |
+
+**Response (200):**
+
+```json
+{
+  "success": true,
+  "message": "Gift code redeemed successfully",
+  "giftData": "{\"coins\": 500, \"gems\": 10}"
+}
+```
+
+`giftData` is a JSON string set by the developer in the Dashboard. Your app must parse and apply the rewards.
+
+**Failed redemption:**
+
+```json
+{
+  "success": false,
+  "message": "Gift code already redeemed by this user",
+  "giftData": null
+}
+```
+
+## Code Examples
+
+### Godot (GDScript)
+
+```gdscript
+# Validate a code first (optional)
+var is_valid = await Horizon.giftCodes.validate("ABCD-1234")
+if is_valid:
+    print("Code is valid!")
+
+# Redeem a code
+var result = await Horizon.giftCodes.redeem("ABCD-1234")
+if result.get("success", false):
+    var gift_data = result.get("giftData", "")
+    print("Rewards: %s" % gift_data)
+
+# Redeem and auto-parse rewards as Dictionary
+var parsed = await Horizon.giftCodes.redeemParsed("ABCD-1234")
+if parsed.get("success", false):
+    var rewards: Dictionary = parsed.get("rewards", {})
+    var coins = rewards.get("coins", 0)
+    var gems = rewards.get("gems", 0)
+
+# Listen for events
+Horizon.giftCodes.code_validated.connect(func(code, valid): print("%s: %s" % [code, "valid" if valid else "invalid"]))
+Horizon.giftCodes.code_redeemed.connect(func(code, data): print("Redeemed %s: %s" % [code, data]))
+Horizon.giftCodes.code_redeem_failed.connect(func(code, error): print("Failed: %s" % error))
+```
+
+### Unity (C#)
+
+```csharp
+using PM.horizOn.Cloud.Manager;
+
+// Validate (optional)
+bool? valid = await GiftCodeManager.Instance.Validate("PROMO2024");
+if (valid == true)
+{
+    Debug.Log("Code is valid!");
+}
+
+// Redeem
+var result = await GiftCodeManager.Instance.Redeem("PROMO2024");
+if (result != null && result.success)
+{
+    // Parse giftData JSON for rewards
+    string giftData = result.giftData;
+    Debug.Log($"Rewards: {giftData}");
+}
+```
+
+### REST (cURL)
+
+```bash
+# Validate
+curl -X POST https://horizon.pm/api/v1/app/gift-codes/validate \
+  -H "X-API-Key: YOUR_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"code": "ABCD-1234", "userId": "user123"}'
+
+# Redeem
+curl -X POST https://horizon.pm/api/v1/app/gift-codes/redeem \
+  -H "X-API-Key: YOUR_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"code": "ABCD-1234", "userId": "user123"}'
+```
+
+## Best Practices
+
+- **Validate before redeeming** — Show the user whether their code is valid before consuming it.
+- **Parse giftData in your app** — The reward structure is defined by you in the Dashboard. Parse the JSON string and apply rewards accordingly.
+- **Handle already-redeemed codes** — Check the `success` field and display the `message` to the user.
+
+## Common Errors
+
+| Status | Cause | Solution |
+|--------|-------|----------|
+| 401 | Invalid API key | Check `X-API-Key` header |
+| 404 | Code does not exist | Verify the code spelling |
+| 429 | Rate limit exceeded | Avoid rapid repeated redemption attempts |

package/src/resources/docs/leaderboard.md

@@ -0,0 +1,201 @@
+# Leaderboards
+
+## Overview
+
+horizOn leaderboards provide global rankings for your app. Scores are submitted per user and **only update if the new score is higher** than the user's previous best. This ensures leaderboards always reflect each player's best achievement.
+
+## Endpoints
+
+### Submit Score
+
+**`POST /api/v1/app/leaderboard/submit`**
+
+Submits a score for the authenticated user. Only updates if the score is higher than the previous best.
+
+**Request Body:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `userId` | string | Yes | The user's ID |
+| `score` | number | Yes | Score value (positive integer) |
+
+**Response (200):**
+
+```json
+{
+  "success": true
+}
+```
+
+---
+
+### Get Top Entries
+
+**`GET /api/v1/app/leaderboard/top?userId={userId}&limit={limit}`**
+
+Returns the top entries on the leaderboard.
+
+**Query Parameters:**
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `userId` | string | Yes | The requesting user's ID |
+| `limit` | number | No | Number of entries (default 10, max 100) |
+
+**Response (200):**
+
+```json
+{
+  "entries": [
+    { "position": 1, "username": "TopPlayer", "score": 50000 },
+    { "position": 2, "username": "Runner-Up", "score": 45000 },
+    { "position": 3, "username": "ThirdPlace", "score": 40000 }
+  ]
+}
+```
+
+---
+
+### Get User Rank
+
+**`GET /api/v1/app/leaderboard/rank?userId={userId}`**
+
+Returns the current user's position on the leaderboard.
+
+**Query Parameters:**
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `userId` | string | Yes | The user's ID |
+
+**Response (200):**
+
+```json
+{
+  "position": 42,
+  "username": "MyPlayer",
+  "score": 12500
+}
+```
+
+---
+
+### Get Entries Around User
+
+**`GET /api/v1/app/leaderboard/around?userId={userId}&range={range}`**
+
+Returns entries around the user's position (players ranked near them).
+
+**Query Parameters:**
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `userId` | string | Yes | The user's ID |
+| `range` | number | No | Number of entries before and after (default 10) |
+
+**Response (200):**
+
+```json
+{
+  "entries": [
+    { "position": 40, "username": "NearbyPlayer1", "score": 13000 },
+    { "position": 41, "username": "NearbyPlayer2", "score": 12800 },
+    { "position": 42, "username": "MyPlayer", "score": 12500 },
+    { "position": 43, "username": "NearbyPlayer3", "score": 12200 }
+  ]
+}
+```
+
+## Code Examples
+
+### Godot (GDScript)
+
+```gdscript
+# Submit a score (only updates if higher than previous best)
+await Horizon.leaderboard.submitScore(1000)
+
+# Get top 10 players
+var top: Array[HorizonLeaderboardEntry] = await Horizon.leaderboard.getTop(10)
+for entry in top:
+    print("#%d %s: %d" % [entry.position, entry.username, entry.score])
+
+# Get current user's rank
+var myRank: HorizonLeaderboardEntry = await Horizon.leaderboard.getRank()
+print("My rank: #%d (Score: %d)" % [myRank.position, myRank.score])
+
+# Get entries around the user's position
+var around: Array[HorizonLeaderboardEntry] = await Horizon.leaderboard.getAround(5)
+
+# Use caching (enabled by default)
+var cached_top = await Horizon.leaderboard.getTop(10, true)  # uses cache
+var fresh_top = await Horizon.leaderboard.getTop(10, false)  # forces refresh
+
+# Clear cache manually
+Horizon.leaderboard.clearCache()
+
+# Listen for events
+Horizon.leaderboard.score_submitted.connect(func(score): print("Submitted: %d" % score))
+Horizon.leaderboard.top_entries_loaded.connect(func(entries): print("Loaded %d entries" % entries.size()))
+```
+
+### Unity (C#)
+
+```csharp
+using PM.horizOn.Cloud.Manager;
+
+// Submit score
+await LeaderboardManager.Instance.SubmitScore(12500);
+
+// Get top 10 players
+var top = await LeaderboardManager.Instance.GetTop(10);
+foreach (var entry in top)
+{
+    Debug.Log($"#{entry.position} {entry.username}: {entry.score}");
+}
+
+// Get your rank
+var rank = await LeaderboardManager.Instance.GetRank();
+Debug.Log($"My rank: #{rank.position} (Score: {rank.score})");
+
+// Get entries around user
+var around = await LeaderboardManager.Instance.GetAround(5);
+
+// Clear cache
+LeaderboardManager.Instance.ClearCache();
+```
+
+### REST (cURL)
+
+```bash
+# Submit score
+curl -X POST https://horizon.pm/api/v1/app/leaderboard/submit \
+  -H "X-API-Key: YOUR_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"userId": "user123", "score": 12500}'
+
+# Get top 10
+curl "https://horizon.pm/api/v1/app/leaderboard/top?userId=user123&limit=10" \
+  -H "X-API-Key: YOUR_API_KEY"
+
+# Get rank
+curl "https://horizon.pm/api/v1/app/leaderboard/rank?userId=user123" \
+  -H "X-API-Key: YOUR_API_KEY"
+
+# Get around
+curl "https://horizon.pm/api/v1/app/leaderboard/around?userId=user123&range=5" \
+  -H "X-API-Key: YOUR_API_KEY"
+```
+
+## Best Practices
+
+- **Only submit on new high score** — The server already enforces "highest wins," but avoiding unnecessary requests saves your rate limit quota.
+- **Cache leaderboard data** — Both SDKs cache by default. Use cached data for display and refresh periodically.
+- **Limit query size** — Request only as many entries as you display (e.g., top 10, not top 100).
+
+## Common Errors
+
+| Status | Cause | Solution |
+|--------|-------|----------|
+| 401 | Invalid API key | Check `X-API-Key` header |
+| 404 | User not found on leaderboard | User may not have submitted a score yet |
+| 429 | Rate limit exceeded | Cache data and reduce API calls |

package/src/resources/docs/news.md

@@ -0,0 +1,114 @@
+# News
+
+## Overview
+
+The News feature lets you display in-game announcements, patch notes, and updates to your players. News entries are created in the horizOn Dashboard and fetched by the app at runtime. Entries can be filtered by language.
+
+## Endpoints
+
+### Get News
+
+**`GET /api/v1/app/news?limit={limit}&languageCode={languageCode}`**
+
+Returns a list of published news entries, ordered by release date (newest first).
+
+**Query Parameters:**
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `limit` | number | No | Max entries to return (default 20, max 100) |
+| `languageCode` | string | No | Filter by language (e.g., `en`, `de`, `fr`) |
+
+**Response (200):**
+
+```json
+[
+  {
+    "id": "news-001",
+    "title": "Version 2.0 Released!",
+    "message": "We've added new features including cloud saves and leaderboards.",
+    "releaseDate": "2025-01-15T12:00:00Z",
+    "languageCode": "en"
+  },
+  {
+    "id": "news-002",
+    "title": "Holiday Event",
+    "message": "Earn double XP during the holiday season!",
+    "releaseDate": "2025-01-10T08:00:00Z",
+    "languageCode": "en"
+  }
+]
+```
+
+## Code Examples
+
+### Godot (GDScript)
+
+```gdscript
+# Load latest 20 news entries
+var news: Array[HorizonNewsEntry] = await Horizon.news.loadNews()
+
+# Load with filters
+var english_news = await Horizon.news.loadNews(10, "en")
+
+# Iterate over entries
+for entry in news:
+    print("%s: %s" % [entry.title, entry.message])
+    print("  Date: %s | Language: %s" % [entry.releaseDate, entry.languageCode])
+
+# Caching (enabled by default)
+var cached = await Horizon.news.loadNews(20, "", true)   # uses cache
+var fresh = await Horizon.news.loadNews(20, "", false)    # forces refresh
+
+# Get cached news without network request
+var cached_entries = Horizon.news.getCachedNews()
+
+# Clear cache
+Horizon.news.clearCache()
+
+# Listen for events
+Horizon.news.news_loaded.connect(func(entries): print("Loaded %d entries" % entries.size()))
+```
+
+### Unity (C#)
+
+```csharp
+using PM.horizOn.Cloud.Manager;
+
+// Load news
+var news = await NewsManager.Instance.LoadNews(limit: 10);
+foreach (var item in news)
+{
+    Debug.Log($"{item.title}: {item.message}");
+}
+
+// Filter by language
+var germanNews = await NewsManager.Instance.LoadNews(limit: 10, languageCode: "de");
+
+// Get specific entry from cache
+var entry = NewsManager.Instance.GetNewsById("news-001");
+
+// Clear cache
+NewsManager.Instance.ClearCache();
+```
+
+### REST (cURL)
+
+```bash
+# Get latest 10 news entries in English
+curl "https://horizon.pm/api/v1/app/news?limit=10&languageCode=en" \
+  -H "X-API-Key: YOUR_API_KEY"
+```
+
+## Best Practices
+
+- **Fetch news at startup** — Load news once when the app starts and display in a news panel.
+- **Use language filtering** — Show news in the user's preferred language.
+- **Cache results** — News does not change frequently; cache for the session duration.
+
+## Common Errors
+
+| Status | Cause | Solution |
+|--------|-------|----------|
+| 401 | Invalid API key | Check `X-API-Key` header |
+| 429 | Rate limit exceeded | Cache news data, fetch once at startup |

package/src/resources/docs/overview.md

@@ -0,0 +1,80 @@
+# horizOn Overview
+
+## What is horizOn?
+
+horizOn is a **multi-tenant Backend-as-a-Service (BaaS)** designed for game and app developers. It provides ready-to-use backend features so developers can focus on building their games instead of managing servers.
+
+**Base URL:** `https://horizon.pm`
+
+## Key Concept: Account vs User
+
+This distinction is critical when working with horizOn:
+
+- **Account** — The developer or company using horizOn. An account owns one or more apps, manages API keys, and configures features via the horizOn Dashboard.
+- **User** — The end-user of the developer's app (a player). Users sign up, sign in, save data, submit scores, etc.
+
+The App API (used by SDKs and this MCP server) operates on behalf of **Users** within a developer's **Account**. The `X-API-Key` header identifies which Account/App the request belongs to.
+
+## Core Features
+
+horizOn provides 8 core features:
+
+| # | Feature | Description |
+|---|---------|-------------|
+| 1 | **Authentication** | Anonymous, email/password, and Google OAuth sign-in/sign-up |
+| 2 | **Cloud Save** | Persist player data across devices (JSON or binary) |
+| 3 | **Leaderboards** | Global rankings with score submission and queries |
+| 4 | **Remote Config** | Server-side key-value configuration (feature flags, balancing) |
+| 5 | **News** | In-game news and announcements with language filtering |
+| 6 | **Gift Codes** | Promotional code validation and redemption |
+| 7 | **User Feedback** | Bug reports, feature requests, and general feedback |
+| 8 | **User Logs** | Server-side event and error tracking per user |
+
+## Tier System
+
+horizOn offers four pricing tiers with different limits:
+
+| Feature | FREE | BASIC | PRO | ENTERPRISE |
+|---------|------|-------|-----|------------|
+| **Cloud Save Size** | 1 KB | 5 KB | 20 KB | 250 KB |
+| **User Logs** | Not available | Available | Available | Available |
+| **Rate Limit** | 10 req/min | 10 req/min | 10 req/min | 10 req/min |
+| **All other features** | Available | Available | Available | Available |
+
+**Rate Limit:** All tiers are limited to **10 requests per minute per client**. Plan API calls carefully and use caching.
+
+## API Structure
+
+All App API endpoints follow the pattern:
+
+```
+{METHOD} /api/v1/app/{feature}/{action}
+```
+
+Every request requires the `X-API-Key` header:
+
+```
+X-API-Key: your-api-key-here
+Content-Type: application/json
+```
+
+## SDKs
+
+| Engine | SDK | Language |
+|--------|-----|----------|
+| **Godot** | [horizOn SDK for Godot](https://github.com/ProjectMakersDE/horizOn-SDK-Godot) | GDScript |
+| **Unity** | [horizOn Cloud SDK for Unity](https://github.com/ProjectMakersDE/horizOn-SDK-Unity) | C# |
+| **Unreal Engine** | No official SDK | Use REST API directly (C++ FHttpModule or VaRest plugin) |
+
+## Common HTTP Status Codes
+
+| Code | Meaning | Action |
+|------|---------|--------|
+| 200 | Success | Request completed successfully |
+| 400 | Bad Request | Check request parameters |
+| 401 | Unauthorized | Invalid or missing API key |
+| 403 | Forbidden | Feature not available for tier, or user not verified |
+| 404 | Not Found | Resource does not exist |
+| 409 | Conflict | User already exists (signup) |
+| 429 | Too Many Requests | Rate limit exceeded, wait and retry |
+| 500 | Server Error | Internal server error, retry later |

package/src/resources/docs/remote-config.md

@@ -0,0 +1,149 @@
+# Remote Config
+
+## Overview
+
+Remote Config lets you store key-value pairs on the server that your app can fetch at runtime. This is useful for:
+
+- **Feature flags** — Enable/disable features without an app update
+- **Game balance** — Tweak difficulty, rewards, or economy values
+- **A/B testing** — Serve different values to different users
+- **Maintenance mode** — Toggle server maintenance messages
+- **Version gating** — Enforce minimum app versions
+
+Config values are set in the horizOn Dashboard and are read-only from the app side.
+
+## Endpoints
+
+### Get Single Config
+
+**`GET /api/v1/app/remote-config/{configKey}`**
+
+Retrieves a single configuration value by its key.
+
+**Path Parameters:**
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `configKey` | string | Yes | The configuration key |
+
+**Response (200):**
+
+```json
+{
+  "configKey": "max_level",
+  "configValue": "50",
+  "found": true
+}
+```
+
+If the key does not exist:
+
+```json
+{
+  "configKey": "unknown_key",
+  "configValue": null,
+  "found": false
+}
+```
+
+---
+
+### Get All Configs
+
+**`GET /api/v1/app/remote-config/all`**
+
+Retrieves all configuration values for the app.
+
+**Response (200):**
+
+```json
+{
+  "configs": {
+    "max_level": "50",
+    "difficulty": "1.5",
+    "maintenance_mode": "false",
+    "welcome_message": "Hello, Player!"
+  },
+  "total": 4
+}
+```
+
+## Code Examples
+
+### Godot (GDScript)
+
+```gdscript
+# Get a single config value
+var version: String = await Horizon.remoteConfig.getConfig("game_version")
+
+# Typed getters with defaults
+var maxLevel: int = await Horizon.remoteConfig.getInt("max_level", 100)
+var difficulty: float = await Horizon.remoteConfig.getFloat("difficulty", 1.0)
+var maintenance: bool = await Horizon.remoteConfig.getBool("maintenance_mode", false)
+
+# Parse JSON config values
+var jsonData = await Horizon.remoteConfig.getJson("event_config")
+
+# Get all configs at once (recommended at startup)
+var all: Dictionary = await Horizon.remoteConfig.getAllConfigs()
+
+# Caching (enabled by default)
+var cached = await Horizon.remoteConfig.getConfig("key", true)   # uses cache
+var fresh = await Horizon.remoteConfig.getConfig("key", false)   # forces refresh
+
+# Check if a key exists
+var exists: bool = await Horizon.remoteConfig.hasKey("some_key")
+
+# Clear cache
+Horizon.remoteConfig.clearCache()
+
+# Listen for events
+Horizon.remoteConfig.config_loaded.connect(func(key, value): print("%s = %s" % [key, value]))
+Horizon.remoteConfig.all_configs_loaded.connect(func(configs): print("Loaded %d configs" % configs.size()))
+```
+
+### Unity (C#)
+
+```csharp
+using PM.horizOn.Cloud.Manager;
+
+// Get a single config
+string value = await RemoteConfigManager.Instance.GetConfig("game_version");
+
+// Type-safe getters with defaults
+int maxLives = await RemoteConfigManager.Instance.GetInt("max_lives", 3);
+float difficulty = await RemoteConfigManager.Instance.GetFloat("difficulty", 1.0f);
+bool eventActive = await RemoteConfigManager.Instance.GetBool("holiday_event", false);
+
+// Get all configs at once (recommended at startup)
+var configs = await RemoteConfigManager.Instance.GetAllConfigs();
+
+// Clear cache
+RemoteConfigManager.Instance.ClearCache();
+```
+
+### REST (cURL)
+
+```bash
+# Get single config
+curl "https://horizon.pm/api/v1/app/remote-config/max_level" \
+  -H "X-API-Key: YOUR_API_KEY"
+
+# Get all configs
+curl "https://horizon.pm/api/v1/app/remote-config/all" \
+  -H "X-API-Key: YOUR_API_KEY"
+```
+
+## Best Practices
+
+- **Fetch all configs at startup** — Use `getAllConfigs()` once on app launch and rely on the cache.
+- **Provide sensible defaults** — Always pass default values in typed getters in case the config key is missing.
+- **Cache aggressively** — Config values rarely change during a session.
+- **Avoid frequent polling** — Config changes take effect when users restart the app or you explicitly refresh.
+
+## Common Errors
+
+| Status | Cause | Solution |
+|--------|-------|----------|
+| 401 | Invalid API key | Check `X-API-Key` header |
+| 429 | Rate limit exceeded | Cache config values, fetch once at startup |