@layers/amba 1.0.1 → 4.0.2

package/skill-bundle/references/economy.md

@@ -0,0 +1,331 @@
+# Economy
+
+Virtual currencies, the catalog of things they buy, stores (curated catalog subsets, possibly segment-gated), and the per-user inventory. Currencies come in two flavors: **soft** (earned in-app, e.g. `gold` / `coins` / `gems`) and **premium** (bought with real money via App Store / Play / Stripe / RevenueCat). Both flow through the same APIs; the difference is whether real money or a tracked event is the input.
+
+Pattern:
+
+1. Agent (MCP): create a currency, create catalog items, set prices, group items into one or more stores.
+2. Client SDK: read the catalog, read the store, show the offer, call `Amba.stores.purchase(...)` (real money) or `Amba.inventory.purchase(...)` (soft currency). The server debits the currency / records the IAP receipt and grants the item.
+
+Real-money purchases need a billing integration configured separately — see `references/infrastructure.md` for `amba_integrations_configure` with RevenueCat. Without RevenueCat, premium currencies still work (you grant them manually) but `Amba.stores.purchase(...)` for IAP-backed items won't validate.
+
+## MCP tools
+
+### Currencies
+
+| Tool | Purpose | Example args |
+| --- | --- | --- |
+| `amba_currencies_create` / `amba_create_currency` | Define a currency. Soft or premium, with optional auto-recharge (hearts / energy mechanics). | `{ project_id, code: "gems", name: "Gems", is_premium: false, initial_balance: 0, max_balance: null }` |
+| `amba_currencies_list` / `amba_list_currencies` | List currencies. | `{ project_id }` |
+| `amba_currencies_update` / `amba_update_currency` | Edit a currency (rename, change caps, change auto-recharge). | `{ project_id, currency_id, max_balance: 10000 }` |
+| `amba_currencies_delete` / `amba_delete_currency` | Delete a currency (irreversible — users lose their balance). | `{ project_id, currency_id }` |
+| `amba_currencies_grant` / `amba_grant_currency` | Grant currency to a specific user (rewards, refunds, admin adjustments). | `{ project_id, app_user_id, currency_code: "gems", amount: 100, reason: "welcome_bonus" }` |
+| `amba_currencies_get_transactions` / `amba_get_currency_transactions` | Per-user transaction ledger. | `{ project_id, user_id, currency_code: "gems", limit: 100 }` |
+
+#### Currency grant rules (auto-grants)
+
+| Tool | Purpose | Example args |
+| --- | --- | --- |
+| `amba_currency_grant_rules_create` | Auto-grant currency on an event (e.g. 10 gems per `workout_completed`). | `{ project_id, currency_code: "gems", event_name: "workout_completed", amount: 10, max_per_day: 5 }` |
+| `amba_currency_grant_rules_list` | List grant rules. | `{ project_id, currency_code }` |
+| `amba_currency_grant_rules_delete` | Delete a grant rule. | `{ project_id, rule_id }` |
+
+#### Hearts / energy (auto-recharge)
+
+Set `auto_recharge_amount` + `auto_recharge_interval_hours` when creating the currency:
+
+```jsonc
+{
+  "project_id": "...",
+  "code": "hearts",
+  "name": "Hearts",
+  "is_premium": false,
+  "initial_balance": 5,
+  "max_balance": 5,
+  "auto_recharge_amount": 1,
+  "auto_recharge_interval_hours": 4
+}
+```
+
+This is the Duolingo pattern: spend a heart on failure, regenerate 1 heart every 4 hours, capped at 5.
+
+### Catalog
+
+| Tool | Purpose | Example args |
+| --- | --- | --- |
+| `amba_catalog_items_create` / `amba_create_catalog_item` | Create a catalog item. | `{ project_id, key: "premium_theme", name: "Dark Pro Theme", item_type: "durable", description: "Pitch-black UI with magenta accents", icon_url: "https://...", category: "themes" }` |
+| `amba_catalog_list` / `amba_list_catalog` | List the catalog. | `{ project_id }` |
+| `amba_catalog_items_get` / `amba_get_catalog_item` | Read one item. | `{ project_id, item_id }` |
+| `amba_catalog_items_update` / `amba_update_catalog_item` | Edit an item. | `{ project_id, item_id, name: "..." }` |
+| `amba_catalog_items_delete` / `amba_delete_catalog_item` | Delete an item. | `{ project_id, item_id }` |
+| `amba_catalog_items_set_price` / `amba_set_item_price` | Set or update a price (per currency, or in-app product id for real money). | `{ project_id, item_id, currency_code: "gems", amount: 200 }` or `{ project_id, item_id, iap_product_id: "com.example.premium_theme" }` |
+| `amba_catalog_items_delete_price` / `amba_delete_catalog_price` | Delete a price (e.g. you no longer accept gems for this item). | `{ project_id, item_id, price_id }` |
+| `amba_catalog_bundles_add_item` / `amba_add_catalog_bundle_item` | Add an item to a bundle (a bundle is itself a catalog item with `item_type: "bundle"`). | `{ project_id, bundle_item_id, child_item_id, quantity: 1 }` |
+| `amba_catalog_bundles_remove_item` / `amba_remove_catalog_bundle_item` | Remove an item from a bundle. | `{ project_id, bundle_item_id, child_item_id }` |
+
+Item types:
+- `durable` — owned forever (themes, character skins, ad removal).
+- `consumable` — used up (extra lives, hint packs, energy refills).
+- `bundle` — contains other items (starter pack with 100 gems + 5 hints + 1 theme).
+
+### Stores
+
+| Tool | Purpose | Example args |
+| --- | --- | --- |
+| `amba_stores_create` / `amba_create_store` | Create a store (curated catalog subset). Optionally segment-gated. | `{ project_id, name: "Main Shop", description: "Tap to spend gems" }` |
+| `amba_stores_list` | List stores. | `{ project_id }` |
+| `amba_stores_patch` | Edit a store. | `{ project_id, store_id, name: "..." }` |
+| `amba_stores_delete` | Delete a store. | `{ project_id, store_id }` |
+| `amba_stores_add_listing` / `amba_add_store_listing` | Add an item to a store. | `{ project_id, store_id, item_id, sort_order: 1, featured: true }` |
+| `amba_stores_list_listings` | List items in a store. | `{ project_id, store_id }` |
+| `amba_stores_patch_listing` | Edit a listing (re-order, mark featured). | `{ project_id, store_id, listing_id, featured: true }` |
+| `amba_stores_delete_listing` | Remove an item from a store. | `{ project_id, store_id, listing_id }` |
+
+A segment-gated store: pass `segment_id` to `amba_stores_create` — only users in that segment see it via `Amba.stores.list()`.
+
+### Inventory (admin-side grants)
+
+| Tool | Purpose | Example args |
+| --- | --- | --- |
+| `amba_inventory_grant_item` / `amba_grant_item` | Grant an item to a user without payment (rewards, admin adjustments). | `{ project_id, app_user_id, item_key: "premium_theme", quantity: 1 }` |
+| `amba_users_get_inventory` / `amba_get_user_inventory` | Read a user's inventory. | `{ project_id, user_id }` |
+
+## SDK init per stack
+
+The SDK side is mostly read + purchase. `Amba.configure(...)` runs first.
+
+### Expo
+
+```tsx
+import { Amba } from '@layers/amba-expo';
+
+// Read the user's currency balance
+const balances = await Amba.currencies.getBalance();
+// [{ code: "gems", amount: 150 }, { code: "hearts", amount: 4 }]
+
+// Read the catalog
+const items = await Amba.catalog.list();
+
+// Read a store (a curated catalog subset)
+const stores = await Amba.stores.list();
+const offers = await Amba.stores.getPurchaseOptions(stores[0].key);
+
+// Soft-currency purchase (deducts from currency balance)
+await Amba.inventory.purchase({
+  item_key: 'premium_theme',
+  currency_code: 'gems',
+});
+
+// Consume a consumable item
+await Amba.inventory.consume({ item_key: 'hint_pack', quantity: 1 });
+
+// Read the user's inventory
+const inv = await Amba.inventory.getItems();
+```
+
+### React Native (bare)
+
+Identical surface — only the package name changes:
+
+```tsx
+import { Amba } from '@layers/amba-react-native';
+
+const balances = await Amba.currencies.getBalance();
+const items = await Amba.catalog.list();
+const stores = await Amba.stores.list();
+const offers = await Amba.stores.getPurchaseOptions(stores[0].key);
+await Amba.inventory.purchase({ item_key: 'premium_theme', currency_code: 'gems' });
+```
+
+For real-money IAP, you typically combine Amba with RevenueCat or `react-native-iap`:
+
+```tsx
+import Purchases from 'react-native-purchases';
+
+// Trigger the OS purchase sheet via RevenueCat
+const offerings = await Purchases.getOfferings();
+const product = offerings.current?.availablePackages[0];
+const { customerInfo, transaction } = await Purchases.purchasePackage(product!);
+
+// Forward the receipt to Amba's stores API — server validates with the store
+await Amba.stores.purchase(
+  'main_shop',
+  product!.identifier,
+  { receipt: transaction.transactionReceipt, platform: 'ios' },
+);
+```
+
+### Web
+
+```ts
+import { Amba } from '@layers/amba-web';
+
+const balances = await Amba.currencies.getBalance();
+const items = await Amba.catalog.list();
+const stores = await Amba.stores.list();
+await Amba.inventory.purchase({ item_key: 'pro_plan', currency_code: 'credits' });
+```
+
+Real-money web flow — typically Stripe Checkout:
+
+```ts
+// Server-side: create a Stripe Checkout Session, redirect.
+// Client-side: on return, Amba's webhook (`/webhooks/stripe` if configured)
+// fulfils via `amba_grant_item`. No SDK call required.
+```
+
+### iOS (Swift)
+
+```swift
+import Amba
+
+let balances = try await Amba.currencies.getBalance()
+let items = try await Amba.catalog.list()
+let stores = try await Amba.stores.list()
+let offers = try await Amba.stores.getPurchaseOptions(storeKey: stores[0].key)
+
+// Soft-currency purchase
+_ = try await Amba.inventory.purchase(PurchaseRequest(
+    itemKey: "premium_theme",
+    currencyCode: "gems"
+))
+
+// Consumable
+_ = try await Amba.inventory.consume(ConsumeRequest(itemKey: "hint_pack", quantity: 1))
+
+// Real-money via StoreKit 2
+import StoreKit
+
+let products = try await Product.products(for: ["com.example.premium_theme"])
+let result = try await products[0].purchase()
+if case .success(.verified(let transaction)) = result {
+    _ = try await Amba.stores.purchase(
+        storeKey: "main_shop",
+        purchaseOptionId: products[0].id,
+        receipt: ["jws_representation": transaction.jsonRepresentation]
+    )
+    await transaction.finish()
+}
+```
+
+### Android (Kotlin)
+
+```kotlin
+val balances = Amba.currencies.getBalance()
+val items = Amba.catalog.list()
+val stores = Amba.stores.list()
+
+Amba.inventory.purchase(
+    PurchaseRequest(itemKey = "premium_theme", currencyCode = "gems")
+)
+Amba.inventory.consume(ConsumeRequest(itemKey = "hint_pack", quantity = 1))
+```
+
+Real-money via Google Play Billing — capture the `purchaseToken` then:
+
+```kotlin
+Amba.stores.purchase(
+    storeKey = "main_shop",
+    purchaseOptionId = sku,
+    receipt = mapOf(
+        "purchase_token" to purchaseToken,
+        "package_name" to context.packageName,
+        "product_id" to sku
+    )
+)
+```
+
+### Flutter
+
+```dart
+import 'package:amba/amba.dart';
+
+final balances = await Amba.currencies.getBalance();
+final items = await Amba.catalog.list();
+final stores = await Amba.stores.list();
+
+await Amba.inventory.purchase(
+  PurchaseRequest(itemKey: 'premium_theme', currencyCode: 'gems'),
+);
+await Amba.inventory.consume(
+  ConsumeRequest(itemKey: 'hint_pack', quantity: 1),
+);
+```
+
+For IAP, the `in_app_purchase` Flutter plugin gives you the receipt; pass it to `Amba.stores.purchase(...)` with the same shape as Swift/Kotlin.
+
+## Common follow-ups
+
+Batch.
+
+1. **Virtual currency: what's it called?**
+   - `gems` (recommended — neutral, premium feel)
+   - `coins`
+   - `gold`
+   - `credits` (recommended for ai_chatbot)
+   - `points`
+   - Custom — I'll provide
+   - None — no soft currency for now
+
+2. **Add a "hearts" / energy mechanic?** (only ask for fitness / game / education)
+   - Yes — 5 hearts max, +1 every 4 hours (Duolingo style)
+   - Yes but custom (ask for cap and recharge rate)
+   - No
+
+3. **Premium currency too?** (real-money purchases of a tradeable virtual currency)
+   - Yes — `gems` (premium) — pairs with App Store / Play / Stripe billing
+   - No — only soft currency
+
+4. **Seed a starter catalog?**
+   - Yes — 3 cosmetics + 1 consumable + 1 starter bundle (uses the chosen currency)
+   - Yes but seed it empty — I'll add items myself
+   - No
+
+5. **Stores: one store or segmented stores?**
+   - One "Main Shop" — recommended for v1
+   - Multiple — main + a "Trial Users" segment-gated store
+   - I'll wire stores myself
+
+6. **Auto-grant rules:** earn currency on the gamification event?
+   - Yes — grant 10 of `<currency>` per `<event>` (same event as XP rule), cap at 5/day
+   - No — currency is granted only through achievement rewards / IAP
+
+7. **Real-money integration:** which provider?
+   - RevenueCat (recommended for mobile — handles iOS + Android in one SDK; configure with `amba_integrations_configure`)
+   - Native StoreKit / Play Billing only (no aggregator)
+   - Stripe (web)
+   - None yet — I'll add later
+
+## Re-run behavior
+
+1. `.amba/wired.json`:
+
+   ```json
+   {
+     "surfaces": {
+       "economy": {
+         "currencies": ["gems", "hearts"],
+         "catalog_items": ["premium_theme", "hint_pack", "starter_bundle"],
+         "stores": ["Main Shop"],
+         "grant_rules": [{ "currency": "gems", "event": "workout_completed" }],
+         "integrations": ["revenuecat"]
+       }
+     }
+   }
+   ```
+
+2. Before creating anything:
+   - `amba_currencies_list` — match on `code`. Codes are unique per project. Collision → ask to update instead.
+   - `amba_catalog_list` — match on `key`. Same.
+   - `amba_stores_list` — match on `name`. Same.
+
+3. **Never delete a currency or item without explicit confirmation** — users have balances and inventory tied to them. Suggest renaming + updating instead. If they insist on delete, surface what gets lost (number of users with non-zero balances / inventory).
+
+4. If adding a new currency to an existing project, ask whether to:
+   - Add a grant rule for it on the existing gamification event
+   - Set up auto-recharge (hearts pattern)
+   - Just create it without rules — manual grant only
+
+5. For real-money integrations, treat as orthogonal: `amba_integrations_list` shows what's wired. Don't duplicate. RevenueCat needs webhook URL + secret on the RevenueCat dashboard side; the configure tool prints the URL, but the user has to paste it into RevenueCat themselves — surface that as a "needs your input" line in Step 4.
+
+6. Update `wired.json` to append.