horizon-mcp 0.0.0-development

package/src/resources/docs/user-logs.md

@@ -0,0 +1,144 @@
+# User Logs
+
+## Overview
+
+User Logs allow you to track player events, errors, and actions on the server. This is useful for debugging, analytics, and monitoring player behavior. Log entries are viewable per-user in the horizOn Dashboard.
+
+**Important:** User Logs require **BASIC tier or higher**. The feature is not available on the FREE tier and will return a `403` error.
+
+## Endpoints
+
+### Create Log
+
+**`POST /api/v1/app/user-logs/create`**
+
+Creates a log entry for a user.
+
+**Request Body:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `message` | string | Yes | Log message (max 1000 characters) |
+| `type` | string | Yes | Log type: `INFO`, `WARN`, or `ERROR` |
+| `userId` | string | Yes | The user's ID |
+| `errorCode` | string | No | Error code for categorization (max 50 characters) |
+
+**Response (200):**
+
+```json
+{
+  "id": "log-abc123",
+  "createdAt": "2025-01-15T10:30:00Z"
+}
+```
+
+## Log Types
+
+| Type | Use Case |
+|------|----------|
+| `INFO` | General events: tutorial complete, level up, purchase |
+| `WARN` | Non-critical issues: low memory, retry attempt, degraded performance |
+| `ERROR` | Critical issues: crash, save failure, network error |
+
+## Code Examples
+
+### Godot (GDScript)
+
+```gdscript
+# Create typed log entries
+await Horizon.userLogs.info("Player completed tutorial")
+await Horizon.userLogs.warn("Low memory detected")
+await Horizon.userLogs.error("Failed to load asset", "ERR_001")
+
+# Log game events
+await Horizon.userLogs.logEvent("level_complete", "Level 5")
+await Horizon.userLogs.logEvent("purchase", "item_sword_01")
+
+# Log errors with stack trace
+await Horizon.userLogs.logError("Null reference in combat system", "Line 42: combat.gd")
+
+# Full createLog call
+var result = await Horizon.userLogs.createLog(
+    HorizonUserLogs.LogType.ERROR,
+    "Detailed error message here",
+    "SAVE_FAILED"
+)
+if not result.is_empty():
+    print("Log ID: %s, Created: %s" % [result.id, result.createdAt])
+
+# Listen for events
+Horizon.userLogs.log_created.connect(func(id, created_at): print("Log %s created" % id))
+Horizon.userLogs.log_create_failed.connect(func(error): print("Failed: %s" % error))
+```
+
+### Unity (C#)
+
+```csharp
+using PM.horizOn.Cloud.Manager;
+using PM.horizOn.Cloud.Enums;
+
+// Convenience methods
+await UserLogManager.Instance.Info("Tutorial completed");
+await UserLogManager.Instance.Warn("Low memory detected");
+await UserLogManager.Instance.Error("Save failed", errorCode: "SAVE_001");
+
+// Full CreateLog call
+var result = await UserLogManager.Instance.CreateLog(
+    LogType.ERROR,
+    "Detailed error message",
+    errorCode: "CRASH_002"
+);
+if (result != null)
+{
+    Debug.Log($"Log ID: {result.id}, Created: {result.createdAt}");
+}
+```
+
+### REST (cURL)
+
+```bash
+curl -X POST https://horizon.pm/api/v1/app/user-logs/create \
+  -H "X-API-Key: YOUR_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "message": "Player completed tutorial",
+    "type": "INFO",
+    "userId": "user123"
+  }'
+
+# With error code
+curl -X POST https://horizon.pm/api/v1/app/user-logs/create \
+  -H "X-API-Key: YOUR_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "message": "Failed to save game data",
+    "type": "ERROR",
+    "userId": "user123",
+    "errorCode": "SAVE_FAILED"
+  }'
+```
+
+## Best Practices
+
+- **Log meaningful events** — Track milestones (tutorial complete, level up), not routine actions.
+- **Use error codes** — Consistent error codes make it easy to filter and analyze issues in the Dashboard.
+- **Truncate long messages** — Messages are limited to 1000 characters. Both SDKs auto-truncate.
+- **Be aware of rate limits** — Each log creation counts toward the 10 req/min limit. Batch or throttle logging.
+
+## Tier Requirements
+
+| Tier | User Logs Available |
+|------|-------------------|
+| FREE | No (returns 403) |
+| BASIC | Yes |
+| PRO | Yes |
+| ENTERPRISE | Yes |
+
+## Common Errors
+
+| Status | Cause | Solution |
+|--------|-------|----------|
+| 400 | Missing required fields | Ensure `message`, `type`, and `userId` are provided |
+| 401 | Invalid API key | Check `X-API-Key` header |
+| 403 | FREE tier account | Upgrade to BASIC or higher |
+| 429 | Rate limit exceeded | Throttle log submissions |

package/src/resources/quickstart/godot.md

@@ -0,0 +1,224 @@
+# Godot Quickstart Guide
+
+## Requirements
+
+- **Godot 4.5** or later
+- horizOn API key (get one at [horizon.pm](https://horizon.pm))
+
+## Step 1: Install the SDK
+
+### Option A: Asset Library (Recommended)
+
+1. Open Godot and go to **AssetLib**
+2. Search for "horizOn SDK"
+3. Download and install
+4. Enable the plugin: **Project > Project Settings > Plugins > horizOn SDK**
+
+### Option B: Manual Installation
+
+1. Download the latest release from [GitHub Releases](https://github.com/ProjectMakersDE/horizOn-SDK-Godot/releases)
+2. Copy the `addons/horizon_sdk` folder to your project's `addons/` directory
+3. Enable the plugin: **Project > Project Settings > Plugins > horizOn SDK**
+
+## Step 2: Import Configuration
+
+1. Go to the [horizOn Dashboard](https://horizon.pm) and navigate to SDK Settings
+2. Download your `horizOn_config.json` file
+3. In Godot, go to **Project > Tools > horizOn: Import Config...**
+4. Select your downloaded JSON file
+
+This creates a config resource at `res://addons/horizon_sdk/horizon_config.tres` with your API key and server hosts.
+
+## Step 3: Connect to Server
+
+The SDK is accessed through the `Horizon` singleton (auto-registered when the plugin is enabled).
+
+```gdscript
+extends Node
+
+func _ready():
+    # Connect to the best available server (auto-selects lowest latency)
+    var connected = await Horizon.connect_to_server()
+    if not connected:
+        print("Failed to connect to horizOn!")
+        return
+
+    print("Connected to %s" % Horizon.getActiveHost())
+```
+
+## Step 4: Authenticate
+
+```gdscript
+# Quick anonymous sign-in (creates new user or restores cached session)
+var signed_in = await Horizon.quickSignInAnonymous("Player1")
+if signed_in:
+    var user = Horizon.getCurrentUser()
+    print("Welcome, %s! (ID: %s)" % [user.displayName, user.userId])
+```
+
+### Other Authentication Methods
+
+```gdscript
+# Email sign-up
+await Horizon.auth.signUpEmail("user@example.com", "password123", "MyUsername")
+
+# Email sign-in
+await Horizon.auth.signInEmail("user@example.com", "password123")
+
+# Anonymous sign-up with explicit token
+await Horizon.auth.signUpAnonymous("DisplayName")
+
+# Restore anonymous session from cache
+await Horizon.auth.restoreAnonymousSession()
+
+# Sign out
+Horizon.auth.signOut()
+```
+
+## Step 5: Use Features
+
+### Leaderboards
+
+```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 your rank
+var rank: HorizonLeaderboardEntry = await Horizon.leaderboard.getRank()
+
+# Get entries around your position
+var around: Array[HorizonLeaderboardEntry] = await Horizon.leaderboard.getAround(5)
+```
+
+### Cloud Saves
+
+```gdscript
+# Save a Dictionary (recommended)
+await Horizon.cloudSave.saveObject({"level": 5, "coins": 1000})
+
+# Load as Dictionary
+var data: Dictionary = await Horizon.cloudSave.loadObject()
+if not data.is_empty():
+    var level = data.get("level", 1)
+
+# Save/load raw strings
+await Horizon.cloudSave.saveData('{"custom": "json"}')
+var json: String = await Horizon.cloudSave.loadData()
+
+# Binary data
+await Horizon.cloudSave.saveBytes(my_bytes)
+var bytes: PackedByteArray = await Horizon.cloudSave.loadBytes()
+```
+
+### Remote Config
+
+```gdscript
+# Typed getters with defaults
+var max_level: 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)
+
+# Get all configs at once (recommended at startup)
+var all_configs: Dictionary = await Horizon.remoteConfig.getAllConfigs()
+```
+
+### News
+
+```gdscript
+var news: Array[HorizonNewsEntry] = await Horizon.news.loadNews(20, "en")
+for entry in news:
+    print("%s: %s" % [entry.title, entry.message])
+```
+
+### Gift Codes
+
+```gdscript
+var is_valid = await Horizon.giftCodes.validate("ABCD-1234")
+if is_valid:
+    var result = await Horizon.giftCodes.redeem("ABCD-1234")
+    if result.get("success", false):
+        print("Rewards: %s" % result.get("giftData", ""))
+```
+
+### Feedback
+
+```gdscript
+await Horizon.feedback.submitBugReport("Crash on Level 5", "Game crashes when...")
+await Horizon.feedback.submitFeatureRequest("Dark Mode", "Add dark mode option")
+```
+
+### User Logs
+
+```gdscript
+# Requires BASIC tier or higher
+await Horizon.userLogs.info("Player completed tutorial")
+await Horizon.userLogs.warn("Low memory detected")
+await Horizon.userLogs.error("Failed to load asset", "ERR_001")
+await Horizon.userLogs.logEvent("level_complete", "Level 5")
+```
+
+## Signals (Event-Driven)
+
+All operations emit signals for reactive programming:
+
+```gdscript
+# SDK lifecycle
+Horizon.sdk_initialized.connect(func(): print("SDK ready"))
+Horizon.sdk_connected.connect(func(host): print("Connected to %s" % host))
+
+# Authentication
+Horizon.auth.signin_completed.connect(func(user): print("Signed in: %s" % user.userId))
+Horizon.auth.signin_failed.connect(func(error): print("Auth error: %s" % error))
+
+# Features
+Horizon.leaderboard.score_submitted.connect(func(score): print("Score: %d" % score))
+Horizon.cloudSave.data_saved.connect(func(size): print("Saved %d bytes" % size))
+Horizon.news.news_loaded.connect(func(entries): print("Loaded %d news" % entries.size()))
+```
+
+## Configuration Options
+
+Edit your config resource at `addons/horizon_sdk/horizon_config.tres`:
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `api_key` | - | Your horizOn API key |
+| `hosts` | - | Array of backend server URLs |
+| `connection_timeout_seconds` | 10 | HTTP request timeout |
+| `max_retry_attempts` | 3 | Retry count for failed requests |
+| `retry_delay_seconds` | 1.0 | Delay between retries |
+| `log_level` | INFO | DEBUG, INFO, WARNING, ERROR, NONE |
+
+## Rate Limit Best Practices
+
+The rate limit is **10 requests per minute per client** (all tiers). Plan your API calls:
+
+```gdscript
+func _ready():
+    var connected = await Horizon.connect_to_server()
+    if not connected:
+        return
+
+    # Authenticate (1 request)
+    await Horizon.quickSignInAnonymous("Player")
+
+    # Startup batch (3 requests)
+    await Horizon.remoteConfig.getAllConfigs()
+    await Horizon.news.loadNews()
+    await Horizon.leaderboard.getTop(10)
+
+    # 6 requests remaining for gameplay actions
+```
+
+## Example Project
+
+The SDK includes a test scene demonstrating all features:
+
+```
+res://addons/horizon_sdk/examples/horizon_test_scene.tscn
+```

package/src/resources/quickstart/unity.md

@@ -0,0 +1,317 @@
+# Unity Quickstart Guide
+
+## Requirements
+
+- **Unity 2023.3+** (Unity 6)
+- horizOn API key (get one at [horizon.pm](https://horizon.pm))
+- Namespace: `PM.horizOn.Cloud`
+
+## Step 1: Import the SDK
+
+1. Download the horizOn Cloud SDK package
+2. Import into your project: `Assets/Plugins/ProjectMakers/horizOn/`
+3. The SDK is ready to use once imported (no plugin activation needed)
+
+## Step 2: Import Configuration
+
+1. Go to the [horizOn Dashboard](https://horizon.pm) and navigate to SDK Settings
+2. Download your `horizOn_config.json` file
+3. In Unity, go to **Window > horizOn > Config Importer**
+4. Select your downloaded JSON file
+5. The config is saved as a ScriptableObject in the SDK's Resources folder
+
+## Step 3: Initialize and Connect
+
+```csharp
+using PM.horizOn.Cloud.Core;
+using PM.horizOn.Cloud.Manager;
+
+public class GameManager : MonoBehaviour
+{
+    async void Start()
+    {
+        // Initialize the SDK (creates services, loads config)
+        HorizonApp.Initialize();
+
+        // Connect to the best available server
+        var server = new HorizonServer();
+        await server.Connect();
+
+        Debug.Log("Connected to horizOn!");
+    }
+}
+```
+
+## Step 4: Authenticate
+
+```csharp
+// Anonymous sign-up (auto-generates and caches token)
+await UserManager.Instance.SignUpAnonymous("PlayerName");
+
+// Check if signed in
+if (UserManager.Instance.IsSignedIn)
+{
+    var user = UserManager.Instance.CurrentUser;
+    Debug.Log($"Welcome, {user.DisplayName}! (ID: {user.UserId})");
+}
+```
+
+### Other Authentication Methods
+
+```csharp
+// Email sign-up
+await UserManager.Instance.SignUpEmail("user@example.com", "password123", "DisplayName");
+
+// Email sign-in
+await UserManager.Instance.SignInEmail("user@example.com", "password123");
+
+// Anonymous sign-in (restore cached session)
+await UserManager.Instance.RestoreAnonymousSession();
+
+// Google sign-in
+await UserManager.Instance.SignInGoogle("google-authorization-code");
+
+// Change display name
+await UserManager.Instance.ChangeName("NewName");
+
+// Sign out (preserves anonymous token by default)
+UserManager.Instance.SignOut();
+```
+
+## Step 5: Use Features
+
+### Leaderboards
+
+```csharp
+using PM.horizOn.Cloud.Manager;
+
+// Submit score (only updates if higher than previous best)
+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 your position
+var around = await LeaderboardManager.Instance.GetAround(5);
+```
+
+### Cloud Saves
+
+```csharp
+using PM.horizOn.Cloud.Manager;
+
+// Define your save structure
+[System.Serializable]
+public class GameData
+{
+    public int Level;
+    public int Coins;
+    public string[] Inventory;
+}
+
+// Save a typed object
+var saveData = new GameData { Level = 5, Coins = 1000, Inventory = new[] { "sword" } };
+await CloudSaveManager.Instance.SaveObject(saveData);
+
+// Load a typed object
+var loaded = await CloudSaveManager.Instance.LoadObject<GameData>();
+if (loaded != null)
+{
+    Debug.Log($"Level: {loaded.Level}, Coins: {loaded.Coins}");
+}
+
+// Save/load raw strings
+await CloudSaveManager.Instance.Save("{\"level\": 5}");
+string json = await CloudSaveManager.Instance.Load();
+
+// Binary data
+byte[] data = GetBinaryData();
+await CloudSaveManager.Instance.SaveBytes(data);
+byte[] loadedBytes = await CloudSaveManager.Instance.LoadBytes();
+```
+
+### Remote Config
+
+```csharp
+using PM.horizOn.Cloud.Manager;
+
+// 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);
+string version = await RemoteConfigManager.Instance.GetString("game_version", "1.0.0");
+
+// Get all configs at once (recommended at startup)
+var configs = await RemoteConfigManager.Instance.GetAllConfigs();
+```
+
+### News
+
+```csharp
+using PM.horizOn.Cloud.Manager;
+
+// Load news entries
+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 cached entry by ID
+var entry = NewsManager.Instance.GetNewsById("news-001");
+```
+
+### Gift Codes
+
+```csharp
+using PM.horizOn.Cloud.Manager;
+
+// Validate first (optional)
+bool? valid = await GiftCodeManager.Instance.Validate("PROMO2024");
+
+// Redeem
+var result = await GiftCodeManager.Instance.Redeem("PROMO2024");
+if (result != null && result.success)
+{
+    string giftData = result.giftData; // JSON string with rewards
+    Debug.Log($"Rewards: {giftData}");
+}
+```
+
+### Feedback
+
+```csharp
+using PM.horizOn.Cloud.Manager;
+
+// Bug report with auto device info
+await FeedbackManager.Instance.ReportBug(
+    title: "Crash on level 5",
+    message: "Game crashes when opening inventory"
+);
+
+// Feature request
+await FeedbackManager.Instance.RequestFeature(
+    title: "Dark mode",
+    message: "Please add dark mode option"
+);
+
+// General feedback with email
+await FeedbackManager.Instance.SendGeneral(
+    title: "Great game!",
+    message: "Really enjoying the new update",
+    email: "user@example.com"
+);
+```
+
+### User Logs
+
+```csharp
+using PM.horizOn.Cloud.Manager;
+
+// Requires BASIC tier or higher
+await UserLogManager.Instance.Info("Tutorial completed");
+await UserLogManager.Instance.Warn("Low memory detected");
+await UserLogManager.Instance.Error("Save failed", errorCode: "SAVE_001");
+```
+
+## Event System
+
+Subscribe to SDK events for reactive patterns:
+
+```csharp
+using PM.horizOn.Cloud.Core;
+using PM.horizOn.Cloud.Enums;
+using PM.horizOn.Cloud.Objects.Data;
+
+// Subscribe to auth events
+HorizonApp.Events.Subscribe<UserData>(EventKeys.UserSignInSuccess, OnUserSignedIn);
+HorizonApp.Events.Subscribe<string>(EventKeys.UserSignInFailed, OnSignInFailed);
+
+void OnUserSignedIn(UserData user)
+{
+    Debug.Log($"Welcome back, {user.DisplayName}!");
+}
+
+void OnSignInFailed(string error)
+{
+    Debug.Log($"Sign-in failed: {error}");
+}
+```
+
+## Error Handling
+
+```csharp
+// Check return values
+bool success = await UserManager.Instance.SignInEmail(email, password);
+if (!success)
+{
+    Debug.Log("Sign-in failed. Check credentials.");
+}
+
+// Cloud save with fallback
+var data = await CloudSaveManager.Instance.LoadObject<GameData>();
+if (data == null)
+{
+    data = new GameData(); // Use defaults on first load
+}
+```
+
+## Tier Limits
+
+| Feature | FREE | BASIC | PRO | ENTERPRISE |
+|---------|------|-------|-----|------------|
+| Cloud Save | 1 KB | 5 KB | 20 KB | 250 KB |
+| User Logs | No | Yes | Yes | Yes |
+| Rate Limit | 10/min | 10/min | 10/min | 10/min |
+
+## Efficient Startup Pattern
+
+Plan your API calls to stay within the rate limit:
+
+```csharp
+async void Start()
+{
+    // Initialize and connect
+    HorizonApp.Initialize();
+    await new HorizonServer().Connect();
+
+    // Startup loads (3 requests)
+    await UserManager.Instance.CheckAuth();
+    await RemoteConfigManager.Instance.GetAllConfigs();
+    await NewsManager.Instance.LoadNews();
+
+    // 7 requests remaining for gameplay actions
+}
+```
+
+## Project Structure
+
+```
+Assets/Plugins/ProjectMakers/horizOn/
+├── CloudSDK/
+│   ├── Core/        # HorizonApp, HorizonServer, HorizonConfig
+│   ├── Manager/     # Feature managers (UserManager, LeaderboardManager, etc.)
+│   ├── Service/     # EventService, NetworkService, LogService
+│   ├── Objects/     # Data models, requests, responses
+│   └── Resources/   # HorizonConfig.asset
+```
+
+## Common Status Codes
+
+| Code | Meaning | Action |
+|------|---------|--------|
+| 400 | Bad Request | Check parameters |
+| 401 | Unauthorized | Verify API key |
+| 403 | Forbidden | Check tier/permissions |
+| 429 | Rate Limited | Implement caching, wait and retry |