@layers/amba 1.1.0 → 4.0.2

package/skill-bundle/references/social.md

@@ -0,0 +1,366 @@
+# Social
+
+The social graph and everything that runs on top of it: friendships (with block lists), groups (guilds / clubs), activity feeds with rule-driven filters, 1:1 + group messaging, user-generated reviews, and the moderation queue + trust system that keeps it all from rotting.
+
+Most of this is "create-the-rule, let-the-SDK-call-it" — feeds are rule-driven, moderation has its own queue, friend graph is bidirectional. Only the structural pieces (feed rules, moderation rules, group capacity) are MCP-provisioned; the runtime calls (`Amba.friends.sendRequest`, `Amba.messaging.sendMessage`, `Amba.feeds.getActivity`) are SDK-side.
+
+## MCP tools
+
+### Friendships
+
+| Tool | Purpose | Example args |
+| --- | --- | --- |
+| `amba_friendships_list` / `amba_list_friendships` | List friendships in a project (admin-side — for a moderator panel). | `{ project_id, status: "accepted", limit: 100 }` |
+| `amba_friendships_get_stats` / `amba_get_friendship_stats` | Aggregate friendship metrics — total accepted, pending, blocked. | `{ project_id }` |
+| `amba_friendships_delete` / `amba_delete_friendship` | Admin-delete a friendship row (e.g. moderation outcome). | `{ project_id, friendship_id }` |
+
+Friend requests + accept/decline + block are SDK-side (`Amba.friends.sendRequest(...)` etc.). There's no MCP tool to create a friendship — by design, only end-users can.
+
+### Groups
+
+| Tool | Purpose | Example args |
+| --- | --- | --- |
+| `amba_groups_create` / `amba_create_group` | Create a group (guild / club / squad). | `{ project_id, name: "Morning Runners", owner_id: "u_…", description: "5am crew", is_public: true, max_members: 100 }` |
+| `amba_groups_list` / `amba_list_groups` | List groups. | `{ project_id, limit: 50 }` |
+| `amba_groups_update` / `amba_update_group` | Edit a group (rename, change visibility, change cap). | `{ project_id, group_id, max_members: 500 }` |
+| `amba_groups_delete` / `amba_delete_group` | Delete a group. | `{ project_id, group_id }` |
+| `amba_groups_list_members` / `amba_list_group_members` | List members in a group. | `{ project_id, group_id }` |
+| `amba_groups_update_member` / `amba_update_group_member` | Change a member's role (promote to admin / mute). | `{ project_id, group_id, member_id, role: "admin" }` |
+| `amba_groups_remove_member` / `amba_remove_group_member` | Kick a member. | `{ project_id, group_id, member_id }` |
+
+### Feeds
+
+Activity feeds are rule-driven: each rule says "events of type X published by users matching Y should appear in feed Z". Items land in feeds automatically when matching events fire.
+
+| Tool | Purpose | Example args |
+| --- | --- | --- |
+| `amba_feeds_rules_create` / `amba_create_feed_rule` | Define a feed rule. | `{ project_id, feed: "global", event: "post_published", filter: { all: [{ field: "user.is_creator", op: "==", value: true }] } }` |
+| `amba_feeds_list_rules` | List rules. | `{ project_id, feed }` |
+| `amba_feeds_patch_rule` | Edit a rule (change filter, change destination feed). | `{ project_id, rule_id, filter: {...} }` |
+| `amba_feeds_delete_rule` | Delete a rule. | `{ project_id, rule_id }` |
+| `amba_feeds_list_items` | List items in a feed (admin / debugging). | `{ project_id, feed: "global", limit: 50 }` |
+| `amba_feeds_delete_item` | Remove a single feed item (moderation). | `{ project_id, feed, item_id }` |
+
+Conventional feed names: `global` (everyone), `following` (just users you follow), `group:<group_id>` (a single group's feed).
+
+### Messaging
+
+Mostly SDK-side — admin tools are for moderation + stats.
+
+| Tool | Purpose | Example args |
+| --- | --- | --- |
+| `amba_messaging_list_conversations` | List conversations (admin / moderation view). | `{ project_id, limit: 50 }` |
+| `amba_messaging_list_messages` | List messages in a conversation. | `{ project_id, conversation_id, limit: 100 }` |
+| `amba_messaging_delete_message` | Hard-delete a message (moderation). | `{ project_id, conversation_id, message_id }` |
+| `amba_messaging_get_stats` / `amba_get_messaging_stats` | Aggregate messaging metrics. | `{ project_id }` |
+
+### Moderation
+
+| Tool | Purpose | Example args |
+| --- | --- | --- |
+| `amba_moderation_configure` / `amba_configure_moderation` | Set the project's default moderation policy. | `{ project_id, auto_review_threshold: 0.8, default_action: "queue", auto_block_threshold: 0.95 }` |
+| `amba_moderation_list_rules` | List rules. | `{ project_id }` |
+| `amba_moderation_update_rule` | Edit a rule. | `{ project_id, rule_id, action: "block" }` |
+| `amba_moderation_delete_rule` | Delete a rule. | `{ project_id, rule_id }` |
+| `amba_moderation_queue_list` / `amba_get_moderation_queue` | List pending reports. | `{ project_id, status: "pending", limit: 50 }` |
+| `amba_moderation_queue_get` | Fetch one report. | `{ project_id, report_id }` |
+| `amba_moderation_queue_approve` | Approve (mark report as resolved with no action). | `{ project_id, report_id, reason: "false positive" }` |
+| `amba_moderation_queue_reject` | Reject (take action — hide/delete content, ban user). | `{ project_id, report_id, action: "delete_message", reason: "spam" }` |
+| `amba_moderation_queue_escalate` | Escalate to a senior moderator. | `{ project_id, report_id }` |
+| `amba_moderation_list_trust` | List per-user trust scores. | `{ project_id, limit: 100 }` |
+| `amba_moderation_set_trust` | Manually bump a user's trust score. | `{ project_id, user_id, trust_score: 0.9, reason: "verified power user" }` |
+
+### Reviews
+
+| Tool | Purpose | Example args |
+| --- | --- | --- |
+| `amba_reviews_list` | List reviews. | `{ project_id, target_type: "catalog_item", target_id: "...", limit: 50 }` |
+| `amba_reviews_list_items` | List the things that have reviews on them. | `{ project_id, target_type: "catalog_item" }` |
+| `amba_reviews_patch` | Edit / hide a review (moderation). | `{ project_id, review_id, hidden: true }` |
+| `amba_reviews_delete` | Delete a review. | `{ project_id, review_id }` |
+| `amba_reviews_get_stats` / `amba_get_review_stats` | Aggregate review stats. | `{ project_id, target_type, target_id }` |
+| `amba_reviews_export` | Export to CSV / JSON. | `{ project_id, format: "csv" }` |
+
+## SDK init per stack
+
+`Amba.configure(...)` runs first. Snippets below are the social-only calls.
+
+### Expo
+
+```tsx
+import { Amba } from '@layers/amba-expo';
+
+// Send a friend request
+const friendship = await Amba.friends.sendRequest(otherUserId);
+// friendship.status === 'pending' (until the other user accepts)
+
+// List friendships (incoming requests, friends, blocks)
+const all = await Amba.friends.getList();
+const friends = await Amba.friends.getFriends(); // accepted only
+
+// Accept / decline / unfriend
+await Amba.friends.acceptRequest(friendship.id);
+await Amba.friends.declineRequest(friendship.id);
+await Amba.friends.removeFriend(otherUserId);
+await Amba.friends.blockUser(otherUserId);
+
+// Groups
+const group = await Amba.groups.create({ name: 'Morning Runners' });
+const fetched = await Amba.groups.get(group.id);
+
+// Messaging — 1:1 conversation
+const conv = await Amba.messaging.createConversation({
+  participant_ids: [otherUserId],
+  type: 'direct',
+});
+const msg = await Amba.messaging.sendMessage(conv.id, {
+  body: 'hey, want to start a daily streak together?',
+});
+const inbox = await Amba.messaging.conversations();
+const messages = await Amba.messaging.listMessages(conv.id, { limit: 50 });
+await Amba.messaging.markRead(conv.id);
+
+// Feeds
+const { items, next_cursor } = await Amba.feeds.getActivity('global');
+
+// Reviews
+const reviews = await Amba.reviews.list('catalog_item', 'premium_theme');
+await Amba.reviews.create({
+  target_type: 'catalog_item',
+  target_id: 'premium_theme',
+  rating: 5,
+  body: 'Beautiful theme!',
+});
+
+// Moderation — user-side
+await Amba.moderation.reportUser({
+  reported_user_id: otherUserId,
+  reason: 'harassment',
+});
+await Amba.moderation.reportContent({
+  target_type: 'message',
+  target_id: msg.id,
+  reason: 'spam',
+});
+```
+
+### React Native (bare)
+
+Identical surface:
+
+```tsx
+import { Amba } from '@layers/amba-react-native';
+
+const friendship = await Amba.friends.sendRequest(otherUserId);
+const conv = await Amba.messaging.createConversation({
+  participant_ids: [otherUserId],
+  type: 'direct',
+});
+const msg = await Amba.messaging.sendMessage(conv.id, { body: 'hi' });
+const feed = await Amba.feeds.getActivity('global');
+```
+
+### Web
+
+```ts
+import { Amba } from '@layers/amba-web';
+
+// Friend graph
+await Amba.friends.sendRequest(otherUserId);
+const friends = await Amba.friends.getFriends();
+
+// Messaging
+const conv = await Amba.messaging.createConversation({
+  participant_ids: [otherUserId],
+  type: 'direct',
+});
+await Amba.messaging.sendMessage(conv.id, { body: 'hello' });
+
+// Feed
+const activity = await Amba.feeds.getActivity('global');
+```
+
+With `@layers/amba-react`, build hooks on top:
+
+```tsx
+import { useEffect, useState } from 'react';
+import { Amba } from '@layers/amba-web';
+
+export function useConversations() {
+  const [conversations, setConversations] = useState<Conversation[] | null>(null);
+  useEffect(() => {
+    (async () => setConversations(await Amba.messaging.conversations()))();
+  }, []);
+  return conversations;
+}
+```
+
+### iOS (Swift)
+
+```swift
+import Amba
+
+// Friendships
+let friendship = try await Amba.friends.sendRequest(userId: otherUserId)
+let friends = try await Amba.friends.getFriends()
+_ = try await Amba.friends.acceptRequest(friendshipId: friendship.id)
+
+// Groups
+let group = try await Amba.groups.create(GroupCreate(name: "Morning Runners"))
+
+// Messaging
+let conv = try await Amba.messaging.createConversation(CreateConversationRequest(
+    participantIds: [otherUserId],
+    type: .direct
+))
+let msg = try await Amba.messaging.sendMessage(
+    conversationId: conv.id,
+    request: SendMessageRequest(body: "hi")
+)
+let convs = try await Amba.messaging.conversations()
+let messages = try await Amba.messaging.listMessages(conversationId: conv.id)
+_ = try await Amba.messaging.markRead(conversationId: conv.id)
+
+// Feeds
+let feed = try await Amba.feeds.getActivity(feed: "global")
+
+// Reviews
+let reviews = try await Amba.reviews.list(targetType: "catalog_item", targetId: "premium_theme")
+_ = try await Amba.reviews.create(ReviewCreate(
+    targetType: "catalog_item",
+    targetId: "premium_theme",
+    rating: 5,
+    body: "Beautiful theme!"
+))
+
+// Moderation
+_ = try await Amba.moderation.reportUser(ReportRequest(
+    reportedUserId: otherUserId,
+    reason: "harassment"
+))
+```
+
+### Android (Kotlin)
+
+```kotlin
+val friendship = Amba.friends.sendRequest(otherUserId)
+val friends = Amba.friends.getFriends()
+Amba.friends.acceptRequest(friendship.id)
+
+val group = Amba.groups.create(GroupCreate(name = "Morning Runners"))
+
+val conv = Amba.messaging.createConversation(
+    CreateConversationRequest(participantIds = listOf(otherUserId), type = "direct")
+)
+val msg = Amba.messaging.sendMessage(
+    conversationId = conv.id,
+    request = SendMessageRequest(body = "hi")
+)
+Amba.messaging.markRead(conv.id)
+
+val feed = Amba.feeds.getActivity("global")
+val reviews = Amba.reviews.list("catalog_item", "premium_theme")
+Amba.moderation.reportUser(ReportRequest(reportedUserId = otherUserId, reason = "harassment"))
+```
+
+### Flutter
+
+```dart
+import 'package:amba/amba.dart';
+
+final friendship = await Amba.friends.sendRequest(otherUserId);
+final friends = await Amba.friends.getFriends();
+await Amba.friends.acceptRequest(friendship.id);
+
+final group = await Amba.groups.create(GroupCreate(name: 'Morning Runners'));
+
+final conv = await Amba.messaging.createConversation(
+  CreateConversationRequest(
+    participantIds: [otherUserId],
+    type: ConversationType.direct,
+  ),
+);
+final msg = await Amba.messaging.sendMessage(
+  conv.id,
+  SendMessageRequest(body: 'hi'),
+);
+await Amba.messaging.markRead(conv.id);
+
+final feed = await Amba.feeds.getActivity('global');
+final reviews = await Amba.reviews.list('catalog_item', 'premium_theme');
+await Amba.moderation.reportUser(
+  ReportRequest(reportedUserId: otherUserId, reason: 'harassment'),
+);
+```
+
+## Common follow-ups
+
+Batch.
+
+1. **Which social features?** (multi-select)
+   - [x] Friend graph (friend requests, accept/decline, block, unfriend)
+   - [ ] Groups / guilds (multi-user)
+   - [x] 1:1 messaging
+   - [ ] Group messaging
+   - [x] Activity feed
+   - [ ] User reviews (on catalog items / on other users)
+   - [x] Moderation queue + user-report flow (recommended whenever messaging or feed is on)
+
+2. **Default feed:**
+   - Global (everyone) (recommended for content_creator, social)
+   - Following (only people you friend) (recommended for dating, fitness — privacy-leaning)
+   - Both — wire two feeds, let users switch
+
+3. **Feed rule: what event lands in the feed?**
+   - For fitness: `workout_completed` (with user details)
+   - For social: `post_published`
+   - For game: `level_completed`
+   - For education: `lesson_completed`
+   - Custom — I'll provide
+
+4. **Moderation policy:** (only ask if any social feature was chosen)
+   - Auto-block obvious abuse (>= 0.95 confidence), queue the rest (>= 0.8 confidence), allow below (recommended)
+   - Queue everything — manual review of all flagged content (slow but human-in-the-loop)
+   - Allow everything — only act on user reports (anything-goes; for closed communities only)
+
+5. **Dating-specific:**
+   - Match-only messaging (can only message users you've matched with) — recommended for dating apps
+   - Open messaging (any user can DM any user)
+   - Group chats enabled?
+
+6. **Reviews (only if economy surface is wired):**
+   - Catalog item reviews (users rate things they bought)
+   - User-on-user reviews (e.g. for marketplaces, dating)
+   - Both
+
+## Re-run behavior
+
+1. `.amba/wired.json`:
+
+   ```json
+   {
+     "surfaces": {
+       "social": {
+         "friends": true,
+         "groups": false,
+         "messaging": { "direct": true, "group": false },
+         "feeds": { "rules": ["global/post_published"] },
+         "reviews": { "target_types": ["catalog_item"] },
+         "moderation": { "auto_review_threshold": 0.8, "auto_block_threshold": 0.95 }
+       }
+     }
+   }
+   ```
+
+2. Before creating:
+   - `amba_feeds_list_rules` — match on `feed + event + filter`. Collision → ask to update or skip.
+   - `amba_groups_list` — group names aren't unique; only skip if `name + owner_id` collides.
+   - `amba_moderation_list_rules` — match on rule key.
+
+3. **Never delete a group, friendship, or message without explicit confirmation** — these are user-created. If the user asks to "wipe friendships", give them `amba_moderation_queue_list` to find the actually-problematic rows first.
+
+4. If the user enables messaging on re-run, double-check whether moderation is already wired. If not, **strongly recommend** turning it on before opening the messaging surface to all users — wire it in the same pass (additive — `amba_moderation_configure`).
+
+5. For abusive-user enforcement, prefer trust-score updates (`amba_moderation_set_trust({ trust_score: 0.0 })`) and report rejection over user deletion. Deletion is `amba_users_delete` and is destructive — only on a user-initiated GDPR-style request.
+
+6. Update `wired.json` to append (new rules to `feeds.rules`, new target types to `reviews.target_types`, etc.).