horizon-mcp 0.0.0-development

package/src/resources/docs/auth.md

@@ -0,0 +1,280 @@
+# Authentication
+
+## Overview
+
+horizOn supports three authentication methods:
+
+| Method | Type Value | Description |
+|--------|-----------|-------------|
+| **Anonymous** | `ANONYMOUS` | Token-based, no credentials needed. Ideal for frictionless onboarding. |
+| **Email** | `EMAIL` | Traditional email/password. Supports verification and password reset. |
+| **Google** | `GOOGLE` | OAuth-based. Requires Google authorization code from OAuth flow. |
+
+## Endpoints
+
+### Sign Up
+
+**`POST /api/v1/app/user-management/signup`**
+
+Creates a new user account.
+
+**Request Body:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `type` | string | Yes | `ANONYMOUS`, `EMAIL`, or `GOOGLE` |
+| `username` | string | No | Display name (1-50 chars) |
+| `email` | string | Email only | User's email address |
+| `password` | string | Email only | Password (4-32 chars) |
+| `anonymousToken` | string | Anonymous only | Unique token (max 32 chars). Auto-generated if omitted. |
+| `googleAuthorizationCode` | string | Google only | OAuth authorization code |
+| `googleRedirectUri` | string | No | Redirect URI used in OAuth flow |
+
+**Response (200):**
+
+```json
+{
+  "userId": "abc123",
+  "username": "Player1",
+  "email": "user@example.com",
+  "isAnonymous": false,
+  "isVerified": true,
+  "anonymousToken": null,
+  "createdAt": "2025-01-15T10:30:00Z"
+}
+```
+
+**Error Codes:** `401` invalid API key, `409` user already exists.
+
+---
+
+### Sign In
+
+**`POST /api/v1/app/user-management/signin`**
+
+Authenticates an existing user.
+
+**Request Body:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `type` | string | Yes | `EMAIL`, `ANONYMOUS`, or `GOOGLE` |
+| `email` | string | Email only | User's email |
+| `password` | string | Email only | User's password |
+| `anonymousToken` | string | Anonymous only | The token from signup |
+| `googleAuthorizationCode` | string | Google only | OAuth code |
+| `googleRedirectUri` | string | No | Redirect URI |
+
+**Response (200):**
+
+```json
+{
+  "userId": "abc123",
+  "username": "Player1",
+  "email": "user@example.com",
+  "accessToken": "session-token-here",
+  "authStatus": "AUTHENTICATED",
+  "message": null
+}
+```
+
+`authStatus` values: `AUTHENTICATED` (success), `FAILED`, `NOT_VERIFIED`.
+
+**Error Codes:** `401` invalid API key, `403` user not verified, `404` user not found.
+
+---
+
+### Check Auth
+
+**`POST /api/v1/app/user-management/check-auth`**
+
+Validates whether a session token is still active.
+
+**Request Body:**
+
+```json
+{
+  "userId": "abc123",
+  "sessionToken": "session-token-here"
+}
+```
+
+**Response (200):**
+
+```json
+{
+  "userId": "abc123",
+  "isAuthenticated": true,
+  "authStatus": "AUTHENTICATED",
+  "message": null
+}
+```
+
+---
+
+### Change Name
+
+**`POST /api/v1/app/user-management/change-name`**
+
+Changes the display name of an authenticated user.
+
+**Request Body:**
+
+```json
+{
+  "userId": "abc123",
+  "sessionToken": "session-token-here",
+  "newName": "NewDisplayName"
+}
+```
+
+**Response (200):**
+
+```json
+{
+  "isAuthenticated": true,
+  "authStatus": "AUTHENTICATED"
+}
+```
+
+---
+
+### Verify Email
+
+**`POST /api/v1/app/user-management/verify-email`**
+
+Verifies a user's email address using a token sent via email.
+
+**Request Body:**
+
+```json
+{
+  "token": "verification-token-from-email"
+}
+```
+
+---
+
+### Forgot Password
+
+**`POST /api/v1/app/user-management/forgot-password`**
+
+Sends a password reset email to the user.
+
+**Request Body:**
+
+```json
+{
+  "email": "user@example.com"
+}
+```
+
+---
+
+### Reset Password
+
+**`POST /api/v1/app/user-management/reset-password`**
+
+Resets the user's password using a reset token.
+
+**Request Body:**
+
+```json
+{
+  "token": "reset-token-from-email",
+  "newPassword": "newSecurePassword"
+}
+```
+
+## Code Examples
+
+### Godot (GDScript)
+
+```gdscript
+# Anonymous sign-up
+await Horizon.auth.signUpAnonymous("PlayerName")
+
+# Email sign-up
+await Horizon.auth.signUpEmail("user@example.com", "password", "Username")
+
+# Email sign-in
+await Horizon.auth.signInEmail("user@example.com", "password")
+
+# Restore anonymous session from cached token
+await Horizon.auth.restoreAnonymousSession()
+
+# Quick anonymous sign-in (restores or creates new)
+await Horizon.quickSignInAnonymous("Player1")
+
+# Check if signed in
+if Horizon.isSignedIn():
+    var user = Horizon.getCurrentUser()
+    print("Welcome, %s!" % user.displayName)
+
+# Change display name
+await Horizon.auth.changeName("NewName")
+
+# Sign out (preserves anonymous token by default)
+Horizon.auth.signOut()
+
+# Listen for auth events
+Horizon.auth.signin_completed.connect(func(user): print("Signed in: %s" % user.userId))
+Horizon.auth.signin_failed.connect(func(error): print("Error: %s" % error))
+```
+
+### Unity (C#)
+
+```csharp
+using PM.horizOn.Cloud.Manager;
+
+// Anonymous sign-up
+await UserManager.Instance.SignUpAnonymous("PlayerName");
+
+// Email sign-up
+await UserManager.Instance.SignUpEmail("user@example.com", "password", "DisplayName");
+
+// Email sign-in
+await UserManager.Instance.SignInEmail("user@example.com", "password");
+
+// Restore anonymous session
+await UserManager.Instance.RestoreAnonymousSession();
+
+// Check if signed in
+if (UserManager.Instance.IsSignedIn)
+{
+    var user = UserManager.Instance.CurrentUser;
+    Debug.Log($"Welcome, {user.DisplayName}!");
+}
+
+// Change name
+await UserManager.Instance.ChangeName("NewName");
+
+// Sign out
+UserManager.Instance.SignOut();
+```
+
+### REST (cURL)
+
+```bash
+# Anonymous signup
+curl -X POST https://horizon.pm/api/v1/app/user-management/signup \
+  -H "X-API-Key: YOUR_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"type": "ANONYMOUS", "username": "Player1"}'
+
+# Email signin
+curl -X POST https://horizon.pm/api/v1/app/user-management/signin \
+  -H "X-API-Key: YOUR_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"type": "EMAIL", "email": "user@example.com", "password": "pass123"}'
+```
+
+## Common Errors
+
+| Status | Cause | Solution |
+|--------|-------|----------|
+| 401 | Invalid API key | Check `X-API-Key` header |
+| 403 | User not verified | Complete email verification first |
+| 404 | User not found | User may not exist, try signup |
+| 409 | User already exists | Use signin instead of signup |
+| 429 | Rate limit exceeded | Wait before retrying (10 req/min limit) |

package/src/resources/docs/cloud-save.md

@@ -0,0 +1,180 @@
+# Cloud Save
+
+## Overview
+
+Cloud Save allows players to persist their game data across devices and sessions. horizOn supports two modes:
+
+- **JSON mode** — Send structured data as a UTF-8 string via `application/json`
+- **Binary mode** — Send raw bytes via `application/octet-stream`
+
+## Tier Limits
+
+Data size is limited by the account's pricing tier:
+
+| Tier | Max Save Size |
+|------|--------------|
+| FREE | 1 KB |
+| BASIC | 5 KB |
+| PRO | 20 KB |
+| ENTERPRISE | 250 KB |
+
+If the save data exceeds the tier limit, the save request will fail with a `403` error.
+
+## Endpoints
+
+### Save Data
+
+**`POST /api/v1/app/cloud-save/save`**
+
+Saves user data to the cloud. Overwrites any existing save.
+
+**Request Body (JSON mode):**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `userId` | string | Yes | The user's ID |
+| `saveData` | string | Yes | Data to save (JSON string) |
+
+**Response (200):**
+
+```json
+{
+  "success": true,
+  "dataSizeBytes": 256
+}
+```
+
+**Binary mode:** `POST /api/v1/app/cloud-save/save?userId={userId}` with `Content-Type: application/octet-stream` and raw bytes in the body.
+
+---
+
+### Load Data
+
+**`POST /api/v1/app/cloud-save/load`**
+
+Loads the user's saved data from the cloud.
+
+**Request Body (JSON mode):**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `userId` | string | Yes | The user's ID |
+
+**Response (200):**
+
+```json
+{
+  "found": true,
+  "saveData": "{\"level\":5,\"coins\":1000}"
+}
+```
+
+If no save data exists:
+
+```json
+{
+  "found": false,
+  "saveData": null
+}
+```
+
+**Binary mode:** `GET /api/v1/app/cloud-save/load?userId={userId}` with `Accept: application/octet-stream`.
+
+## Code Examples
+
+### Godot (GDScript)
+
+```gdscript
+# Save a Dictionary (recommended approach)
+await Horizon.cloudSave.saveObject({"level": 5, "coins": 1000, "inventory": ["sword", "shield"]})
+
+# Load as Dictionary
+var data: Dictionary = await Horizon.cloudSave.loadObject()
+if not data.is_empty():
+    var level = data.get("level", 1)
+    var coins = data.get("coins", 0)
+
+# Save raw JSON string
+await Horizon.cloudSave.saveData('{"level": 5}')
+
+# Load raw JSON string
+var json: String = await Horizon.cloudSave.loadData()
+
+# Binary data support
+await Horizon.cloudSave.saveBytes(my_packed_byte_array)
+var bytes: PackedByteArray = await Horizon.cloudSave.loadBytes()
+
+# Save any Variant using Godot serialization
+await Horizon.cloudSave.saveVariant(my_resource)
+var loaded = await Horizon.cloudSave.loadVariant()
+
+# Listen for events
+Horizon.cloudSave.data_saved.connect(func(size): print("Saved %d bytes" % size))
+Horizon.cloudSave.data_loaded.connect(func(data): print("Data loaded"))
+Horizon.cloudSave.data_save_failed.connect(func(error): print("Save failed: %s" % error))
+```
+
+### Unity (C#)
+
+```csharp
+using PM.horizOn.Cloud.Manager;
+
+// Save a typed object as JSON
+[System.Serializable]
+public class GameData
+{
+    public int Level;
+    public int Coins;
+    public string[] Inventory;
+}
+
+var saveData = new GameData { Level = 5, Coins = 1000, Inventory = new[] { "sword", "shield" } };
+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 string
+await CloudSaveManager.Instance.Save("{\"level\": 5}");
+string json = await CloudSaveManager.Instance.Load();
+
+// Binary data support
+byte[] data = GetBinaryData();
+await CloudSaveManager.Instance.SaveBytes(data);
+byte[] loadedBytes = await CloudSaveManager.Instance.LoadBytes();
+```
+
+### REST (cURL)
+
+```bash
+# Save data (JSON mode)
+curl -X POST https://horizon.pm/api/v1/app/cloud-save/save \
+  -H "X-API-Key: YOUR_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"userId": "user123", "saveData": "{\"level\":5,\"coins\":1000}"}'
+
+# Load data (JSON mode)
+curl -X POST https://horizon.pm/api/v1/app/cloud-save/load \
+  -H "X-API-Key: YOUR_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"userId": "user123"}'
+```
+
+## Best Practices
+
+- **Save on meaningful events** — Save when a level is completed, not on every frame or action.
+- **Compress large saves** — If nearing the tier limit, consider compressing JSON data.
+- **Handle "not found" gracefully** — On first load, `found` will be `false`. Initialize defaults.
+- **Use typed objects** — Both SDKs support saving/loading typed objects directly.
+
+## Common Errors
+
+| Status | Cause | Solution |
+|--------|-------|----------|
+| 401 | Invalid API key | Check `X-API-Key` header |
+| 403 | Save exceeds tier limit | Reduce data size or upgrade tier |
+| 429 | Rate limit exceeded | Batch saves, save less frequently |

package/src/resources/docs/feedback.md

@@ -0,0 +1,126 @@
+# User Feedback
+
+## Overview
+
+The User Feedback feature lets players submit bug reports, feature requests, and general feedback directly from your app. All submissions are visible in the horizOn Dashboard. Optional device information can be attached to help with debugging.
+
+## Endpoints
+
+### Submit Feedback
+
+**`POST /api/v1/app/user-feedback/submit`**
+
+Submits a feedback entry.
+
+**Request Body:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `title` | string | Yes | Feedback title (1-100 characters) |
+| `message` | string | Yes | Feedback message (1-2048 characters) |
+| `userId` | string | Yes | The user's ID |
+| `email` | string | No | Contact email for follow-up |
+| `category` | string | No | Category: `BUG`, `FEATURE`, or `GENERAL` |
+| `deviceInfo` | string | No | Device information (max 500 characters) |
+
+**Response (200):**
+
+```
+"ok"
+```
+
+## Code Examples
+
+### Godot (GDScript)
+
+```gdscript
+# Submit general feedback
+await Horizon.feedback.submit("Great Game!", "I love the new features.", "GENERAL")
+
+# Submit bug report with auto device info
+await Horizon.feedback.submitBugReport("Crash on Level 5", "Game crashes when opening inventory")
+
+# Submit feature request
+await Horizon.feedback.submitFeatureRequest("Dark Mode", "Please add a dark mode option")
+
+# Full submit with all options
+await Horizon.feedback.submit(
+    "Bug Title",
+    "Detailed description of the bug...",
+    "BUG",
+    "user@example.com",  # optional email
+    true                  # include device info
+)
+
+# Listen for events
+Horizon.feedback.feedback_submitted.connect(func(): print("Feedback sent!"))
+Horizon.feedback.feedback_submit_failed.connect(func(error): print("Failed: %s" % error))
+```
+
+**Automatic device info includes:** OS, model, Godot version, screen resolution, renderer, and memory usage.
+
+### Unity (C#)
+
+```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
+await FeedbackManager.Instance.SendGeneral(
+    title: "Great game!",
+    message: "Really enjoying the new update"
+);
+
+// Full submit with all options
+await FeedbackManager.Instance.Submit(
+    title: "Bug Title",
+    category: "BUG",
+    message: "Detailed description...",
+    email: "user@example.com",
+    includeDeviceInfo: true
+);
+```
+
+**Automatic device info includes:** Unity version, OS, device model, and graphics device.
+
+### REST (cURL)
+
+```bash
+curl -X POST https://horizon.pm/api/v1/app/user-feedback/submit \
+  -H "X-API-Key: YOUR_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "title": "Bug Report",
+    "message": "Game crashes on level 5",
+    "userId": "user123",
+    "email": "user@example.com",
+    "category": "BUG",
+    "deviceInfo": "Windows 11 | RTX 3080 | 16GB RAM"
+  }'
+```
+
+## Best Practices
+
+- **Include device info for bug reports** — Both SDKs auto-collect device info; enable it for bug reports.
+- **Use categories** — Categorize feedback as `BUG`, `FEATURE`, or `GENERAL` for easier triage in the Dashboard.
+- **Add contact email** — Include the user's email if they want to receive follow-up responses.
+- **Rate limit awareness** — Feedback submission counts toward the 10 req/min limit.
+
+## Common Errors
+
+| Status | Cause | Solution |
+|--------|-------|----------|
+| 400 | Missing required fields | Ensure `title`, `message`, and `userId` are provided |
+| 401 | Invalid API key | Check `X-API-Key` header |
+| 429 | Rate limit exceeded | Limit feedback submissions per session |