ab-ecosystem-cpass 1.0.11 → 1.0.13

package/docs/inbox/connection.md

@@ -132,6 +132,8 @@ try {
 |---|---|---|
 | 401 | `unauthorized` | The handshake's token did not verify. |
 | 403 | `forbidden` | The action is beyond this member's permissions. |
+| 403 | `A403` | The role does not hold the permission the action needs. |
+| 403 | `E403` | The account's plan does not include the feature. `details.feature` names it. |
 | 404 | `not_found` | No such chat or message **for this account**. |
 | 422 | `validation_failed` | Payload rejected. `details` names the fields. |
 | 500 | `internal_error` | Server fault. Nothing further is disclosed. |
@@ -146,6 +148,29 @@ Every read and write is scoped to the account the token identifies, the same way
 the REST contact endpoints are. Quoting another account's chat or message id
 produces `404`, not that account's data.
 
+Which account that is depends on who signed in. The token's `act` claim says:
+
+| `act` | The account | Who you are |
+|---|---|---|
+| `owner` (or absent) | your own `psuid` | the account holder |
+| `member` | the `accountId` claim | someone the holder granted access to |
+
+A member works inside the owner's account — the owner's chats, contacts and
+channels, counted against the owner's plan. How much of it they see is the
+role's `data_scope`:
+
+| `data_scope` | Sees |
+|---|---|
+| `own` (or absent) | the chats and contacts assigned to them |
+| `all` | everything in the account |
+
+Absent means `own`: a role the server could not read narrows rather than opens.
+Nothing distinguishes an owner from a member in a request — the same events, the
+same payloads — and a chat nobody assigned you simply is not there. A chat
+assigned to nobody at all is the account's, not everybody's, so an `own`-scoped
+member does not see it either; `live_chat.unassigned.*` below is how that is
+granted.
+
 ## Permissions
 
 Visibility inside an account is gated on inbox permissions, not API scopes. An
@@ -160,6 +185,69 @@ owner or a manager is never gated; a team member needs the permission named.
 A team member without these is narrowed to their own chats rather than refused —
 and the reply says so. See [chats.md](https://github.com/udghatan-dev/crm-sdk/blob/main/packages/sdk-js/docs/inbox/chats.md#the-applied-filter).
 
+The token carries a `roleId` rather than a list of permissions. The server
+resolves it against the SSO at connect — once per role version, cached — and the
+grants it returns are what the table above is checked against. A role that
+grants none of these names leaves the member in the narrow case: their assigned
+chats, no unassigned queue, no sending as somebody else. So does a role the SSO
+cannot be asked about, which is deliberate — an SSO outage narrows a member, it
+never opens an account.
+
+Permissions are read once, at connect. A role edited mid-session takes effect on
+the next reconnect, the same way an upgraded plan does. A member's `role` is
+`team_member` unless the token says `manager`.
+
+### Permission keys, per event
+
+`CRM.CHAT` governs the inbox, and every event names a verb of it. There is no
+router here, so the check runs in the dispatcher in the position route
+middleware would occupy — before the handler, after the payload is validated.
+
+| Event | Key |
+| --- | --- |
+| `contact.list`, `ctwa.list` | `CRM.CHAT.LIST` |
+| `contact.fetch`, `chat_session.list`, `message.list`, `message.fetch`, `message.retry_download` | `CRM.CHAT.READ` |
+| `message.send` | `CRM.CHAT.SEND` |
+| `message.delete` | `CRM.CHAT.DELETE` |
+| `contact.update`, `contact.done`, `contact.bot_assign` | `CRM.CHAT.UPDATE` |
+| `chat.action` | **depends on the action** |
+| `ping` | none — it is a liveness probe |
+
+`chat.action` carries thirteen actions under one event name, and they are not one
+capability: `transfer` and `bulk_transfer` need `CRM.CHAT.TRANSFER`, `delete`
+needs `CRM.CHAT.DELETE`, and the state changes — archive, unarchive, close, done,
+block, mark read/unread, pause/resume automation, pause timer — need
+`CRM.CHAT.UPDATE`. The key is resolved from the validated payload, so a client
+that may archive but not delete gets `A403` on the second and nothing changes.
+
+`contact.bot_assign` is `UPDATE`, not `ASSIGN`: it hands a conversation to
+automation rather than to a colleague, and the catalogue's `ASSIGN` implies
+`TEAM.LIST` because choosing a person means seeing the team.
+
+A refusal arrives as the same `A403` / `E403` the REST API returns, in the
+acknowledgement callback and as an `error` emit.
+
+### `live_chat.*` is a separate, older vocabulary
+
+The three permissions in the table above this section are **not in the SSO's
+catalogue**. A role can only grant what the catalogue publishes, so nothing can
+currently grant `live_chat.unassigned.ALL` — the way to give a member the whole
+account's inbox is `data_scope: all` on their role, which `CRM.CHAT` is marked
+**scopable** for. The three names are kept because the inbox still checks them.
+
+### Two different refusals
+
+Beyond the inbox's own visibility rules, an action can be refused for either of
+two reasons, and the codes are distinct because the answers are:
+
+- **`A403`** — the role does not hold the permission. Ask the account owner.
+- **`E403`** — the account's plan does not cover the feature. Upgrade.
+  `details.feature` names the feature, so the client can say which.
+
+An owner is never refused for `A403` — there is no role to check them against —
+but an owner *is* refused for `E403`: a feature outside the plan is outside it
+for everybody on the account.
+
 ## Modules
 
 | Page | Actions |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ab-ecosystem-cpass",
-  "version": "1.0.11",
+  "version": "1.0.13",
   "description": "JavaScript/TypeScript SDK for the CPaaS CRM gateway: audience and channels",
   "license": "MIT",
   "main": "dist/index.js",