@layers/amba 1.1.0 → 4.0.2

package/skill-bundle/references/gamification.md

@@ -0,0 +1,316 @@
+# Gamification
+
+Five primitives that turn a flat app into something users come back to: XP rules (auto-award points on a tracked event), achievements (badges that unlock on criteria), streaks (consecutive-period qualification), leaderboards (rank by metric), and challenges (time-bounded goals with rewards). All five are define-once / use-many: you create the definitions via MCP, the SDK qualifies / claims / reads against them at runtime.
+
+The pattern is always:
+
+1. Agent (via MCP): define the rule / achievement / streak / etc.
+2. Client SDK at runtime: track the event (`Amba.events.track(...)`) or qualify (`Amba.streaks.qualify(...)` / `Amba.challenges.claim(...)`).
+3. Server: auto-evaluate, mutate user state, return updated progress.
+
+## MCP tools
+
+### XP rules
+
+| Tool | Purpose | Example args |
+| --- | --- | --- |
+| `amba_xp_rules_create` / `amba_create_xp_rule` | Auto-award XP on a matching event. | `{ project_id, name: "Workout Completed", event_name: "workout_completed", xp_amount: 50, max_per_day: 5, cooldown_seconds: 60 }` |
+| `amba_xp_rules_list` / `amba_list_xp_rules` | List all XP rules. | `{ project_id }` |
+| `amba_xp_update_rule` | Edit a rule. | `{ project_id, rule_id, xp_amount: 75 }` |
+| `amba_xp_delete_rule` | Delete a rule. | `{ project_id, rule_id }` |
+| `amba_xp_list_users` | List users sorted by XP (for an admin panel or smoke-test). | `{ project_id, limit: 50 }` |
+| `amba_users_get_xp` / `amba_get_user_xp` | Read a specific user's XP total + level. | `{ project_id, user_id }` |
+
+### Achievements
+
+| Tool | Purpose | Example args |
+| --- | --- | --- |
+| `amba_achievements_create` / `amba_create_achievement` | Define an achievement that unlocks on criteria. | `{ project_id, key: "first_workout", name: "First Workout", description: "Complete your first workout", xp_reward: 100, criteria: { event: "workout_completed", count: 1 } }` |
+| `amba_achievements_list` / `amba_list_achievements` | List all achievements. | `{ project_id }` |
+| `amba_achievements_get` / `amba_get_achievement` | Read one. | `{ project_id, achievement_id }` |
+| `amba_achievements_update` / `amba_update_achievement` | Edit an achievement. | `{ project_id, achievement_id, xp_reward: 150 }` |
+| `amba_achievements_delete` / `amba_delete_achievement` | Delete. | `{ project_id, achievement_id }` |
+
+Common criteria shapes (the schema is permissive — the server validates against the available metrics):
+
+```jsonc
+// Count-based
+{ "event": "workout_completed", "count": 5 }
+
+// Streak-based
+{ "streak_key": "daily_workout", "min_length": 7 }
+
+// XP-based
+{ "xp_total": 5000 }
+
+// Catalog-item-based
+{ "item_owned": "premium_theme" }
+```
+
+### Streaks
+
+| Tool | Purpose | Example args |
+| --- | --- | --- |
+| `amba_streaks_create` / `amba_create_streak` | Define a streak — what event qualifies, what period, freeze rules. | `{ project_id, key: "daily_workout", name: "Daily Workout", qualifying_event: "workout_completed", period: "daily", grace_period_hours: 6, freeze_enabled: true, max_freezes: 3 }` |
+| `amba_streaks_list` | List streaks. | `{ project_id }` |
+| `amba_streaks_update` | Edit a streak definition. | `{ project_id, streak_id, max_freezes: 5 }` |
+| `amba_streaks_delete` | Delete. | `{ project_id, streak_id }` |
+
+The `key` is **immutable** after creation (the SDK identifies streaks by key, not UUID — changing it breaks live `Amba.streaks.qualify(...)` calls). Keys: lowercase letters, digits, `_`, `-`, 1-64 chars.
+
+### Leaderboards
+
+| Tool | Purpose | Example args |
+| --- | --- | --- |
+| `amba_leaderboards_create` / `amba_create_leaderboard` | Define a leaderboard. | `{ project_id, name: "Weekly XP", metric: "xp", period: "weekly", max_entries: 100 }` |
+| `amba_leaderboards_list` / `amba_list_leaderboards` | List. | `{ project_id }` |
+| `amba_leaderboards_get` / `amba_get_leaderboard` | Read the current top entries. | `{ project_id, leaderboard_id, limit: 50 }` |
+| `amba_leaderboards_get_definition` / `amba_get_leaderboard_definition` | Read the definition without the entries (cheap). | `{ project_id, leaderboard_id }` |
+| `amba_leaderboards_update` / `amba_update_leaderboard` | Edit the period / max_entries. | `{ project_id, leaderboard_id, max_entries: 250 }` |
+| `amba_leaderboards_delete` / `amba_delete_leaderboard` | Delete. | `{ project_id, leaderboard_id }` |
+
+Metrics: `xp`, `streak`, `custom`. For `custom`, pass `custom_event` (e.g. `"workout_completed"`) — the leaderboard ranks by the count of that event in the period. Periods: `all_time`, `daily`, `weekly`, `monthly`.
+
+### Challenges
+
+| Tool | Purpose | Example args |
+| --- | --- | --- |
+| `amba_challenges_create` / `amba_create_challenge` | Define a time-bounded challenge with a goal + reward. | `{ project_id, name: "Spring Sprint", description: "5 workouts in 7 days", goal_event: "workout_completed", goal_count: 5, starts_at: "2026-06-01T00:00:00Z", ends_at: "2026-06-08T00:00:00Z", reward: { xp: 500, currency: { code: "gems", amount: 50 } } }` |
+| `amba_challenges_list` / `amba_list_challenges` | List. | `{ project_id }` |
+| `amba_challenges_get` / `amba_get_challenge` | Read. | `{ project_id, challenge_id }` |
+| `amba_challenges_update` / `amba_update_challenge` | Edit. | `{ project_id, challenge_id, ends_at: "..." }` |
+| `amba_challenges_delete` / `amba_delete_challenge` | Delete. | `{ project_id, challenge_id }` |
+| `amba_challenges_list_participants` / `amba_list_challenge_participants` | List opt-in participants + progress. | `{ project_id, challenge_id, limit: 100 }` |
+
+## SDK init per stack
+
+`Amba.configure(...)` runs first — see `identity.md`. The snippets below show only the gamification calls.
+
+### Expo
+
+```tsx
+import { Amba } from '@layers/amba-expo';
+
+// 1. Track the event that drives XP / achievements / streaks / leaderboards.
+//    XP rules + achievements + streaks + leaderboards all match on event_name,
+//    so a single track() call can fire all of them.
+async function onWorkoutCompleted(durationMinutes: number) {
+  await Amba.events.track('workout_completed', { duration_minutes: durationMinutes });
+
+  // 2. Qualify the streak. The server keeps the consecutive-period count;
+  //    the SDK returns the updated state.
+  const streak = await Amba.streaks.qualify('daily_workout');
+  // streak.current_count, streak.longest_count, streak.status, streak.freezes_remaining
+
+  // 3. Show the user any newly-unlocked achievements (poll progress).
+  const progress = await Amba.achievements.getProgress();
+  const newlyUnlocked = progress.filter(p => p.unlocked && p.unlocked_within_seconds < 5);
+
+  // 4. Show their current XP balance.
+  const xp = await Amba.xp.getBalance();
+  // xp.total, xp.level, xp.next_level_xp
+}
+
+// 5. Read the leaderboard for a UI screen.
+async function loadLeaderboard(leaderboardKey: string) {
+  const entries = await Amba.leaderboards.getEntries(leaderboardKey, 50);
+  const myRank = await Amba.leaderboards.getMyRank(leaderboardKey);
+}
+
+// 6. Active challenges (e.g. for a "Challenges" tab).
+async function loadChallenges() {
+  const active = await Amba.challenges.getActive();
+  for (const c of active) {
+    const progress = await Amba.challenges.getProgress(c.id);
+    if (progress.completed && !progress.claimed) {
+      await Amba.challenges.claim(c.id);
+    }
+  }
+}
+```
+
+### React Native (bare)
+
+```tsx
+import { Amba } from '@layers/amba-react-native';
+
+await Amba.events.track('workout_completed', { duration_minutes: 30 });
+const streak = await Amba.streaks.qualify('daily_workout');
+const achievements = await Amba.achievements.getProgress();
+const entries = await Amba.leaderboards.getEntries('Weekly XP', 50);
+const active = await Amba.challenges.getActive();
+```
+
+### Web (browser / Next.js / Vite)
+
+```ts
+import { Amba } from '@layers/amba-web';
+
+await Amba.events.track('lesson_completed', { course_id: 'algebra-1' });
+const streak = await Amba.streaks.qualify('daily_lesson');
+const xp = await Amba.xp.getBalance();
+const top = await Amba.leaderboards.getEntries('Weekly XP', 100);
+const myRank = await Amba.leaderboards.getMyRank('Weekly XP');
+```
+
+With React hooks (`@layers/amba-react`) — there is no dedicated `useXp` / `useStreak` hook in 1.0, so wrap the SDK calls in your own `useEffect`:
+
+```tsx
+import { useEffect, useState } from 'react';
+import { Amba } from '@layers/amba-web';
+
+export function useStreak(key: string) {
+  const [streak, setStreak] = useState<Streak | null>(null);
+  const refresh = async () => {
+    const all = await Amba.streaks.getAll();
+    setStreak(all.find(s => s.key === key) ?? null);
+  };
+  useEffect(() => { refresh(); }, [key]);
+  return { streak, refresh };
+}
+```
+
+### iOS (Swift)
+
+```swift
+import Amba
+
+try await Amba.events.track("workout_completed", properties: ["duration_minutes": 30])
+let streak = try await Amba.streaks.qualify(streakKey: "daily_workout")
+let progress = try await Amba.achievements.getProgress()
+let xp = try await Amba.xp.getBalance()
+let entries = try await Amba.leaderboards.getEntries(key: "Weekly XP", limit: 50)
+let myRank = try await Amba.leaderboards.getMyRank(key: "Weekly XP")
+let active = try await Amba.challenges.getActive()
+for challenge in active {
+    let p = try await Amba.challenges.getProgress(id: challenge.id)
+    if p.completed && !p.claimed {
+        _ = try await Amba.challenges.claim(id: challenge.id)
+    }
+}
+```
+
+### Android (Kotlin)
+
+```kotlin
+Amba.events.track("workout_completed", mapOf("duration_minutes" to 30))
+val streak = Amba.streaks.qualify("daily_workout")
+val progress = Amba.achievements.getProgress()
+val xp = Amba.xp.getBalance()
+val entries = Amba.leaderboards.getEntries("Weekly XP", limit = 50)
+val myRank = Amba.leaderboards.getMyRank("Weekly XP")
+val active = Amba.challenges.getActive()
+for (c in active) {
+    val p = Amba.challenges.getProgress(c.id)
+    if (p.completed && !p.claimed) Amba.challenges.claim(c.id)
+}
+```
+
+### Flutter
+
+```dart
+import 'package:amba/amba.dart';
+
+await Amba.events.track('workout_completed', {'duration_minutes': 30});
+final streak = await Amba.streaks.qualify('daily_workout');
+final progress = await Amba.achievements.getProgress();
+final xp = await Amba.xp.getBalance();
+final entries = await Amba.leaderboards.getEntries('Weekly XP', limit: 50);
+final myRank = await Amba.leaderboards.getMyRank('Weekly XP');
+final active = await Amba.challenges.getActive();
+for (final c in active) {
+  final p = await Amba.challenges.getProgress(c.id);
+  if (p.completed && !p.claimed) {
+    await Amba.challenges.claim(c.id);
+  }
+}
+```
+
+## Common follow-ups
+
+Batch into one or two questions.
+
+1. **What's the qualifying event for XP / achievements / streaks?** Most preset answers below — accept the suggestion or override:
+   - fitness: `workout_completed`
+   - education: `lesson_completed`
+   - game: `level_completed` (or `match_played`)
+   - productivity: `task_completed`
+   - content_creator: `post_published`
+   - ai_chatbot: `prompt_sent`
+
+2. **Default XP per qualifying event?** (defaults to `50`)
+
+3. **Streak period?**
+   - Daily (recommended)
+   - Weekly
+   - None (skip streaks)
+
+4. **Streak freezes?**
+   - 3 freezes/month (recommended — covers the occasional missed day without breaking)
+   - Hard mode (no freezes)
+   - None — don't enable freezes
+
+5. **Leaderboard scope:** (multi-select)
+   - [x] Weekly (recommended — rotates, never gets stale)
+   - [ ] All-time
+   - [ ] Daily (high-engagement apps only — daily resets feel relentless)
+   - [ ] Monthly
+
+6. **Which achievements to seed?** Defaults per preset (offer to create, or skip):
+
+   **fitness:**
+   - `first_workout` — Complete 1 workout (+100 XP)
+   - `week_warrior` — 7-day streak (+250 XP)
+   - `century_club` — 100 workouts (+1000 XP)
+
+   **education:**
+   - `first_lesson` — Complete 1 lesson (+100 XP)
+   - `dedicated_learner` — 7-day streak (+250 XP)
+   - `course_complete` — Finish a course (+1000 XP, criteria: `event: course_completed, count: 1`)
+
+   **game:**
+   - `first_win` — Win 1 match (+100 XP)
+   - `streak_master` — 5 wins in a row (custom criteria)
+   - `level_50` — Reach level 50 (`xp_total: 50000`)
+
+   **productivity:**
+   - `first_task` — Complete 1 task (+100 XP)
+   - `inbox_zero` — Clear all tasks (criteria: `event: inbox_zeroed, count: 1`)
+   - `monthly_warrior` — 30-day streak (+1000 XP)
+
+   For other presets, ask the user to confirm 3 achievements they want or skip.
+
+7. **Challenges:** seed an example weekly challenge?
+   - Yes — "5 workouts this week" (or equivalent for the preset) ending next Sunday
+   - No
+
+## Re-run behavior
+
+1. Read `.amba/wired.json` `surfaces.gamification`:
+
+   ```json
+   {
+     "surfaces": {
+       "gamification": {
+         "xp_rules": ["Workout Completed"],
+         "achievements": ["first_workout", "week_warrior", "century_club"],
+         "streaks": ["daily_workout"],
+         "leaderboards": ["Weekly XP"],
+         "challenges": []
+       }
+     }
+   }
+   ```
+
+2. Before creating anything, list-then-diff:
+   - `amba_xp_rules_list` — match on `name`. If exists, ask to update (`amba_xp_update_rule`) or skip.
+   - `amba_achievements_list` — match on `key`. Achievement `key` is unique per project; collision → skip or update.
+   - `amba_streaks_list` — match on `key`. **Never recreate** a streak with an existing key — the SDK calls would silently target a stale definition. Update instead.
+   - `amba_leaderboards_list` — match on `name`. Collision → ask.
+   - `amba_challenges_list` — match on `name + starts_at`. New challenge with same name + different date is fine; same name + overlapping date → ask.
+
+3. In the entry file: detect existing `Amba.events.track('<event_name>')` calls. If they already exist, don't add another. If they're missing for an event tied to a new XP rule, add a sample comment / TODO showing where to call `Amba.events.track`.
+
+4. Update `wired.json` — append to each list, never replace.
+
+5. If the user asks to "remove gamification": offer a soft path — pause XP rules and unschedule challenges rather than deleting definitions (deletion is irreversible and loses historical user XP / unlocks).