@layers/amba 1.0.1 → 4.0.2

package/skill-bundle/references/infrastructure.md

@@ -0,0 +1,348 @@
+# Infrastructure
+
+The plumbing that sits behind every other surface: custom database tables (Collections — schema-first, per-tenant), serverless functions (run server-side code without standing up a backend), analytics (events + sessions), AI prompts (managed LLM templates, callable from the SDK with per-tenant keys), secrets, runtime configs, feature flags, third-party integrations (RevenueCat / Superwall / Resend / Stripe / etc.), media (file storage + CDN), and sites (static asset hosting at `*.app.amba.host`).
+
+If gamification, economy, and social are the playable surface, **infrastructure is what you build a custom product on top of**. Anything that doesn't fit the canned surfaces lands here.
+
+## MCP tools
+
+### Collections (typed tables)
+
+A collection is a schema-first table inside the project's isolated tenant database. You describe the columns, the server creates the table and any indexes. Rows are scoped to the signed-in `app_user` automatically (server-enforced auto row-level isolation) for SDK clients — admin tools bypass this.
+
+| Tool | Purpose | Example args |
+| --- | --- | --- |
+| `amba_collections_create` / `amba_create_collection` | Create a typed collection. | `{ project_id, name: "todos", columns: [{ name: "title", type: "text", nullable: false }, { name: "done", type: "boolean", nullable: false, default: false }, { name: "due_at", type: "timestamptz", nullable: true }] }` |
+| `amba_collections_list` / `amba_list_collections` | List collections in this project. | `{ project_id }` |
+| `amba_collections_get` / `amba_get_collection` | Read one collection's schema. | `{ project_id, collection_name: "todos" }` |
+| `amba_collections_alter` / `amba_alter_collection` | Add / drop columns, add / drop indexes. | `{ project_id, collection_name: "todos", add_columns: [{ name: "priority", type: "int", nullable: true }] }` |
+| `amba_collections_delete` / `amba_delete_collection` | Drop the table (destructive). | `{ project_id, collection_name }` |
+| `amba_admin_insert_row` | Insert a row as the developer (bypasses user-scope). Useful for seed data. | `{ project_id, collection: "todos", row: { title: "Sample todo", done: false } }` |
+| `amba_admin_list_rows` | Read rows as the developer (bypasses user-scope — sees every user's rows). | `{ project_id, collection: "todos", limit: 100 }` |
+| `amba_client_insert_row` | Insert as an end-user. Requires `api_key` + `session_token`. | `{ project_id, api_key, session_token, collection: "todos", row: {...} }` |
+| `amba_client_list_rows` | Read as an end-user (auto-RLS-scoped). | `{ project_id, api_key, session_token, collection: "todos" }` |
+| `amba_client_get_row` | Get one row by id (end-user). | `{ project_id, api_key, session_token, collection, row_id }` |
+| `amba_client_update_row` | Update one row (end-user). | `{ project_id, api_key, session_token, collection, row_id, patch: {...} }` |
+| `amba_client_delete_row` | Delete one row (end-user). | `{ project_id, api_key, session_token, collection, row_id }` |
+| `amba_client_count_rows` | Count rows matching a filter (end-user). | `{ project_id, api_key, session_token, collection, filter: {...} }` |
+| `amba_client_find_rows` | Filter / sort / paginate rows (end-user). | `{ project_id, api_key, session_token, collection, filter: {...}, order_by: [...], limit: 50 }` |
+| `amba_client_find_nearest_rows` | Vector-similarity search (rows with a `vector(<dim>)` column). | `{ project_id, api_key, session_token, collection, vector_column: "embedding", query_vector: [...], k: 10 }` |
+
+Column types: `text`, `int`, `bigint`, `float`, `boolean`, `timestamptz`, `date`, `json`, `jsonb`, `uuid`, `vector(<dim>)` (e.g. `vector(1536)` for OpenAI embeddings).
+
+### Functions (serverless code)
+
+Run user code in a sandbox triggered by HTTP, cron, or webhook. The function gets the tenant connection automatically via injected env.
+
+| Tool | Purpose | Example args |
+| --- | --- | --- |
+| `amba_functions_deploy` / `amba_deploy_function` | Deploy a function from source (TypeScript / JavaScript / Python). | `{ project_id, name: "send_welcome_email", runtime: "node22", source: "export default async (req) => { ... }", trigger: { type: "http" } }` |
+| `amba_functions_list` / `amba_list_functions` | List functions. | `{ project_id }` |
+| `amba_functions_get` / `amba_get_function` | Read function metadata. | `{ project_id, function_id }` |
+| `amba_functions_get_logs` / `amba_get_function_logs` | Recent invocation logs. | `{ project_id, function_id, limit: 100 }` |
+| `amba_functions_delete` / `amba_delete_function` | Delete a function. | `{ project_id, function_id }` |
+| `amba_functions_schedule` / `amba_schedule_function` | Attach a cron schedule. | `{ project_id, function_id, cron: "0 9 * * *", timezone: "America/Los_Angeles" }` |
+| `amba_functions_pause_schedule` / `amba_pause_function_schedule` | Pause a scheduled trigger without deleting it. | `{ project_id, function_id }` |
+| `amba_functions_resume_schedule` / `amba_resume_function_schedule` | Resume. | `{ project_id, function_id }` |
+| `amba_functions_trigger_schedule` / `amba_trigger_function_schedule` | Fire a scheduled function ad-hoc (testing). | `{ project_id, function_id }` |
+
+### AI prompts
+
+Managed LLM templates: stored prompt with model + system message + variables, callable by name from the SDK. The actual LLM call is rewritten per-tenant — the customer's API keys (Anthropic / OpenAI) live in the tenant secrets, never on the device.
+
+| Tool | Purpose | Example args |
+| --- | --- | --- |
+| `amba_ai_prompts_create` / `amba_create_ai_prompt` | Create a prompt template. | `{ project_id, key: "summarize", model: "claude-opus-4-5", system: "Summarize the user's text in 2 sentences.", variables: ["text"] }` |
+| `amba_ai_prompts_list` / `amba_list_ai_prompts` | List prompts. | `{ project_id }` |
+| `amba_ai_prompts_get` / `amba_get_ai_prompt` | Read one prompt. | `{ project_id, key }` |
+| `amba_ai_prompts_update` / `amba_update_ai_prompt` | Edit a prompt (model swap, system message change). | `{ project_id, key, system: "..." }` |
+| `amba_ai_prompts_invoke` / `amba_invoke_ai_prompt` | Invoke a prompt server-side (no client involvement — admin testing). | `{ project_id, key, variables: { text: "..." } }` |
+| `amba_ai_prompts_delete` / `amba_delete_ai_prompt` | Delete. | `{ project_id, key }` |
+
+### Analytics + events + sessions
+
+| Tool | Purpose | Example args |
+| --- | --- | --- |
+| `amba_analytics_get` / `amba_get_analytics` | Top-level metrics dashboard (MAU, DAU, retention). | `{ project_id, period: "7d" }` |
+| `amba_events_list` | Browse raw events. | `{ project_id, limit: 100, since: "2026-05-19T00:00:00Z" }` |
+| `amba_events_count` | Count events matching a filter. | `{ project_id, event: "workout_completed", since: "2026-05-19T00:00:00Z" }` |
+| `amba_sessions_list` | List user sessions. | `{ project_id, limit: 50 }` |
+| `amba_sessions_analytics` | Session-level metrics (avg duration, screens/session). | `{ project_id, period: "7d" }` |
+| `amba_users_list_events` / `amba_users_events_export` | Per-user event history / export to CSV. | `{ project_id, user_id }` |
+| `amba_users_export` | Export the full user list (CSV / JSON). | `{ project_id, format: "csv" }` |
+
+### Secrets + configs + integrations
+
+| Tool | Purpose | Example args |
+| --- | --- | --- |
+| `amba_secrets_set` / `amba_set_secret` | Set a tenant secret (encrypted at rest). Use for third-party API keys called from functions. | `{ project_id, name: "OPENAI_API_KEY", value: "sk-..." }` |
+| `amba_secrets_get` / `amba_get_secret` | Read a secret (returns `"<redacted>"` unless explicitly requested). | `{ project_id, name }` |
+| `amba_secrets_list` / `amba_list_secrets` | List secret names. | `{ project_id }` |
+| `amba_secrets_delete` / `amba_delete_secret` | Delete. | `{ project_id, name }` |
+| `amba_configs_create` / `amba_create_config` | Create a runtime config value (read from SDK as `Amba.config.fetch()`). | `{ project_id, key: "primary_color", value: "#ff0066", segment_id: null }` |
+| `amba_configs_list` / `amba_list_configs` | List configs. | `{ project_id }` |
+| `amba_configs_update` / `amba_update_config` | Edit. | `{ project_id, config_id, value: "..." }` |
+| `amba_configs_delete` / `amba_delete_config` | Delete. | `{ project_id, config_id }` |
+| `amba_integrations_list` | List third-party integrations configured for this project. | `{ project_id }` |
+| `amba_integrations_configure` / `amba_configure_integration` | Configure a provider. | `{ project_id, provider: "revenuecat", config: { webhook_secret: "...", default_offering: "..." } }` |
+| `amba_integrations_set` | Set/replace integration config wholesale. | `{ project_id, provider, config }` |
+| `amba_integrations_patch` | Patch one field. | `{ project_id, provider, patch: { webhook_secret: "..." } }` |
+| `amba_integrations_test` / `amba_test_integration` | Send a test event to a configured provider. | `{ project_id, provider }` |
+
+### Media (file storage + CDN)
+
+| Tool | Purpose | Example args |
+| --- | --- | --- |
+| `amba_media_upload` / `amba_upload_media` | Upload a file (returns a tenant-scoped URL). | `{ project_id, name: "logo.png", content_type: "image/png", data: "<base64>" }` |
+| `amba_media_list` / `amba_list_media` | List files. | `{ project_id, folder: "/", limit: 100 }` |
+| `amba_media_delete` | Delete a file. | `{ project_id, file_id }` |
+| `amba_media_create_folder` | Create a logical folder. | `{ project_id, path: "/uploads/avatars" }` |
+| `amba_media_list_folders` | List folders. | `{ project_id }` |
+| `amba_media_delete_folder` | Delete a folder (must be empty). | `{ project_id, path }` |
+
+### Sites (static asset hosting)
+
+| Tool | Purpose | Example args |
+| --- | --- | --- |
+| `amba_sites_deploy` / `amba_deploy_site` | Deploy a static site bundle (zip / tar). | `{ project_id, name: "marketing", bundle: "<base64>", index: "index.html" }` |
+| `amba_sites_list` / `amba_list_sites` | List sites. | `{ project_id }` |
+| `amba_sites_get` / `amba_get_site` | Read a site. | `{ project_id, site_id }` |
+| `amba_sites_add_domain` / `amba_add_site_domain` | Attach a custom domain. | `{ project_id, site_id, domain: "marketing.example.com" }` |
+| `amba_sites_list_domains` / `amba_list_site_domains` | List domains on a site. | `{ project_id, site_id }` |
+| `amba_sites_remove_domain` / `amba_remove_site_domain` | Detach a domain. | `{ project_id, site_id, domain }` |
+| `amba_sites_delete` / `amba_delete_site` | Delete a site. | `{ project_id, site_id }` |
+
+## SDK init per stack
+
+`Amba.configure(...)` runs first. The infrastructure surfaces — collections, AI, config, flags, events — are SDK-side reads; the snippets below show what the client calls look like.
+
+### Expo
+
+```tsx
+import { Amba } from '@layers/amba-expo';
+
+// Collections — typed table, user-scoped reads + writes
+type Todo = { id: string; title: string; done: boolean; created_at: string };
+
+const { data: todos } = await Amba.collections.find<Todo>('todos', {
+  filter: Amba.collections.where.eq('done', false),
+  order: [{ column: 'created_at', direction: 'desc' }],
+  limit: 50,
+});
+
+const newTodo = await Amba.collections.insert('todos', {
+  title: 'Ship the app',
+  done: false,
+});
+
+await Amba.collections.update('todos', newTodo.id, { done: true });
+await Amba.collections.delete('todos', newTodo.id);
+
+// AI — call a managed prompt
+const response = await Amba.ai.anthropic.messages.create({
+  prompt_key: 'summarize',
+  variables: { text: 'A long article about backend services …' },
+});
+// response.content — the model's reply
+
+// Track an analytics event (also drives XP rules / achievements / etc.)
+await Amba.events.track('button_clicked', { button: 'cta' });
+
+// Read runtime config
+const config = await Amba.config.fetch();
+// config.values.primary_color — '#ff0066'
+
+// Read a feature flag
+const showBeta = await Amba.flags.get('beta_feature');
+// or load them all at app start
+const allFlags = await Amba.flags.fetch();
+
+// Diagnostics — wire-verify
+const ping = await Amba.diagnostics.ping();
+if (!ping.ok) {
+  console.error('Amba misconfigured:', ping);
+}
+```
+
+### React Native (bare)
+
+```tsx
+import { Amba } from '@layers/amba-react-native';
+
+const { data: todos } = await Amba.collections.find('todos', { limit: 50 });
+await Amba.collections.insert('todos', { title: 'hi', done: false });
+const config = await Amba.config.fetch();
+const showBeta = await Amba.flags.get('beta_feature');
+await Amba.events.track('app_opened');
+```
+
+### Web
+
+```ts
+import { Amba } from '@layers/amba-web';
+
+const { data: todos } = await Amba.collections.find('todos', {
+  filter: Amba.collections.where.eq('done', false),
+  limit: 50,
+});
+
+await Amba.collections.insert('todos', { title: 'Ship', done: false });
+await Amba.events.track('page_view', { path: location.pathname });
+```
+
+With `@layers/amba-react`:
+
+```tsx
+import { useCollection, useFlag } from '@layers/amba-react';
+
+function TodoList() {
+  const { data: todos, loading, refetch } = useCollection<{ id: string; title: string }>('todos');
+  const showArchive = useFlag('archive_todos');
+  if (loading) return <Spinner />;
+  return (
+    <ul>
+      {todos?.map(t => <li key={t.id}>{t.title}</li>)}
+      {showArchive && <ArchiveButton onArchive={refetch} />}
+    </ul>
+  );
+}
+```
+
+### iOS (Swift)
+
+```swift
+import Amba
+
+struct Todo: Codable {
+    let id: String
+    let title: String
+    let done: Bool
+}
+
+let response = try await Amba.collections.find("todos", as: Todo.self)
+let todos = response.data
+
+_ = try await Amba.collections.insert("todos", row: ["title": "Ship", "done": false])
+
+let config = try await Amba.config.fetch()
+let showBeta = try await Amba.flags.get(name: "beta_feature")
+try await Amba.events.track("app_opened", properties: ["source": "deep_link"])
+
+// AI
+let reply = try await Amba.ai.anthropic.messages.create(
+    promptKey: "summarize",
+    variables: ["text": "A long article..."]
+)
+```
+
+### Android (Kotlin)
+
+```kotlin
+data class Todo(val id: String, val title: String, val done: Boolean)
+
+val todos = Amba.collections.find<Todo>("todos")
+Amba.collections.insert("todos", mapOf("title" to "Ship", "done" to false))
+
+val config = Amba.config.fetch()
+val showBeta = Amba.flags.get("beta_feature")
+Amba.events.track("app_opened", mapOf("source" to "deep_link"))
+
+val reply = Amba.ai.anthropic.messages.create(
+    promptKey = "summarize",
+    variables = mapOf("text" to "A long article…")
+)
+```
+
+### Flutter
+
+```dart
+import 'package:amba/amba.dart';
+
+final response = await Amba.collections.find('todos', limit: 50);
+final todos = response.data;
+
+await Amba.collections.insert('todos', {'title': 'Ship', 'done': false});
+
+final config = await Amba.config.fetch();
+final showBeta = await Amba.flags.get('beta_feature');
+await Amba.events.track('app_opened', {'source': 'deep_link'});
+
+final reply = await Amba.ai.anthropic.messages.create(
+  promptKey: 'summarize',
+  variables: {'text': 'A long article…'},
+);
+```
+
+## Common follow-ups
+
+Batch.
+
+1. **Custom data tables (collections):** any domain-specific tables to create?
+   - Yes — I'll list them. (Then for each: name + columns + types.)
+   - No, just use the canned Amba surfaces (auth, push, gamification, etc.)
+   - Auto-create from the existing code's models — read `lib/models/`, `src/types/`, `Models/`, infer column lists, confirm with me.
+
+2. **Custom backend logic (functions):** any server-side code to deploy?
+   - Yes — describe what it should do. (Then offer to scaffold a function template and deploy.)
+   - No
+
+3. **AI features:** want managed LLM prompts?
+   - Yes — what's the use case? (summarize, translate, classify, generate, custom)
+   - No
+
+4. **Analytics:** which tracker do you want?
+   - Only Amba's built-in events (recommended — already wired)
+   - Amba + Mixpanel / PostHog / Segment forwarding (configure via `amba_integrations_configure`)
+   - None — disable event tracking entirely (rarely useful — events also drive XP / achievements / streaks; disabling cripples gamification)
+
+5. **Third-party integrations to set up:**
+   - [ ] RevenueCat (IAP / subscriptions on iOS + Android)
+   - [ ] Superwall (paywall A/B)
+   - [ ] Resend (transactional email)
+   - [ ] Stripe (web payments / subscriptions)
+   - [ ] Mixpanel / PostHog / Segment (analytics forwarding)
+   - [ ] OpenAI / Anthropic (LLM keys — required for `Amba.ai.*` calls)
+
+6. **Feature flags:** seed any starter flags?
+   - Yes — wire `beta_feature` (off by default) so I can ship the wiring before the feature exists
+   - No
+
+7. **Static site:** want a marketing page hosted under your tenant subdomain?
+   - Yes — scaffold and deploy a 1-page index
+   - No
+
+## Re-run behavior
+
+1. `.amba/wired.json`:
+
+   ```json
+   {
+     "surfaces": {
+       "infrastructure": {
+         "collections": ["todos", "favorites"],
+         "functions": ["send_welcome_email"],
+         "ai_prompts": ["summarize"],
+         "integrations": ["revenuecat", "anthropic"],
+         "flags": ["beta_feature"],
+         "configs": ["primary_color", "max_uploads_per_day"]
+       }
+     }
+   }
+   ```
+
+2. Before creating:
+   - `amba_collections_list` — match on `name`. Collisions: never silently recreate (data loss). Offer `amba_collections_alter` to add new columns instead.
+   - `amba_functions_list` — match on `name`. Collisions: ask to redeploy (with the new source) or skip.
+   - `amba_ai_prompts_list` — match on `key`. Same.
+   - `amba_integrations_list` — match on `provider`. Same.
+   - `amba_configs_list` — match on `key`. Same.
+
+3. **Never call `amba_collections_delete` on re-run unless the user explicitly asks** — this drops the underlying table and every row in it across every user of the tenant.
+
+4. For functions: re-deploying replaces source in place (versioned server-side). It's safe to call `amba_functions_deploy` with the same name + new source — but log the deploy in `wired.json.surfaces.infrastructure.function_deploys` with a timestamp so the user can audit.
+
+5. For integrations: if a provider is already configured, prefer `amba_integrations_patch` (partial update) over `amba_integrations_set` (full replace) to avoid clobbering fields the user filled in via the console.
+
+6. Secrets: don't list secret values in chat output, even on read. Just confirm "OPENAI_API_KEY is set" / "not set" — the actual value stays in the tenant's secret store.
+
+7. Update `wired.json` to append.