upstream-rocketchat/packages/ddp-client/README.md

# 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