npm package: @poengalex/handy-channel-sdk
Description: SDK for using the Handy channel capabilities
Author: poengAlex
Latest version: 0.1.1

# Get started

## Installation

### Browser 
Add the handy-channel-sdk lib to your website.

Latest:
```html
<script src="https://unpkg.com/@poengalex/handy-channel-sdk"></script>
```

Specific version:
```html
<script src="https://unpkg.com/@poengalex/handy-channel-sdk@1.0.2"></script>
```

Latest of major
```html
<script src="https://unpkg.com/@poengalex/handy-channel-sdk@1"></script>
```

Access the the handy channel sdk by **HandyChannel.XXXXX** where XXXX is function or variable listed in this document.


### Other
```
npm i @poengalex/handy-channel-sdk
```

Please note that documentation is written with browser use in mind. Please remove **HandyChannel.** from any functions or varibles in this SDK to use it with import.

Another note: you should try and catch Promise when using await. For readability try and catch is not added to the examples in this documentation.

## Examples

### Create a controller
This example will create a channel and set the mode to up and down motion (HAMP - default), start motion and finally set the speed to 50%.



Share channelId and subscriberKey to the users that wants to join the channel.

```js
let controller = new HandyChannel.Controller();	
let channel = await controller.createChannel();
//Share channelId and subscriberKey to the subscribers:
console.log("channel.channelId:", channel.channelId);
console.log("channel.subscriberKey:", channel.subscriberKey);
await controller.start();
await controller.setSpeed(50);
```

### Create a user
This example will make a Handy join a channel with id: **channelId** and key: **subscriberKey**

```js
let user = new HandyChannel.User("YOUR_CONNECTION_KEY");
await user.joinChannel("channelId","subscriberKey")
```


---



# How to use

## API docs
The full detailed channel docs can be found here: <https://staging.handyfeeling.com/api/channel/v0/docs/>.


## Controller

You must initiate the Controller before you can use all the functions. this can be done with **createChannel** if you want a new channel or **reuseExistingChannel** if you want to reuse a channel you already have created.

### Controller class
Controller constructor.

apiUrlConfig - Optional API config (channel API url and Handy API v2 url) - default is set to Production
config - optional open API config
```ts
constructor(apiUrlConfig: ApiUrlConfig = CHANNEL_CONFIG_PRODUCTION, channelConfig: Partial<OpenAPIConfig> = {},apiConfig: Partial<OpenAPIConfig> = {}) {
```

Example production:
```js
let controller = new HandyChannel.Controller()
```

Example staging:
```js
let controller = new HandyChannel.Controller(HandyChannel.CHANNEL_CONFIG_STAGING);
```

### createChannel
Creates a new channel

```ts
createChannel(name: string = "", description: string = ""): Promise<Channel>
```

Example production:
```js
let controller = new HandyChannel.Controller();	
let channel = await controller.createChannel();
//Share channelId and subscriberKey to the subscribers:
console.log("channel.channelId:", channel.channelId);
console.log("channel.subscriberKey:", channel.subscriberKey);
```

### reuseExistingChannel
Reuses a exsisting channel. Use this function to initialize a channel that you already have created.

```ts
reuseExistingChannel(channelId: ChannelId,channelKey: string): Promise<Channel>
```

Example production:
```js
let controller = new HandyChannel.Controller();	
let channel = await reuseExistingChannel("CHANNEL_ID", "CHANNEL_KEY");
```

### getChannelInfo
Gets the latest channel info / Including any meta data that is change when setting commands

```ts
getChannelInfo(): Promise<Channel>
```

Example production:
```js
let controller = new HandyChannel.Controller();	
let channelInfo = await getChannelInfo();
```

### updateChannelInfo
Updates the channel information

```ts
updateChannelInfo(update: ChannelUpdate): Promise<Channel>
```

Example production:
```js
let controller = new HandyChannel.Controller();	
await controller.updateChannelInfo({name: "A_NEW_CHANNEL_NAME", description: "A_NEW_CHANNEL_DESCRIPTION"});
```

### updateChannelInfo
Close a channel

```ts
closeChannel(): Promise<Channel>
```

Example production:
```js
let controller = new HandyChannel.Controller();	
await controller.closeChannel();
```

### getSubscribers
Get a list of all the subscribers that are subscribing to the channel

```ts
getSubscribers(): Promise<Subscriber[]>
```

Example production:
```js
let controller = new HandyChannel.Controller();	
let subscribers = await controller.getSubscribers();
```

### setMode
Set mode on all the subscribers

- Default is HAMP mode. HAMP mode is a a mode where the Handy moves up and down continuslly with a set speed.

NB! Currently only HAMP mode is supported in the Channel API
NB! When creating a new channel the Mode is set to HAMP

```ts
setMode(mode:Mode = Mode.HAMP) : Promise<ModeUpdateResponse | ErrorResponse>
```

Example production - set mode to HAMP mode:
```js
let controller = new HandyChannel.Controller();	
await controller.setMode();
```

### start
Start the subscribing machines

NB! The channel must be in mode HAMP to use this function

```ts
start(start) : Promise<HAMPStartResponse | ErrorResponse>
```

Example production - start:
```js
let controller = new HandyChannel.Controller();	
await controller.start();
```

### stop
Stop the subscribing machines

NB! The channel must be in mode HAMP to use this function

```ts
stop(start) : Promise<HAMPStopResponse | ErrorResponse>
```

Example production - start and stop after 5000ms:
```js
let controller = new HandyChannel.Controller();	
await controller.start();
setTimeout(async ()=>{
    await controller.stop();
},5000)

```

### setSpeed
Set the speed of the subscribing machines

NB! The channel must be in mode HAMP to use this function. start must be called to for this to have an effect. When calling start() the speed is reset to 0%.

```ts
setSpeed(velocity:number) : Promise<HAMPVelocityPercentResponse | ErrorResponse>
```

Example production - set speed to 50%:
```js
let controller = new HandyChannel.Controller();	
await controller.start();
await controller.setSpeed(50);
```

### setSpeed
Set the speed of the subscribing machines

NB! The channel must be in mode HAMP to use this function. start must be called to for this to have an effect. When calling start() the speed is reset to 0%.

```ts
setStrokeZone(settings: SlideSettings) : Promise<SlideUpdateResponse | ErrorResponse>
```

Example 1: set min stroke to 10%:
```js
let controller = new HandyChannel.Controller();	
await controller.start();
await controller.setStrokeZone({min:10});
```

Example 2: set max stroke to 90%:
```js
let controller = new HandyChannel.Controller();	
await controller.start();
await controller.setStrokeZone({max:90});
```

Example 3: set min stroke to 20% and max stroke to 75%:
```js
let controller = new HandyChannel.Controller();	
await controller.start();
await controller.setStrokeZone({min:20,max:75});
```

## Admin
This class is only for Handy admins and approved moderators.

### Admin class

Admin constructor.
adminAuth - Admin auth token
ApiUrlConfig - Optional API config (channel API url and Handy API v2 url) - default is set to Production
config - optional open API config
```ts
constructor(adminAuth: string,apiUrlConfig: ApiUrlConfig = CHANNEL_CONFIG_PRODUCTION,config: Partial<OpenAPIConfig> = {}) {
```

Example production:
```js
let admin = new HandyChannel.Admin("MY_SECRET_ADMIN_KEY");
```

Example staging:
```js
let admin = new HandyChannel.Admin("MY_SECRET_ADMIN_KEY",HandyChannel.CHANNEL_CONFIG_STAGING);
```

### listChannels
List all active channels

```ts
listChannels(): Promise<Channel>
```

Example - List all active channel on production servers:
```js
let admin = new HandyChannel.Admin("MY_SECRET_ADMIN_KEY");
let channels = await admin.listChannels
```