@amityco/social-plus-vise 0.4.0 → 0.7.0

package/rules/security.yaml

@@ -157,6 +157,66 @@
         "deterministic": [{ "check": "validator-finding-absent", "finding_rule_id": "react-native.logging.no-secret-in-log" }],
         "attestation": { "allowed": true, "host_agent_min_confidence": "high", "human_allowed": true, "evidence_required": [{ "field": "redaction_policy", "description": "Where the value being logged is redacted or proven to be a placeholder.", "upload_policy": "upload-with-consent" }] }
       }
+    },
+    {
+      "id": "android.logging.no-pii-in-log",
+      "version": 1,
+      "title": "Android logging must not include PII-shaped values",
+      "severity": "warning",
+      "rationale": "Logging userName, email, phone, displayName, address, or other PII-shaped values to Log.* or println exposes user data to crash reports, log aggregators, and device logs. Redact or drop the value.",
+      "applies_when": { "platforms": ["android"], "outcomes": ["setup-sdk", "setup-push", "setup-live-data", "add-feed", "validate-setup"] },
+      "enforcement": {
+        "deterministic": [{ "check": "validator-finding-absent", "finding_rule_id": "android.logging.no-pii-in-log" }],
+        "attestation": { "allowed": true, "host_agent_min_confidence": "high", "human_allowed": true, "evidence_required": [{ "field": "redaction_policy", "description": "Explanation of how PII is redacted or why the logged value is not real user PII.", "upload_policy": "upload-with-consent" }] }
+      }
+    },
+    {
+      "id": "flutter.logging.no-pii-in-log",
+      "version": 1,
+      "title": "Flutter logging must not include PII-shaped values",
+      "severity": "warning",
+      "rationale": "Logging userName, email, phone, displayName, address, or other PII-shaped values to print, debugPrint, or developer.log exposes user data to crash reports and log aggregators. Redact or drop the value.",
+      "applies_when": { "platforms": ["flutter"], "outcomes": ["setup-sdk", "setup-push", "setup-live-data", "add-feed", "validate-setup"] },
+      "enforcement": {
+        "deterministic": [{ "check": "validator-finding-absent", "finding_rule_id": "flutter.logging.no-pii-in-log" }],
+        "attestation": { "allowed": true, "host_agent_min_confidence": "high", "human_allowed": true, "evidence_required": [{ "field": "redaction_policy", "description": "Explanation of how PII is redacted or why the logged value is not real user PII.", "upload_policy": "upload-with-consent" }] }
+      }
+    },
+    {
+      "id": "ios.logging.no-pii-in-log",
+      "version": 1,
+      "title": "iOS logging must not include PII-shaped values",
+      "severity": "warning",
+      "rationale": "Logging userName, email, phone, displayName, address, or other PII-shaped values via print, NSLog, os_log, or Logger exposes user data to system logs and crash reports. Redact or drop the value.",
+      "applies_when": { "platforms": ["ios"], "outcomes": ["setup-sdk", "setup-push", "setup-live-data", "add-feed", "validate-setup"] },
+      "enforcement": {
+        "deterministic": [{ "check": "validator-finding-absent", "finding_rule_id": "ios.logging.no-pii-in-log" }],
+        "attestation": { "allowed": true, "host_agent_min_confidence": "high", "human_allowed": true, "evidence_required": [{ "field": "redaction_policy", "description": "Explanation of how PII is redacted or why the logged value is not real user PII.", "upload_policy": "upload-with-consent" }] }
+      }
+    },
+    {
+      "id": "typescript.logging.no-pii-in-log",
+      "version": 1,
+      "title": "TypeScript logging must not include PII-shaped values",
+      "severity": "warning",
+      "rationale": "Logging userName, email, phone, displayName, address, or other PII-shaped values via console.* exposes user data to browser devtools, server logs, and error trackers. Redact or drop the value.",
+      "applies_when": { "platforms": ["typescript"], "outcomes": ["setup-sdk", "setup-push", "setup-live-data", "add-feed", "validate-setup"] },
+      "enforcement": {
+        "deterministic": [{ "check": "validator-finding-absent", "finding_rule_id": "typescript.logging.no-pii-in-log" }],
+        "attestation": { "allowed": true, "host_agent_min_confidence": "high", "human_allowed": true, "evidence_required": [{ "field": "redaction_policy", "description": "Explanation of how PII is redacted or why the logged value is not real user PII.", "upload_policy": "upload-with-consent" }] }
+      }
+    },
+    {
+      "id": "react-native.logging.no-pii-in-log",
+      "version": 1,
+      "title": "React Native logging must not include PII-shaped values",
+      "severity": "warning",
+      "rationale": "Logging userName, email, phone, displayName, address, or other PII-shaped values via console.* exposes user data to Metro, Flipper, and crash reports. Redact or drop the value.",
+      "applies_when": { "platforms": ["react-native"], "outcomes": ["setup-sdk", "setup-push", "setup-live-data", "add-feed", "validate-setup"] },
+      "enforcement": {
+        "deterministic": [{ "check": "validator-finding-absent", "finding_rule_id": "react-native.logging.no-pii-in-log" }],
+        "attestation": { "allowed": true, "host_agent_min_confidence": "high", "human_allowed": true, "evidence_required": [{ "field": "redaction_policy", "description": "Explanation of how PII is redacted or why the logged value is not real user PII.", "upload_policy": "upload-with-consent" }] }
+      }
     }
   ]
 }

package/skills/social-plus-vise/SKILL.md

@@ -61,6 +61,9 @@ Ask the user before editing when required values are missing:
 
 - region, auth/user identity, or session-handler ownership (which class/module implements `sessionWillRenewAccessToken`)
 - feed target, community ID, target ID, feed ID, or channel ID
+- comment target source (which parent entity provides postId/referenceId)
+- moderation target types (post, comment, message, user), action set, or rendering policy for blocked content
+- chat shape (1:1, group, community), channel source (never invent channelId), or message capabilities scope
 - notification platform type, token source, permission owner, or logout cleanup owner
 - Live Object/Collection domain, object vs collection choice, lifecycle owner, or cleanup location
 - app surface in a monorepo when Vise reports multiple surfaces
@@ -106,7 +109,90 @@ Per platform:
 - Flutter Dart: implement `AmitySessionHandler.sessionWillRenewAccessToken(AmityAccessTokenRenewal)` and call `renewal.renew()`.
 - iOS Swift: implement `AmitySessionHandler.sessionWillRenewAccessToken(renewal:)` and call `renewal.renew()`.
 
-`vise check` enforces `*.session.renewal` per platform when login is present.
+### Session Handler Retention
+
+**CRITICAL:** The session handler object must outlive the function that created it. If you declare the session handler as a function-local variable (e.g. inside `setUp()`, `initState()`, `onCreate()`), the host language's garbage collector (Dart, JS, Kotlin) or ARC (iOS) will destroy it before the SDK ever needs to renew the session.
+
+- **Correct pattern:** Declare it as a class-level property/field, a module-scoped constant, or retain it via a state container (e.g. `useRef` in React).
+- **Wrong pattern:** `func setUp() { let handler = AppSessionHandler(); ... login(..., handler) }` — handler dies at the end of `setUp()`.
+
+`vise check` enforces `*.session.renewal` per platform when login is present, and `*.session-handler.retained` to prevent garbage-collection bugs.
+
+## Notifications & Media
+
+### Notification Preferences
+
+Amity has its own server-side notification preferences (e.g. mute community, mute user, granular per-event toggles) that are entirely separate from FCM/APNS. Customers often register the push token and stop there. As a result, notifications fire but ignore the user's preferences, leading to bug reports.
+
+- **Correct pattern**: Register the push token, then load or observe Amity's notification settings (e.g. `AmityCoreClient.notifications().getSettings()`, `notificationRepository.getSettings()`).
+- **Wrong pattern**: Only calling `registerPushNotification` without ever inspecting or respecting Amity's own notification settings.
+
+### Unread Counts
+
+Amity exposes a global `unreadCount` stream that syncs across devices.
+
+- **Correct pattern**: Subscribe to the unread stream provided by the SDK (e.g. `AmityCoreClient.unreadCount()`, `getUnreadCount()`, `unread.stream`).
+- **Wrong pattern**: Hand-rolling unread counting on the client (e.g. `posts.filter(p => !p.isRead).length`). This causes counts to go out of sync because the server's read state isn't pushed to the manual counter.
+
+### File Upload & Media
+
+Uploading media to external buckets (S3, Cloudinary) directly and trying to attach the resulting URL to an Amity post will fail. The SDK won't recognize external URLs as attachments.
+
+- **Correct pattern**: Upload media through `AmityFileClient` or `AmityFileRepository` to get an `AmityFileId`, then attach the file ID to the post.
+- **Wrong pattern**: Passing external URLs directly in the `attachments` array or object when creating a post.
+
+### Image & Video Posts
+
+After creating a post with an image or video attachment, the parent post returns immediately, but the image child post is still being processed server-side.
+
+- **Correct pattern**: Await the child post's ready state (e.g. `await result.children.first.whenReady`) or observe the post before rendering.
+- **Wrong pattern**: Rendering the result immediately after creation, yielding an empty image or broken thumbnail.
+
+## Data Correctness
+
+### Live Collection API Mismatch
+When querying lists of entities (e.g., `getPosts`, `getCommunityFeed`), always use reactive LiveCollection APIs instead of Future-based one-shot queries. One-shot APIs do not listen for real-time updates or local mutations, leading to stale UIs.
+- **Correct pattern:** Observe the collection (e.g., `.observe()`, `.listen()`, `StreamBuilder`, `LiveData`, `getLiveCollection()`) and render the stream.
+- **Wrong pattern:** `await getPosts(...)` and assigning to a static array.
+
+### Post Status Filters
+Always filter post queries to exclude deleted or flagged content. Amity's older SDKs include flagged/deleted posts by default, which can leak moderated content into the feed UI if unfiltered.
+- **Correct pattern:** Apply `.includeDeleted(false)`, `.statuses([.published])`, or `.feedType(AmityFeedType.PUBLISHED)` to your query builders.
+
+### Opaque Pagination Cursors
+Amity uses opaque, token-based cursors for pagination. Never attempt to construct the `nextPage` argument using numeric math (e.g., `page * size`). This will cause silent failures or HTTP 400 errors.
+- **Correct pattern:** Pass the exact `nextPageToken` returned from the previous query result, or call `.loadMore()` / `.nextPage()` on the collection itself.
+- **Wrong pattern:** `.nextPage(pageNumber * 20)`
+
+### Parent-Child Post Rendering
+Amity models image and video attachments as "child posts" attached to a parent post. If your UI only renders the parent post's text, it will silently drop all media attachments.
+- **Correct pattern:** Ensure the post-rendering component recursively processes `post.children`, `.childrenPosts`, or calls `getChildren()`.
+- **Wrong pattern:** `Text(post.data.text)` with no reference to the post's children.
+
+### Explicit Feed Target Types
+When calling `createPost`, do not hardcode the `targetType` to a literal value like `AmityPostTargetType.COMMUNITY` if the composer component is meant to be reusable.
+- **Correct pattern:** Pass the `targetType` dynamically (e.g. from props, parameters, or intent extras) so the composer can post to a user feed, community feed, or global feed interchangeably.
+- **Wrong pattern:** Hardcoding `targetType: AmityPostTargetType.COMMUNITY` inside a generic post composer.
+
+### Comment Reference Type Enum
+When creating comments, always use the SDK's provided enum types for the reference type rather than raw string literals.
+- **Correct pattern:** `AmityCommentReferenceType.POST`, `AmityCommentReferenceType.post`, etc.
+- **Wrong pattern:** Passing `"POST"` or `'post'` directly as a string literal.
+
+### Channel Type Matches Semantic Shape
+`AmityChannelType` exposes four channel shapes — `community`, `conversation`, `broadcast`, `live` — each with different capabilities (membership, messaging, presence). Picking the wrong type silently breaks conversation semantics: 1:1 chats end up in the community list, broadcasts allow replies, etc.
+- **Correct pattern:** Use `.conversation` for 1:1 or small private chats, `.community` for many-to-many public discussion, `.broadcast` for announcement-style one-to-many, `.live` for live-stream chat. If the component is reusable across types, accept `channelType` as a parameter / prop.
+- **Wrong pattern:** A `DirectMessageScreen` or `OneOnOneChat` component that calls `createChannel(channelType: AmityChannelType.COMMUNITY, ...)`.
+
+### Reaction Names Match Console Config
+Reaction names are configured per-tenant in the social.plus console. Hardcoding `"like"` because the docs show it will silently no-op or 400 if the tenant configured `"heart"` or `"clap"` instead.
+- **Correct pattern:** Import reaction names from a shared config module (e.g. `import { LIKE_REACTION } from './reactions';`), receive them as a parameter, or fetch them from runtime tenant config.
+- **Wrong pattern:** `post.addReaction("like")` — the literal string couples your client to one specific console state.
+
+### Custom Post Types Must Declare `dataType`
+Amity routes custom-shape post payloads via the `dataType` tag. Omitting it makes the SDK fall back to text rendering — your custom data renders as a JSON-stringified blob in the UI.
+- **Correct pattern:** `createPost({ dataType: "custom.poll", data: { question, options } })` — both fields together.
+- **Wrong pattern:** `createPost({ data: { score: 100, level: "expert" } })` with no `dataType` set.
 
 ## SDK Version Handling
 
@@ -159,6 +245,18 @@ vise plan . --request "<feed or post request>"
 
 Require a concrete target from the app: current user feed, selected community, selected channel, or another user-provided domain object. Do not hardcode random target IDs.
 
+**Demo wiring (when the app needs to compile before the real target source exists):** even at the top-level `App` / `MaterialApp` / `_app.tsx` / `AppDelegate` wiring site, do not pass a literal string. Use the host platform's compile-time env channel so the rule sees no string literal at the call site:
+
+- Flutter: `const String.fromEnvironment('AMITY_COMMUNITY_ID')` — value injected via `flutter run --dart-define=AMITY_COMMUNITY_ID=…`
+- TypeScript / React / Next.js: `process.env.NEXT_PUBLIC_AMITY_COMMUNITY_ID` (or framework equivalent — `EXPO_PUBLIC_`, `VITE_`)
+- React Native: `process.env.AMITY_COMMUNITY_ID` (via `react-native-config` or a build-time replacement)
+- Android: `BuildConfig.AMITY_COMMUNITY_ID` populated from `buildConfigField` in `build.gradle`
+- iOS: `ProcessInfo.processInfo.environment["AMITY_COMMUNITY_ID"]` or an `xcconfig` build setting
+
+If the customer prefers a runtime source (route param, app state, user selection), document the source in the attestation rather than committing a placeholder literal.
+
+**Custom Post Types:** When creating a post with a custom data payload (e.g. an object or dictionary), the `dataType` tag must be explicitly provided in the same call so the SDK routes it correctly. If the custom payload intentionally falls back to a text post, add `// vise: custom post type <reason>` to the code.
+
 For notification setup:
 
 ```bash
@@ -177,6 +275,55 @@ vise plan . --request "<live data request>"
 
 Require object vs collection, observed domain, lifecycle owner, loading/error/update states, and observer/subscription cleanup.
 
+For comments:
+
+```bash
+vise search-docs "comment reply thread create observe"
+vise plan . --request "<comment request>"
+```
+
+Require target source (post ID from parent entity, not hardcoded), observer cleanup on view disposal, loading/empty/error states, and moderation affordance on comment content.
+
+### Moderation UX
+
+When rendering moderation actions (like `flagPost`, `deletePost`, `banUser`, `muteChannelMember`), you must ensure these actions are gated by a role check. Showing these buttons to all users causes a poor UX since the API calls will fail for non-moderators.
+
+- **Correct pattern**: Wrap the button or action in a role check (e.g. `currentUser.roles.contains('moderator')`, `isModerator`, `permissions.includes('moderation')`).
+- **Wrong pattern**: Unconditionally rendering `flagPost` or `banUser` and relying on the server to return a 403 error.
+
+Similarly, moderator-only data such as `flagCount` must not be leaked to non-moderators. Rendering `post.flagCount` unconditionally exposes moderation signal to all users, which is a privacy regression. Gating it with a role check ensures it is only visible to authorized users.
+
+### User Ban State
+
+Banned users still see interaction buttons (like `createPost`, `createComment`, `sendMessage`) if you don't check their ban state before rendering them. These API calls will fail on the server, causing a poor UX and support tickets.
+
+- **Correct pattern**: Wrap interaction buttons in a ban state check (e.g. `!currentUser.isGlobalBan`, `!user.banState`, `!channel.isMuted`).
+- **Wrong pattern**: Unconditionally rendering `createPost` or `sendMessage` buttons for a banned user.
+
+For reactions:
+
+```bash
+vise search-docs "reaction add remove list"
+vise plan . --request "<reaction request>"
+```
+
+Reaction names are per-tenant. Retrieve the reaction name from a configuration file, backend response, or component prop instead of hardcoding a string literal like `"like"`. If the literal matches the console config, add `// vise: reaction "<name>" matches console config` to the code.
+
+For chat/messaging:
+
+```bash
+vise search-docs "chat channel message send observe"
+vise plan . --request "<chat request>"
+```
+
+Require chat shape (1:1, group, community), channel source (never hardcode channelId), message observer cleanup on view dismissal, send error handling, and moderation affordance on messages.
+
+**Channel Types:** When creating channels, the channel type must match the semantic shape of the UI:
+- Use `conversation` for 1:1, DM, or private-chat semantics.
+- Use `broadcast` for one-way announcement channels.
+- Use `community` or `live` for groups.
+If the type intentionally mismatches the UI name, add `// vise: channel type rationale — <reason>` to the code.
+
 ## Monorepos
 
 If `vise inspect .` reports multiple surfaces, choose the intended app with the user or surrounding task context. Pass it consistently: