diff --git a/README.md b/README.md index 2a6ef87..d4d9525 100644 --- a/README.md +++ b/README.md @@ -29,12 +29,13 @@ Also, add [typing indicators](https://www.pubnub.com/docs/chat/chat-sdk/build/fe ## Samples -Test our TypeScript sample chat apps created in various JavaScript frameworks: +Test our sample Chat SDK apps created in various frameworks: -| Source code | Framework | Description | -| :------------------------------------------------------------------------------------------ | :----------- | :--------------------------------------------------------------------------------------- | -| [Direct chat](https://github.com/pubnub/js-chat/blob/master/samples/getting-started/README.md) | React | Basic 1:1 support chat letting you exchange messages between a user and a support agent. | -| [Group chat](https://github.com/pubnub/js-chat/blob/master/samples/react-native-group-chat/README.md) | React Native | Feature-full group chat letting you test most of the features offered by the Chat SDK. | +| Source code | Framework | Description | +| :--------------------------------------------------------------------------------------------------------------- | :----------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| [Direct chat](https://github.com/pubnub/js-chat/blob/master/samples/getting-started/README.md) | React | Basic 1:1 support chat letting you exchange messages between a user and a support agent. | +| [Group chat](https://github.com/pubnub/js-chat/blob/master/samples/react-native-group-chat/README.md) | React Native | Feature-full group chat letting you test most of the features offered by the Chat SDK. | +| [Access Manager API service](https://github.com/pubnub/js-chat/blob/master/samples/access-manager-api/README.md) | NestJS | Backend service creating an authentication key endpoint for users, integrated with PubNub's Chat SDK to generate Access Manager authentication tokens with appropriate permissions. It allows for controlled access to all channels and reflects user-specific restrictions, with tokens expiring after 15 minutes. | ## Chat SDK docs diff --git a/samples/README.md b/samples/README.md index 676fe37..7b81198 100644 --- a/samples/README.md +++ b/samples/README.md @@ -4,7 +4,8 @@ This folder contains sample applications created with Chat SDK and various frame Follow the instructions behind the links to run a chosen app. -* [getting-started](https://github.com/pubnub/js-chat/tree/master/samples/getting-started/README.md) -* [react-native-group-chat](https://github.com/pubnub/js-chat/tree/master/samples/react-native-group-chat/README.md) +- [access-manager-api](https://github.com/pubnub/js-chat/tree/master/samples/access-manager-api/README.md) +- [getting-started](https://github.com/pubnub/js-chat/tree/master/samples/getting-started/README.md) +- [react-native-group-chat](https://github.com/pubnub/js-chat/tree/master/samples/react-native-group-chat/README.md) This folder also contains [e2e automation tests](https://github.com/pubnub/js-chat/tree/master/samples/e2e-tests) covered with Playwright framework. diff --git a/samples/access-manager-api/README.md b/samples/access-manager-api/README.md index ae884ab..5d904cd 100644 --- a/samples/access-manager-api/README.md +++ b/samples/access-manager-api/README.md @@ -1,35 +1,88 @@ -## Description +# Access Manager API service -Sample code for PubNub Access Manager API +This simple NestJS service contains an endpoint generating authentication keys for selected users that can be used in Chat SDK apps using [PubNub's Access Manager](https://www.pubnub.com/docs/general/security/access-control) to control user-to-channel permissions. -## Installation +In its simplest use case, the Access Manager API service's controller (`AppController`) defines an `/auth-key/:userId` endpoint and listens to it on port `3000`. When a GET request is made to this endpoint with any `userId`, the `getAccessToken` method in the controller is called, and an authentication token (`authKey`) is generated for that user. -```bash -$ yarn install +For example, by calling the endpoint `http://localhost:3000/auth-key/jenny`, the following authentication key is generated for user `jenny`. + +```html +{"authKey":"qEF2AkF0GmZF1rdDdHRsD0NyZXOlRGNoYW6sc2dlbmVyYWxfY2hhdC1wbnByZXMYI2xnZW5lcmFsX2NoYXQYI3Jrbm93bGVkZ2VfZXhjaGFuZ2UYI3FxdWlja19oZWxwLXBucHJlcxgjdnRlYW1fZGlzY3Vzc2lvbi1wbnByZXMYI2xqZW5ueS1wbnByZXMY72pxdWlja19oZWxwGCNvdGVhbV9kaXNjdXNzaW9uGCNlamVubnkY725wcmlvcml0eV9xdWV1ZRgjdXByaW9yaXR5X3F1ZXVlLXBucHJlcxgjeBlrbm93bGVkZ2VfZXhjaGFuZ2UtcG5wcmVzGCNDZ3JwoENzcGOgQ3VzcqBEdXVpZKJsamVubnktcG5wcmVzGO9lamVubnkY70NwYXSlRGNoYW6gQ2dycKBDc3BjoEN1c3KgRHV1aWSgRG1ldGGgRHV1aWRlamVubnlDc2lnWCBppKbGcIMw3bI92NVfg6KD0GZyw_MR7AD2ci7r-2y82w=="} ``` -## Running the app +This Access Manager API service is configured to work with a [Chat SDK](https://www.pubnub.com/docs/chat/chat-sdk/overview) application. Once you provide the Admin Portal keys to your app (publish, subscribe, and secret) in the `chatsdk.service.ts` file (`ChatSdkService`) of this service, its controller (`AppController`) delegates the business logic to the `AppService` through the `getAuthKey` method. The `AppService` uses the `ChatSdkService` to initialize and interact with the Chat SDK. Depending on whether the user exists on the Chat SDK app and what their channel restrictions are, the `AppService` constructs and returns a token with reflected permissions. -```bash -# development -$ yarn run start +By default, the Access Manager API service integrated with the Chat SDK app will generate authentication tokens that grant users all access to all channels on a selected keyset, contrary to the default Access Manager behavior where enabling it on the Admin Portal immediately restricts all users' access on all channels on a given keyset. When the Chat SDK app sets other permissions for selected users (for example, mutes them on or bans them from a given channel), the permissions schema in the Access Manager API service will reflect that in the autogenerated token for that user and set the token to expire after 15 minutes. -# watch mode -$ yarn run start:dev +To check how the Access Manager permissions schema is defined in the Access Manager API service, head to the [`app.service.ts`](https://github.com/pubnub/js-chat/tree/master/samples/access-manager-api/src/app.service.ts) file. -# production mode -$ yarn run start:prod -``` +> **NOTE:** You can use the Access Manager API service in an end-to-end scenario to see how to integrate Access Manager in your Chat SDK app. To do that, use [Channel Monitor](https://www.pubnub.com/docs/bizops-workspace/channel-monitor) from [BizOps Workspace](https://www.pubnub.com/docs/bizops-workspace/basics) to mute or ban users on a given keyset, Access Manager API service to generate authentication tokens for users with correct permissions on channels, and the [React Native Group Chat](https://github.com/pubnub/js-chat/tree/master/samples/react-native-group-chat) app to mock muted/banned users. -## Test +## Prerequisites -```bash -# unit tests -$ yarn run test +To run the Access Manager API service, make sure you have the following: -# e2e tests -$ yarn run test:e2e +- [yarn](https://classic.yarnpkg.com/en/docs/install) (>=1.22.19) +- Code Editor (e.g. [Visual Studio Code](https://code.visualstudio.com/download)) +- PubNub [Publish, subscribe, and secret keys](https://www.pubnub.com/docs/basics/initialize-pubnub) that you can obtain from [Admin Portal](https://admin.pubnub.com/) after setting up an [account](https://www.pubnub.com/docs/setup/account-setup). The autogenerated **Demo Keyset** in **My First App** on the Admin Portal already contains the required configuration (enabled **App Context** and selected region). -# test coverage -$ yarn run test:cov -``` +## Usage + +To run the service, follow these steps: + +1. Open the terminal, select the location, and download the Chat SDK repository. + + ```ssh showLineNumbers + git clone git@github.com:pubnub/js-chat.git + ``` + +1. Go to the downloaded repository folder. + + ```bash showLineNumbers + cd js-chat + ``` + +1. Go to the `samples/access-manager-api` folder with the service's source code. + + ```bash showLineNumbers + cd ../samples/access-manager-api + ``` + +1. Provide the Admin Portal keys to your app (publish, subscribe, and secret) in the `chatsdk.service.ts` file and specify the admin user. + + ```ts + async getChatSdkInstance() { + return Chat.init({ + publishKey: 'YOUR_PUB_KEY', + subscribeKey: 'YOUR_SUB_KEY', + secretKey: 'YOUR_SECRET_KEY', + userId: 'secret-user', + }); + } + ``` + +1. Run the app in the terminal. + + ```bash + # development + $ yarn run start + + # watch mode + $ yarn run start:dev + + # production mode + $ yarn run start:prod + ``` + + Alternatively, use these commands for testing: + + ```bash + # unit tests + $ yarn run test + + # e2e tests + $ yarn run test:e2e + + # test coverage + $ yarn run test:cov + ``` diff --git a/samples/react-native-group-chat/README.md b/samples/react-native-group-chat/README.md index 6d635f2..142bc2c 100644 --- a/samples/react-native-group-chat/README.md +++ b/samples/react-native-group-chat/README.md @@ -20,7 +20,12 @@ To run the React Native Group Chat app, make sure to have the following: - [Node.js](https://nodejs.org/en/download/)(>=18.10.0) - [Xcode](https://developer.apple.com/xcode/) - Code Editor (e.g. [Visual Studio Code](https://code.visualstudio.com/download)) -- PubNub [Publish & Subscribe keys](https://www.pubnub.com/docs/basics/initialize-pubnub) that you can obtain from [Admin Portal](https://admin.pubnub.com/) after setting up an [account](https://www.pubnub.com/docs/setup/account-setup). You must enable **App Context** (with selected region, User Metadata Events, Channel Metadata Events, and Membership Metadata Events) and **Message Persistence** on your keyset to manage user and channel data in the app. +- PubNub [Publish & Subscribe keys](https://www.pubnub.com/docs/basics/initialize-pubnub) that you can obtain from [Admin Portal](https://admin.pubnub.com/) after setting up an [account](https://www.pubnub.com/docs/setup/account-setup). You must enable the following configuration options on your app's keyset: + - **App Context** (with selected region, `User Metadata Events`, `Channel Metadata Events`, and `Membership Metadata Events`) to manage user and channel data in your app. If you use Access Manager in the app, the `Disallow Get All Channel Metadata` and `Disallow Get All User Metadata` options must be unmarked. + - **Message Persistence** to store messages in your app. + - **Access Manager** if you want to use Access Manager in your app. + +> **NOTE:** You can use the React Native Group Chat app in an end-to-end scenario to see how to integrate Access Manager in your Chat SDK app. To do that, use [Channel Monitor](https://www.pubnub.com/docs/bizops-workspace/channel-monitor) from [BizOps Workspace](https://www.pubnub.com/docs/bizops-workspace/basics) to mute or ban users on a given keyset, [Access Manager API service](https://github.com/pubnub/js-chat/tree/master/samples/access-manager-api) to generate authentication tokens for users with correct permissions on channels, and the React Native Group Chat app to mock muted/banned users. ## Usage @@ -35,7 +40,7 @@ To run the app on an iOS simulator, follow these steps: 1. Go to the downloaded repository folder. ```bash showLineNumbers - cd js-chat-master + cd js-chat ``` 1. Install all the required dependencies.