diff --git a/.changeset/cyan-balloons-unite.md b/.changeset/cyan-balloons-unite.md new file mode 100644 index 00000000000..608b6d970f4 --- /dev/null +++ b/.changeset/cyan-balloons-unite.md @@ -0,0 +1,5 @@ +--- +"@rocket.chat/ddp-client": patch +--- + +chore: Add readme to ddp-client package diff --git a/ee/packages/ddp-client/README.md b/ee/packages/ddp-client/README.md new file mode 100644 index 00000000000..81cfe53fffe --- /dev/null +++ b/ee/packages/ddp-client/README.md @@ -0,0 +1,90 @@ +# Getting started +Add `@rocket.chat/ddp-client` and `@rocket.chat/emitter` as dependencies of your project: + +`yarn add @rocket.chat/ddp-client @rocket.chat/emitter` +or: +`npm install @rocket.chat/ddp-client @rocket.chat/emitter` + +> @rocket.chat/emitter is listed as a peer dependency of ddp-client and is strictly necessary to make it work. + +> Tip: The whole project is typed using typescript. For that reason, references to interfaces and objects will be kept to a minimum. + +## Setting up the SDK + >This works out of the box for browsers. if you want to use it on NodeJS, you need to offer a `WebSocket` implementation and a `fetch` implementation. + + First things first, let's import the SDK: + `import { DDPSDK } from '@rocket.chat/ddp-client';` + + Now we need to create a new SDK instance. Fortunately, `DDPSDK` exposes a `create` function that initalizes everything for a quick setup: + `const sdk = DDPSDK.create('http://localhost:3000');` + + We can then try to connect to the Rocket.Chat instance by doing: + `await sdk.connection.connect();` + + You can check the connection status by referencing `sdk.connection.status`. If everything went right, it's value should be `'connected'`. + +> If you're feeling fancy, you can create and connect in a single function call: +> `const sdk = DDPSDK.createAndConnect('http://localhost:3000');` + +## SDK Modules +### Connection + +Responsible for the connection to the server, status and connection states. + +### Account + +Responsible for the account management, login, logout, handle credentials, get user information, etc. + +### ClientStream + +Responsible for the DDP communication, method calls, subscriptions, etc. + +### TimeoutControl + +Responsible for the Reconnection control + +### RestClient + +Responsible for the REST API communication for more info [see here](https://developer.rocket.chat/reference/api/rest-api) + +## Login handling + +The just created `sdk` exposes an `account` interface (`sdk.account`), which should have everything you need. It has 3 methods: + + 1. `sdk.account.loginWithPassword(username, hashedPassword)` + - This method accepts 2 parameters, `username` and `password`. The password must be hashed as `sha-256` for it to work + 2. `sdk.account.loginWithToken('userTokenGoesHere')` + - If you already got the token someway through the API, you can call this method. + 3. `sdk.account.logout()` + - This one is self-explanatory. + +While the `sdk` instance is kept in memory, you can find some user information and credentials by referencing `sdk.account.user` + +## REST API +> TIP: You might have to enable CORS in your Rocket.Chat instance for this to work. + +The sdk exposes a `rest` interface, which accept all rest methods (`get`, `post`, `put`, `delete`). + +Example call: +`await sdk.rest.post('/v1/chat.sendMessage', { message: { rid: id, msg } });` + +> WARNING: if you wrap a rest call in a try catch block, the error will be of type `Response`. By calling `error.json()` you get access to the server error response. + +## Streams + +Rocket.Chat uses websockets as to provide realtime data. You can subscribe to publications in order to listen to data updates. + +Below is an example of subscribing to the room-messages publication, which receives message updates from a room: +```ts +const messages = new Map([]); +const stream = sdk.stream('room-messages', roomId, (args) => { + setMessages((messages) => { + messages.set(args._id, args); + return new Map(messages); +}); + +// Stop the stream when you're done +stream.stop(); +``` + +> TIP: always unsubscribe from publications when you're done with them. This saves bandwidth and server resources diff --git a/ee/packages/ddp-client/src/README.md b/ee/packages/ddp-client/src/README.md deleted file mode 100644 index 99e313f0dba..00000000000 --- a/ee/packages/ddp-client/src/README.md +++ /dev/null @@ -1,97 +0,0 @@ -[rest]: https://rocket.chat/docs/developer-guides/rest-api/ -[api-rest]: ../../api-client/ - - - -# Rocket.Chat Javascript/Typescript SDK - -Library for building Rocket.Chat clients in Javascript/Typescript. - -## Quick Start - -``` -npm install @rocket.chat/sdk --save -``` - -or - -``` -yarn add @rocket.chat/sdk -``` - -This is pretty straightforward, but covers all the basics you need to do! - -```ts -import { DDPSDK } from '@rocket.chat/sdk'; - -const sdk = DDPSDK.create('http://localhost:3000'); - -await sdk.connection.connect(); - -await sdk.accounts.login({ - user: { - username: 'username', - }, - password: 'password', -}); - -await sdk.stream('room-messages', 'GENERAL', (data) => { - console.log('RECEIVED->>', data); -}); - -await sdk.rest.post('chat.postMessage', { - rid: 'GENERAL', - msg: 'Hello World', -}); -``` - -This works out of the box for browsers. if you want to use it on NodeJS, you need to offer a `WebSocket` implementation and a `fetch` implementation. - -We decided to not include any of those dependencies on the SDK, keeping it as lightweight as possible. - -If you are coding in Typescript, which we recommend, you are going to inherit all the types from the Rocket.Chat server, so everything is going to be type safe. - -All types used on the server and original clients are going to be available for you to use. - -if you don't want to use realtime communication, you can use the REST API client directly: `@rocket.chat/api-rest` - -## Overview - -The sdk is implemented based on the following interface definition: - -```ts -export interface SDK { - stream(name: string, params: unknown[], cb: (...data: unknown[]) => void): Publication; - - connection: Connection; - account: Account; - client: ClientStream; - - timeoutControl: TimeoutControl; - rest: RestClient; -} -``` - -Which means that in case of any new feature, bug fix or improvement, you can implement your own SDK variant and use it instead of the default one. - -Each peace contains a set of methods and responsibilities: - -### Connection - -Responsible for the connection to the server, status and connection states. - -### Account - -Responsible for the account management, login, logout, handle credentials, get user information, etc. - -### ClientStream - -Responsible for the DDP communication, method calls, subscriptions, etc. - -### TimeoutControl - -Responsible for the Reconnection control - -### RestClient - -Responsible for the REST API communication for more info [see here][api-rest]