@realtimexsco/live-chat 1.4.17 → 1.4.19

package/PERMISSIONS.md

@@ -56,6 +56,215 @@ Same rules apply in **DM and group** chats.
 
 ---
 
+## Permission reference (with live examples)
+
+Everything below comes from one response:
+
+```http
+GET /settings/effective
+```
+
+```json
+{
+  "pushNotificationEnabled": true,
+  "audioCallEnabled": true,
+  "videoCallEnabled": true,
+  "blockUsersEnabled": true,
+  "groupCreationEnabled": true,
+  "calls": {
+    "allowedByPlatform": true,
+    "configured": true,
+    "enabled": true
+  },
+  "attachments": {
+    "enabled": true,
+    "maxFileSizeMB": 10,
+    "allowedMimeTypes": ["image/*", "video/*", "audio/*", "application/pdf"],
+    "maxAttachmentsPerMessage": 10
+  },
+  "groupPolicy": {
+    "defaults": {
+      "onlyAdminCanSendMessage": false,
+      "onlyAdminCanEditInfo": false,
+      "senderCanEditMessage": true,
+      "allowMemberAdd": true,
+      "allowMemberRemove": false,
+      "moderationEnabled": false
+    },
+    "locked": []
+  },
+  "messageTimers": {
+    "dmEditMinutes": 5,
+    "dmDeleteMinutes": 5,
+    "groupEditMinutes": 10,
+    "groupDeleteMinutes": 10
+  },
+  "maxAdminsPerGroup": 5,
+  "maxParticipantsPerGroup": 100,
+  "maxPinnedMessagesPerConversation": 10
+}
+```
+
+These are the same values shipped as `DEFAULT_EFFECTIVE_SETTINGS` (used before the fetch resolves, and as a fallback if the fetch fails), so the examples below double as "what you get out of the box."
+
+### `pushNotificationEnabled`
+
+Single on/off switch for the push-notification row in Settings.
+
+- Admin sets it `false` → the toggle row stays visible, the switch is disabled, hovering shows *"This feature is disabled by your administrator."*
+- Check it yourself: `useAdminFeatureGate("pushNotification").enabled`
+
+### `audioCallEnabled` / `videoCallEnabled`
+
+Per-call-type switches for the header phone / video buttons. They are evaluated **after** the three `calls.*` gates below — see [Calls check order](#calls-check-order).
+
+- `videoCallEnabled: false`, everything else `true` → video button greyed out, tooltip *"This feature is disabled by your administrator."*; phone button unaffected.
+- Check it yourself: `useAdminFeatureGate("videoCall")` / `useAdminFeatureGate("audioCall")`
+
+### `calls.allowedByPlatform` / `calls.configured` / `calls.enabled`
+
+Three gates checked **in order** before `audioCallEnabled`/`videoCallEnabled` are even looked at — first failing one wins:
+
+| Field is `false` | Tooltip shown |
+|---|---|
+| `calls.allowedByPlatform` | *"Calls are not allowed on this platform. Please contact your administrator."* |
+| `calls.configured` | *"Calls are not configured. Please contact your administrator."* |
+| `calls.enabled` | *"This feature is disabled by your administrator."* |
+
+Example: a workspace on a plan without calling has `"calls": { "allowedByPlatform": false, "configured": true, "enabled": true }`. Both call buttons stay visible but disabled with the "not allowed on this platform" message — `videoCallEnabled: true` doesn't matter, the platform check runs first.
+
+### `blockUsersEnabled`
+
+Gates the "Block user" item in the conversation's overflow menu.
+
+- `false` → menu item stays visible, disabled, tooltip *"This feature is disabled by your administrator."*
+- Check it yourself: `useAdminFeatureGate("blockUsers").enabled`
+
+### `attachments.enabled`
+
+Master switch for the paperclip / attach button.
+
+- `false` → attach button visible but disabled, same tooltip pattern.
+- Check it yourself: `useAdminFeatureGate("attachments").enabled`
+
+### `attachments.maxFileSizeMB`
+
+Per-file size ceiling, enforced client-side before upload.
+
+- `maxFileSizeMB: 10` and the user picks a 15 MB video → the picker rejects it before it's added to the message.
+- Read the raw value (there's no gate for this, it's a limit not a boolean): `useEffectiveSettingsOptional().settings.attachments.maxFileSizeMB`
+
+### `attachments.allowedMimeTypes`
+
+Whitelist of MIME patterns the file picker accepts. `"*"` or `"*/*"` in the list means "allow everything."
+
+- `["image/*", "application/pdf"]` → the file picker's `accept` attribute (and any manual filtering) only allows images and PDFs; a `.zip` is rejected.
+- Read it: `settings.attachments.allowedMimeTypes`
+
+### `attachments.maxAttachmentsPerMessage`
+
+Caps how many files can ride on one message.
+
+- `maxAttachmentsPerMessage: 10` and the user has already attached 10 images → the attach button (or drop zone) stops accepting more until one is removed.
+
+### `groupCreationEnabled`
+
+Gates the "New group" tab in the create-chat dialog.
+
+- `false` → tab stays visible, disabled, tooltip explains why.
+- Check it yourself: `useAdminFeatureGate("groupCreation").enabled`
+
+### `groupPolicy.defaults` — starting permissions for a *new* group
+
+Each key seeds the permission drawer when a group is created; group admins can still change them afterward **unless locked** (see next section).
+
+| Key | Meaning | Example |
+|---|---|---|
+| `onlyAdminCanSendMessage` | If `true`, only admins can post — everyone else is read-only | Announcement-only groups set this `true` |
+| `onlyAdminCanEditInfo` | If `true`, only admins can change group name/avatar/description | Prevents members from renaming the group |
+| `senderCanEditMessage` | If `true`, a member can edit their own sent messages | `false` disables the "Edit" option on your own messages |
+| `allowMemberAdd` | If `true`, non-admin members can add other people | `false` restricts inviting to admins only |
+| `allowMemberRemove` | If `true`, non-admin members can remove other members | Usually left `false`; only admins remove people |
+| `moderationEnabled` | If `true`, messages go through the moderation pipeline before appearing | Turned on for public/large groups |
+
+### `groupPolicy.locked` — permissions the workspace admin has frozen
+
+An array of the `GroupPermissions` keys above (or arbitrary policy keys) that a **group admin cannot toggle** in the permission drawer, no matter what they pick.
+
+- `"locked": ["onlyAdminCanSendMessage", "moderationEnabled"]` → in the group's permission drawer, those two rows render disabled at whatever value `defaults` set them to; every other row stays editable.
+- Check it yourself: `useEffectiveSettingsOptional().isGroupPermissionLocked("onlyAdminCanSendMessage")` → `true`/`false`
+
+### `messageTimers.*`
+
+Editable/deletable time windows, split by conversation type. Each is "minutes since send."
+
+- `dmEditMinutes: 5` → in a 1:1 chat, the "Edit" option disappears from a message 5 minutes after it was sent.
+- `groupDeleteMinutes: 10` → in a group, "Delete for everyone" disappears 10 minutes after send (still allows "Delete for me").
+- `dmDeleteMinutes` / `groupEditMinutes` follow the same pattern for their combination.
+
+### `maxAdminsPerGroup`
+
+Ceiling on how many members can hold admin rights in one group.
+
+- `maxAdminsPerGroup: 5` and a group already has 5 admins → the "Make admin" action is disabled for remaining members until an existing admin is demoted.
+
+### `maxParticipantsPerGroup`
+
+Ceiling on total members in a group.
+
+- `maxParticipantsPerGroup: 100` and the group has 100 members → "Add members" stops accepting new invites, whether the group was created here or is at the platform-wide cap.
+
+### `maxPinnedMessagesPerConversation`
+
+Ceiling on pinned messages, per conversation (DM or group).
+
+- `maxPinnedMessagesPerConversation: 10` and 10 messages are already pinned → the "Pin" action on an 11th message is disabled until something is unpinned.
+
+---
+
+## Setting these values (important: read this before asking "how do I set X")
+
+The package calls **`GET /settings/effective`** ([settings.api.ts](src/services/api/settings.api.ts)) — it only *reads* this JSON, there is no `PUT`/`POST` in this SDK for most of it. Where a value comes from splits into two groups:
+
+### Group A — workspace-wide settings (backend/admin-panel only)
+
+`calls.allowedByPlatform`, `calls.configured`, `calls.enabled`, `audioCallEnabled`, `videoCallEnabled`, `pushNotificationEnabled`, `blockUsersEnabled`, `groupCreationEnabled`, `attachments.*`, `messageTimers.*`, `maxAdminsPerGroup`, `maxParticipantsPerGroup`, `maxPinnedMessagesPerConversation`, and `groupPolicy.locked`.
+
+**This npm package cannot set these.** They're whatever your backend returns from `/settings/effective` — that response is produced by your server/admin dashboard, which lives outside this SDK. To change `calls.allowedByPlatform` or `maxAdminsPerGroup`, go to wherever your team configures that endpoint (admin panel, database row, backend config) and change it there. Once changed, the package picks it up automatically on the next `refresh()` (or next mount) — no package-side action needed.
+
+If you don't have that admin panel yet, this SDK doesn't provide one — you'd build/expose it server-side and have it write into the same store `/settings/effective` reads from.
+
+```ts
+// You CANNOT do this — there is no setter for workspace settings:
+// settings.calls.allowedByPlatform = false   ❌ read-only, and mutating it wouldn't call the server anyway
+// settings.maxAdminsPerGroup = 10             ❌ same
+
+// What you CAN do: re-fetch after the backend/admin side changes it
+const { refresh } = useEffectiveSettingsOptional();
+await refresh(); // re-pulls GET /settings/effective
+```
+
+### Group B — per-conversation group permissions (settable from this package)
+
+Only the 6 `groupPolicy.defaults` keys (`onlyAdminCanSendMessage`, `onlyAdminCanEditInfo`, `senderCanEditMessage`, `allowMemberAdd`, `allowMemberRemove`, `moderationEnabled`) can be changed through this SDK, and only **per group**, and only for keys **not** in `groupPolicy.locked` — a locked key always wins regardless of what a group admin submits.
+
+This ships as `PermissionDrawer` in the default UI, backed by the store action `updateGroupPermissions`, which calls `POST /conversation/group/permission/update`:
+
+```ts
+import { useStore } from "@realtimexsco/live-chat";
+
+const updateGroupPermissions = useStore((s) => s.updateGroupPermissions);
+
+// Toggle "only admins can send messages" on for this one group
+await updateGroupPermissions(conversationId, {
+  onlyAdminCanSendMessage: true,
+});
+```
+
+Server-side, locked keys should be rejected/ignored even if a client sends them — the drawer already keeps locked rows disabled, but don't rely on the client alone to enforce that.
+
+---
+
 ## Exports you need
 
 ```ts

package/README.md

@@ -2,9 +2,9 @@
 
 > Drop-in real-time chat UI for React and Next.js — direct messages, group chats, reactions, replies, forwarding, pinned/starred messages, and more. Built on Socket.IO, Zustand, Tailwind CSS v4, and Radix UI.
 
-[npm version](https://www.npmjs.com/package/@realtimexsco/live-chat)
-[npm downloads](https://www.npmjs.com/package/@realtimexsco/live-chat)
-[license](#license)
+[![npm version](https://img.shields.io/npm/v/@realtimexsco/live-chat.svg)](https://www.npmjs.com/package/@realtimexsco/live-chat)
+[![npm downloads](https://img.shields.io/npm/dm/@realtimexsco/live-chat.svg)](https://www.npmjs.com/package/@realtimexsco/live-chat)
+[![License: MIT](https://img.shields.io/npm/l/@realtimexsco/live-chat.svg)](#license)
 
 
 |              |                                                                                    |

package/dist/firebase-messaging-sw.js

@@ -314,14 +314,17 @@ if (rawConfig) {
           }
 
           var data = payload.data || {};
+          var isCall = data.kind === "call";
           var title =
             (payload.notification && payload.notification.title) ||
             data.title ||
-            "New message";
+            (isCall
+              ? "Incoming " + (data.mode === "video" ? "video" : "voice") + " call"
+              : "New message");
           var body =
             (payload.notification && payload.notification.body) ||
             data.body ||
-            "";
+            (isCall ? "Tap to open the chat" : "");
 
           console.log(
             "[realtimex-push] single background notification:",