AWS Elastic Transcoder Connector

# reshuffle-aws-connectors

[Code](https://github.com/reshufflehq/reshuffle-aws-connectors) |
[npm](https://www.npmjs.com/package/reshuffle-aws-connectors) |
[Code sample](https://github.com/reshufflehq/reshuffle/blob/master/examples/aws/elastic-transcoder.js)

`npm install reshuffle-aws-connectors`

### Reshuffle AWS Elastic Transcoder Connector

This [Reshuffle](https://github.com/reshufflehq/reshuffle) connector can be used to transcode video and audio using Amazon's
transcoder service. Full information about the Amazon Elastic Transcoder
service API can be found
[here](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/ElasticTranscoder.html).

The following example provides two API endpoints, one to initiate a
transcoding job and another for tracking its progress:

```js
const { HttpConnector, Reshuffle } = require('reshuffle')
const { AWSElasticTranscoderConnector } = require('reshuffle-aws-connectors')

;(async () => {
  const app = new Reshuffle()

  const awsElasticTranscoder = new AWSElasticTranscoderConnector(app, {
    accessKeyId: process.env.AWS_ACCESS_KEY_ID,
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
    region: process.env.AWS_DEFAULT_REGION,
  })

  const httpConnector = new HttpConnector(app)

  const pipeline = await awsElasticTranscoder.findPipelineByName(
    process.env.ELASTIC_TRANSCODER_PIPELINE,
  )
  const preset = await awsElasticTranscoder.findPresetByDescription('240')

  httpConnector.on({ method: 'GET', path:'/go' }, async (event) => {
    const output = `video-${Date.now().toString(16)}.mp4`

    const job = await awsElasticTranscoder.createJob({
      PipelineId: pipeline.Id,
      Input: {
        Key: 'video.mov', // replace with actual filename
      },
      Output: {
        PresetId: preset.Id,
        Key: output,
        Rotate: '180',
      },
    })

    return event.res.json({ jobId: job.Id, output })
  })

  awsElasticTranscoder.on({ pipelineId: pipeline.Id }, async (event) => {
    console.log(`Transcoding job progress ${event.jobId}: ${
      event.old.Status} -> ${event.current.Status}`)
  })

  app.start(8000)
})()
```

#### Table of Contents

[Configuration](#configuration) Configuration options

_Connector events_:

[JobStatusChanged](#JobStatusChanged) Transcoding job status changed

_Connector actions_:

[cancelJob](#cancelJob) Cancel a transcoding job

[createJob](#createJob) Start a transcoding job

[findPipelineByName](#findPipelineByName) Find pipeline by name

[findPresetByDescription](#findPresetByDescription) Find preset by description

[listPipelines](#listPipelines) Get a list of all transcoding pipelines

[listPresets](#listPresets) Get a list of all format presets

[readJob](#readJob) Get information about a transcoding job

_SDK_:

[sdk](#sdk) Get direct SDK access

##### <a name="configuration"></a>Configuration options

```js
const app = new Reshuffle()
const awsElasticTranscoderConnector = new AWSElasticTranscoderConnector(app, {
  accessKeyId: process.env.AWS_ACCESS_KEY_ID,
  secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
  region: process.env.AWS_DEFAULT_REGION,
})
```

#### Connector events

##### <a name="JobStatusChanged"></a>Job Status Changed event

_Example:_

```js
public handler(event) {
  console.log(`Job ${event.jobId}: ${
    event.old.Status} -> ${event.current.Status}`)
}
```

This event is fired when the status of a transcoding job changes.

Job status can be one of `Submitted`, `Progressing`, `Complete`,
`Canceled`, or `Error`.

#### Connector actions

##### <a name="cancelJob"></a>Cancel Job action

_Definition:_

```ts
(
  id: string,
) => void
```

_Usage:_

```js
const job = await awsElasticTranscoderConnector.createJob(...)
await awsElasticTranscoderConnector.cancelJob(job.Id)
```

Cancel a transcoding job.

##### <a name="createJob"></a>Create Job action

_Definition:_

```ts
(
  params: object,
) => object
```

_Usage:_

```js
const job = await awsElasticTranscoderConnector.createJob({
  PipelineId: '3141592653589-pipipe',
  Input: {
    Key: 'my-input-file.mov',
  },
  Output: {
    PresetId: '2718281828459-045235',
    Key: 'my-output-file.mp4',
    Rotate: '180',
  },
})
```

This action start a new transcoding job using the specified pipeline. The
full set of parameters for creating a new job is described
[here](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/ElasticTranscoder.html#createJob-property).

##### <a name="findPipelineByName"></a>Find Pipeline By Name action

_Definition:_

```ts
(
  token: string,
) => object
```

_Usage:_

```js
const pipeline = await awsElasticTranscoderConnector.findPipelineByName(
  'My Pipeline'
)
```

Find a pipeline whose name matches the specified token. Matching is performed according to different criteria in this order of preference:
* Exact match
* Exact case-insensitive match
* Name starts with token
* Token included in name

If no match is found, this action throws an Error.

##### <a name="findPresetByDescription"></a>Find Preset By Description action

_Definition:_

```ts
(
  token: string,
) => object
```

_Usage:_

```js
const preset = await awsElasticTranscoderConnector.findPresetByDescription('iphone')
```

Find a preset object with a description matching the specified token.
Matching is performed according to different criteria in this order of
preference:
* Exact match
* Exact case-insensitive match
* Description starts with token
* Token included in description

If no match is found, this action throws an Error.

##### <a name="listPipelines"></a>List Pipelines action

_Definition:_

```ts
() => object[]
```

_Usage:_

```js
const pipelines = await awsElasticTranscoderConnector.listPipelines()
```

List all the available transcoding pipelines. Pipelines define the S3
buckets for input and output video files, as well as encryption and
other storage related parameters, as described
[here](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/ElasticTranscoder.html#listPipelines-property).


At this time, this connector does not support creation and modification of
pipelines. Pipelines can be created through the AWS console or the CLI.

##### <a name="listPresets"></a>List Presets action

_Definition:_

```ts
() => object[]
```

_Usage:_

```js
const presets = await awsElasticTranscoderConnector.listPresets()
```

Get a list of transcoding output
[presets](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/ElasticTranscoder.html#listPresets-property).

##### <a name="readJob"></a>Read Job action

_Definition:_

```ts
(
  id: string,
) => object
```

_Usage:_

```js
const job = await awsElasticTranscoderConnector.createJob(...)
await Script.sleep(1000)
const info = await awsElasticTranscoderConnector.readJob(job.Id)
```

Get updated information on a transcoding job.

#### SDK

##### <a name="sdk"></a>SDK action

_Definition:_

```ts
(
  options ?: object,
) => object
```

_Usage:_

```js
const et = await awsElasticTranscoderConnector.sdk()
```

Get the underlying SDK object. You can specify additional options to override
or add to the required fields in the connector's configuration.


AWS Lambda Connector

# reshuffle-aws-connectors

[Code](https://github.com/reshufflehq/reshuffle-aws-connectors) |
[npm](https://www.npmjs.com/package/reshuffle-aws-connectors) |
[Code sample](https://github.com/reshufflehq/reshuffle/blob/master/examples/aws/lambda-create-invoke.js)

`npm install reshuffle-aws-connectors`

### Reshuffle AWS Lambda Connector

This [Reshuffle](https://github.com/reshufflehq/reshuffle) connector can be used to access AWS Lambda. It is implemented
using Amazon's
[Lambda SDK](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Lambda.html).

The following example creates, invokes and deletes a simple Lambda function:

```js
const crypto = require('crypto')
const { Reshuffle } = require('reshuffle')
const { AWSLambdaConnector } = require('reshuffle-aws-connectors')

;(async () => {
  const app = new Reshuffle()

  const awsLambdaConnector = new AWSLambdaConnector(app, {
    accessKeyId: process.env.AWS_ACCESS_KEY_ID,
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
    region: process.env.AWS_DEFAULT_REGION,
  })

  const funcName = `function-${crypto.randomBytes(8).toString('hex')}`

  console.log('Creating Lambda function:', funcName)
  await awsLambdaConnector.createFromCode(funcName, `
    exports.handler = async (event) => ({
      statusCode: 200,
      body: JSON.stringify(event),
    })
  `)

  const req = { foo: 'bar' }
  const res = await awsLambdaConnector.invoke(funcName, req)
  console.log('Lambda response:', req, '->', res)

  console.log('Deleting Lambda function')
  await awsLambdaConnector.delete(funcName)
})()
```

#### Table of Contents

[Configuration](#configuration) Configuration options

_Connector events_:

[queueComplete](#queueComplete) Queue processing is complete

_Connector actions_:

[command](#command) Run a CLI command on Lambda

[create](#create) Create a new Lambda function

[createFromBuffer](#createFromBuffer) Create a new Lambda function from buffer

[createFromCode](#createFromCode) Create a new Lambda function from code string

[createFromFile](#createFromFile) Create a new Lambda function from file

[createInFolder](#createInFolder) Create a new Lambda function by collecting files in a folder

[delete](#delete) Delete a Lambda function

[enqueue](#enqueue) Process a queue of tasks in Lambda functions

[getFunctionInfo](#getFunctionInfo) Get detailed function information

[invoke](#invoke) Execute a Lambda function

[listFunctions](#listFunctions) List deployed functions

[updateCode](#updateCode) Update Lambda function code

[updateCodeFromBuffer](#updateCodeFromBuffer) Update Lambda function code from buffer

[updateCodeFromCode](#updateCodeFromCode) Update Lambda function code from code string

[updateCodeFromFile](#updateCodeFromFile) Update Lambda function code from file

[updateCodeInFolder](#updateCodeInFolder) Update Lambda function code by collecting files in a folder

_SDK_:

[sdk](#sdk) Get direct SDK access

##### <a name="configuration"></a>Configuration options

```js
const app = new Reshuffle()
const awsLambdaConnector = new AWSLambdaConnector(app, {
  accessKeyId: process.env.AWS_ACCESS_KEY_ID,
  secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
  region: process.env.AWS_DEFAULT_REGION,
})
```

#### Connector events

##### <a name="queueComplete"></a>Queue Complete event

_Example:_

```js
awsLambdaConnector.on(
  { type: 'QueueComplete' },
  async (event, app) => {
    console.log(event.qid)
    console.log(event.payloads)
    console.log(event.resolutions)
  }
)
```

This event is fired when a processing queue has completed processing all
its payloads. See the [enqueue](#enqueue) action for details.

#### Connector actions

##### <a name="command"></a>Command action

```ts
(
  functionName: string,
  executable: string,
  command: string,
  files: string | string[] = [],
  options: Options = {},
) => any
```

_Usage:_

```js
const mediaInfo = await awsLambdaConnector.command(
  'reshuffle-command-mediainfo',
  'https://<my-server>/mediainfo'
  `mediainfo --output=JSON <my-video>`,
  's3://<my-bucket>/<my-video>',
)
```

Use AWS Lambda to run a CLI command. This action invokes the Lambda function named `functionName`, loads the files with the specified `urls` into a
temporary folder and runs the specified CLI `command`. The standard output
from the CLI command is collected and returned to the user. At this point,
the action does not support collection of output files generated by the CLI
command.

URLs for executable and files can be either HTTP(S) URLS or S3 URLS. Note
that the executable name in `command` must match the filename in the
specified by the `executable` URL.

If needed, the action creates the Labda function and loads `executable`
into the Lambda container. The executable needs to be compatible with
the AWS Lambda Linux runtime environment. If a Lambda function with this
name exists that was not previsouly deployed by the connector, deployment
fails. If a Lambda exists that was deployed by the connector, then
deployment is skipped unless `options.force` is `true`.

The `options` are the same as the ones used by [create](#create) with the
addition of the `force` flag mentioned above.

##### <a name="create"></a>Create action

_Definition:_

```ts
interface Payload {
  code?: string
  filename?: string
  buffer?: Buffer
}

(
  functionName: string,
  payload: Payload,
  options: object = {},
) => object
```

_Usage:_

```js
const functionInfo = await awsLambdaConnector.create(
  'toLowerUpperString',
  { code: `
    exports.handler = async (event) => {
      const str = event.str || 'Hello, world!'
      return {
        statusCode: 200,
        body: JSON.stringify({
          lower: str.toLowerCase(),
          upper: str.toUpperCase(),
        }),
      }
    }
  ` },
)
```

Create a new Lambda function with the given `functionName`. The code for
the newly created function can be specified in one of three ways:

* `buffer` a NodeJS buffer with zipped content (a package like [JSZip](https://stuk.github.io/jszip/) can help)
* `code` a string with code
* `filename` a name of a file containing code

The optional `options` object may contain the following properties:

* `env` - Environment variables
* `memorySize` - Container memory size in MB (defaults to 256)
* `roleName` - Function execution role (defaults to `lambda_basic_execution`)
* `runtime` - Runtime environment (defaults to `nodejs12.x`)
* `tags` - Tags
* `timeout` - Execution timeout in seconds (default to 3)

The created function can be invoked using the [invoke](#invoke) action, or
tied to a myriad of AWS supported events.

We note that the AWS SDK provides many more options for creating and
configuring Lambda functions. For example, functions can be deployed
from an S3 zip file, allowing multiple files and dependencies to be
deployed simultaneously. to leverage these capbilities, you can use
the [sdk](#sdk) action to gain direct access to the SDK and use its
[createFunction](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Lambda.html#createFunction-property)
method directly.

##### <a name="createFromBuffer"></a>Create From Buffer action

_Definition:_

```ts
(
  functionName: string,
  buffer: Buffer,
  options: object = {},
) => object
```

_Usage:_

```js
const zip = new require('JSZip')()
// ... add files ...
const buffer = await zip.generateAsync({ type: 'nodebuffer' })
const functionInfo = await awsLambdaConnector.createFromBuffer(
  'toLowerUpperString',
  buffer,
)
```

Create a new Lambda function with the given `functionName` to execute
the code in the specified buffer. See [create](#create) above for more
details.

##### <a name="createFromCode"></a>Create From Code action

_Definition:_

```ts
(
  functionName: string,
  code: string,
  options: object = {},
) => object
```

_Usage:_

```js
const functionInfo = await awsLambdaConnector.createFromCode(
  'toLowerUpperString',
  `
  exports.handler = async (event) => {
    const str = event.str || 'Hello, world!'
    return {
      statusCode: 200,
      body: JSON.stringify({
        lower: str.toLowerCase(),
        upper: str.toUpperCase(),
      }),
    }
  }
  `,
)
```

Create a new Lambda function with the given `functionName` to execute
the code in `code`. See [create](#create) above for more details.

##### <a name="createFromFile"></a>Create From File action

_Definition:_

```ts
(
  functionName: string,
  filename: string,
  options: object = {},
) => object
```

_Usage:_

```js
const functionInfo = await awsLambdaConnector.createFromFile(
  'toLowerUpperString',
  './toLowerUpperString.js',
)
```

Create a new Lambda function with the given `functionName` to execute
the code inside the file `filename`. See [create](#create) above for more
details.

##### <a name="createInFolder"></a>Create In Folder action

_Definition:_

```ts
(
  functionName: string,
  fileHandler: async (folder => Folder) => Promise<void>,
  options: object = {},
) => object
```

_Usage:_

```js
const functionInfo = await awsLambdaConnector.createInFolder(
  'toLowerUpperString',
  async folder => {
    await folder.copy('index.js', `${__dirname}/toLowerUpperString.js`)
  }
)
```

Create a new Lambda function with the given `functionName` by setting up
files in a folder. The `folderHandler` object receives a single `folder`
object that provides the following methods:

* **copy(targetName: string, sourcePath: string): Promise<void>** Copy a file into the folder
* **exec(cmd: string): Promise<{ error?: Error, stdout: string | Buffer, stderr: string | Buffer }>** Run a command inside the folder
* **contains(filename: string): Promise<boolean>** Check if the folder contains a file
* **write(targetName: string, data: string): Promise<void>** Create a file inside the folder with the specified data

See [create](#create) above for more details.

##### <a name="delete"></a>Delete action

_Definition:_

```ts
(
  functionName: string,
) => void
```

_Usage:_

```js
await awsLambdaConnector.delete('toLowerUpperString')
```

Delete the Lambda function with the name `functionName`. Be careful, this
action is not reversible and will delete any function, not just ones
created by this connector.

##### <a name="enqueue"></a>Enqueue action

_Definition:_

```ts
(
  functionName: string,
  payload: any|any[],
  maxConcurrent: number = 100,
) => string
```

_Usage:_

```js
const qid = await awsLambdaConnector.enqueue(
  'toLowerUpperString',
  [
    { str: 'Alpha' },
    { str: 'Beta' },
    { str: 'Gamma' },
  ],
)
```

Asynchronously process a series of tasks with the Lambda function named
`functionName`. The `payload` is an array of elements, each would be passed
in turn as an input to the Lambda function. If `payload` is scalar, only
a single invocation will ensue.

The `maxConcurrent` argument can be used to limit the number of simultaneous
invocaions of the Lambda function, with a hard limit of 100 per queue.
Currently the connector does not enforce a global limit on the number
of functions it invokes through this action.

When all payloads have been processed, the action triggers a
[queueComplete](#queueComplete) event with the queue ID, the payloads array
and a resolutions array in the event object. Each resolution is either the
value returned by the Lambda function or an `Error` object if the invocation
failed.

##### <a name="getFunctionInfo"></a>Get Function Info action

_Definition:_

```ts
(
  functionName: string,
) => any
```

_Usage:_

```js
const info = await awsLambdaConnector.getFunctionInfo(
  'toLowerUpperString',
)
```

Get detailed information about the specified function.

##### <a name="invoke"></a>Invoke action

_Definition:_

```ts
(
  functionName: string,
  requestPayload: any = {},
) => any
```

_Usage:_

```js
const { lower, upper } = await awsLambdaConnector.invoke(
  'toLowerUpperString',
  { str: 'My Awesome String' },
)
```

Invoke the Lambda function with the name `functionName`, passing it the
payload provided in `requestPayload`. The payload can be any JSON
serializable JavaScript object.

The invoke action returns the response payload returned by the Lambda
function. In case of an error during invocation or execution of the
function, this action throws an error.

##### <a name="listFunctions"></a>List Functions action

_Definition:_

```ts
() => any[]
```

_Usage:_

```js
const list = await awsLambdaConnector.listFunctions()
```

Get information about deployed Lambda functions.

##### <a name="updateCode"></a>Update Code action

_Definition:_

```ts
(
  functionName: string,
  payload: Payload,
  options: object = {},
) => object
```

_Usage:_

```js
const functionInfo = await awsLambdaConnector.updateCode(
  'toLowerUpperString',
  { code: `
    exports.handler = async (event) => {
      const str = event.str || 'Hello, beautiful world!!'
      return {
        statusCode: 200,
        body: JSON.stringify({
          lower: str.toLowerCase(),
          upper: str.toUpperCase(),
        }),
      }
    }
  ` },
)
```

Update the code of an existing Lambda function with the given `functionName`.
The code can be specified in one of three ways, as defined in [create](#create)
above.

##### <a name="updateCodeFromBuffer"></a>Update Code From Buffer action

_Definition:_

```ts
(
  functionName: string,
  buffer: Buffer,
) => object
```

_Usage:_

```js
const zip = new require('JSZip')()
// ... add files ...
const buffer = await zip.generateAsync({ type: 'nodebuffer' })
const functionInfo = await awsLambdaConnector.updateCodeFromBuffer(
  'toLowerUpperString',
  buffer,
)
```

Update an existing Lambda function with the given `functionName` to execute
the code in the specified buffer. See [create](#create) above for more
details.

##### <a name="updateCodeFromCode"></a>Update Code From Code action

_Definition:_

```ts
(
  functionName: string,
  code: string,
) => object
```

_Usage:_

```js
const functionInfo = await awsLambdaConnector.updateCodeFromCode(
  'toLowerUpperString',
  `
  exports.handler = async (event) => {
    const str = event.str || 'Hello, beautiful world!!'
    return {
      statusCode: 200,
      body: JSON.stringify({
        lower: str.toLowerCase(),
        upper: str.toUpperCase(),
      }),
    }
  }
  `,
)
```

Update an existing Lambda function with the given `functionName` to execute
the code in `code`. See [create](#create) above for more details.

##### <a name="updateCodeFromFile"></a>Update Code From File action

_Definition:_

```ts
(
  functionName: string,
  filename: string,
) => object
```

_Usage:_

```js
const functionInfo = await awsLambdaConnector.createFromFile(
  'toLowerUpperString',
  './toLowerUpperString.js',
)
```

Update an existing Lambda function with the given `functionName` to execute
the code inside the file `filename`. See [create](#create) above for more
details.

##### <a name="updateCodeInFolder"></a>Update Code In Folder action

_Definition:_

```ts
(
  functionName: string,
  fileHandler: async (folder => Folder) => Promise<void>,
) => object
```

_Usage:_

```js
const functionInfo = await awsLambdaConnector.updateCodeInFolder(
  'toLowerUpperString',
  async folder => {
    await folder.copy('index.js', `${__dirname}/toLowerUpperString.js`)
  }
)
```

Update an existing Lambda function with the given `functionName` to execute
the code set up in a folder. See [createInFolder](#createInFolder) above for
more details.


#### SDK

##### <a name="sdk"></a>SDK action

_Definition:_

```ts
(
  options ?: object,
) => object
```

_Usage:_

```js
const lambda = await awsLambdaConnector.sdk()
```

Get the underlying SDK object. You can specify additional options to override
or add to the required fields in the connector's configuration.


AWS Media Convert Connector

# reshuffle-aws-connectors

[Code](https://github.com/reshufflehq/reshuffle-aws-connectors) |
[npm](https://www.npmjs.com/package/reshuffle-aws-connectors) |
[Code sample](https://github.com/reshufflehq/reshuffle-aws-connectors/blob/master/examples/media-convert.js)

`npm install reshuffle-aws-connectors`

### Reshuffle AWS Media Convert Connector

This [Reshuffle](https://github.com/reshufflehq/reshuffle) connector can be used to transcode video and audio using Amazon's
Elemental Media Convert service. Complete information about the service API
can be found [Elemental Media Convert](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/MediaConvert.html).

The following example provides two API endpoints, one to initiate a
transcoding job and another for tracking its progress:

```js
const { HttpConnector, Reshuffle } = require('reshuffle')
const { AWSMediaConvertConnector } = require('reshuffle-aws-connectors')

;(async () => {
  const bucket = process.env.AWS_DEFAULT_BUCKET

  const app = new Reshuffle()
  const awsMediaConvertConnector = new AWSMediaConvertConnector(app, {
    accessKeyId: process.env.AWS_ACCESS_KEY_ID,
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
    region: process.env.AWS_DEFAULT_REGION,
  })
  const httpConnector = new HttpConnector(app)

  httpConnector.on({ method: 'GET', path:'/go' }, async (event) => {
    const filename = event.req.query.filename
    if (!filename) {
      return event.res.status(400).json({ error: 'No filename' })
    }

    const job = await awsMediaConvertConnector.createSingleJob(
      `s3://${bucket}/${filename}`,
      `s3://${bucket}/${filename}-thumbnail`,
      {
        VideoDescription: {
          Height: 200,
          Width: 200,
          CodecSettings: {
            Codec: 'H_264',
            H264Settings: {
              Bitrate: 262144,
            },
          },
        },
        ContainerSettings: {
          Container: 'MP4',
        },
      },
    )

    return event.res.json({ jobId: job.Id })
  })

  awsMediaConvertConnector.on({ type: 'JobStatusChanged' }, async (event) => {
    console.log(`Job progress ${event.jobId}: ${
      event.old.Status} -> ${event.current.Status}`)
  })

  app.start(8000)
})()
```

#### Table of Contents

[Configuration](#configuration) Configuration options

_Connector events_:

[jobStatusChanged](#jobStatusChanged) Job status changed

_Connector actions_:

[cancelJob](#cancelJob) Cancel a transcoding job

[cancelJobById](#cancelJobById) Cancel a transcoding job using its Id

[createJob](#createJob) Create a new transcoding job

[createSimpleJob](#createSimpleJob) Create a simple transcoding job

[createSingleJob](#createSingleJob) Create a job for transcoding a single file

[getJobStatus](#getJobStatus) Get the status of a transcoding job

[getJobStatusById](#getJobStatusById) Get job status by its Id

[listJobs](#listJobs) List active and past transcoding jobs

[listJobsById](#listJobsById) List jobs and index by job Id

_SDK_:

[sdk](#sdk) Get direct SDK access

##### <a name="configuration"></a>Configuration options

```js
const app = new Reshuffle()
const awsMediaConvertConnector = new AWSMediaConvertConnector(app, {
  accessKeyId: process.env.AWS_ACCESS_KEY_ID,
  secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
  region: process.env.AWS_DEFAULT_REGION,
})
```

#### Connector events

##### <a name="jobStatusChanged"></a>Job Status Changed event

_Example:_

```js
async (job) => {
  console.log(`Media Convert job ${job.jobId}: ${job.current.Status}`);
}
```

This event is fired when the status of a transcoding job changes. The
event object contains the followin information:

```ts
{
  jobId: string,
  current: {
    Id: string,
    Status: string,
  },
  old: {
    Id: string,
    Status: string,
  },
}
```

Status is one of the following: `NEW`, `SUBMITTED`, `PROGRESSING`,
`COMPLETE`, `CANCELED` or `ERROR`.

#### Connector actions

### <name="cancelJob"></a>Cancel Job action

_Definition:_

```ts
(
  job: Job,
) => void
```

_Usage:_

```js
await awsMediaConvertConnector.cancelJob(job);
```

Cancel a transcoding job, using the job object returned when the job was
created.

### <name="cancelJobById"></a>Cancel Job By Id action

_Definition:_

```ts
(
  id: string,
) => void
```

_Usage:_

```js
await awsMediaConvertConnector.cancelJobById('...');
```

Cancel a transcoding job, using its Id.

### <name="createJob"></a>Create Job action

_Definition:_

```ts
(
  params: object,
) => Job
```

_Usage:_

```js
const job = await awsMediaConvertConnector.createJob({
  // ...
});
```

Create a new transcoding job using the parameters and returning the job
information as defined by the
[AWS DSK](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/MediaConvert.html#createJob-property).

### <name="createSimpleJob"></a>Create Simple Job action

_Definition:_

```ts
(
  input: object,
  outputGroup: object,
  settings?: object,
) => Job
```

_Usage:_

```js
const job = await awsMediaConvertConnector.createSimpleJob({
  // ...
});
```

Create a simple transcoding job using the `input` and `outputGroup` arguments,
and returning the job information as defined by the
[AWS DSK](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/MediaConvert.html#createJob-property).

The optional `settings` argument allows the caller to define additional
transcoding settings like `Crop`, `Position` or `PsiControl` as defined by
the SDK.

### <name="createSingleJob"></a>Create Single Job action

_Definition:_

```ts
(
  src: string,
  dst: string,
  output: object,
  settings?: object,
) => Job
```

_Usage:_

```js
const job = await awsMediaConvertConnector.createSingleJob(
  `s3://<source-bucket>/<source-file>`,
  `s3://<target-bucket>/<target-file>`,
  {
    VideoDescription: {
      CodecSettings: {
        Codec: 'H_264',
        H264Settings: {
          Bitrate: 10000,
        },
      },
    },
    ContainerSettings: {
      Container: 'MP4',
    },
  },
);
```

Create a transcoding job for processing a single video file. The `src` and
`dst` arguments are S3 URLs poiting to the original and the transcoded video
files respectively. The `output` aregument is a single out object as defined
by the
[AWS DSK](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/MediaConvert.html#createJob-property).

The optional `settings` argument allows the caller to define additional
transcoding settings like `Crop`, `Position` or `PsiControl` as defined by
the SDK.

### <name="getJobStatus"></a>Get Job Status action

_Definition:_

```ts
(
  job: object,
) => object
```

_Usage:_

```js
const job = await awsMediaConvertConnector.createJob(...);
const status = await awsMediaConvertConnector.getJobStatus(job);
```

Get the status of a transcoding job, as defined by the
[AWS SDK](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/MediaConvert.html#getJob-property).

### <name="getJobStatusById"></a>Get Job Status By Id action

_Definition:_

```ts
(
  id: string,
) => object
```

_Usage:_

```js
const job = await awsMediaConvertConnector.createJob(...);
const status = await awsMediaConvertConnector.getJobStatusById(job.Id);
```

Get the status of a transcoding job by the job Id, as defined by the
[AWS SDK](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/MediaConvert.html#getJob-property).

### <name="listJobs"></a>List Jobs action

_Definition:_

```ts
() => object[]
```

_Usage:_

```js
const jobs = await awsMediaConvertConnector.listJobs();
for (job of jobs) {
  console.log(job);
}
```

Get information on past and active transcoding jobs as defined
[here](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/MediaConvert.html#listJobs-property).

### <name="listJobsById"></a>List Jobs By Id action

_Definition:_

```ts
() => object
```

_Usage:_

```js
const jobs = await awsMediaConvertConnector.listJobsById();
for (id in jobs) {
  console.log(jobs[id]);
}
```

Get information on past and active transcoding jobs as defined
[here](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/MediaConvert.html#listJobs-property),
indexed by job Id.

#### SDK Details

##### <a name="sdk"></a>SDK action

_Definition:_

```ts
(
  options ?: object,
) => object
```

_Usage:_

```js
const mc = await awsMediaConvertConnector.sdk()
```

Get the underlying SDK object. You can specify additional options to override
or add to the required fields in the connector's configuration.


AWS S3 Connector

# reshuffle-aws-connectors

[Code](https://github.com/reshufflehq/reshuffle-aws-connectors) |
[npm](https://www.npmjs.com/package/reshuffle-aws-connectors) |
[Code sample](https://github.com/reshufflehq/reshuffle/blob/master/examples/aws/s3-list-files.js)

`npm install reshuffle-aws-connectors`

### Reshuffle AWS S3 Connector

This [Reshuffle](https://github.com/reshufflehq/reshuffle) connector can be used to manage AWS S3 buckets and objects. Full
details on the S3 API can be found
[here](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html).

The following example creates an API endpoint to list all files in an S3
bucket:

```js
const { HttpConnector, Reshuffle } = require('reshuffle')
const { AWSS3Connector } = require('reshuffle-aws-connectors')

const app = new Reshuffle()

const s3Connector = new AWSS3Connector(app, {
  accessKeyId: process.env.AWS_ACCESS_KEY_ID,
  secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
  bucket: process.env.AWS_DEFAULT_BUCKET,
})

const httpConnector = new HttpConnector(app)

httpConnector.on({ method: 'GET', path: '/list' }, async (event) => {
  const keys = await s3Connector.listObjectKeys()
  event.res.json(keys)
})

app.start(8000)
```

#### Table of Contents

[Configuration](#configuration) Configuration options

_Connector events_:

[bucketInitialized](#bucketInitialized) Bucket traching initialized

[bucketChanged](#bucketChanged) Bucket content changes

[objectAdded](#objectAdded) Object added to bucket

[objectModified](#objectModified) Object modified in bucket

[objectRemoved](#objectRemoved) Object removed from bucket

_Connector actions_:

[listBuckets](#listBuckets) Get a list of bucket info objects

[listBucketNames](#listBucketNames) Get a list of bucket names

[createBucket](#createBucket) Create a new bucket

[deleteBucket](#deleteBucket) Delete a bucket

[listObjects](#listObjects) Get a list of object info objects

[listObjectKeys](#listObjectKeys) Get a list of object keys

[copyObject](#copyObject) Create a copy of an existing object

[deleteObject](#deleteObject) Delete an object

[getObject](#getObject) Get the contents of an object

[putObject](#putObject) Create a new object

[getSignedURL](#getSignedURL) Get a signed URL for a single operation

[getSignedObjectGetURL](#getSignedObjectGetURL) Get a signed download URL

[getSignedObjectPutURL](#getSignedObjectPutURL) Get a signed upload URL

[getS3URL](#getS3URL) Get an S3 object URL

[getWebURL](#getWebURL) Get an web object URL

_SDK_:

[sdk](#sdk) Get direct SDK access

##### <a name="configuration"></a>Configuration options

```js
const app = new Reshuffle()
const awsS3Connector = new AWSS3Connector(app, {
  accessKeyId: process.env.AWS_ACCESS_KEY_ID,
  secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
  bucket: process.env.AWS_DEFAULT_BUCKET,
})
```

#### Connector events

##### <a name="bucketInitialized"></a>Bucket Initialized event

_Example:_

```js
async (objects) => {
  console.log(objects)
}
```

This event is fired when the connector starts tracking a specific S3
bucket. More technically, it is fired when the connector first reads
the content of an S3 bucket and does not have a previous record of its
object in its internal database.

For example, if a set of scripts is used to synchronize the contents of
one bucket to another, this event can be used to read the contents of the
target bucket and copy over the missing objects. This prevents the need to
copy over every object in case of a database failure.

When this event is fired, neither the [bucketChanged](#bucketChanged)
event nor the individual [objectAdded](#objectAdded) events are fired for
the same objects. Subsequent additions or modification to the tracked
bucket will generate those events.

##### <a name="bucketChanged"></a>Bucket Changed event

_Event parameters:_

```
bucket: string - S3 bucket name
```

_Handler inputs:_

```
objects: object - Bucket state
```

_Example:_

```js
async (objects) => {
  console.log('All keys:', Object.keys(objects).join(', '))
}
```

This event is triggered when one or more of the objects in an S3 buckets
change: a new object is created, the content of an existing object is
modified or an object is removed.

This event consolidates multiple changes. For each of this changes, the
appropriate `objectAdded`, `objectModified` or `objectRemoved` is also
fired. Those events are fired one per each object changed.

The `objects` argument has the following format:

```ts
{
  'key 1': {
    key: string, // equals to 'key 1' in this case
    lastModified: Date,
    eTag: '"..."' // 32 character hex string
    size: number // In bytes
  },
  'key 2': { ... },
  ...
}
```

##### <a name="objectAdded"></a>Object Added event

_Event parameters:_

```
bucket: string - S3 bucket name
```

_Handler inputs:_

```
object: object - Object info
```

_Example:_

```js
async (object) => {
  console.log('New object added:')
  console.log('  Key:', object.key)
  console.log('  Modified:', object.lastModified)
  console.log('  eTag:', object.eTag)
  console.log('  Size:', object.size, 'bytes')
}
```

This event is triggered once for each new object added to the bucket.

The `object` info argument has the following format:

```ts
{
  key: string,
  lastModified: Date,
  eTag: '"..."' // 32 character hex string
  size: number // Size in bytes
}
```

##### <a name="objectModified"></a>Object Modified event

_Event parameters:_

```
bucket: string - S3 bucket name
```

_Handler inputs:_

```
object: object - Object info
```

_Example:_

```js
async (object) => {
  console.log('New object added:')
  console.log('  Key:', object.key)
  console.log('  Modified:', object.lastModified)
  console.log('  eTag:', object.eTag)
  console.log('  Size:', object.size, 'bytes')
}
```

This event is triggered once whenever the content of an object in the
bucket is modified.

The `object` info argument has the following format:

```ts
{
  key: string,
  lastModified: Date,
  eTag: '"..."' // 32 character hex string
  size: number // Size in bytes
}
```

##### <a name="objectRemoved"></a>Object Removed event

_Event parameters:_

```
bucket: string - S3 bucket name
```

_Handler inputs:_

```
object: object - Object info
```

_Example:_

```js
async (object) => {
  console.log('New object added:')
  console.log('  Key:', object.key)
  console.log('  Modified:', object.lastModified)
  console.log('  eTag:', object.eTag)
  console.log('  Size:', object.size, 'bytes')
}
```

This event is triggered once whenever an object is removed from
the bucket.

The `object` info argument has the following format:

```ts
{
  key: string,
  lastModified: Date,
  eTag: '"..."' // 32 character hex string
  size: number // Size in bytes
}
```

#### Connector actions

##### <a name="listBuckets"></a>List Buckets action

_Definition:_

```ts
() => object[]
```

_Usage:_

```js
const buckets = await awsS3Connector.listBuckets()
```

Get a list of
[bucket information objects](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html#listBuckets-property)
for accessible buckets.

##### <a name="listBucketNames"></a>List Bucket Names action

_Definition:_

```ts
() => string[]
```

_Usage:_

```js
const names = await awsS3Connector.listBucketNames()
```

Get a list of accessible bucket names.

##### <a name="createBucket"></a>Create Bucket action

_Definition:_

```ts
(
  bucket: string,
  region?: string,
) => void
```

_Usage:_

```js
await awsS3Connector.createBucket('my-bucket-name', 'us-west-1')
```

Create a new bucket.

##### <a name="deleteBucket"></a>Delete Bucket action

_Definition:_

```ts
(
  bucket: string,
) => void
```

_Usage:_

```js
await awsS3Connector.deleteBucket('my-bucket-name')
```

Delete a bucket.

##### <a name="listObjects"></a>List Objects action

_Definition:_

```ts
(
  bucket: string,
) => object[]
```

_Usage:_

```js
const objects = await awsS3Connector.listObjects('my-bucket-name')
```

Get a list of
[object information objects](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html#listObjects-property)
for objects in the specified bucket.

##### <a name="listObjectKeys"></a>List Object Keys action

_Definition:_

```ts
(
  bucket: string,
) => string[]
```

_Usage:_

```js
const keys = await awsS3Connector.listObjectKeys()
```

Get a list of object keys in the specified bucket.

##### <a name="copyObject"></a>Copy Object action

_Definition:_

```ts
(
  sourceBucket: string,
  sourceKey: string,
  targetBucket: string,
  targetKey: string,
) => object
```

_Usage:_

```js
const result = await awsS3Connector.copyObject(
  'old-bucket',
  'original.jpg',
  'new-bucket',
  'copy.jpg',
)
```

Create a new copy of an existing object. Returns a
[copy result](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html#copyObject-property).

##### <a name="deleteObject"></a>Delete Object action

_Definition:_

```ts
(
  bucket: string,
  key: string,
) => void
```

_Usage:_

```js
await awsS3Connector.deleteObject('my-bucket-name', 'no-longer-needed.txt')
```

Delete an object from the specified bucket.

##### <a name="getObject"></a>Get Object action

_Definition:_

```ts
(
  bucket: string,
  key: string,
) => object
```

_Usage:_

```js
const info = await awsS3Connector.getObject('my-bucket-name', 'image.png')
```

Get information about an object, including its contents, as defined
[here](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html#getObject-property).

##### <a name="putObject"></a>Put Object action

_Definition:_

```ts
(
  bucket: string,
  key: string,
  buffer: Buffer,
) => object
```

_Usage:_

```js
const info = await awsS3Connector.putObject(
  'my-bucket-name',
  'hello.txt',
  Buffer.from('Hello, world!'),
)
```

Returns information about the new object, as defined
[here](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html#putObject-property).

##### <a name="getSignedURL"></a>Get Signed URL action

_Definition:_

```ts
(
  operation: string,
  key: string,
  expires?: number = 60,
) => string
```

_Usage:_

```js
const url = await awsS3Connector.getSignedURL('getObject', 'me.png')
```

Get a pre-signed URL for a single operation. The URL can be used to
access an object without requiring any credentials.

The URL is valid for a limited time, as specified by `expires` in seconds.

##### <a name="getSignedObjectGetURL"></a>Get Signed Object Get URL action

_Definition:_

```ts
(
  key: string,
  expires?: number = 60,
) => string
```

_Usage:_

```js
const url = await awsS3Connector.getSignedObjectGetURL('me.png')
```

Get a pre-signed URL for downloading an object. The URL can be used to
download the content of an object without requiring any credentials.

The URL is valid for a limited time, as specified by `expires` in seconds.

##### <a name="getSignedObjectPutURL"></a>Get Signed Object Put URL action

_Definition:_

```ts
(
  key: string,
  expires?: number = 60,
) => string
```

_Usage:_

```js
const url = await awsS3Connector.getSignedObjectPutURL('you.png')
```

Get a pre-signed URL for uploading an object. The URL can be used with a PUT
HTTP request to create a new object without requiring any credentials.

The URL is valid for a limited time, as specified by `expires` in seconds.

##### <a name="getS3URL"></a>Get S3 URL action

_Definition:_

```ts
(
  key: string,
  bucket?: string,
) => string
```

_Usage:_

```js
const url = await awsS3Connector.getS3URL('image.png')
```

Get an S3 object URL in the form "s3://<bucket>//<key>". If `bucket` is omitted
then the valude from the connector options is used.

##### <a name="getWebURL"></a>Get Web URL action

_Definition:_

```ts
(
  key: string,
  bucket?: string,
) => string
```

_Usage:_

```js
const url = await awsS3Connector.getWebURL('image.png')
```

Get an HTTP URL for accessing objet `key` in `bucket`. If `bucket` is omitted
then the valude from the connector options is used.

This URL is only valid if the specified S3 bucket is configured for web access.
The action does not configure the bucket for web access nor does it validate
that such access is enabled.

#### SDK

##### <a name="sdk"></a>SDK action

_Definition:_

```ts
(
  options ?: object,
) => object
```

_Usage:_

```js
const s3 = await awsS3Connector.sdk()
```

Get the underlying SDK object. You can specify additional options to override
or add to the required fields in the connector's configuration.


AWS SNS Connector

# reshuffle-aws-connectors

[Code](https://github.com/reshufflehq/reshuffle-aws-connectors) |
[npm](https://www.npmjs.com/package/reshuffle-aws-connectors) |
[Code sample](https://github.com/reshufflehq/reshuffle/blob/master/examples/aws/sns-messages.js)

`npm install reshuffle-aws-connectors`

### Reshuffle AWS SNS Connector

This [Reshuffle](https://github.com/reshufflehq/reshuffle) connector can be used to send messages using
[AWS SNS](https://docs.aws.amazon.com/sns/index.html).

The following example sends a message via AWS SNS when Reshuffle receives an HTTP request on `/send`

```js
const { HttpConnector, Reshuffle } = require('reshuffle')
const { AWSSNSConnector } = require('reshuffle-aws-connectors')

const app = new Reshuffle()

const snsConnector = new AWSSNSConnector(app, {
  accessKeyId: process.env.AWS_ACCESS_KEY_ID,
  secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
  region: process.env.AWS_REGION,
})

const httpConnector = new HttpConnector(app)

httpConnector.on({ method: 'GET', path: '/send' }, async (event, app) => {
  const params = {
    Message: 'Message from Reshuffle!',
    TopicArn: 'arn:aws:sns:<region>:<id>:<topic_name>',
  }

  const response = await snsConnector.publish(params)

  return event.res.json({ ok: !!response.MessageId })
})

app.start()
```

#### Table of Contents

[Configuration](#configuration) Configuration options

_Connector actions_:

[Publish](#publish) Publish messages
_SDK_:

[sdk](#sdk) Get direct SNS SDK access

##### <a name="configuration"></a>Configuration options

```js
const app = new Reshuffle()
const awsSNSConnector = new AWSSNSConnector(app, {
  accessKeyId: process.env.AWS_ACCESS_KEY_ID,
  secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
  region: process.env.AWS_DEFAULT_REGION,
})
```

#### Connector events
N/A

#### Connector actions

##### <a name="publish"></a>Publish message

_Definition:_

```ts
(params: AWS.SNS.Types.PublishInput) => Promise<PromiseResult<AWS.SNS.PublishResponse, AWS.AWSError>>

// At least one of these parameters must be provided
export interface PublishInput {
    /**
     * The topic to publish to.
     */
    TopicArn?: topicARN;
    /**
     *The TargetArn to publish to
     */
    TargetArn?: String;
    /**
     * The phone number to deliver an SMS message to. Use E.164 format.
     */
    PhoneNumber?: String;
    /**
     * The message you to send. If you are publishing to a topic and you want to send the same message to
     all transport protocols, include the text of the message as a String value. If you want to send
     different messages for each transport protocol, set the value of the MessageStructure parameter to json 
     and use a JSON object for the Message parameter.   
     Constraints:   With the exception of SMS, messages must be UTF-8 encoded strings 
     and at most 256 KB in size (262,144 bytes, not 262,144 characters).   For SMS, each message can 
     contain up to 140 characters. This character limit depends on the encoding schema. For example, 
     an SMS message can contain 160 GSM characters, 140 ASCII characters, or 70 UCS-2 characters. If 
     you publish a message that exceeds this size limit, Amazon SNS sends the message as multiple 
     messages, each fitting within the size limit. Messages aren't truncated mid-word but are cut off 
     at whole-word boundaries. The total size limit for a single SMS Publish action is 1,600 
     characters.   JSON-specific constraints:   Keys in the JSON object that correspond to supported 
     transport protocols must have simple JSON string values.   The values will be parsed (unescaped) 
     before they are used in outgoing messages.   Outbound notifications are JSON encoded (meaning 
     that the characters will be reescaped for sending).   Values have a minimum length of 0 (the 
     empty string, "", is allowed).   Values have a maximum length bounded by the overall message 
     size (so, including multiple protocols may limit message sizes).   Non-string values will cause 
     the key to be ignored.   Keys that do not correspond to supported transport protocols are 
     ignored.   Duplicate keys are not allowed.   Failure to parse or validate any key or value in 
     the message will cause the Publish call to return an error (no partial delivery).  
     */
    Message: message;
    /**
     * Optional parameter to be used as the "Subject" line when the message is delivered to email 
     endpoints. This field will also be included, if present, in the standard JSON messages delivered 
     to other endpoints. Constraints: Subjects must be ASCII text that begins with a letter, number, 
     or punctuation mark; must not include line breaks or control characters; and must be less than 
     100 characters long.
     */
    Subject?: subject;
    /**
     * Set MessageStructure to json if you want to send a different message for each protocol. For 
     example, using one publish action, you can send a short message to your SMS subscribers and a 
     longer message to your email subscribers. If you set MessageStructure to json, the value of the 
     Message parameter must:    be a syntactically valid JSON object; and   contain at least a 
     top-level JSON key of "default" with a value that is a string.   You can define other top-level 
     keys that define the message you want to send to a specific transport protocol (e.g., "http"). 
     Valid value: json 
     */
    MessageStructure?: messageStructure;
    /**
     * Message attributes for Publish action.
     */
    MessageAttributes?: MessageAttributeMap;
    /**
     * This parameter applies only to FIFO (first-in-first-out) topics. The MessageDeduplicationId 
     can contain up to 128 alphanumeric characters (a-z, A-Z, 0-9) and punctuation 
     (!"#$%&amp;'()*+,-./:;&lt;=&gt;?@[\]^_`{|}~). 
     Every message must have a unique MessageDeduplicationId, which is a token used for deduplication 
     of sent messages. If a message with a particular MessageDeduplicationId is sent successfully, 
     any message sent with the same MessageDeduplicationId during the 5-minute deduplication interval 
     is treated as a duplicate.  If the topic has ContentBasedDeduplication set, the system generates
     a MessageDeduplicationId based on the contents of the message. Your MessageDeduplicationId 
     overrides the generated one.
     */
    MessageDeduplicationId?: String;
    /**
     * This parameter applies only to FIFO (first-in-first-out) topics. The MessageGroupId can 
     contain up to 128 alphanumeric characters (a-z, A-Z, 0-9) and punctuation 
     (!"#$%&amp;'()*+,-./:;&lt;=&gt;?@[\]^_`{|}~). 
     The MessageGroupId is a tag that specifies that a message belongs to a specific message group. 
     Messages that belong to the same message group are processed in a FIFO manner (however, messages 
     in different message groups might be processed out of order). Every message must include a 
     MessageGroupId.
     */
    MessageGroupId?: String;
  }
```

_Usage:_

```js
const params = {
  Message: 'Message from Reshuffle!',
  TopicArn: 'arn:aws:sns:<region>:<id>:<topic_name>',
}
const response = await snsConnector.publish(params)
console.log(response.MessageId)
```

#### SDK

##### <a name="sdk"></a>SDK action

Returns a AWS SNS client instance

_Definition:_

```ts
() => AWS.SNS
```

_Usage:_

```js
const sns = await snsConnector.sdk()
```


AWS SQS Connector

# reshuffle-aws-connectors

[Code](https://github.com/reshufflehq/reshuffle-aws-connectors) |
[npm](https://www.npmjs.com/package/reshuffle-aws-connectors) |
[Code sample](https://github.com/reshufflehq/reshuffle/blob/master/examples/aws/sqs-messages.js)

`npm install reshuffle-aws-connectors`

### Reshuffle AWS SQS Connector

This [Reshuffle](https://github.com/reshufflehq/reshuffle) connector can be used to interact with AWS SQS queues.
[AWS SQS documentation](https://docs.aws.amazon.com/sqs/index.html).

The following code listens to new messages in the queue. When a message arrives it logs the details of the message event.
```js
const { HttpConnector, Reshuffle } = require('reshuffle')
const { AWSSQSConnector } = require('reshuffle-aws-connectors')

const queueUrl = 'https://sqs.<region>.amazonaws.com/<id>/<queue_name>'

const app = new Reshuffle()

const sqsConnector = new AWSSQSConnector(app, {
  accessKeyId: process.env.AWS_ACCESS_KEY_ID,
  secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
  region: process.env.AWS_REGION
})

sqsConnector.on({ queueUrl }, (event, app) => {
  console.log('new message', event)
  //{ MessageId: '71c06956-76e1-4a8c-bc00-ed910566f36e', ReceiptHandle: 'AQEBTL1CTtn1clJ0XMSmRtpz7...', MD5OfBody: '9a72c70562843b823c2c9cad30665fe4', Body: 'Message from Reshuffle to queue' }
})

app.start()
```

#### Table of Contents

[Configuration](#configuration) Configuration options

_Connector events_:

[Receive messages event](#receiveMessagesEvent) Receive messages event

_Connector actions_:

[Send message](#sendMessage) Send a message
_SDK_:

[sdk](#sdk) Get direct SQS SDK access

##### <a name="configuration"></a>Configuration options

```js
const app = new Reshuffle()
const awsSQSConnector = new AWSSQSConnector(app, {
  accessKeyId: process.env.AWS_ACCESS_KEY_ID,
  secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
  region: process.env.AWS_DEFAULT_REGION,
})
```

#### Connector events

##### <a name="receiveMessagesEvent"></a>Receive messages event
_Event parameters:_

```typescript
interface AWSSQSConnectorEventOptions {
queueUrl: string // SQS queue url
deleteAfterReceive?: boolean // default to true
}
```

_Handler inputs:_

```typescript
(event: MESSAGE, app: Reshuffle) => void

interface MESSAGE {
  MessageId?: string
  ReceiptHandle?: string
  MD5OfBody?: string
  Body?: string
  Attributes?: MessageSystemAttributeMap
  MD5OfMessageAttributes?: string
  MessageAttributes?: MessageBodyAttributeMap
}
```

_Example:_

```js
(event, app) => { 
  console.log('new message received', event)
  // 'new message received', { MessageId: '71c06956-76e1-4a8c-bc00-ed910566f36e', ReceiptHandle: 
  // 'AQEBTL1CTtn1clJ0XMSmRtpz7...', MD5OfBody: '9a72c70562843b823c2c9cad30665fe4', Body: 'Message 
  // from Reshuffle to queue' }
}
```

This event is triggered when new messages are received from the queue.
Reshuffle checks for new messages every minute.
Per default, it deletes the messages from the queue once retrieved. 
Set `deleteAfterReceive` to `false` to prevent this.

__Note:__ if you do so, events can be triggered several times for the same message depending on your queue strategy.

#### Connector actions

Most of the actions are provided via the [sdk](#sdk).

##### <a name="sendMessage"></a>Send message

_Definition:_

```ts
(params: AWS.SQS.Types.SendMessageRequest) => Promise<PromiseResult<AWS.SQS.SendMessageResponse, AWS.AWSError>>

export interface SendMessageRequest {
  QueueUrl: string
  MessageBody: string
  DelaySeconds?: Integer
  MessageAttributes?: MessageBodyAttributeMap
  MessageSystemAttributes?: MessageBodySystemAttributeMap
  MessageDeduplicationId?: string
  MessageGroupId?: string
}
export interface SendMessageResult {
  MD5OfMessageBody?: string
  MD5OfMessageAttributes?: string
  MD5OfMessageSystemAttributes?: string
  MessageId?: string
  SequenceNumber?: string
}
```

Go [here](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_SendMessage.html) for sendMessage AWS documentation.

_Usage:_

```js
const params = {
  MessageBody: 'Message from Reshuffle to AWS SQS!',
  QueueUrl: 'https://sqs.us-east-1.amazonaws.com/<project_id>/<queue_name>',
}
const response = await sqsConnector.sendMessage(params)
console.log(response.MessageId)
```

#### SDK

##### <a name="sdk"></a>SDK action

Returns an AWS SQS client instance
Full list of available actions in [NODE AWS SQS client](https://github.com/aws/aws-sdk-js/blob/master/clients/sqs.d.ts)

_Definition:_

```ts
() => AWS.SQS
```

_Usage:_

```js
const sqs = await sqsConnector.sdk()
```

_Example:_

Receive messages from queue
```js
const response = await sqsConnector.sdk().receiveMessage({ QueueUrl }).promise()
console.log(response.Messages)
```

For more examples, go [here](https://github.com/reshufflehq/reshuffle/tree/master/examples/aws/sqs-messages.js).


Asana Connector

# reshuffle-asana-connector

[Code](https://github.com/reshufflehq/reshuffle-asana-connector) |  [npm](https://www.npmjs.com/package/reshuffle-asana-connector) | [Code sample](https://github.com/reshufflehq/reshuffle/tree/master/examples/asana)

`npm install reshuffle-asana-connector`

This connector uses [Node Asana Client](https://github.com/Asana/node-asana) package.

### Reshuffle Asana Connector

This package contains a [Reshuffle](https://github.com/reshufflehq/reshuffle) connector for [Asana](https://app.asana.com/).

The following example listen to Asana updates:
```js
const { Reshuffle } = require('reshuffle')
const { AsanaConnector } = require('reshuffle-asana-connector')

const app = new Reshuffle()

const connector = new AsanaConnector(app, {
  accessToken: process.env.ASANA_ACCESS_TOKEN,
  baseURL: process.env.RUNTIME_BASE_URL,
  workspaceId: process.env.ASANA_WORKSPACE_ID,
})

// Listening to any changes for a given project
connector.on({ gid: projectId, asanaEvent: 'changed' }, (event, app) => {
  console.log(event.change) // { field: 'likes', action: 'added', added_value: { gid: '1199236509904757', resource_type: 'like', user: {...} } }
})

app.start()
```

### Table of Contents

[Create Asana API token](#apitoken)

[Configuration Options](#configuration)

#### Connector Events

[Listening to Asana events](#listen)

#### Connector Actions
[SDK](#sdk) - Node Asana Client SDK

[Examples using the SDK](#sdk)

#### <a name="apitoken"></a>Create Asana access token
Create Asana access token:
- Go to https://app.asana.com/0/developer-console
- Under 'Personal Access Token'' > '+ New Access Token'
- Name it, copy your token, and pass it to the connector as below

#### <a name="configuration"></a>Configuration Options

```typescript
const connector = new AsanaConnector(app, {
  accessToken: process.env.ASANA_ACCESS_TOKEN,
})
``` 

To use Reshuffle Asana connector events, you need to provide at least your runtime baseURL and workspaceId.
The workspaceId can be find in Asana Console page url (e.g. https://app.asana.com/admin/<YOUR_WORKSPACE_ID>) 
You can also override the default webhookPath.
```typescript
const connector = new AsanaConnector(app, {
  accessToken: process.env.ASANA_ACCESS_TOKEN,
  baseURL: process.env.RUNTIME_BASE_URL,
  workspaceId: process.env.ASANA_WORKSPACE_ID,
  webhookPath: process.env.ASANA_WEBHOOK_PATH // Optional, default is '/reshuffle-asana-connector/webhook'
})
```

Required webhooks will be automatically set up for you on app.start().
It uses existing webhooks when ti finds one already registered with the same base URL / workspace ID.

#### Connector events

##### <a name="listen"></a>Listening to Asana events

*Note: Reshuffle Asana events uses Asana webhooks which can be triggered up to a minute after the actual event took place in asana.com*

To listen to events happening in Asana, simply pass the gid of the entity you want to track (project or task id)
This can be found in the URL (e.g for your project home page: https://app.asana.com/0/<YOUR_PROJECT_ID>/board)
You can also pass an asanaEvent (default is trigger for any changes)
```typescript
interface AsanaConnectorEventOptions {
  gid: string // Asana project or task unique identifier
  asanaEvent?: AsanaEvent // Optional, the default is to listen to any Asana events 
}

// List extracted from section 'Resources and Actions' at https://developers.asana.com/docs/webhooks
type AsanaEvent = '*' | 'deleted' | 'undeleted' | 'added' | 'removed' | 'changed'
```

- Listening to all events in your project
```typescript
connector.on({ gid: projectId }, (event, app) => {
  console.log(event.change) // type is AsanaEvent, e.g. 'changed'
})
```

- Listening to added entities in your project
```typescript
connector.on({ gid: projectId, asanaEvent: 'added' }, async (event, app) => {
  console.log(event.change) // e.g. 'added'
  console.log(event.resource) // { gid: '1198840429184158', resource_type: 'story', resource_subtype: 'added_to_project' }

  // Get the new task details
  const newTask = await connector.sdk().tasks.findById(event.resource.gid)
  console.log('new task details', newTask) // { gid: '1199238260452125', created_at: '2020-11-20T01:13:37.669Z', name: 'task name', ... }
})
```

#### Connector actions

All actions are provided via the sdk.
See full list of actions with documentation in [Node Asana Client code](https://github.com/Asana/node-asana/tree/master/lib/resources) (select a resource and see the list of actions available via the sdk action.)


##### <a name="sdk"></a>SDK

Full access to the Node Asana Client SDK

```typescript
const sdk = await connector.sdk()
```

##### <a name="examples"></a>Examples using the SDK

- Get project details
```typescript
const project = await connector.sdk().projects.findById(projectId)
console.log('project details', project) // { name: 'my project name', ... }
```

- Create a new task:
```typescript
const task = await connector.sdk().tasks.createInWorkspace(project.workspace.gid, { name: 'task 1' })
console.log(`task created`, task) // { gid: '1234567898765', name: 'task 1' }
```

- Get all tasks for a project
```typescript
const tasks = await connector.sdk().tasks.findByProject(projectId)
console.log(`tasks for project ${projectId}`, tasks.data) // [{ gid: '1199204075353966', name: 'File uploader broken on Chrome' }, ...]
```

- Amend a task
```typescript
const taskUpdated = await connector.sdk().tasks.update(tasks.data[0].gid, { name: 'New name' }) // tasks coming from 'Get all tasks for a project' example above
console.log(taskUpdated) // {gid: '0123456789', name: 'New name', ... }
```

- Get the team details
```typescript
const team = await connector.sdk().teams.findById(project.team.gid) // project object coming from 'Get project details' example above 
console.log('team details', team) // { name: 'Engineering', gid: '112233', organization: { name: 'my organisation name', gid: '12345'} ... }
```


Atlassian Jira Connector

# reshuffle-jira-connector

[Code](https://github.com/reshufflehq/reshuffle-jira-connector) |  [npm](https://www.npmjs.com/package/reshuffle-jira-connector) | [Code sample](https://github.com/reshufflehq/reshuffle/tree/master/examples/jira)

`npm install reshuffle-jira-connector`

This connector uses [Node Jira Client](https://github.com/jira-node/node-jira-client) package.

### Reshuffle Jira Connector

This package provides a [Reshuffle](https://github.com/reshufflehq/reshuffle) connector for [Atlassian Jira](https://www.atlassian.com/software/jira).

The following example listen to jira issue updates:
```js
const { Reshuffle } = require('reshuffle')
const { JiraConnector } = require('reshuffle-jira-connector')

const app = new Reshuffle()
const connector = new JiraConnector(app, {
  host: process.env.JIRA_HOST,
  protocol: process.env.JIRA_PROTOCOL,
  username: process.env.JIRA_USERNAME,
  password: process.env.JIRA_PASSWORD,
  baseURL: process.env.RUNTIME_BASE_URL,
})
  
connector.on({ jiraEvent: 'jira:issue_updated' }, (event, app) => {
  console.log(event.issue) // {"id":"10000","self":"https://reshuffle-demo.atlassian.net/rest/api/2/10000","key":"DEMO-1","fields":{"statuscategorychangedate":"2020-11-11T14:44:56.016+1300","issuetype":{"self":"https://reshuffle-demo.atlassian.net/rest/api/2/issuetype/10001","id":"10001","description":"Functionality or a feature expressed as a user goal.","iconUrl":"https://reshuffle-demo.atlassian.net/secure/viewavatar?size=medium&avatarId=10315&avatarType=issuetype","name":"Story","subtask":false,"avatarId":10315},"timespent":null,"project":{"self":"https://reshuffle-demo.atlassian.net/rest/api/2/project/10000","id":"10000","key":"DEMO","name":"demo","projectTypeKey":"software","simplified":false,"avatarUrls":{"48x48":"https://reshuffle-demo.atlassian.net/secure/projectavatar?pid=10000&avatarId=10410","24x24":"https://reshuffle-demo.atlassian.net/secure/projectavatar?size=small&s=small&pid=10000&avatarId=10410","16x16":"https://reshuffle-demo.atlassian.net/secure/projectavatar?size=xsmall&s=xsmall&pid=10000&avatarId=10410","32x32":"https://reshuffle-demo.atlassian.net/secure/projectavatar?size=medium&s=medium&pid=10000&avatarId=10410"}},"fixVersions":[],"aggregatetimespent":null,"resolution":null,"customfield_10028":null,"resolutiondate":null,"workratio":-1,"lastViewed":"2020-11-10T15:25:02.313+1300","issuerestriction":{"issuerestrictions":{},"shouldDisplay":false},"watches":{"self":"https://reshuffle-demo.atlassian.net/rest/api/2/issue/DEMO-1/watchers","watchCount":1,"isWatching":true},"created":"2020-11-10T15:25:02.104+1300","customfield_10020":null,"customfield_10021":null,"customfield_10022":null,"priority":{"self":"https://reshuffle-demo.atlassian.net/rest/api/2/priority/3","iconUrl":"https://reshuffle-demo.atlassian.net/images/icons/priorities/medium.svg","name":"Medium","id":"3"},"customfield_10023":null,"customfield_10024":null,"customfield_10025":null,"labels":[],"customfield_10016":null,"customfield_10017":null,"customfield_10018":{"hasEpicLinkFieldDependency":false,"showField":false,"nonEditableReason":{"reason":"PLUGIN_LICENSE_ERROR","message":"The Parent Link is only available to Jira Premium users."}},"customfield_10019":"0|hzzzzz:","timeestimate":null,"aggregatetimeoriginalestimate":null,"versions":[],"issuelinks":[],"assignee":null,"updated":"2020-11-11T14:44:56.015+1300","status":{"self":"https://reshuffle-demo.atlassian.net/rest/api/2/status/10001","description":"","iconUrl":"https://reshuffle-demo.atlassian.net/","name":"Selected for Development","id":"10001","statusCategory":{"self":"https://reshuffle-demo.atlassian.net/rest/api/2/statuscategory/2","id":2,"key":"new","colorName":"blue-gray","name":"New"}},"components":[],"timeoriginalestimate":null,"description":null,"customfield_10010":null,"customfield_10014":null,"timetracking":{},"customfield_10015":null,"customfield_10005":null,"customfield_10006":null,"customfield_10007":null,"security":null,"customfield_10008":null,"customfield_10009":null,"aggregatetimeestimate":null,"attachment":[],"summary":"Connect to Jira without pulling your hair","creator":{"self":"https://reshuffle-demo.atlassian.net/rest/api/2/user?accountId=5ed044d047d31e0c2a19ac39","accountId":"5ed044d047d31e0c2a19ac39","avatarUrls":{"48x48":"https://avatar-management--avatars.us-west-2.prod.public.atl-paas.net/5ed044d047d31e0c2a19ac39/405fd060-08c4-4bb1-8bdb-50af14e300dc/48","24x24":"https://avatar-management--avatars.us-west-2.prod.public.atl-paas.net/5ed044d047d31e0c2a19ac39/405fd060-08c4-4bb1-8bdb-50af14e300dc/24","16x16":"https://avatar-management--avatars.us-west-2.prod.public.atl-paas.net/5ed044d047d31e0c2a19ac39/405fd060-08c4-4bb1-8bdb-50af14e300dc/16","32x32":"https://avatar-management--avatars.us-west-2.prod.public.atl-paas.net/5ed044d047d31e0c2a19ac39/405fd060-08c4-4bb1-8bdb-50af14e300dc/32"},"displayName":"Christophe Gachiniard","active":true,"timeZone":"Pacific/Auckland","accountType":"atlassian"},"subtasks":[],"reporter":{"self":"https://reshuffle-demo.atlassian.net/rest/api/2/user?accountId=5ed044d047d31e0c2a19ac39","accountId":"5ed044d047d31e0c2a19ac39","avatarUrls":{"48x48":"https://avatar-management--avatars.us-west-2.prod.public.atl-paas.net/5ed044d047d31e0c2a19ac39/405fd060-08c4-4bb1-8bdb-50af14e300dc/48","24x24":"https://avatar-management--avatars.us-west-2.prod.public.atl-paas.net/5ed044d047d31e0c2a19ac39/405fd060-08c4-4bb1-8bdb-50af14e300dc/24","16x16":"https://avatar-management--avatars.us-west-2.prod.public.atl-paas.net/5ed044d047d31e0c2a19ac39/405fd060-08c4-4bb1-8bdb-50af14e300dc/16","32x32":"https://avatar-management--avatars.us-west-2.prod.public.atl-paas.net/5ed044d047d31e0c2a19ac39/405fd060-08c4-4bb1-8bdb-50af14e300dc/32"},"displayName":"Christophe Gachiniard","active":true,"timeZone":"Pacific/Auckland","accountType":"atlassian"},"aggregateprogress":{"progress":0,"total":0},"customfield_10000":"{}","customfield_10001":null,"customfield_10002":null,"customfield_10003":null,"customfield_10004":null,"environment":null,"duedate":null,"progress":{"progress":0,"total":0},"votes":{"self":"https://reshuffle-demo.atlassian.net/rest/api/2/issue/DEMO-1/votes","votes":0,"hasVoted":false}}}
  console.log(event.changelog.items[0]) // {"field":"status","fieldtype":"jira","fieldId":"status","from":"3","fromString":"In Progress","to":"10001","toString":"Selected for Development"}
})

app.start()
```

Create an API token from your Atlassian account:

1. Log in to https://id.atlassian.com/manage/api-tokens.
2. Click Create API token.
3. From the dialog that appears, enter a memorable and concise Label for your token and click Create.
4. Click Copy to clipboard, then paste the token to your script, or elsewhere to save

#### Configuration Options:

Provide options as below for connecting to Jira:
```typescript
const connector = new JiraConnector(app, {
  host: '<your jira instance host>',
  protocol: 'https',
  username: '<your user email address>',
  password: '<your api token>',
  baseURL: '<your runtime base url for events only>',
})
``` 

To use Jira connector events, you need to provide at least your runtime baseURL. 
You can also override the default webhookPath and webhookName.
```typescript
interface JiraConnectorConfigOptions extends JiraApiOptions {
  baseURL?: string
  webhookPath?: string // Default to '/reshuffle-jira-connector/webhook'
  webhookName?: string // Default to 'reshuffle-runtime-jira'
}

// Full list of available options to connect to Jira Rest API
interface JiraApiOptions {
  protocol?: string
  host: string
  port?: string
  username?: string
  password?: string
  apiVersion?: string
  base?: string
  intermediatePath?: string
  strictSSL?: boolean
  request?: any
  timeout?: number
  webhookVersion?: string
  greenhopperVersion?: string
  bearer?: string
  oauth?: OAuth
}
```

#### Connector events

##### listening to Jira events

To listen to events happening in Jira, pass the Jira event type as options

```typescript
interface JiraConnectorEventOptions {
  jiraEvent: JiraEvent
  
}

// List extracted from https://developer.atlassian.com/server/jira/platform/webhooks/#configuring-a-webhook
type JiraEvent =
  | 'jira:issue_created'
  | 'jira:issue_updated'
  | 'jira:issue_deleted'
  | 'jira:worklog_updated'
  | 'issuelink_created'
  | 'issuelink_deleted'
  | 'worklog_created'
  | 'worklog_updated'
  | 'worklog_deleted'
  | 'comment_created'
  | 'comment_updated'
  | 'comment_deleted'
  | 'project_created'
  | 'project_updated'
  | 'project_deleted'
  | 'jira:version_released'
  | 'jira:version_unreleased'
  | 'jira:version_created'
  | 'jira:version_moved'
  | 'jira:version_updated'
  | 'jira:version_deleted'
  | 'jira:version_merged'
  | 'user_created'
  | 'user_updated'
  | 'user_deleted'
  | 'option_voting_changed'
  | 'option_watching_changed'
  | 'option_unassigned_issues_changed'
  | 'option_subtasks_changed'
  | 'option_attachments_changed'
  | 'option_issuelinks_changed'
  | 'option_timetracking_changed'
  | 'sprint_created'
  | 'sprint_deleted'
  | 'sprint_updated'
  | 'sprint_started'
  | 'sprint_closed'
  | 'board_created'
  | 'board_updated'
  | 'board_deleted'
  | 'board_configuration_changed'
```

#### Connector actions

All actions are provided via the sdk.
// See full list of actions with documentation in [Node Jira Client code](https://github.com/jira-node/node-jira-client/blob/master/src/jira.js)

Few examples:

- Get details for project 'DEMO'
```typescript
const jiraProject = await connector.sdk().getProject('DEMO')
```

- Get list of issues for a board
```typescript
const board1Issues = await connector.sdk().getIssuesForBoard(1)
console.log(board1Issues[0].fields)
```

- Get current user details:
```typescript
const user = await connector.sdk().getCurrentUser()
```

##### sdk

Full access to the Node Jira Client SDK

```typescript
const sdk = await connector.sdk()
```


Cron Connector

*NPM Package:*  [reshuffle](https://www.npmjs.com/package/reshuffle)

The Cron connector fires events according to the specified cron expression. If you are not familiar with cron expressions, you can use an online tool like [crontab.guru](https://crontab.guru) to help you generate one.

For example, you can use this connector to monitor a system every 10 seconds, or send a daily email report. 

Here is an example of how you would send a daily email using this connector:
```js
const { Reshuffle, CronConnector } = require('reshuffle')
const { SMTPConnector } = require('reshuffle-smtp-connector')

const app = new Reshuffle()
const cronConnector = new CronConnector(app)
const smtpConnector = new SMTPConnector(
  app,
  {
    username: 'superman',
    password: 'hunter123',
    host: 'email.some.com',
    port: 587,
    fromName: 'Spiderman II',
    fromEmail: 'admin@superheros.com',
  },
  'connectors/email',
)

cronConnector.on({ expression: '*/10 * * * * *' }, (event, app) => {
  app.getConnector('connectors/email').send({
    to: 'email@exmaple.com',
    subject: 'daily report!',
    html: 'The report itself',
  })
})

app.start()
```

_Triggers_:

[task](#task) Create a Cron task

### Event Details

#### <a name="task"></a>

Cron Event

_Event parameters:_

```
expression: string - the cron expression for a task
```

_Handler inputs:_

```
none, general event provided
```

_Example:_

```js
async (event, app) => {
  console.log('Task executed')
}
```

Execute a single task based on the cron expression


EIDR Connector

# reshuffle-eidr-connector

[Code](https://github.com/reshufflehq/reshuffle-eidr-connector) |
[npm](https://www.npmjs.com/package/reshuffle-eidr-connector) |
[Code sample](https://github.com/reshufflehq/reshuffle-eidr-connector/tree/master/examples)

`npm install reshuffle-eidr-connector`

### Reshuffle EIDR Connector

This package contains a [Reshuffle](https://github.com/reshufflehq/reshuffle)
connector to the Entertainment Identifier Registry (EIDR) service
at [eidr.org](https://eidr.org/).

Please review the EIDR
[API Specification](http://eidr.org/documents/EIDR_2.1_REST_API.pdf) and
[User Guide](http://eidr.org/documents/EIDR_2.1_Registry_User_Guide.pdf) for
full details about the service.

The following example creates and API endpoint to query EIDR for movie data:

```js
const { Reshuffle, HttpConnector } = require('reshuffle')
const { EIDRConnector } = require('reshuffle-eidr-connector')

const app = new Reshuffle()
const eidr = new EIDRConnector(app, {
  userId: process.env.EIDR_USERID,
  partyId: process.env.EIDR_PARTYID,
  password: process.env.EIDR_PASSWORD,
})
const http = new HttpConnector(app)

http.on({ method: 'GET', path: '/query' }, async (event) => {
  const name = (event.req.query.name || '').trim()
  if (name.length === 0) {
    return event.res.status(400).send('Missing name')
  }

  try {
    const { results } = await eidr.query({ title: { exact: name } })
    return event.res.json(results)

  } catch (e) {
    return event.res.status(e.status).json({
      error: e.message,
      details: e.details,
    })
  }
})

app.start(8000)
```

#### Table of Contents

[Configuration](#configuration) Configuration options

_Connector actions_:

[info](#info) Get connector information

[query](#query) Search for media information

[resolve](#resolve) Get information for one media resource

[simpleQuery](#simpleQuery) Simple search for media information

##### <a name="configuration"></a>Configuration options

```js
const app = new Reshuffle()
const eidrConnector = new EIDRConnector(app)
```

This default initialization will allow access to all public available EIDR
functions, including ID resolution. Some functions, including query and
ID registration, require EIDR membership credentials. Credentials can
be passed as an object in the form:

```ts
{
  userId: string
  partyId: string
  password?: string
  shaddow?: string
  domain?: string
}
```

The `userId` and `partyId` are mandatory and provided by EIDR to its members.
Either `password` or `shaddow` (the base64 encoded MD5 hash of password) must
also be provided. The `domain` can used left out in most cases unless there
is a specific reason to use a mirror service.

Credentials can also be passed as a string with the following format:
`Eidr <userId>:<partyId>:<shaddow>`.

Credentials can be passed as a second argument to the connector's constructor:

```js
const credentials = { ... }
const eidrConnector = new EIDRConnector(app, credentials)
```

or as the last optional argument to priviledged actions like [query](#query).
This method is usedful when building an service or API to allow third patries
to perform queries or other priviledged operations against the EIDR registry.

#### Connector actions

##### <a name="info"></a>Info action

_Definition:_

```
() => {
  eidrApiVersion: string,
  eidrConnectorVersion: string,
}
```

_Usage:_

```js
const info = await eidrConnector.info()
```

Get connector information.

##### <a name="query"></a>Query action

_Definition:_

```
(
  query: object | string,
  options?: object,
  credentials?: string | object,
) => {
  totalMatches: number,
  results: object[],
}
```

_Usage:_

```js
const q = '(/FullMetadata/BaseObjectData/ResourceName "abominable")'

// Get first 25 results
const { results } = await eidrConnector.query(q)

// Get results 11 - 20
const { results } = await eidrConnector.query(
  q,
  { pageNumber: 2, pageSize: 10 },
)
```

or

```js
const id = '10.5240/DF48-AB62-4486-C185-9E1B-4'
const { results } = await eidrConnector.query({ title: { exact: name } })
```

Search the EIDR database for matches to the query. You can specify the query
using EIDR XML query language or the EIDR Proxy JSON query language.

The optional `options` object supports the following optional fields:

* `pageNumber?: number` - Results page number (default is 1)
* `pageSize?: number` - Results page size (default is 25)
* `root?: string` - EIDR ID for rooted queries

See the [Configuration](#configuration) section above for more details about
access credentials.

##### <a name="resolve"></a>Resolve action

_Definition:_

```
(
  id: string,
) => {
  // media information
}
```

_Usage:_

```js
const id = '10.5240/DF48-AB62-4486-C185-9E1B-4'
const info = await eidrConnector.resolve(id)
```

Get the full information for the media resource (movie, tv show etc) with
the specified id. The full information can be very details, as described
in page 21 of the
[EIDR API Specification](http://eidr.org/documents/EIDR_2.1_REST_API.pdf).

##### <a name="simpleQuery"></a>Simple Query action

_Definition:_

```
(
  exprOrObj: string | object,
  compareFunction?: (a: object, b: object) => number,
  credentials?: string | object,
) => object[]
```

_Usage:_

```js
const id = '10.5240/DF48-AB62-4486-C185-9E1B-4'
const results = await eidrConnector.simpleQuery({
  name,
  movie: true,
  valid: true,
  StructuralType: 'Performance',
})
```

Search the EIDR database for matches to the query. See [query](#query) above
for details.

The Simple Query action does not support pagination and returns the results
array directly to the caller. The results are automatically sorted by
descending order of release date. You can control the sort order by specifying
a `compareFunction` that behaves like the one used by
[Array.sort](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort).

See the [Configuration](#configuration) section above for more details about
access credentials.

## Learn more

You can learn more about Reshuffle on
[dev.reshuffle.com](https://dev.reshuffle.com).


Elasticsearch Connector

## reshuffle-elasticsearch-connector

[Code](https://github.com/reshufflehq/reshuffle-elasticsearch-connector) |  [npm](https://www.npmjs.com/package/reshuffle-elasticsearch-connector) | [Code sample](https://github.com/reshufflehq/reshuffle/tree/master/examples/elasticsearch)

`npm install reshuffle-elasticsearch-connector`

This connector uses [Elasticsearch Node JS Client](https://www.npmjs.com/package/@elastic/elasticsearch) package.


### Reshuffle Elasticsearch Connector

This package contains a [Reshuffle](https://github.com/reshufflehq/reshuffle) connector for connecting to [Elasticsearch](https://www.elastic.co/elasticsearch/).

The following example adds a new entry to an existing index:
```js
const { Reshuffle } = require('reshuffle')
const { ElasticsearchConnector } = require('reshuffle-elasticsearch-connector')

const elasticsearchOptions = {
  cloud: {
    id:
      '<name>:<id>',
  },
  auth: {
    username: '<username>',
    password: '<password>',
  },
}

const app = new Reshuffle()
const connector = new ElasticsearchConnector(app, elasticsearchOptions)

app.start()

connector.sdk().index({
  index: 'game-of-thrones',
  body: {
    character: 'Daenerys Targaryen',
    quote: 'I am the blood of the dragon.'
  }
})
```

### Table of Contents

[Setup Cloud elasticsearch](#setup)

[Configuration Options](#configuration)

#### Connector Events

N/A

#### Connector Actions

[SDK](#sdk) - Retrieve a Node JS Elasticsearch client

[Examples using the SDK](#examples)

#### <a name="setup"></a>Setup Cloud Elasticsearch
Setup Elastic cloud:

1. Go to https://cloud.elastic.co/home
2. Click `Create deployment`
3. Provide a name and create
4. Copy the username/password   
4. Click on your deployment in the deployment list
5. copy the cloud ID which is <deployment-name>:<key>
6. See [Configuration Options](#configuration) below for how to connect to this Elasticsearch cloud instance.

#### <a name="configuration"></a>Configuration Options

The Elasticsearch connector takes the same options as the Node JS Elasticsearch client.
See [Node JS Elasticsearch Client options](https://www.elastic.co/guide/en/elasticsearch/client/javascript-api/current/client-configuration.html)

As an example, for connecting to elasticsearch cloud, provide options as below:

```typescript
const connector = new ElasticsearchConnector(app, {
  cloud: {
    id:
      '<deployment-name>:<key>', // Cloud ID (see Setup Cloud Elasticsearch above for obtaining this id)
  },
  auth: {
    username: '<username>',
    password: '<password>',
  },
})
```

#### Connector actions

All actions are provided via the sdk.
// See full list of actions in [Node JS Elasticsearch Client API reference](https://www.elastic.co/guide/en/elasticsearch/client/javascript-api/current/api-reference.html#api-reference)

##### <a name="sdk"></a>SDK

Return a Node Elasticsearch Client

```typescript
const sdk = await connector.sdk()
```

##### <a name="examples"></a>Examples using the SDK

- Search entries
```typescript
const entries = await connector.sdk().search({
  index: 'my-index',
  from: 20,
  size: 10,
  body: { foo: 'bar' }
}, {
  ignore: [404],
  maxRetries: 3
})
```

- Add entry
```typescript
await connector.sdk().index({
  index: 'game-of-thrones',
  body: {
    character: 'Ned Stark',
    quote: 'Winter is coming.'
  }
})
```



## How do I render plain HTML?

```js
const { HttpConnector, Reshuffle } = require('reshuffle')

const app = new Reshuffle()

const connector = new HttpConnector(app)

connector.on({ method: 'GET', path: '/html' }, (event, app) => {
  event.res.send(`<!doctype html>
<html>
<head>
  <meta charset="utf-8">
</head>
<body>
    <h1>Hello World</h1>
</body>
</html>
  `)
})

app.start()
```

## How do I handle errors?

```js
const { HttpConnector, Reshuffle } = require('reshuffle')

const app = new Reshuffle()

const connector = new HttpConnector(app)

connector.on({ method: 'GET', path: '/error-test' }, (event, app) => {
  try {
    throw new Error('Error')
  } catch (error) {
    event.res.send('Error handled!')
  }
})

app.start()
```

## How do serve a static file?

There is an example of how to serve a static file in the [examples folder](https://github.com/reshufflehq/reshuffle/blob/master/examples/http/HTTPSendFileExample.js)

## What is the order of preference for routes?

Route preference works as follows:

- All routes not using parameters (not containing ':') are processed first.

- When using routes with parameters (e.g. path is /foo/:id), handlers associated to this path will only be executed if no specific routes matched.

## Can I use my own express middleware?

We currently don't support this, but we are looking at adding this feature in the future.


FastSpring Connector

# reshuffle-fastspring-connector

[Code](https://github.com/reshufflehq/reshuffle-fastspring-connector) |
[npm](https://www.npmjs.com/package/reshuffle-fastspring-connector) |
[Code sample](https://github.com/reshufflehq/reshuffle-fastspring-connector/tree/master/examples)

`npm install reshuffle-fastspring-connector`

### Reshuffle FastSpring Connector

This package contains a [Reshuffle](https://github.com/reshufflehq/reshuffle)
connector to [fastspring.com](https://fastspring.com/). It can be used to
configure and manage online store and purchases, and provides access to the
full [FastSpring API](https://fastspring.com/docs/fastspring-api/).

This example gets the product list from Fast Spring:

```js
const { Reshuffle } = require('reshuffle')
const { FastSpringConnector } = require('reshuffle-fastspring-connector')

;(async () => {
  const app = new Reshuffle()
  const fs = new FastSpringConnector(app, {
    username: process.env.FASTSPRING_USERNAME,
    password: process.env.FASTSPRING_PASSWORD,
  })

  const products = await fs.getProductList()
  console.log(products)
})()
```

#### Table of Contents

[Configuration](#configuration) Configuration options

_Connector actions_:

[deleteProduct](#deleteProduct) Delete a product

[getLocalizedPrice](#getLocalizedPrice) Get price in a specific country

[getProductInfo](#getProductInfo) Get product information

[getProductList](#getProductList) Get a list of available products

[updateProduct](#updateProduct) Create or update one product

[updateProducts](#updateProducts) Create or update multiple products

[updateSimpleProduct](#updateSimpleProduct) Simplified create/update action

_REST_:

[DELETE](#DELETE) Direct REST DELETE

[GET](#GET) Direct REST GET

[POST](#POST) Direct REST POST

##### <a name="configuration"></a>Configuration options

```js
const app = new Reshuffle()
const fastSpringConnector = new FastSpringConnector(app)
```

#### Connector actions

##### <a name="deleteProduct"></a>Delete Product action

_Definition:_

```ts
(
  productID: string,
) => void
```

_Usage:_

```js
await fastSpringConnector.deleteProduct('my-product')
```

Delete a product from the store.

##### <a name="getLocalizedPrice"></a>Get Localized Price action

_Definition:_

```ts
(
  productID: string,
  countryCode?: string, // optional
) => number
```

_Usage:_

```js
const usd = await fastSpringConnector.getLocalizedPrice('my-product', 'US')
```

Get the price for a product in a specific country. If a price in local
currency was not defined for the product, then the stored price is
automaically converted into local currency.

##### <a name="getProductInfo"></a>Get Product Info action

_Definition:_

```ts
(
  productID: string,
) => Object
```

_Usage:_

```js
const info = await fastSpringConnector.getProductInfo('my-product')
```

Get the full product information. See [updateProduct](#updateProduct) below
for details.

##### <a name="getProductList"></a>Get Product List action

_Definition:_

```ts
() => string[]
```

_Usage:_

```js
const list = await fastSpringConnector.getProductist()
```

Get a list of product IDs for all the products in your store.

##### <a name="updateProduct"></a>Update Product action

_Definition:_

```ts
(
  productID: string,
  info: Object,
) => void
```

_Usage:_

```js
await fastSpringConnector.updateProduct('my-product', {
  display: {
    en: 'My Product',
  },
  pricing: {
    price: { USD: 3.14 },
  },
})
```

Create or update a product with a specified ID. A full description of the
product information object can be found
[here](https://fastspring.com/docs/products/#update).

Update is an additive operation, i.e. fields that are not included in the
`info` object are not removed from the object record. Rather, new fields are
added and new values for exsiting fields are updated.

If no product with the specified ID exists, then a new object is created.

##### <a name="updateProducts"></a>Update Products action

_Definition:_

```ts
(
  info: Object[],
) => void
```

_Usage:_

```js
await fastSpringConnector.updateProducts([
  { product: 'p1', display: { en: 'Product One' } },
  { product: 'p2', display: { en: 'Product Two' } },
])
```

Create or update multiple products using product info objects. A full
description of the product information object can be found
[here](https://fastspring.com/docs/products/#update).

##### <a name="updateSimpleProduct"></a>Update Simple Product action

_Definition:_

```ts
(
  productID: string,
  englishDisplay: string,  // display name
  usd: number,             // price in USD
) => void
```

_Usage:_

```js
await fastSpringConnector.updateProduct('my-product', 'My Product', 3.14)
```

A simplified interface for creating or updating product information. For full
control over product info, use [updateSimpleProduct](#updateSimpleProduct)
above.

#### REST

##### <a name="DELETE"></a>DELETE action

_Definition:_

```ts
(
  path: string,
) => object | text
```

_Usage:_

```js
const response = await fastSpringConnector.DELETE(`products/${id}`)
```

Send a DELETE request. Returns a JavaScript object for JSON responses or text
string otherwise. Throws an exception if a non-2xx HTTP code is returned.

##### <a name="GET"></a>GET action

_Definition:_

```ts
(
  path: string,
) => object | text
```

_Usage:_

```js
const response = await fastSpringConnector.GET(`products/${id}`)
```

Send a GET request. Returns a JavaScript object for JSON responses or text
string otherwise. Throws an exception if a non-2xx HTTP code is returned.

##### <a name="POST"></a>POST action

_Definition:_

```ts
(
  path: string,
  body: object,
) => object | text
```

_Usage:_

```js
const response = await fastSpringConnector.POST(
  'products',
  { products: productInfo },
)
```

Send a POST request. Returns a JavaScript object for JSON responses or text
string otherwise. Throws an exception if a non-2xx HTTP code is returned.


Firebase Connector

# reshuffle-firebase-connector

[Code](https://github.com/reshufflehq/reshuffle-firebase-connector) |
[npm](https://www.npmjs.com/package/reshuffle-firebase-connector) |
[Code sample](https://github.com/reshufflehq/reshuffle-firebase-connector/tree/master/examples)

`npm install reshuffle-firebase-connector`

### Reshuffle Firebase Connector

This package contains a [Reshuffle](https://github.com/reshufflehq/reshuffle)
connector to [Google Firebase](https://firebase.google.com).

The following example tracks values in the Firebase realtime database:

```js
const { Reshuffle } = require('reshuffle')
const { FirebaseConnector } = require('reshuffle-firebase-connector')

const app = new Reshuffle()
const fb = new FirebaseConnector(app, {
  credentials: process.env.FIREBASE_CREDENTIALS,
  databaseURL: process.env.FIREBASE_DATABASE_URL,
})

const ref = fb.ref('myKey')
fb.on({ type: 'Value', ref }, (snapshot) => {
  console.log(`New value for key ${snapshot.key}: ${snapshot.val()}`)
})

app.start(8000)
setInterval(() => ref.set(Date.now()), 1000)
```

#### Table of Contents

[Configuration](#configuration) Configuration options

[Types](#types) TypeScript types

_Connector events_:

[ChildAdded](#ChildAdded) Child added to key

[ChildChanged](#ChildChanged) Child changed

[ChildMoved](#ChildMoved) Child moved

[ChildRemoved](#ChildRemoved) Child removed

[Value](#Value) Value changed

_Connector actions_:

[database](#database) Get the realtime database

[ref](#ref) Get a key reference in the realtime database

##### <a name="configuration"></a>Configuration options

```js
const app = new Reshuffle()
const firebaseConnector = new FirebaseConnector(app, {
  credentials: process.env.FIREBASE_CREDENTIALS,
  databaseURL: process.env.FIREBASE_DATABASE_URL,
})
```

Credentials can be an object or a JSON string with service account
credentials that can be downloaded from the Firebase admin console.
See the `Credentials` interface exported from the connector for details.

The `databaseURL` is a string provided by Firebase.

##### <a name="types"></a>TypeScript types

The following types are exported from the connector:

* **interface FirebaseCredentials** Google service account credentials
* **interface FirebaseConnectorOptions** Connector configuration options
* **type FirebaseEventType** Supported events
* **interface FirebaseEventOptions** Event options
* **type FirebaseSnapshot** Data snapshot used as event handler argument
* **class FirebaseConnector** Connector class

#### Connector events

##### <a name="ChildAdded"></a>Child Added event

_Event options:_

```ts
type: 'ChildAdded'
ref: firebase.database.Reference | string
```

_Event object:_

Firebase's [snapshot object](https://firebase.google.com/docs/reference/node/firebase.database.DataSnapshot)

_Example:_

```js
firebaseConnector.on({ type: 'ChildAdded', ref: 'mkKey' }, (snapshot) => {
  console.log(`${snapshot.key} = ${snapshot.val()}`)
})
```

Child added in the realtime database. Learn more [here](https://firebase.google.com/docs/database/admin/retrieve-data#child-added).

##### <a name="ChildChanged"></a>Child Changed event

_Event options:_

```ts
type: 'ChildChanged'
ref: firebase.database.Reference | string
```

_Event object:_

Firebase's [snapshot object](https://firebase.google.com/docs/reference/node/firebase.database.DataSnapshot)

_Example:_

```js
firebaseConnector.on({ type: 'ChildChanged', ref: 'mkKey' }, (snapshot) => {
  console.log(`${snapshot.key} = ${snapshot.val()}`)
})
```

Child changed in the realtime database. Learn more [here](https://firebase.google.com/docs/database/admin/retrieve-data#child-changed).

##### <a name="ChildMoved"></a>Child Moved event

_Event options:_

```ts
type: 'ChildMoved'
ref: firebase.database.Reference | string
```

_Event object:_

Firebase's [snapshot object](https://firebase.google.com/docs/reference/node/firebase.database.DataSnapshot)

_Example:_

```js
firebaseConnector.on({ type: 'ChildMoved', ref: 'mkKey' }, (snapshot) => {
  console.log(`${snapshot.key} = ${snapshot.val()}`)
})
```

Child moved in the realtime database. Learn more [here](https://firebase.google.com/docs/database/admin/retrieve-data#child-moved).

##### <a name="ChildRemoved"></a>Child Removed event

_Event options:_

```ts
type: 'ChildRemoved'
ref: firebase.database.Reference | string
```

_Event object:_

Firebase's [snapshot object](https://firebase.google.com/docs/reference/node/firebase.database.DataSnapshot)

_Example:_

```js
firebaseConnector.on({ type: 'ChildRemoved', ref: 'mkKey' }, (snapshot) => {
  console.log(`${snapshot.key} = ${snapshot.val()}`)
})
```

Child removed from the realtime database. Learn more [here](https://firebase.google.com/docs/database/admin/retrieve-data#child-removed).

##### <a name="Value"></a>Value event

_Event options:_

```ts
type: 'Value'
ref: firebase.database.Reference | string
```

_Event object:_

Firebase's [snapshot object](https://firebase.google.com/docs/reference/node/firebase.database.DataSnapshot)

_Example:_

```js
firebaseConnector.on({ type: 'Value', ref: 'mkKey' }, (snapshot) => {
  console.log(`${snapshot.key} = ${snapshot.val()}`)
})
```

Value changed in the realtime database. Learn more [here](https://firebase.google.com/docs/database/admin/retrieve-data#value).

#### Connector actions

##### <a name="database"></a>Database action

_Definition:_

```ts
() => firebase.database.Database
```

_Usage:_

```js
const database = firebaseConnector.database()
```

Get the realtime database object.

##### <a name="ref"></a>Ref action

_Definition:_

```ts
(
  path: string,
) => firebase.database.Reference
```

_Usage:_

```js
firebaseConnector.ref('myKey').set('myValue')
```

Get a key reference in the realtime database.


Github Connector

# reshuffle-github-connector

[Code](https://github.com/reshufflehq/reshuffle-github-connector) | [npm](https://www.npmjs.com/package/reshuffle-github-connector) | [Code sample](https://github.com/reshufflehq/reshuffle/tree/master/examples/github)

`npm install reshuffle-github-connector`


This connector uses the [Octokit GitHub REST API](https://github.com/octokit/rest.js) package.

### Reshuffle GitHub Connector

This package contains a [Reshuffle](https://github.com/reshufflehq/reshuffle) connector to connect to [GitHub](https://www.github.com).

The following example listens to all GitHub events on a repository:

```js
const { Reshuffle } = require('reshuffle')
const { GitHubConnector } = require('reshuffle-github-connector')

const app = new Reshuffle()
const connector = new GitHubConnector(app, {
  token: process.env.TOKEN,
  runtimeBaseUrl: process.env.RUNTIME_BASE_URL
})

connector.on({ githubEvent: 'push' }, (event) => {
  console.log('GitHub Event: ', event)
})

app.start()
```

### Table of Contents

[Create GitHub API token](#apitoken)

[Configuration Options](#configuration-options)

[Connector Events](#connector-events)

[Connector Actions](#connector-actions)

<a name="apitoken"></a>Create an API token from your GitHub account:

1. Log in and go to https://github.com/settings/tokens.
2. Click "Generate new token".
3. Click Copy to clipboard, then paste the token to your script, or elsewhere to save

#### Configuration Options:

Provide options as below for connecting to GitHub:

```typescript
const connector = new GitHubConnector(app, {
  token: process.env.TOKEN,
  runtimeBaseUrl: process.env.RUNTIME_BASE_URL
})
```

To use GitHub connector events, you need to provide at least your runtimeBaseUrl.
You can also override the default webhookPath and webhookName.

```typescript
interface GithubConnectorConfigOptions extends OctokitOptions {
  secret?: string
  webhookPath?: string
  runtimeBaseUrl?: string
  token?: string
}

// Full list of available options to connect to Octokit GitHub Rest API
type OctokitOptions = {
  authStrategy?: any
  auth?: any
  userAgent?: string
  previews?: string[]
  baseUrl?: string
  log?: {
    debug: (message: string) => unknown
    info: (message: string) => unknown
    warn: (message: string) => unknown
    error: (message: string) => unknown
  }
  request?: OctokitTypes.RequestRequestOptions
  timeZone?: string
  [option: string]: any
}
```

#### Connector events

##### listening to GitHub events

To listen to events happening in GitHub, pass the GitHub event type as options

```typescript
interface GitHubConnectorEventOptions {
  owner: process.env.OWNER,
  repo: process.env.REPO,
  githubEvent: GithubEvent
}

// From: https://developer.github.com/webhooks/event-payloads/#webhook-event-payloads
type GithubEvent =
  | 'check_run'
  | 'check_suite'
  | 'commit_comment'
  | 'content_reference'
  | 'create'
  | 'delete'
  | 'deploy_key'
  | 'deployment'
  | 'deployment_status'
  | 'fork'
  | 'github_app_authorization'
  | 'gollum'
  | 'installation'
  | 'installation_repositories'
  | 'issue_comment'
  | 'issues'
  | 'label'
  | 'marketplace_purchase'
  | 'member'
  | 'membership'
  | 'meta'
  | 'milestone'
  | 'organization'
  | 'org_block'
  | 'package'
  | 'page_build'
  | 'ping'
  | 'project_card'
  | 'project_column'
  | 'project'
  | 'public'
  | 'pull_request'
  | 'pull_request_review'
  | 'pull_request_review_comment'
  | 'push'
  | 'release'
  | 'repository_dispatch'
  | 'repository'
  | 'repository_import'
  | 'repository_vulnerability_alert'
  | 'security_advisory'
  | 'sponsorship'
  | 'star'
  | 'status'
  | 'team'
  | 'team_add'
  | 'watch'
```

##### Examples of event listeners:

```typescript
const app = new Reshuffle()
const connector = new GitHubConnector(app, {
  token: process.env.TOKEN,
  runtimeBaseUrl: process.env.RUNTIME_BASE_URL
})

connector.on({ 
    owner: process.env.OWNER,
    repo: process.env.REPO,
    githubEvent: 'issues' 
  }, async (event, app) => {
  console.log(event)
})

connector.on({ 
    owner: process.env.OWNER,
    repo: process.env.REPO,
    githubEvent: 'fork' 
  }, async (event, app) => {
  console.log(event)
})
```

#### Connector actions

All actions are provided via the sdk.
// See full list of actions with documentation [Octokit GitHub Rest.js Documentation](https://octokit.github.io/rest.js/v18)

Few examples:

- Get the issues for a repository

```typescript
const repoIssues = await connector.sdk().issues.get({
  owner,
  repo,
  issue_number,
})
```

- Create a pull request

```typescript
const pullRequest = await connector.sdk().pulls.create({
  owner,
  repo,
  title,
  head,
  base,
})
```

- Follow another user:

```typescript
const user = await connector.sdk().users.follow({
  username,
})
```

##### sdk

Full access to the Octokit GitHub Rest Client

```typescript
const sdk = await connector.sdk()
```


Google Analytics Connector

## Reshuffle Google Analytics Connector

`npm install reshuffle-google-connectors`

_ES6 import_: `import { GoogleAnalyticsConnector } from 'reshuffle-google-connectors'`

This is a [Reshuffle](https://reshuffle.com) connector that provides an Interface to the Google Analytics Platform.

This connector uses [Universal Analytics](https://www.npmjs.com/package/universal-analytics) package.

#### Example
```js
const { GoogleAnalyticsConnector } = require('reshuffle-google-connectors')
const app = new Reshuffle()

const options = { trackingId: 'UA-XXXXXXXXX-Y' }

const gaConnector = new GoogleAnalyticsConnector(app, options)

gaConnector.trackEvent('my category', 'my action') // Capture an event in Google Analytics
```

### Table of Contents

[Setup Google Analytics (get a tracking id)](#setup)

[Configuration Options](#configuration)

#### Connector Events

N/A

#### Connector Actions

[Track Event](#trackevent)

[Track Page View](#trackpageview)

[SDK](#sdk) - Get a universal analytics client


### <a name="setup"></a>Setup Google Analytics (get a tracking id)
1. Log in to [Google Analytics Platform](https://analytics.google.com/analytics/web/)
2. 'Admin' > 'Create a property'
3. Enter a property name
4. Click on 'Show Advanced Options'
5. Switch on 'Create a Universal Analytics property'
6. Select 'Create a Universal Analytics property only'
7. In Website URL, use your Reshuffle runtime URL
8. Click 'Next' then 'Create'
9. Copy your tracking ID (e.g. UA-XXXXXXXXX-Y)
10. Provide this tracking ID when creating your Reshuffle connector (see below instructions) 

### <a name="configuration"></a>Configuration Options
```typescript
export interface GoogleAnalyticsConnectorConfigOptions {
    trackingId: string // Google Analytics Tracking Identifier (e.g. UA-XXXXXXXXX-Y)
    clientId?: string
    uaOptions?: ua.VisitorOptions
}
```

Example:
```typescript
const { GoogleAnalyticsConnector } = require('reshuffle-google-connectors')
const app = new Reshuffle()

const gaConnector = new GoogleAnalyticsConnector(app, { trackingId: 'UA-XXXXXXXXX-Y' })
```

### Connector events
N/A

#### <a name="trackevent"></a>Track Event

For tracking custom events
```typescript
trackEvent(category: string, action: string, label?: string, value?: string|number) : Promise<void>
```

#### <a name="trackpageview"></a>Track Page View

For tracking page views
```typescript
trackPageView(path: string, hostname?: string, title?: string): Promise<void>
```

#### <a name="sdk"></a>SDK

Returns a Universal Analytics client ([See details on npm](https://www.npmjs.com/package/universal-analytics))

```typescript
 sdk() : ua.Visitor
```
See ua.Visitor class in [Universal Analytics Visitor type](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/universal-analytics/index.d.ts#L375)

Example using the sdk:
```typescript
const app = new Reshuffle()
const options = { trackingId: 'UA-XXXXXXXXX-Y' }
const gaConnector = new GoogleAnalyticsConnector(app, options)

await gaConnector.sdk().event(category, action).send()
```


Google Language Connector

## Reshuffle Google Language Connector

`npm install reshuffle-google-connectors`

_ES6 import_: `import { GoogleLanguageConnector } from 'reshuffle-google-connectors'` 

This is a [Reshuffle](https://dev.reshuffle.com) connector that provides an Interface to the Google Language Client.

#### Configuration Options:
```typescript
interface GoogleLanguageConnectorConfigOptions {
  credentials: string
}
```
#### Connector events
N/A

#### Connector actions

##### analyzeSentiment
Returns the analyzed sentiment response
```typescript
analyzeSentiment(
    text: string,
  ): Promise<protos.google.cloud.language.v1.IAnalyzeSentimentResponse>
```

Analyzes the sentiment of the provided text

###### Example
```js
const connector = new GoogleLanguageConnector({ credentials })
const result = await connector.analyzeSentiment("The text I want analyzed")
console.log("Language:", result.language, " Sentiment score: ", result.documentSentiment.score)
```

##### sdk
Returns the Google Language Service Client
```typescript
// See: https://googleapis.dev/nodejs/language/latest/v1.LanguageServiceClient.html
sdk(): v1.LanguageServiceClient
```

###### Example
```js
const document = {
  content: 'The text I want analyzed',
  type: 'PLAIN_TEXT',
};
const connector = new GoogleLanguageConnector({ credentials })
const [result] = await connector.sdk().analyzeEntities({ document });
const entities = result.entities;
entities.forEach(entity => {
  console.log(entity.name);
}
```


Google Sheets Connector

## Reshuffle Google Sheets Connector

`npm install reshuffle-google-connectors`


This is a [Reshuffle](https://dev.reshuffle.com) connector that allows you to Interact with online Google Sheets.

The connector is designed to work with Google Sheets in the form of a table,
where the header row (first row) is defined.

The following example listens to changes in online spreadsheet:
```js
const { GoogleSheetsConnector } = require('reshuffle-google-connectors')

const myGoogleSheetsConnector = new GoogleSheetsConnector(app, {
  credentials: {
    client_email: '<your_client_email>',
    private_key: '<your_private_key>',
  },
  documentId: '<your_documentId>',
})

const myHandler = (event, app) => {
  // event is { oldRows, newRows, worksheetsRemoved: WorkSheetChanges[], worksheetsAdded: WorkSheetChanges[], worksheetsChanged: WorkSheetChanges[] }
  // WorkSheetChanges is { worksheetId, rowsRemoved, rowsAdded, rowsChanged }
  console.log('New rows detected!')
  event.options.sheetIdOrTitle &&
    console.log(
      `'sheetIdOrTitle' is set in event options so it only checks for changes in sheet ${event.options.sheetIdOrTitle}`,
    )

  event.newRows.forEach(({ worksheetId, rows }) => {
    console.log(`workSheetId: ${worksheetId}`)

    rows.forEach((row, index) => {
      let rowString = `line ${index + 1}\t`
      Object.values(row).forEach((val) => (rowString += `${val}\t`))
      console.log(rowString)
    })
  })

  event.worksheetsChanged[0] &&
    event.worksheetsChanged[0].rowsAdded[0] &&
    console.log(
      `Example of new line values ${JSON.stringify(
        event.worksheetsChanged[0].rowsAdded[0],
      )}`,
    )
}

/** Trigger a handler when changes are detected in document <sheetId> (it will check for changes every 10 seconds) */
myGoogleSheetsConnector.on({}, myHandler)

app.start()
```

#### Configuration Options:
```typescript
interface GoogleSheetsConnectorConfigOptions {
  credentials: ServiceAccountCredentials
  sheetId: string
}
```

#### Connector events

##### rows changed
This event is fired when rows have changed in the online Sheets.

You can trigger a handler on rows changed by providing the following options to the `on` method:
```typescript
interface GoogleSheetsConnectorEventOptions {
  interval?: number
  sheetIdOrTitle?: string
  keyColumn?: string
}
```

Event is an object containing attribute:
```typescript
oldRows: cellValue[]
newRows: cellValue[]
worksheetsRemoved: WorkSheetChanges[]
worksheetsAdded: WorkSheetChanges[]
worksheetsChanged: WorkSheetChanges[]

export interface cellValue {
  headerName: string
  value: string
}

export interface WorkSheetChanges {
  worksheetId: string
  rowsRemoved: any[]
  rowsAdded: any[]
  rowsChanged: RowChange[]
}

export interface RowChange {
  prev: any
  curr: any
}
```

##### Example:
```js
const myHandler = (event, app) => {
  console.log('New rows detected!')
  event.options.sheetIdOrTitle && console.log(`'sheetIdOrTitle' is set in event options so it only checks for changes in sheet ${event.options.sheetIdOrTitle}`)

  event.newRows.forEach(({worksheetId, rows}) => {
    console.log(`workSheetId: ${worksheetId}`)

    rows.forEach((row, index) => {
      let rowString = `line ${index + 1}\t`
      Object.values(row).forEach(val => rowString += `${val}\t`)
      console.log(rowString)
    })
  })

  event.worksheetsChanged[0]
    && event.worksheetsChanged[0].rowsAdded[0]
    && console.log(`Example of new line values ${JSON.stringify(event.worksheetsChanged[0].rowsAdded[0])}`)
}

/** Trigger a handler when changes are detected in document <sheetId> (it will check for changes every 10 seconds) */
myGoogleSheetsConnector.on({}, myHandler)

/** Check for changes every minute (it overrides the default timer set to 10 sec) */
const aMinuteMs = 60 * 1000
myGoogleSheetsConnector.on({interval: aMinuteMs}, myHandler)

/** Check for changes in a specific sheet by id */
myGoogleSheetsConnector.on({sheetIdOrTitle: 0}, myHandler)

/** Check for changes only in a specific sheet by title and every 30 seconds */
myGoogleSheetsConnector.on({sheetIdOrTitle: 'Sheet1', interval: 30 * 1000}, myHandler)

/** Check for changes using a key column for more accuracy, see Known Issues below */
myGoogleSheetsConnector.on({keyColumn: 'Identifier'}, myHandler)
```

##### Known Issues:
Since Google Sheets does not provide row identifiers, it is hard to identify which events caused the changes, for example when deleting a row which is not the last one in the spreadsheet, the rows below are shifted up. This can be interpreted as an update of all the rows below including the "deleted" row and a deletion of the last row.
These are the options to handle such cases:
1. Add or delete rows just from the bottom of the spreadsheet.
2. Treat `event.oldRows` and `event.newRows` as before and after snapshots. You may compare these yourself to ascertain which changes your code is interested in.
3. Set a Key column in your spreadsheet with a unique identifier and provide its name as the `GoogleSheetsConnectorEventOptions.keyColumn`. When this option is used, the connector can differentiate added and deleted rows based on these unique identifiers. This removes the ambiguity described above.
Note that these identifiers must be unique. If duplicates exist in your spreadsheet, the connector will not behave as expected.

When using the `keyColumn` and having multiple sheets, the same column name should be used in all the sheets. In every sheet the column can have different types of identifiers but the column name should be the same, for example `keyColumn` is set to be 'RS-Identifier', in Sheet1 it can be email address while in Sheet2 it can be a serial number.

#### Connector actions
This connector provides all the common actions to interact with a Google Sheets document.
It also provides the sdk (which return a Google Sheets instance) for more advanced operations.

##### getRows
Get all rows of a sheet id|title. This action returns an array of rows. Each row
is an object, with properties matching the column names set by the header row.

###### Example
```js
const sheetTitle = 'Sheet1'
const rows = await myGoogleSheetsConnector.getRows(sheetTitle)
console.log(`Sheet ${sheetTitle} contains ${rows.length} row(s)`)
rows.forEach(row => console.log(row._rawData))
```

##### getCell
Get data of a cell at rowIndex/columnIndex of a sheet id|title

###### Example
```js
const rowIndex = 2
const columnIndex = 1
const cell = await myGoogleSheetsConnector.getCell(sheetId, rowIndex, columnIndex)
console.log(`Cell details [value: ${cell.value}, a1Address: ${cell.a1Address},` +
   ` rowIndex: ${cell.rowIndex}, columnIndex: ${cell.columnIndex}, a1Row: ${cell.a1Row}, a1Column:${cell.a1Column}]`)
```

##### getCellByA1
Get data of a cell by a1 address of a sheet id|title

###### Example
```js
const a1Address = 'B2'
const cell = await myGoogleSheetsConnector.getCellByA1(sheetTitle, a1Address)
console.log(`Cell has properties ${JSON.stringify(cell)}`)
```

##### getCells
Get cells data for range in sheet by id|title

###### Example
```js
const range = {startRowIndex: 1, endRowIndex: 5, startColumnIndex: 0, endColumnIndex: 2}
const rows = await myGoogleSheetsConnector.getCells(sheetTitle, range)
console.log(`Sheets contains ${rows.length} row(s)`)
rows.forEach(row => console.log(row))
```

##### addRow
Adds a new row to a sheet identified by its id|title

###### Example
```js
const sheetId = 0
const values = ['value 1', 'value 2', 'value 3']
await myGoogleSheetsConnector.addRow(sheetId, values)
```

##### getInfo
Get document info (returns an object with sheetCount and sheetsByIndex)

###### Example
```js
const docInfo = await myGoogleSheetsConnector.getInfo()
console.log(`Document has ${docInfo.sheetCount} sheets.`)
docInfo.sheetsByIndex.forEach(
  sheetDetails => console.log(`[id: ${sheetDetails.sheetId}, title: ${sheetDetails.title}]`)
)
```

##### sdk
returns a Google Sheets instance for sheetId

See documentation in github: https://github.com/theoephraim/node-google-spreadsheet

###### Examples
```js
/** Add new sheet using the sdk */
const newSheetTitle = 'new sheet'
const newSheetProperties = {title: newSheetTitle, headerValues: ['header 1', 'header 2', 'header 3']}
const doc = await myGoogleSheetsConnector.sdk()
await doc.addSheet(newSheetProperties)

/** Delete sheet by id|title using the sdk */
const sheetTitleToDelete = 'new sheet'
const doc = await myGoogleSheetsConnector.sdk()
const sheet = doc.sheetsByTitle[sheetTitleToDelete]
// const sheet = doc.sheetsByIndex[2] // Use this line for deleting by sheet id
await sheet.delete()
```

More examples on how to use this connector can be [found here](https://github.com/reshufflehq/reshuffle/blob/master/examples/google/sheets/GoogleSheetsExamples.js).


Google Text To Speech Connector

## Reshuffle Google Text to Speech Connector

`npm install reshuffle-google-connectors`

_ES6 import_: `import { GoogleTextToSpeechConnector } from 'reshuffle-google-connectors'` 

This is a [Reshuffle](https://dev.reshuffle.com) connector that provides an Interface to the Google Text to Speech  Client.

#### Example
```js
const connector = new GoogleText2SpeechConnector(app, {})
const sdk = connector.sdk()
const request = {
  input: { text: "Hello, pleased to meet you. Have a seat" },
  voice: { languageCode: 'en-US', ssmlGender: 'FEMALE' },
  audioConfig: { audioEncoding: 'MP3', effectsProfileId: ['handset-class-device'] }
}
const [response] = await sdk.synthesizeSpeech(request)

// an mp3 file is returned as response.audioContent
```

### Configuration Options:
```typescript
interface GoogleTextToSpeechConnectorConfigOptions {
  credentials: string
}
```
### Connector events
N/A

### Connector actions

#### sdk
Returns a Text to Speech client ([See details on npm](https://www.npmjs.com/package/@google-cloud/text-to-speech))
```typescript
sdk() : TextToSpeechClient
```


Google Translate Connector

# reshuffle-google-translate-connector
[Code](https://github.com/reshufflehq/reshuffle-google-translate-connector) |  [npm](https://www.npmjs.com/package/reshuffle-google-translate-connector) | [Code sample](https://github.com/reshufflehq/reshuffle/tree/master/examples/google/translate)

`npm install reshuffle-google-connectors`

This connector uses [Official Node Google Translate Client](https://www.npmjs.com/package/@google-cloud/translate) package.

### Reshuffle Google Translate Connector



_ES6 import_: `import { GoogleTranslateConnector } from 'reshuffle-google-connectors'` 

This is a [Reshuffle](https://dev.reshuffle.com) connector that provides an Interface to the Google Translate Client.

#### Setup
You need a project in Google Cloud that has the Cloud Translation API enabled and credentials to make authenticated calls. 
See more details [here](https://cloud.google.com/translate/docs/setup)


#### Configuration Options:
```typescript
interface GoogleTranslateConnectorConfigOptions {
  credentials: string
}
```

### Table of Contents

[Translate text - translateText](#translateText)

[Translate text array - translateTexts](#translateTexts)

[SDK](#sdk)

#### Connector events
N/A

#### Connector actions

##### <a name="translateText"></a>translateText
Returns the translated text response from source to target language

```typescript
translateText(
    text: string,
    source: string,    // e.g. 'en',
    target: string,    // e.g. 'fr',    
    location: string,  // Project's location like 'global' or 'us-central1'
    mimeType: string,  // mime types: text/plain, text/html
  ): Promise<string | undefined | null>
```

###### Example
```js
  const connector = new GoogleTranslateConnector(app, { credentials: credentials, location: 'global' })
  const result = await connector.translateText(['Hello world', 'Text to translate'], 'en', 'fr', 'global', 'text/plain' )
  console.log(`Translation: ${result}`)
  
```

##### <a name="translateTexts"></a>translateTexts
Returns the translated array text response from source to target language

```typescript
translateTexts(
    text: string[],
    source: string,    // e.g. 'en',
    target: string,    // e.g. 'fr',    
    location: string,  // Project's location like 'global' or 'us-central1'
    mimeType: string,  // mime types: text/plain, text/html
  ): Promise<google.cloud.translation.v3.TranslateTextResponse>
```

###### Example
```js
  const connector = new GoogleTranslateConnector(app, { credentials: credentials, location: 'global' })
  const result = await connector.translateTexts(['Hello world', 'Text to translate'], 'en', 'fr', 'global', 'text/plain' )
  for (const translation of result.translations) {
    console.log(`Translation: ${translation.translatedText}`)
  }
```

##### <a name="sdk"></a>sdk
Returns the Google Translate Service Client
```typescript
// See: https://googleapis.dev/nodejs/translate/latest/v3.TranslationServiceClient.html
sdk(): v3.TranslationServiceClient
```

###### Example
```js
  const [result] = await connector.sdk().translateText({
      parent: `projects/<project-id>/locations/<location>`,
      contents: ['Hello world', 'Text to translate'],
      mimeType: 'text/plain',
      sourceLanguageCode: 'en',
      targetLanguageCode: 'fr',
  })
  for (const translation of result.translations) {
      console.log(`Translation: ${translation.translatedText}`)
  }
```
`<project-id>` - Google Cloud Project Id, see https://cloud.google.com/resource-manager/docs/creating-managing-projects

`<location>` - Project's location like 'global' or 'us-central1'

Http Connector

*NPM Package:*  [reshuffle](https://www.npmjs.com/package/reshuffle)

The HTTP connector is a wrapper to a web server (Express under the hood) it lets developers trigger logic when an HTTP endpoint is hit. 

The HTTP Connector is not a full replacement for Express. If you are building a pure web application, 
without any integration requirements, then using pure Express might be a better decision. The HTTP connector and Reshuffle are a good fit when  but if you are building an integrating system that needs HTTP integration then this connector will do the job.  
building integrated flows that need to interact with other systems over HTTP.

The following example exposes an endpoint that changes your status in Slack:
```js
const { HttpConnector, Reshuffle } = require('reshuffle')
const { SlackConnector } = require('reshuffle-slack-connector')

const app = new Reshuffle()
const httpConnector = new HttpConnector(app)
const slackConnector = new SlackConnector(
  app,
  {
    authkey: process.env.SLACK_AUTH_KEY,
  },
  'connectors/Slack',
)

httpConnector.on(
  {
    method: 'GET',
    path: '/status',
  },
  (event, app) => {
    app.getConnector('connectors/Slack').setStatus('U8675636646', event.req.query.slack_status)
  },
)

app.start()
```

_Events_:

[request](#request) Handle HTTP request

### Event Details

#### <a name="request"></a>Request event

_Event parameters:_

```
method: string - HTTP request method
path: string - URL path prefix
```

_Handler inputs:_

```
event.ctx.req: object - Express request object
event.ctx.res: object - Express response object
```

_Example:_

```js
async (event, app) => {
  event.res.status(200).send('Ok')
}
```

Create API endpoint by handling HTTP requests. This event can
be used to create REST or other types of HTTP based APIs.

The handler function is an Express framework handler. It receives
standard Express request and response object. The response object
is also used to formulate the HTTP response to the caller.


IMAP Connector

# reshuffle-imap-connector

[Code](https://github.com/reshufflehq/reshuffle-imap-connector) |  [npm](https://www.npmjs.com/package/reshuffle-imap-connector)

`npm install reshuffle-imap-connector`

### Reshuffle IMAP Connector


This is a [Reshuffle](https://github.com/reshufflehq/reshuffle) connector that lets you use IMAP email fetching capabilities.

The following example listens to an incoming email:

```js
const { Reshuffle } = require('reshuffle')
const { IMAPConnector } = require('reshuffle-imap-connector')

// Can easily be tested using https://ethereal.email/

const app = new Reshuffle()
const imap = new IMAPConnector(
  app,
  {
    host: '<imap host>',
    port: 993,
    user: '<inbox email address>',
    password: '<inbox password>',
    tls: true,
    // tlsOptions: Record<string, any>
    markSeen: false,
  },
  'connectors/IMAP',
)

imap.on({ name: 'email' }, 'email', (event) => {
  console.log(event.mail.body.text)
})

app.start()
```

#### Configuration Options:
```typescript
interface IMAPConnectorConfigOptions {
  host: string // The imap host
  port: number // The imap port
  user: string // User to the host. This is normally an email address
  password: string // User password
  tls: boolean // Whether to use TLS to the server
  tlsOptions: Record<string, any> // Any TLS options required by the server 
  markSeen: boolean // Whether the connector should mark the messages as seen after fetched
}
```

#### Connector events
##### Email Received (default)
The connector fires this event when an email arrives.

Usage:
```js
const options = { mailbox:'INBOX' }
const handler = (event, app) => {
                
// event is an object with
// {
//    mailbox
//    mail: {
//      headers
//      body: {
//        html
//        text
//        textAsHtml
//      }
//    }
//  }
}
myImapConnector.on(options, handler)
```

###### Email Received Event configuration 
The event configuration takes an attribute mailbox (which is usually a folder in your email client).
Default mailbox is 'INBOX'

Example on how to use this connector can be [found here](https://github.com/reshufflehq/reshuffle/blob/master/examples/email/IMAPReceiveEmailExample.js).


Mixpanel Connector

## Reshuffle Mixpanel Connector

[Code](https://github.com/reshufflehq/reshuffle-mixpanel-connector) |
[npm](https://www.npmjs.com/package/reshuffle-mixpanel-connector) |


`npm install reshuffle-mixpanel-connector`

_ES6 import_: `import { MixpanelConnector } from 'reshuffle-mixpanel-connectors'`

This is a [Reshuffle](https://github.com/reshufflehq/reshuffle) connector that provides an Interface to the [Mixpanel](https://mixpanel.com) Platform.

This connector uses [Mixpanel node](https://www.npmjs.com/package/mixpanel) package.

#### Example
```js
const { Reshuffle } = require('reshuffle')
const { MixpanelConnector } = require('reshuffle-mixpanel-connector')

const app = new Reshuffle()
const mixpanelConnector = new MixpanelConnector(app, {
    token: '<mixpanel-token>',
    secret: '<mixpanel-secret>',
})

mixpanelConnector.track('test', { key1: 'value1', key2: 'value2' })
```

### Table of Contents

[Setup Mixpanel](#setup)

[Configuration Options](#configuration)

#### Connector Events

N/A

#### Connector Actions

[Track](#track)

[Import](#import)

[SDK](#sdk) - Get a Mixpanel client


### <a name="setup"></a>Setup Mixpanel
Follow the instructions [here](https://help.mixpanel.com/hc/en-us/articles/115004502806)

### <a name="configuration"></a>Configuration Options
```typescript
export interface MixpanelConnectorConfigOptions {
    token: string
    secret: string
}
```

Example:
```typescript
const { Reshuffle } = require('reshuffle')
const { MixpanelConnector } = require('reshuffle-mixpanel-connector')

const app = new Reshuffle()
const mixpanelConnector = new MixpanelConnector(app, {
    token: '<mixpanel-token>',
    secret: '<mixpanel-secret>',
})
```

### Connector events
N/A

#### <a name="track"></a>Track

For tracking events
```typescript
track(eventName: string, properties?: Record<string, any>): void
```

#### <a name="import"></a>Import

For importing events
```typescript
import(eventName: string, time: Date | number, properties?: Record<string, any>): void
```

#### <a name="sdk"></a>SDK

Returns a Mixpanel client ([See details on npm](https://www.npmjs.com/package/mixpanel))

```typescript
 sdk() : Mixpanel.Mixpanel
```
See Mixpanel.Mixpanel class in [Mixpanel Node type](https://github.com/mixpanel/mixpanel-node/blob/master/lib/mixpanel-node.d.ts#L45)

Example using the sdk:
```typescript
const { Reshuffle } = require('reshuffle')
const { MixpanelConnector } = require('reshuffle-mixpanel-connector')

const app = new Reshuffle()
const mixpanelConnector = new MixpanelConnector(app, {
    token: '<mixpanel-token>',
    secret: '<mixpanel-secret>',
})
mixpanelConnector.sdk().import('action', Date.now())
```


Monday Connector

# reshuffle-monday-connector

[Code](https://github.com/reshufflehq/reshuffle-monday-connector) |
[npm](https://www.npmjs.com/package/reshuffle-monday-connector) |
[Code sample](https://github.com/reshufflehq/reshuffle/tree/master/examples/monday)

`npm install reshuffle-monday-connector`

### Reshuffle Monday Connector

This package contains a [Reshuffle](https://github.com/reshufflehq/reshuffle)
connector for connecting to [Monday](https://monday.com).

A full documentation of Monday's API is available [here](https://monday.com/developers/v2).

### Table of Contents

[Configuration Options](#configuration)

#### Connector Events

[Listening to Monday events](#listen)

#### Connector Actions
[Get Board](#getBoard) - Retrieve a board details object from Monday

[Get Board by name](#getBoardIdByName) - Lookup a board id from its name.

[Get Board Items](#getBoardItems) - Retrieve all items for a specific board.

[Get Group](#getGroup) - Retrieve a group details object from Monday

[Get Item](#getItem) - Retrieve an item details object from Monday

[Create Item](#createItem) - Create a new item in a board

[Update Item](#updateItem) - Update an item's name in a board

[Update Column Values](#updateColumnValues) - Update an item's column values

[Query](#query) - Run a GraphQL query

[SDK](#sdk) - Retrieve a full Monday sdk object


### <a name="configuration"></a>Configuration Options

To work with this connector, you'll need to get a token [from here](https://monday.com/developers/v2#authentication-section) :

1. Log into your monday.com account.
2. Click on your avatar (picture icon) in the bottom left corner.
3. Select Admin from the resulting menu (this requires you to have admin permissions).
4. Go to the API section.
5. Generate a “API v2 Token”
6. Copy your token.

```typescript
interface MondayConnectorConfigOptions {
  token: string
  baseURL?: string
  webhookPath?: string
}
```
The token is the only configuration value required if you just want to send data to Monday. If, however, you need to listen to events happening on your boards (e.g. creation or update of a task) - you'll need to provide the `baseURL` and optionally the `webhookPath` values as well.

**baseURL** is the URL where the running Reshuffle instance can be found (e.g. https://my-reshuffle.com)

**webhookPath** is an optional path to append to `baseURL` to create a full webhook path. 

For example - providing the above `baseURL` and `webhookPath='/mondayhook` will result in a complete webhook path of `https://my-reshuffle.com/mondayhook`.

If you do not provide a `webhookPath`, Reshuffle will use the default webhook path for the connector which is `/webhooks/monday`.

You will need to register this webhook with Monday. See [instructions](https://support.monday.com/hc/en-us/articles/360003540679-Webhook-Integration). 

### Connector events

#### <a name="listen"></a> Listening to Monday events

To listen to events happening in Monday, create an event handler with the
boardId, event type optional column id:

```typescript
interface MondayConnectorEventOptions {
  boardId: string | number
  type:
    | 'IncomingNotification'
    | 'ChangeColumnValue'
    | 'ChangeSpecificColumnValue'
    | 'CreateItem'
    | 'CreateUpdate'
    | 'UpdateName' 
  columnId?: string // for type === ChangeSpecificColumnValue
}
```

Events require that an integration webhook be configured in Monday. The
connector does not configure integrations automatically becuase at the
moment it has no way of tracking which integrations are already configured
in Monday. You can either configure an integration through the Monday UI or
call `createEventWebhook`.

#### Connector actions

#### <a name="getBoard"></a> getBoard

Obtain details of a Monday board (or a list of boards). Use the Monday Board id as the parameter.
_Note: To obtain the board_id, visit your board in the browser and copy the id from the last part of the URL
e.g. if your board's url is https://my-company.monday.com/boards/123456789 - then your board id is 123456789

```typescript
const boardId = '123456789'
const board = await connector.getBoard(boardId)
```

#### <a name="getBoardIdByName"></a> getBoardIdByName

Find a board Id by its name

```typescript
const boardId = await connector.getBoardIdByName('My board')
```

#### <a name="getBoardItems"></a> getBoardItems

Get all the items in a board. The returned object has a `name` field with
the name of the board, and an `items` object, with item data accessible
by item Ids. Data for each item is an object including the item's `name` and
values for each column.

```typescript
const boardItems = await connector.getBoardItems(boardId)
```

#### <a name="getColumn"></a> getColumn

Query a column or a list of columns of a board by the board's Id

```typescript
const column = await connector.getColumn(boardId)
```

##### <a name="getGroup"></a> getGroup

Query a group or a list of groups
_Monday uses groups to group items together inside a board._


```typescript
const group = await connector.getGroup(groupId)
```

#### <a name="getItem"></a> getItem

Query an item or a list of items

```typescript
const item = await connector.getItem(itemId)
```

#### <a name="createItem"></a> createItem

Creates a new item and adds it to the specified board.

| Parameter     | Type   | Required |
| ------------- | ------ | -------- |
| board_id      | Int    | Yes      |
| item_name     | String | Yes      |
| column_values | JSON   | No       |
| group_id      | String | No       |

Example of column_values

```typescript
const column_values = JSON.stringify({
  [column_id]: 'example data',
  [column_id2]: 'another example',
})
```

```typescript
const item = await connector.createItem(boardId, item_name, column_values, groupId)
```

#### <a name="updateItem"></a> updateItem

Update an item's name

```typescript
const item = await connector.updateItem(boardId, groupId, 'Updated Item Name')
```

#### <a name="updateColumnValues"></a> updateColumnValues

Update an specific item in a specific board with new values. The `updaters`
object should include one update function for each column that needs to be
updated, with property names being the titles for these columns. Each
function receives the old value and should return the new value for that
column.

```typescript
await updateColumnValues(myBoardId, myItemId, {
  Name: (name: string) => name.toUpperCase,
  Phone: (phone: string) => phone.startsWith('+') ? phone : `+${phone}`,
})
```

#### createWebhook

Create a webhook. Note - using when you create an `on` handler the event will be created for you if you dont pass a webhookId

```typescript
const webhookId = await connector.createWebhook(
  BOARD_ID,
  'https://example.com/monday-webhook',
  'create_item',
)
```

##### createEventWebhook

Create a webhook for an event. This action requires that the connector be
configured with a `baseURL`.

```typescript
const webhookId = await connector.createEventWebhook(
  BOARD_ID,
  'ChangeColumnValue'
)
```

##### deleteWebhook

Delete a webhook

```typescript
const deletedWebhook = await connector.deleteWebhook(WEBHOOK_ID)
```

#### <a name="query"></a> query

Run any GraphQL query

```typescript
const res = await connector.query('query { users { name } }')
```

#### <a name="sdk"></a> sdk

Returns an object providing full access to the Monday GraphQL API

```typescript
const sdk = await connector.sdk()
```


Movies Anywhere Connector

# reshuffle-moviesanywhere-connector

[Code](https://github.com/reshufflehq/reshuffle-moviesanywhere-connector) |
[npm](https://www.npmjs.com/package/reshuffle-moviesanywhere-connector) |
[Code sample](https://github.com/reshufflehq/reshuffle-moviesanywhere-connector/tree/master/examples)

`npm install reshuffle-moviesanywhere-connector`

### Reshuffle Movies Anywhere Connector

This package contains a [Reshuffle](https://github.com/reshufflehq/reshuffle)
connector to Movies Anywhere, providing access to movie data per the
[Movies Anywhere API](https://api.moviesanywhere.com/v1/title/docs/index.html).

The following actions return title information in the `TitleData` structure,
as defined by the Movies Anywhere API. If the connector is configured with an
API token, the returned data will include trailer information.

The following example creates an API endpoint for retrieving movie data using
its [EIDR](https://eidr.org) ID. You can try
**10.5240/DF48-AB62-4486-C185-9E1B-4** or find EIDR IDs using the
[Reshuffle EIDR Connector](https://github.com/reshufflehq/reshuffle-eidr-connector):

```js
const { Reshuffle, HttpConnector } = require('reshuffle')
const { MoviesAnywhereConnector } = require('reshuffle-moviesanywhere-connector')

const app = new Reshuffle()
const ma = new MoviesAnywhereConnector(app)
const http = new HttpConnector(app)

http.on({ method: 'GET', path: '/' }, async (event) => {
  const eidr = event.req.query.eidr
  if (!/^10\.5240\/([0-9A-F]{4}-){5}[0-9A-Z]$/.test(eidr)) {
    return event.res.status(400).send(`Invalid EIDR ID: ${eidr}`)
  }
  const data = await ma.getTitleByEIDR(eidr)
  return event.res.json(data)
})

app.start(8000)
```

#### Table of Contents

[Configuration](#configuration) Configuration options

_Connector actions_:

[getAllTitles](#getAllTitles) Get all titles data

[getTitleById](#getTitleById) Get title data by Movies Anywhere ID

[getTitleByEIDR](#getTitleByEIDR) Get title data by EIDR ID

[getTitlesByStudio](#getTitleByStudio) Get titles data for a specific studio

[getTransactionsByUser](#getTransactionsByUser) Get transaction history for user

##### <a name="configuration"></a>Configuration options

```js
const app = new Reshuffle()
const moviesAnywhereConnector = new MoviesAnywhereConnector(app)
```

#### Connector actions

##### <a name="getAllTitles"></a>Get all titles action

_Definition:_

```
() => {
  count: number,
  results: TitleData[],
}
```

_Usage:_

```js
const { count, results } = await moviesAnywhereConnector.getAllTitles()
```

Retrieve all title information stored by Movies Anywhere.

##### <a name="getTitleById"></a>Get title by ID action

_Definition:_

```
(
 id: string
) => TitleData
```

_Usage:_

```js
const id = '7c1d0438-a71d-40a7-8567-6a4f714355cd'
const titleData = await moviesAnywhereConnector.getTitleById(id)
```

Get the title information associated with a given Movies Anywhere ID.

##### <a name="getTitleByEIDR"></a>Get title by EIDR action

_Definition:_

```
(
 eidr: string
) => TitleData
```

_Usage:_

```js
const eidr = '10.5240/CEFE-FECA-CBD0-F72A-E650-H'
const titleData = await moviesAnywhereConnector.getTitleByEIDR(eidr)
```

Get the title information associated with a given EIDR ID, as specified by
the [EIDR API](http://eidr.org/documents/EIDR_2.1_REST_API.pdf).

##### <a name="getTitlesByStudio"></a>Get titles by studio action

_Definition:_

```
(
 studio: 'Disney' | 'Fox' | 'Lionsgate' | 'Sony' | 'Universal' | 'WB'
) => {
  count: number,
  results: TitleData[],
}
```

_Usage:_

```js
const studio = 'Universal'
const { count, results } =
  await moviesAnywhereConnector.getTitlesByStudio(studio)
```

Retrieve all title information for movies released by the specified studio.

##### <a name="getTransactionsByUser"></a>Get transactions by user action

_Definition:_

```ts
(userId: string) => tranasactions: Object[]
```

_Usage:_

```js
const transactions =
  await moviesAnywhereConnector.getTransactionsByUser('myid')
```

Retrieve the transaction (purchase) history for the specified user. The
specified `userId` must be pre-registered with Movies Anywhere.


MySQL Connector

# reshuffle-mysql-connector

[Code](https://github.com/reshufflehq/reshuffle-mysql-connector) |
[npm](https://www.npmjs.com/package/reshuffle-mysql-connector) |
[Code sample](https://github.com/reshufflehq/reshuffle-mysql-connector/tree/master/examples)

`npm install reshuffle-mysql-connector`

### Reshuffle MySQL Connector

This package contains a [Reshuffle](https://github.com/reshufflehq/reshuffle)
connector to MySQL databases.

The connector uses [Node MySQL 2 Client](https://www.npmjs.com/package/mysql2) package.

The following example lists all information from the "users" table:

```js
const { Reshuffle } = require('reshuffle')
const { MySQLConnector } = require('reshuffle-mysql-connector')

  const app = new Reshuffle()
  const mysql = new MySQLConnector(app, {
    host: process.env.DB_HOST,
    user: process.env.DB_USERNAME,
    password: process.env.DB_PASSWORD,
    database: process.env.DB_NAME
  })

  const result = await mysql.query("SELECT * FROM Users where firstName = 'John'")
  console.log('rows: ',result.rows)
  console.log('fields: ',result.fields)

```

#### Table of Contents

[Configuration](#configuration) Configuration options

_Connector actions_:

[close](#close) Close all active connections

[query](#query) Run a single query on the database

[sequence](#sequence) Run a series of queries on the databse

[transaction](#transaction) Run a transaction on the databae

[sdk](#sdk) Retrieve the client sdk object with support of Promise API

##### <a name="configuration"></a>Configuration options

```js

const app = new Reshuffle();
const mysql = new MySQLConnector(app, {
  host: process.env.DB_HOST,
  user: process.env.DB_USERNAME,
  password: process.env.DB_PASSWORD,
  database: process.env.DB_NAME 
})
```

For more information about connection attributes check the [mysql2](https://www.npmjs.com/package/mysql2) and [Node.js mysql Connection Options](https://github.com/mysqljs/mysql#connection-options) documentation.


#### Connector actions

##### <a name="close"></a>Close action

```js
await mysql.close()
```

Close all connections to the database. If an application terminates without
calling close, it might hang for a few seconds until active connections
time out.

##### <a name="query"></a>Query action


```js
await mysql.query("INSERT INTO users VALUES ('John', 'Coltrane', 42)")

const family = await mysql.query(
  "SELECT firstName, lastName, age FROM users WHERE lastName='Coltrane'"
)

const avgResponse = await mysql.query(
  "SELECT average(age) AS avg FROM users WHERE lastName='Coltrane'"
)
const averageAge = avgResponse.rows[0].avg

```

The `query` action can be used to run _any_ SQL command on the connected
database (not just `SELECT`). The query is defined in the `sql` string. The
optional `params` can be used to generate parameterized queries, as shown in
the following example:

```js
const age = await mysql.query(
  "SELECT age FROM users WHERE firstName = ? and lastName = ?",
  ['John', 'Smith']
)
```

This action returns an object with the results of the query, where
`fields` is an array of all field names, as returned by the query.
Field names in a `SELECT` query are column names, or are specified
with an `AS` clause. Every element of `rows` uses the names in
`fields` as its object keys.

Note that every call to `query` may use a different database connection.
You can use the [sequence](#sequence) or [transaction](#transaction) actions
if such a guarantee is required.

##### <a name="sequence"></a>Sequence action


```js
const res = await mysql.sequence(async (query) => {
  await query("INSERT INTO users VALUES ('Miles', 'Davis', 43)")
  return query("SELECT COUNT(*) FROM users")
})
const userCount = res.rows[0].count

```

Use `sequence` to perform multiple queries on the same database connection.
This action receives a `seq` function that may issue queries to the database,
all of which are guaranteed to run through the same connection. `seq` gets
one argument, which is a `query` function that can be used the same way as
the [query](#query) action. `seq` may, of course, use any JavaScript code to
implement its logic, log to the console etc.

Note that while `sequence` uses the same connection to run all queries, it
does not offer the transactional guarantees offered by
[transaction](#transaction). You can use it for weak isolation models, or
construct transactions directly without using `transaction`.

##### <a name="transaction"></a>Transaction action


```js
await mysql.transaction(async (query) => {
  const res = await query("SELECT COUNT(*) FROM users")
  const userCount = res.rows[0].count
  if (100 <= userCount) {
    throw new Error('Too many users:', userCount)
  }
  return query("INSERT INTO users VALUES ('Charlie', 'Parker', 49)")
})
```

Use `transaction` to run multiple queries as an atomic SQL transaction.
The interface is identical to the [sequence action](#sequence), but all
the queries issued `seq` either success or fail together. If any of the
queries fail, all queries are rolled back and an error is thrown.

Consider, for example, the following code for updating a bank account
balance:

```js
  const accountId = 289
  const change = 1000
  mysql.transaction(async (query) => {
    await query(`
      UPDATE accounts
        SET balance = balance + ?
        WHERE account_id = ?
      `,
      [change, accountId],
    )
    await query(`
      INSERT INTO accounts_log(account_id, change, time)
        VALUES (?, ?, current_timestamp)
      `,
      [change, accountId],
    )
  })
```

##### <a name="sdk"></a>Full access to the MySQL Client SDK with support of Promise API


```js
const sdk = mysql.sdk()

const connection = await mysql.sdk().createConnection({
  host: process.env.DB_HOST,
  user: process.env.DB_USERNAME,
  password: process.env.DB_PASSWORD,
  database: process.env.DB_NAME 
})

const [rows, fields] = await connection.execute('SELECT * FROM Users')
console.log('rows: ',rows)
console.log('fields: ',fields)


```


More details and code samples about Node MySQL 2 Promise API can be found [here](https://www.npmjs.com/package/mysql2#using-promise-wrapper)

NLP Connector

### Reshuffle NLP Connector

[Code](https://github.com/reshufflehq/reshuffle-nlp-connector) |  [npm](https://www.npmjs.com/package/reshuffle-nlp-connector)

`npm install reshuffle-nlp-connector`

This is a [Reshuffle](https://github.com/reshufflehq/reshuffle) connector that provides language detection and sentiment analysis.
 

#### Connector events
N/A

#### Connector actions

##### sentiment

Detect the sentiment of some text

```typescript
async sentiment(text = ''): Promise<{ score: number; vote: string; emoji: string }>
```

###### Example
```js
const text = 'The text I want analyzed'
const connector = new NlpConnector()
const result = await connector.sentiment(text)
console.log('Score: ', result.score, ' Vote: ', result.vote, ' Emoji: ', result.emoji)
```

##### language

Detect the language of some text

```typescript
language(text = ''): { name?: string; code?: string }
```

###### Example
```js
const text = 'The text I want analyzed'
const connector = new NlpConnector()
const result = connector.language(text)
console.log('Name: ', result.name, ' Code: ', result.code)
```



PostgreSQL Connector

# reshuffle-pgsql-connector

[Code](https://github.com/reshufflehq/reshuffle-pgsql-connector) |
[npm](https://www.npmjs.com/package/reshuffle-pgsql-connector) |
[Code sample](https://github.com/reshufflehq/reshuffle-pgsql-connector/tree/master/examples)

`npm install reshuffle-pgsql-connector`

### Reshuffle Postgres SQL Connector

This package contains a [Reshuffle](https://github.com/reshufflehq/reshuffle)
connector to Postgres SQL databases.

The following example lists all information from the "users" table:

```js
const { Reshuffle } = require('reshuffle')
const { PgsqlConnector } = require('reshuffle-pgsql-connector')

;(async () => {
  const app = new Reshuffle()
  const pg = new PgsqlConnector(app, { url: process.env.POSTGRES_URL })

  const res = await pg.query(`SELECT * FROM users`)
  console.log(res)

  await pg.close()
})().catch(console.error)
```

#### Table of Contents

[Configuration](#configuration) Configuration options

_Connector actions_:

[close](#close) Close all active connections

[query](#query) Run a single query on the database

[sequence](#sequence) Run a series of queries on the databse

[transaction](#transaction) Run a transaction on the databae

##### <a name="configuration"></a>Configuration options

```js
const app = new Reshuffle();
const pg = new PgsqlConnector(app, {
  url: "postgres://user[:password]@hostname[:port]/database",
  //Only include ssl option when connecting to a database protected by ssl
  ssl: {
    rejectUnauthorized: false,
    // Configure any of the relevant options below to your own ssl details
    ca: fs.readFileSync("/path/to/server-certificates/root.crt").toString(),
    key: fs.readFileSync("/path/to/client-key/postgresql.key").toString(),
    cert: fs
      .readFileSync("/path/to/client-certificates/postgresql.crt")
      .toString(),
  },
});
```

If connecting to a local database, `ssl` option is not needed and can be left blank.

For more information check the [ssl](https://node-postgres.com/features/ssl) and [TLSSocket](https://nodejs.org/api/tls.html#tls_tls_createsecurecontext_options) documentation.

#### Connector actions

##### <a name="close"></a>Close action

_Definition:_

```ts
() => void
```

_Usage:_

```js
await pg.close()
```

Close all connections to the database. If an application terminates without
calling close, it might hang for a few seconds until active connections
time out.

##### <a name="query"></a>Query action

_Definition:_

```ts
(
  sql: string,
  params?: any[],
) => {
  fields: { name: string }[],
  rows: any[],
  rowCount: number,
}
```

_Usage:_

```js
await pg.query("INSERT INTO users VALUES ('John', 'Coltrane', 42)")

const family = await pg.query(
  "SELECT firstName, lastName, age FROM users WHERE lastName='Coltrane'"
)
// {
//   rowCount: 2,
//   fields: [{ name: 'firstName' }, { name: 'lastName' }, { name: 'age' }],
//   rows: [
//     { firstName: 'Alice', lastName: 'Coltrane', age: 31 },
//     { firstName: 'John', lastName: 'Coltrane', age: 42 },
//   ],
// }

const avgResponse = await pg.query(
  "SELECT average(age) AS avg FROM users WHERE lastName='Coltrane'"
)
const averageAge = avgResponse.rows[0].avg
// 36.5
```

The `query` action can be used to run _any_ SQL command on the connected
database (not just `SELECT`). The query is defined in the `sql` string. The
optional `params` can be used to generate parameterized queries, as shown in
the following example:

```js
const age = await pg.query(
  "SELECT age FROM users WHERE firstName=$1 and lastName=$2",
  ['John', 'Smith']
)
```

This action returns an object with the results of the query, where
`fields` is an array of all field names, as returned by the query.
Field names in a `SELECT` query are column names, or are specified
with an `AS` clause.  Every element of `rows` is uses the names in
`fields` as its object keys.

Note that every call to `query` may use a different database connection.
You can use the [sequence](#sequence) or [transaction](#transaction) actions
if such a guarantee is required.

##### <a name="sequence"></a>Sequence action

_Definition:_
```js
(
  seq: (query) => any,
) => any
```

_Usage:_

```js
const res = await pg.sequence(async (query) => {
  await query("INSERT INTO users VALUES ('Miles', 'Davis', 43)")
  return query("SELECT COUNT(*) FROM users")
})
const userCount = res.rows[0].count
// 3
```

Use `sequence` to perform multiple queries on the same database connection.
This action receives a `seq` function that may issue queries to the database,
all of which are guaranteed to run through the same connection. `seq` gets
one argument, which is a `query` function that can be used the same way as
the [query](#query) action. `seq` may, of course, use any JavaScript code to
implement its logic, log to the console etc.

Note that while `sequence` uses the same connection to run all queries, it
does not offer the transactional guarantees offered by
[transaction](#transaction). You can use it for weak isolation models, or
construct transactions directly without using `transaction`.

##### <a name="transaction"></a>Transaction action

_Definition:_
```js
(
  seq: (query) => any,
) => any
```

_Usage:_

```js
await pg.transaction(async (query) => {
  const res = await query("SELECT COUNT(*) FROM users")
  const userCount = res.rows[0].count
  if (100 <= userCount) {
    throw new Error('Too many users:', userCount)
  }
  return query("INSERT INTO users VALUES ('Charlie', 'Parker', 49)")
})
```

Use `transaction` to run multiple queries as an atomic SQL transaction.
The interface is identical to the [sequence action](#sequence), but all
the queries issued `seq` either success or fail together. If any of the
queries fail, all queries are rolled back and an error is thrown.

Consider, for example, the following code for updating a bank account
balance:

```js
const accountId = 289
const change = +1000
pg.transaction(async (query) => {
  await query(`
    UPDATE accounts
      SET balance = balance + $1
      WHERE account_id = $2
    `,
    [change, accountId],
  )
  await query(`
    INSERT INTO accounts_log(account_id, change, time)
      VALUES ($1, $2, current_timestamp)
    `,
    [change, accountId],
  )
})
```

In the example above, `accounts` holds current balances of accounts,
while `accounts_log` holds a history of all changes made. Using `transaction`
ensures that both tables are always updated together.


Quickbooks Connector

# reshuffle-quickbooks-connector

[Code](https://github.com/reshufflehq/reshuffle-quickbooks-connector) |
[npm](https://www.npmjs.com/package/reshuffle-quickbooks-connector) |
[Code sample](https://github.com/reshufflehq/reshuffle/tree/master/examples/quickbooks)

`npm install reshuffle-quickbooks-connector`

### Reshuffle Quickbooks Connector

This package contains a [Reshuffle](https://github.com/reshufflehq/reshuffle)
connector to connect [QuickBooks Online app APIs](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/most-commonly-used/account).
This connector requires to define a [Reshuffle Datastore](https://reshuffle.com/docs/persistency) in order to maintain the Quickbooks access and refresh tokens, the Datastore can be in memory, file or Database. The connector takes care of refreshing the access token.

The following example exposes an endpoint to return the data of Bill after an Update action, the access and refresh tokens are stored in reshuffle DB and will be managed internally by the Reshuffle engine.

```js
const { Reshuffle, SQLStoreAdapter } = require('reshuffle')
const { QuickbooksConnector } = require('reshuffle-quickbooks-connector')

const app = new Reshuffle()

const pool = new Pool({user: 'RESHUFFLE_DB_USER',
  host: 'RESHUFFLE_DB_HOST',
  database: 'RESHUFFLE_DB',
  password: 'RESHUFFLE_DB_PASS',
  port: RESHUFFLE_DB_PORT})
  const persistentStore = new SQLStoreAdapter(pool, 'reshuffledb')
  app.setPersistentStore(persistentStore)

const quickbooksConnector = new QuickbooksConnector(app, {
  realmId: 'REALM_ID',
  consumerKey: 'CONSUMER_KEY',
  consumerSecret: 'CONSUMER_SECRET',
  sandbox: true,
  debug: true,
  baseUrl: 'BASE_RUNTIME_URL',
  webhooksVerifier: 'WEBHOOK_VERIFIER'
})

quickbooksConnector.on({ type: 'Bill/Update' }, async (event, app) => {
  console.log('Bill/Update event ')
  console.log(event.id)
  console.log(event.name)
  console.log(event.operation)
})

app.start()
```

### Table of Contents

[Configuration Options](#configuration)

#### Connector Events

[Listening to Quickbooks events](#listen)

#### Connector Actions

[SDK](#sdk) - Retrieve a full Quickbooks sdk object


### <a name="configuration"></a> Configuration options

```js
const app = new Reshuffle()
const quickbooksConnector = new QuickbooksConnector(app, {
  realmId: 'YOUR_REALM_ID',
  consumerKey: 'CONSUMER_KEY',
  consumerSecret: 'CONSUMER_SECRET',
  sandbox: false, // Working environment, Sandbox or Production. Default false. Can be set in process.env.NODE_ENV
  debug: false, // Default false
  callback: 'CALLBACK_PATH', // Default '/callbacks/quickbooks', The path component of one of the redirect URIs listed for this project in the Quickbooks developer dashboard.
  webhookPath: 'WEBHOOK_PATH', // Default '/webhooks/quickbooks', The path component of the Webhook Endpoint URI for this project in the developer dashboard
  baseUrl: 'BASE_RUNTIME_URL',
  webhooksVerifier: 'WEBHOOK_VERIFIER' // Webhook Verifier Token for this project in the developer dashboard
})
```

`sandbox`, `debug`, `callback` and `webhookPath` are optional.

More details about the fields are described in [node-quickbooks](https://www.npmjs.com/package/node-quickbooks)

You can use the `webhookPath` to configure the url that Quickbooks hits when it makes its calls to.
For example - providing `baseURL=https://my-reshuffle.com` and `webhookPath='/webhook` will result in a complete webhook path of `https://my-reshuffle.com/webhook`.
If you do not provide a `webhookPath`, Reshuffle will use the default webhook path for the connector which is `/webhooks/quickbooks`.
You will need to register this webhook with Quickbooks. See [instructions](https://developer.intuit.com/app/developer/qbo/docs/develop/webhooks).

You can use the `callback` to configure the redirect URI that your app serves to users upon authentication.
For example - providing `baseURL=https://my-reshuffle.com` and `callback='/callback` will result in a complete webhook path of `https://my-reshuffle.com/callback`.
If you do not provide a `callback`, Reshuffle will use the default callback path for the connector which is `/callbacks/quickbooks`.
You will need to register this callback with Quickbooks. See more details about [authentication](https://developer.intuit.com/app/developer/qbo/docs/develop/authentication-and-authorization/oauth-2.0).

### <a name="events"></a> Events

#### <a name="listen"></a> Listening to Quickbooks events

To listen to events happening in Quickbooks, you'll need to capture them with the connector's `on`
function, providing a `QuickbooksConnectorEventOptions` to it.


```typescript
interface QuickbooksConnectorEventOptions {
  type: QBEventType // See bellow 
}

// Where...
type QBEventType =
  | 'Account/Delete'
  | 'Account/Merge'
  | 'Account/Create'
  | 'Account/Update'
  | 'Bill/Delete'
  | 'Bill/Create'
  | 'Bill/Update'
  | 'BillPayment/Delete'
  | 'BillPayment/Void'
  | 'BillPayment/Create'
  | 'BillPayment/Update'
  | 'Budget/Create'
  | 'Budget/Update'
  | 'Class/Delete'
  | 'Class/Merge'
  | 'Class/Create'
  | 'Class/Update'
  | 'CreditMemo/Delete'
  | 'CreditMemo/Emailed'
  | 'CreditMemo/Void'
  | 'CreditMemo/Create'
  | 'CreditMemo/Update'
  | 'Currency/Create'
  | 'Currency/Update'
  | 'Customer/Delete'
  | 'Customer/Merge'
  | 'Customer/Create'
  | 'Customer/Update'
  | 'Department/Merge'
  | 'Department/Create'
  | 'Department/Update'
  | 'Deposit/Delete'
  | 'Deposit/Create'
  | 'Deposit/Update'
  | 'Employee/Delete'
  | 'Employee/Merge'
  | 'Employee/Create'
  | 'Employee/Update'
  | 'Estimate/Delete'
  | 'Estimate/Emailed'
  | 'Estimate/Create'
  | 'Estimate/Update'
  | 'Invoice/Delete'
  | 'Invoice/Emailed'
  | 'Invoice/Void'
  | 'Invoice/Create'
  | 'Invoice/Update'
  | 'Item/Delete'
  | 'Item/Merge'
  | 'Item/Create'
  | 'Item/Update'
  | 'JournalCode/Create'
  | 'JournalCode/Update'
  | 'JournalEntry/Delete'
  | 'JournalEntry/Create'
  | 'JournalEntry/Update'
  | 'Payment/Delete'
  | 'Payment/Emailed'
  | 'Payment/Void'
  | 'Payment/Create'
  | 'Payment/Update'
  | 'PaymentMethod/Merge'
  | 'PaymentMethod/Create'
  | 'PaymentMethod/Update'
  | 'Preferences/Update'
  | 'Purchase/Delete'
  | 'Purchase/Void'
  | 'Purchase/Create'
  | 'Purchase/Update'
  | 'PurchaseOrder/Delete'
  | 'PurchaseOrder/Emailed'
  | 'PurchaseOrder/Create'
  | 'PurchaseOrder/Update'
  | 'RefundReceipt/Delete'
  | 'RefundReceipt/Emailed'
  | 'RefundReceipt/Void'
  | 'RefundReceipt/Create'
  | 'RefundReceipt/Update'
  | 'SalesReceipt/Delete'
  | 'SalesReceipt/Emailed'
  | 'SalesReceipt/Void'
  | 'SalesReceipt/Create'
  | 'SalesReceipt/Update'
  | 'TaxAgency/Create'
  | 'TaxAgency/Update'
  | 'Term/Create'
  | 'Term/Update'
  | 'TimeActivity/Delete'
  | 'TimeActivity/Create'
  | 'TimeActivity/Update'
  | 'Transfer/Delete'
  | 'Transfer/Void'
  | 'Transfer/Create'
  | 'Transfer/Update'
  | 'Vendor/Delete'
  | 'Vendor/Merge'
  | 'Vendor/Create'
  | 'Vendor/Update'
  | 'VendorCredit/Delete'
  | 'VendorCredit/Create'
  | 'VendorCredit/Update'
```

Events require that an integration webhook is configured in Quickbooks. 

The connector triggers events of the following type:

```typescript
interface QBEvent {
  realmId: string
  name: string // Entity type name e.g. Customer, Account, Bill
  id: string   // Entity ID
  operation: string 
  lastUpdated: string
  action: string
}
```

_Example:_

```typescript
quickbooksConnector.on({ type: 'Bill/Update' }, async (event, app) => {
  console.log('Bill/Update event ')
  console.log(event.id)
  console.log(event.name)
  console.log(event.operation)
})
```

The description of fields and events can be found [here](hhttps://developer.intuit.com/app/developer/qbo/docs/develop/webhooks/entities-and-operations-supported)

### <a name="actions"></a> Actions

The actions are provided via the [sdk](#sdk).

#### <a name="sdk"></a> sdk

Returns an object providing full access to the Quickbooks APIs.
Full list of available actions in [node-quickbooks](https://www.npmjs.com/package/node-quickbooks)

```typescript
const sdk = await connector.sdk()
```

_Example:_

```typescript
const sdk = await quickbooksConnector.sdk()
sdk.getCompanyInfo('YOUR_REALM_ID', function(err, result) {
  console.log('Result: ', JSON.stringify(result))
}
```


Redis Connector

# reshuffle-redis-connector

[Code](https://github.com/reshufflehq/reshuffle-redis-connector) |
[npm](https://www.npmjs.com/package/reshuffle-redis-connector) |
[Code sample](https://github.com/reshufflehq/reshuffle-redis-connector/tree/master/examples)

`npm install reshuffle-redis-connector`

### Reshuffle Redis Connector

This package contains a [Reshuffle](https://github.com/reshufflehq/reshuffle)
connector to Redis databases.

The following example sets and gets a value from Redis:

```js
const { Reshuffle } = require('reshuffle')
const { RedisConnector } = require('reshuffle-redis-connector')

const app = new Reshuffle()

const redis = new RedisConnector(app, {
  endpoint: process.env.REDIS_ENDPOINT,
  password: process.env.REDIS_PASSWORD,
})

async function main() {
  try {
    await redis.set('key', 'value')
    console.log(await redis.get('key')) // 'value'
  } catch (error) {
    console.error(error)
  }   
}

app.start()
main()
```

### Table of Contents

[Configuration Options](#configuration)

#### Connector actions

[sequence](#sequence) Run a sequence of queries

[transaction](#transaction) Run a sequence of queries inside a transaction

[sdk](#sdk) Returns the Node Redis Client that allows direct calls to the underlying redis

[close](#close) Close redis connections

### <a name="configuration"></a> Configuration options

```js
const app = new Reshuffle()
const redis = new RedisConnector(app, {
  endpoint: process.env.REDIS_ENDPOINT, // <hostname>:<port>
  password: process.env.REDIS_PASSWORD,
})
```

### Connector actions

#### <a name="sequence"></a> Sequence action

_Definition:_
```js
(
  seq: (query) => any,
) => any
```

_Usage:_

```js
const res = await res.sequence(async (conn) => {
  const val = conn.get('key')
  conn.set('key', val + 1)
})
```

Use `sequence` to perform multiple queries on the same database connection.
This assures sequential access, but not atomicity in case other connections
are open to the database.

##### <a name="transaction"></a> Transaction action

_Definition:_
```js
(
  seq: (query) => any,
) => any
```

_Usage:_

```js
await redis.transaction(async (multi) => {
  const val = multi.get('key')
  multi.set('key', val + 1)
})
```

Use `transaction` to execute multiple queries as an atomic sequence using a
[Redis transaction](https://redis.io/topics/transactions) and the MULTI
command. 

All operations either succeed or fail together.

#### <a name="sdk"></a> SDK action

The `sdk()` action provides raw access to the async version of [npm redis](https://www.npmjs.com/package/redis). The following actions are provided
as convenience wrappers for its corresponding async methods. 

For instance, calling `redis.sdk().append()` is equivalent to `redis.append()`. You can
access the methods not listed below using the `redis.sdk().` notation.

```ts
async function append(key: string, value: any)
async function decr(key: string)
async function decrby(key: string, decrement: number)
async function del(key: string)
async function exists(key: string)
async function get(key: string)
async function getset(key: string, value: string)
async function hdel(key: string, field: string)
async function hexists(key: string, field: string)
async function hget(key: string, field: string)
async function hgetall(key: string)
async function hincrby(key: string, field: string, increment: number)
async function hincrbyfloat(key: string, field: string, increment: number)
async function hkeys(key: string)
async function hlen(key: string)
async function hmget(key: string, fields: string[])
async function hmset(key: string, dict: Record<string, any>)
async function hset(key: string, field: string, value: any)
async function hsetnx(key: string, field: string, value: any)
async function hstrlen(key: string, field: string)
async function hvals(key: string)
async function incr(key: string)
async function incrby(key: string, increment: number)
async function incrbyfloat(key: string, increment: number)
async function mget(keys: string[])
async function mset(dict: Record<string, any>)
async function set(key: string, value: any)
async function setnx(key: string, value: any)
async function keys(pattern: string): Promise<string[]>
```

#### <a name="close"></a> Close action

_Definition:_

```ts
() => void
```

_Usage:_

```js
await redis.close()
```

Close all connections to redis. If an application terminates without
calling close, it might hang for a few seconds until all active connections
time out.


SMTP Connector

# reshuffle-smtp-connector

[Code](https://github.com/reshufflehq/reshuffle-smtp-connector) |  [npm](https://www.npmjs.com/package/reshuffle-smtp-connector)

`npm install reshuffle-smtp-connector`

### Reshuffle SMTP Connector


*NPM Package:*  [reshuffle-smtp-connector](https://www.npmjs.com/package/reshuffle-smtp-connector)

This package is a [Reshuffle](http://dev.reshuffle.com) connector that allows a developer to configure a transport that sends emails via SMTP.

The following code creates an HTTP endpoint at `/ping`. Sending a `GET` request to this endpoint with the following pattern, 
sends an email to the address in the `to` query parameter.

```js
const { HttpConnector, Reshuffle } = require('reshuffle')
const { SMTPConnector } = require('reshuffle-smtp-connector')

const app = new Reshuffle()
const httpConnector = new HttpConnector(app)
const smtpConnector = new SMTPConnector(
  app,
  {
    username: 'superman',
    password: 'hunter123',
    host: 'email.some.com',
    port: 587,
    fromName: 'Spiderman III',
    fromEmail: 'admin@superheros.com',
  },
  'connectors/smtp',
)

httpConnector.on(
  {
    method: 'GET',
    path: '/ping',
  },
  (event, app) => {
    app.getConnector('connectors/smtp').send({
      to: event.req.query.to,
      subject: 'Ping Email',
      html: 'You have been pinged',
    })
  },
)

app.start()
```

Hitting `/ping?to=doc@exmaple.com` will send a ping email to `doc@example.com`


#### Configuration Options:
```typescript
interface SMTPConnectorOptions {
  fromName: string // The sender name to appear on outgoing emails
  fromEmail: string // The sender email address to appear on outgoing emails
  host: string // SMTP host
  port: number // Port number for the host. Normally 587
  username: string // Username to login to the SMTP host
  password?: string // Password to login to the SMTP host
}
```

#### Connector actions
The SMTP connector provides the following actions:

##### send
send an email message defined by the message parameter.
SMTPConnector.send(message: EmailMessage)
The EmailMessage type expects the following:

```typescript
interface EmailMessage {
  to: string // Recipient email address
  subject: string // Message subject
  html: string // message content
  attachments?: Attachment[]
}
```

Example on how to use this connector can be [found here](https://github.com/reshufflehq/reshuffle/tree/master/examples/email).

Salesforce Connector

# reshuffle-salesforce-connector

[Code](https://github.com/reshufflehq/reshuffle-salesforce-connector) |
[npm](https://www.npmjs.com/package/reshuffle-salesforce-connector) |
[Code sample](https://github.com/reshufflehq/reshuffle-salesforce-connector/tree/master/examples)

`npm install reshuffle-salesforce-connector`

### Reshuffle Salesforce Connector

This package contains a [Reshuffle](https://github.com/reshufflehq/reshuffle)
connector to [Salesforce](https://www.salesforce.com/).

The following example tracks changes to account names:

```js
const { Reshuffle } = require('reshuffle')
const { SalesforceConnector } = require('reshuffle-salesforce-connector')

;(async () => {
  const app = new Reshuffle()
  const sf = new SalesforceConnector(app, {
    clientId: process.env.SALESFORCE_CLIENT_ID,
    clientSecret: process.env.SALESFORCE_CLIENT_SECRET,
    baseURL: process.env.RESHUFFLE_RUNTIME_BASE_URL,
    encryptionKey: process.env.RESHUFFLE_ENCRYPTION_KEY,
  })

  app.start(8000)  // Listen to HTTP for authentication

  console.log('Authenticate with Salesforce')
  await sf.authenticate()
  console.log('Authenticated')

  sf.on({ query: 'SELECT Id,Name FROM Account' }, async (event, app) => {
    console.log(event)
  })

  console.log('Edit an account name to trigger an event...')

})().catch(console.error)
```

#### Table of Contents

[Configuration](#configuration) Configuration options

_Connector events_:

[query](#query) Query result changed

_Connector actions_:

[authenticate](#authenticate) Authenticate against Salsforce

[isAuthenticated](#isAuthenticated) Is authenticated with Salsforce

[query](#query) Query Salesforce data

[map](#map) Process a collection of Salesforce objects

[sobject](#sobject) Access a Salesforce object type

_SDK_:

[sdk](#sdk) Get direct JSForce SDK access

##### <a name="configuration"></a>Configuration options

The first step to access Salesforce is to create a new Connected App. You can
do this by accessing the settings on your Salesforce platform. See
[this guide](https://help.salesforce.com/articleView?id=connected_app_create.htm)
for details.

The app should have OAuth access enabled with the following scopes:
* Full access (full)
* Perform requests on your behalf at any time (refresh_token, offline_access)

You can limit the app to only support certain operations, by replacing "Full
access" with more specific scopes.

Once the app is created, copy the clientId (Consumer Key) and clientSecret
(Consumer Secret). We recommend configuring them in the environment variables
like so:

```js
const app = new Reshuffle()
const salesforceConnector = new SalesforceConnector(app, {
  clientId: process.env.SALESFORCE_CLIENT_ID,
  clientSecret: process.env.SALESFORCE_CLIENT_SECRET,
  baseURL: process.env.RESHUFFLE_RUNTIME_BASE_URL,
  encryptionKey: process.env.RESHUFFLE_ENCRYPTION_KEY,
})
```

The configuration also uses `RESHUFFLE_RUNTIME_BASE_URL` to point to the base
URL of the server hosting the Reshuffle runtime, and `RESHUFFLE_ENCRYPTION_KEY`
which is a 64 digit hex string (32 bytes) which is used to encrypt the access
tokens received from Salesforce during the authentication process.

During the authentication process, Salesforce sends back credentials including
an access token, a refresh token and an instance URL. If you already have
these access credentials, you can skip the authentication flow and pass them
when initializing the connector like so:

```js
const salesforceConnector = new SalesforceConnector(app, {
  clientId: process.env.SALESFORCE_CLIENT_ID,
  clientSecret: process.env.SALESFORCE_CLIENT_SECRET,
  baseURL: process.env.RESHUFFLE_RUNTIME_BASE_URL,
  encryptionKey: process.env.RESHUFFLE_ENCRYPTION_KEY,
  accessToken: process.env.SALESFORCE_ACCESS_TOKEN, /* credentials */
  refreshToken: process.env.SALESFORCE_REFRESH_TOKEN, /* credentials */
  instanceUrl: process.env.SALESFORCE_INSTANCE_URL, /* credentials */
})
```

#### Connector events

##### <a name="query"></a>Query event

_Example:_

```js
async (event, app) => {
  console.log('Salesforce event:', event)
})
```

This event is fired when the result of a query changes. This could be when
a new object is added, and existing object removed, or one of the queried
fields changes.

For example, the following event will trigger when a new Account object is
created, when an Account object is removed or when an account name changes:

```js
salesforceConnector.on(
  { query: 'SELECT Id,Name FROM Account' },
  async (event, app) => {
    console.log(event)
  },
)
```

Note that the event will not trigger if other fields, like the account owner,
are changed. You can exapnd the query to SELECT other fields as well. In this
case these fields will also trigger the event and will be returned in the
event object.

#### Connector actions

##### <a name="authenticate"></a>Authenticate action

_Definition:_

```ts
() => void
```

_Usage:_

```js
await salesforceConnector.authenticate()
```

Authenticate against the Salesforce API. This action return immediately if
a connection is already authenticated or if it finds valid access tokens
in the datastore and is able to connect with Salesforce.

If it does not have valid access token, the action attempts to open a browser
to allow the user to authenticate through a standard OAuth flow.

Note that in order to complete the OAuth flow, Reshuffle must be accessible
from the Internet, with its base URL provided to the connector config
(typically through the RESHUFFLE_RUNTIME_BASE_URL environment variable). If
Reshuffle is running on your dev machine, we recommend using
[ngrok](https://ngrok.com) to expose a local port to the world (see example
in the scripts section of package.json).

When Reshuffle is running on a server, you can use the `authenticator` utility
provided with this connector to start the authentication process from your
(or your user's) machine.

This action throws an error if the connector already has Salesforce access
credentials. This can happen if credentials were passed upon initialization,
read from persistent store or if the action is called more than once.

##### <a name="isAuthenticated"></a>Is Authenticated action

_Definition:_

```ts
() => boolean
```

_Usage:_

```js
const isAuthenticated = salesforceConnector.isAuthenticated()
```

Checks whether the connector is authenticated with Salesforce. Auth
credentials (access token, refresh token and instance URL) may be passed upon
connector initialization, read from data store or obtained from Salesforce
through the OAuth flow (see [authenticate](#authenticate) above).

##### <a name="query"></a>Query action

_Definition:_

```ts
(
  query: string,
) => object
```

_Usage:_

```js
const res = await salesforceConnector.query('SELECT Id, Name FROM Account')
console.log('Salesforce accounts:')
for (const account of res.records) {
  console.log(' ', account.Id, account.Name)
}
```

Query Salesforce for data.

##### <a name="map"></a>Map action

_Definition:_

```ts
(
  type: string,
  func: object => void,
) => object
```

_Usage:_

```js
const res = await salesforceConnector.map('Account', async (account) => {
  if (account.Name.startsWith('A')) {
    console.log(account)
  }
})
```

Apply a JavaScript function to process a collection of Salesforce objects
of the specified type.

##### <a name="sobject"></a>Sobject action

_Definition:_

```ts
(
  type: string,
) => object
```

_Usage:_

```js
const account = await salesforceConnector.sobject('Account')
const res = account.find({ Name: 'Acme' }, '*')
})
```

Get an accessor to a Salesforce object type. The accessor provides methods for
finding objects of this type and provide CRUD operations on this type of
object.

#### SDK

##### <a name="sdk"></a>SDK action

_Definition:_

```ts
() => object
```

_Usage:_

```js
const conn = await salesforceConnector.sdk()
```

The connector uses [JSForce](https://jsforce.github.io/) to connect with
Salesforce. This action returns the underlying JSForce connection so you can
directly access its [methods](https://jsforce.github.io/document).


Shopify Connector

# reshuffle-shopify-connector

[Code](https://github.com/reshufflehq/reshuffle-shopify-connector) |  [npm](https://www.npmjs.com/package/reshuffle-shopify-connector) | [Code sample](https://github.com/reshufflehq/reshuffle/tree/master/examples/shopify)

`npm install reshuffle-shopify-connector`

This connector uses [Official Node Shopify Client](https://www.npmjs.com/package/shopify-api-node) package.

### Reshuffle Shopify Connector

This package contains a [Reshuffle](https://github.com/reshufflehq/reshuffle) connector for connecting to [Shopify](https://www.shopify.com/online).

The following example listens to Shopify order fulfillment events:
```js
const { Reshuffle } = require('reshuffle')
const { ShopifyConnector } = require('reshuffle-shopify-connector')

const app = new Reshuffle()
const connector = new ShopifyConnector(app, {
  shopName: process.env.SHOPIFY_SHOP_NAME,
  apiKey: process.env.SHOPIFY_API_KEY,
  password: process.env.SHOPIFY_PASSWORD
})
  
connector.on({ topic: 'orders/fulfilled' }, (event, app) => {
  console.log('congratulations! Another order fulfilled')
})

app.start()
```

### Table of Contents

[Create Shopify API token](#apitoken)

[Configuration Options](#configuration)

#### Connector Events

[Listening to Shopify events](#listen)

#### Connector Actions
[Examples using the SDK](#sdk)

[SDK](#sdk) - Retrieve a full Shopify sdk object

#### <a name="apitoken"></a>Create Shopify API token
Create an API token on your Shopify Admin Page:

1. Go to https://<your_shop_name>.myshopify.com/admin/apps/private
2. Click `Create new private app`, 
3. Provide a name and scopes (keeping in mind that permissions are very limited per default)
4. Click Save, and you'll get api key and password

#### <a name="configuration"></a>Configuration Options

Provide options as below for connecting to Shopify:
```typescript
const connector = new ShopifyConnector(app, {
  shopName: '<your_shop_name>',
  apiKey: '<your_api_key>',
  password: '<your password>',
})
``` 

To use Shopify connector events, you need to provide at least your runtime baseURL. 
You can also override the default webhookPath and webhookName.
```typescript
interface ShopifyConnectorConfigOptions extends Shopify.IPrivateShopifyConfig {
  baseURL?: string
  webhookPath?: string // Default to '/reshuffle-shopify-connector/webhook'
}

// Full list of available options to connect to Shopify API
interface IPrivateShopifyConfig {
  shopName: string
  apiKey: string
  password: string
  apiVersion?: string
  autoLimit?: boolean | IAutoLimit
  presentmentPrices?: boolean
  timeout?: number
}
```

#### Connector events

##### <a name="listen"></a>Listening to Shopify events

To listen to events happening in Shopify, pass the topic as options to the `connector.on` function

```typescript
interface ShopifyConnectorEventOptions {
  topic: WebhookTopic
}

// List extracted from https://github.com/MONEI/Shopify-api-node/blob/master/index.d.ts#L2869
type WebhookTopic =
    | 'app/uninstalled'
    | 'carts/create'
    | 'carts/update'
    | 'checkouts/create'
    | 'checkouts/delete'
    | 'checkouts/update'
    | 'collection_listings/add'
    | 'collection_listings/remove'
    | 'collection_listings/update'
    | 'collections/create'
    | 'collections/delete'
    | 'collections/update'
    | 'customer_groups/create'
    | 'customer_groups/delete'
    | 'customer_groups/update'
    | 'customers/create'
    | 'customers/delete'
    | 'customers/disable'
    | 'customers/enable'
    | 'customers/update'
    | 'draft_orders/create'
    | 'draft_orders/delete'
    | 'draft_orders/update'
    | 'fulfillment_events/create'
    | 'fulfillment_events/delete'
    | 'fulfillments/create'
    | 'fulfillments/update'
    | 'inventory_items/create'
    | 'inventory_items/update'
    | 'inventory_items/delete'
    | 'inventory_levels/connect'
    | 'inventory_levels/update'
    | 'inventory_levels/disconnect'
    | 'locations/create'
    | 'locations/update'
    | 'locations/delete'
    | 'order_transactions/create'
    | 'orders/cancelled'
    | 'orders/create'
    | 'orders/delete'
    | 'orders/fulfilled'
    | 'orders/paid'
    | 'orders/partially_fulfilled'
    | 'orders/updated'
    | 'product_listings/add'
    | 'product_listings/remove'
    | 'product_listings/update'
    | 'products/create'
    | 'products/delete'
    | 'products/update'
    | 'refunds/create'
    | 'shop/update'
    | 'themes/create'
    | 'themes/delete'
    | 'themes/publish'
    | 'themes/update'
```

Examples of event listeners:
```typescript
const app = new Reshuffle()
const connector = new ShopifyConnector(app, {
  shopName: '<shop_name>',
  apiKey: '<api_key>',
  password: '<password>',
  baseURL: '<your_reshuffle_runtime_base_url>',
})

connector.on({ topic: 'shop/update' }, async (event, app) => {
  console.log(event.options.topic) // 'shop/update'
  console.log(event) // { id: '<your_shop_id>', name: 'shop name', ... }
})    

connector.on({ topic: 'orders/create' }, async (event, app) => {                             
  console.log(event) // event representing the order just created 
})  
```
                                                                    
#### Connector actions

All actions are provided via the sdk.
// See full list of actions documentations in [Shopify Client Available Resources and Methods](https://www.npmjs.com/package/shopify-api-node#available-resources-and-methods)

##### <a name="sdk"></a>SDK

Full access to the Node Shopify Client SDK

```typescript
const sdk = await connector.sdk()
```


##### <a name="examples"></a>Examples using the SDK

- Get list of products (you can filter them by passing options to `list(options)`)
```typescript
const products = await connector.sdk().product.list()
console.log(products) // [{ id: 6095693840581, tite: 'Reshuffle cap', created_at: '2020-11-23T15:23:09+13:00', published_scope: 'web', admin_graphql_api_id: 'gid://shopify/Product/6095693840581', ... }]
```

- Get list of orders
```typescript
const orders = await connector.sdk().order.list({ limit: 5 })
console.log(orders)
```

- Add a country:
```typescript
const country = await connector.sdk().country.create({ code: 'FR', tax: 0.25 })
console.log(country) // { id: 381258858693, name: 'France', tax: 0.25, code: 'FR', tax_name: 'FR TVA', provinces: [] }
```


Slack Connector

## Reshuffle Slack Connector

`npm install reshuffle-slack-connector`

_Commonjs_: `const { SlackConnector } = require('reshuffle-slack-connector')`

_ES6 import_: `import { SlackConnector } from 'reshuffle-slack-connector'` 


This connector is designed to interact with Slack API and allow you to post/amend/delete/search messages directly into Slack.

This connector required a Slack App to be configured:
- Go to https://api.slack.com/apps
- Click on `Create New App`
- Enter a `name` and select a `workspace`
- Click on `Create App`
- Click on your new app
- The signing secret is under `Basic Information` > `App Credentials`
- The token is under `Settings` > `Install App` > OAuth Access Token

To create a Slack connector, you need to provide configuration options like this:
```ts
interface SlackConnectorConfigOptions {
  token: string
  signingSecret: string
  port?: number
  endpoints?:
    | string
    | {
        [endpointType: string]: string
      }
}
```

Create a new Slack Connector:
Token and signingSecret are found at https://api.slack.com/apps/<your_slack_app_id>/event-subscriptions
```ts
const app = new Reshuffle()
const slackConnector = new SlackConnector(app, {
token: '<starts with xox>',
signingSecret: '<signing_secret>',
port: '<slack_app_port>', // default port is 3000
endpoints: '<slack_app_endpoints>' // default endpoints is'/'
})
```


_Events_:

*[event](#event) Listening to Slack events such as new messages or new users joining

_Actions_:

*[postMessage](#postMessage) Post a text message to a specified Slack channel or conversation.

*[scheduleMessage](#scheduleMessage) Schedule a text message to be posted on a specified Slack channel or conversation at a given time.

*[updateMessage](#updateMessage) Update an existing Slack message.

*[deleteMessage](#deleteMessage) Delete an existing Slack message.

*[searchMessages](#searchMessages) Search Slack for a message matching a specified query string.

*[getWebClient](#getwebclient) Get Slack Web Client.

*[getSlackApp](#getslackapp) Get Slack Application instance.

*[sdk](#sdk) Returns a Slack Application instance, and a Slack web client instance.

### Connector Events

##### Listening to Slack event

To listen to any kind of events happening in Slack, 
use type `SlackEventType.EVENT` as event option (see example below)
As event option values, pass the Slack Event API type (e.g. 'message') for firing an event on a new message.

['Full list of Slack Event API type'](https://api.slack.com/events)

Your handler receives an event object and Reshuffle app.
Example of event object received:
```ts
{
  payload: {
    client_msg_id: "d1f6d102-69a6-49a0-aa35-f6a9f4ffcf04"
    type: "message"
    text: "my message in Slack"
    user: "U01APN2NLVD"
    ts: "1601003324.000400"
    team: "T01B4LHKJ3D"
    channel: "C01AXNBH0QN"
    event_ts: "1601003324.000400"
    channel_type: "channel"
  },
  say: SayFn,
  context: {
    botToken: "xoxb-..."
    botUserId: "U01BU9WD5S4"
    botId: "B01BAL52SP6"
  },
  client: WebClient
}
```

###### Example
```js
const slackConnector = new SlackConnector(app, {
token: '<starts with xox>',
signingSecret: '<signing_secret>',
port: '<slack_app_port>',
})

// Events
slackConnector.on(
{
  type: SlackEventType.EVENT,
  values: {
    type: SlackEvents.MESSAGE,
  },
},
(event, app) => {
  console.log('new message posted on Slack')
  console.log(JSON.stringify(event))
},
)

app.start()
```

To listen to any kind of events happening in Slack, 
use type `SlackEventType.EVENT` as event option (see example below)
As event option values, pass the Slack Event API type (e.g. 'message') for firing an event on a new message.

['Full list of Slack Event API type'](https://api.slack.com/events)

###### Example
```js
const slackConnector = new SlackConnector(app, {
token: '<starts with xox>',
signingSecret: '<signing_secret>',
port: '<slack_app_port>',
})

// Events
slackConnector.on(
{
  type: SlackEventType.EVENT,
  values: {
    type: SlackEvents.MESSAGE,
  },
},
(event, app) => {
  console.log('new message posted on Slack')
  console.log(JSON.stringify(event))
},
)

app.start()
```

### Connector actions

#### <a name="postMessage"></a>Post a message to Slack

[Slack Documentation 'chat.postMessage'](https://api.slack.com/methods/chat.postMessage)

_Required Slack Permissions:_

**bot**: `chat:write` 

_Definition:_

```
(
  channelId: string,
  text: string,
  msgOptions?: MsgOpts,
) => WebAPICallResult
```

*MsgOpts*

```
{
  as_user?: boolean;
  attachments?: MessageAttachment[];
  blocks?: (KnownBlock | Block)[];
  icon_emoji?: string; // if specified, as_user must be false
  icon_url?: string;
  link_names?: boolean;
  mrkdwn?: boolean;
  parse?: 'full' | 'none';
  reply_broadcast?: boolean; // if specified, thread_ts must be set
  thread_ts?: string;
  unfurl_links?: boolean;
  unfurl_media?: boolean;
  username?: string; // if specified, as_user must be false
}
```

_Usage:_

```js
await slackConnector.postMessage('<channel_id>', 'Some message!', { mrkdwn: true })
```

#### <a name="scheduleMessage"></a>Schedule a message to post on Slack

[Slack Documentation 'chat.scheduleMessage'](https://api.slack.com/methods/chat.scheduleMessage)

_Required Slack Permissions:_

**bot**: `chat:write` 

_Definition:_

```
(
  channelId: string,
  postAt: Date,
  text: string,
) => WebAPICallResult
```

*ScheduleMsgOpts*

```
{
  as_user?: boolean;
  attachments?: MessageAttachment[];
  blocks?: (KnownBlock | Block)[];
  link_names?: boolean;
  parse?: 'full' | 'none';
  reply_broadcast?: boolean; // if specified, thread_ts must be set
  thread_ts?: string;
  unfurl_links?: boolean;
  unfurl_media?: boolean;
}
```

_Usage:_

```js
await slackConnector.scheduleMessage(
    '<channel_id>',
    new Date(Date.now() + 10000), // 10 seconds from current time
    'Scheduled message!',
    { mrkdwn: true },
  )
```

#### <a name="updateMessage"></a>Update an existing Slack message

[Slack Documentation 'chat.update'](https://api.slack.com/methods/chat.update)

_Required Slack Permissions:_

**bot**: `chat:write` 

_Definition:_

```
(
  channelId: string,
  text: string,
  timestamp: string,
  msgOptions?: MsgOpts,
) => WebAPICallResult
```

*MsgOpts*

```
{
  as_user?: boolean;
  attachments?: MessageAttachment[];
  blocks?: (KnownBlock | Block)[];
  icon_emoji?: string; // if specified, as_user must be false
  icon_url?: string;
  link_names?: boolean;
  mrkdwn?: boolean;
  parse?: 'full' | 'none';
  reply_broadcast?: boolean; // if specified, thread_ts must be set
  thread_ts?: string;
  unfurl_links?: boolean;
  unfurl_media?: boolean;
  username?: string; // if specified, as_user must be false
}
```

_Usage:_

```js
await slackConnector.updateMessage(
  '<channel_id>',
  'Some message!',
  '1405894322.002768',
  { mrkdwn: true },
)
```

#### <a name="deleteMessage"></a>Delete an existing Slack message

[Slack Documentation 'chat.delete'](https://api.slack.com/methods/chat.delete)

_Required Slack Permissions:_

**bot**: `chat:write` 

_Definition:_

```
(channelId: string, timestamp: string) => WebAPICallResult
```

_Usage:_

```js
await slackConnector.deleteMessage(
  '<channel_id>',
  '1405894322.002768',
)
```

#### <a name="searchMessages"></a>Search through messages on Slack

[Slack Documentation 'search.messages'](https://api.slack.com/methods/search.messages)

_Required Slack Permissions:_

**user**: `search:read`

Multiple messages will be returned in the case that multiple matches
are found for your given query.

_Definition:_

```
(query: string) => WebAPICallResult
```

_Usage:_

```js
await slackConnector.searchMessages('some text to look for')
```

#### <a name="getwebclient"></a>Get Slack Web Client

[Slack Documentation 'web API'](https://slack.dev/bolt-js/concepts#web-api)

Get Slack Web Client instance to code bespoke solutions

_Definition:_

```
() => WebClient
```

_Usage:_

```js
const webClient = await slackConnector.getWebClient()

// Example:
await webClient.chat.delete({options})
```

#### <a name="getslackapp"></a>Get Slack Application instance

[Slack Documentation 'Creating a Slack App'](https://api.slack.com/start/building/bolt-js#create)

Get Slack Application instance for coding advanced features

_Definition:_

```
() => App
```

_Usage:_

```js
const slackApp = await slackConnector.getSlackApp()

// Example:
await slackApp.client.chat.update({options})
```

#### <a name="sdk"></a>Returns Reshuffle Slack sdk

Returns a Slack Application instance, and a Slack web client instance

_Definition:_

```
() => { slackApp: App; webClient: WebClient }
```

_Usage:_

```js
const { slackApp, webClient } = await slackConnector.sdk()
```

## API definitions

[Definition of WebAPICallResult](https://github.com/slackapi/node-slack-sdk/blob/aa269d160f10b3414812ee335b1dfa961d214c77/packages/web-api/src/WebClient.ts#L874)

More examples on how to use this connector can be [found here](https://github.com/reshufflehq/reshuffle/blob/master/examples/message/SlackMessageExample.js).

SmartSheet Connector

# reshuffle-smartsheet-connector

[Code](https://github.com/reshufflehq/reshuffle-smartsheet-connector) |
[npm](https://www.npmjs.com/package/reshuffle-smartsheet-connector) |
[Code sample](https://github.com/reshufflehq/reshuffle-smartsheet-connector/tree/master/examples)

`npm install reshuffle-smartsheet-connector`

### Reshuffle Smartsheet Connector

This package contains a [Reshuffle](https://github.com/reshufflehq/reshuffle)
connector to access to online spreadsheets at
[smartsheet.com](https://smartsheet.com).

The following example tracks changes to an online spreadtsheet. Changes are
reported at the sheet level, row level and cell level:

```js
const { Reshuffle } = require('reshuffle')
const { SmartsheetConnector } = require('reshuffle-smartsheet-connector')

const app = new Reshuffle()

const ssh = new SmartsheetConnector(app, {
  apiKey: process.env.SMARTSHEET_API_KEY,
  baseURL: process.env.RESHUFFLE_RUNTIME_BASE_URL,
})

ssh.on({ sheetId: sheet.sheetId }, async (event) => {
  console.log('Smartsheet event:', event)
})

async function main() {

  const sheet = await ssh.findOrCreateSheet('Reshuffle Events Example', [
    { title: 'Name', type: 'TEXT_NUMBER', primary: true },
    { title: 'Quest', type: 'TEXT_NUMBER' },
    { title: 'Color', type: 'TEXT_NUMBER' },
  ])

  if (sheet.created) {
    await ssh.addRowToBottom(sheet.sheetId, [
      { columnId: sheet.columns[0].id, value: 'Arthur' },
      { columnId: sheet.columns[1].id, value: 'Find the Holy Grail' },
      { columnId: sheet.columns[2].id, value: 'Blue' },
    ])
  }

  console.log(`Please visit ${sheet.permalink} and make some changes`)
}

app.start()
main().catch(console.error)
```

### Table of Contents

[Configuration](#configuration) Configuration options

#### Connector events

[sheetChanged](#sheetChanged) Sheet changed

#### Connector actions

[addRows](#addRows) Add rows to a sheet

[addRowToBottom](#addRowToBottom) Add one row at the bottom of a sheet

[addRowToTop](#addRowToTop) Add one row at the top of a sheet

[createSheet](#createSheet) Create a new sheet

[deleteRow](#deleteRow) Delete one row

[findOrCreateSheet](#findOrCreateSheet) Find or create a sheet

[getImage](#getImage) Get image from a sheet cell

[getSheetById](#getSheetById) Get sheet data by sheet id

[getSheetIdByName](#getSheetIdByName) Find sheet id by its name

[getSheetByName](#getSheetByName) Get sheet data by sheet name

[getSimpleSheetById](#getSimpleSheetById) Get a simple sheet object by ID

[getSimpleSheetByName](#getSimpleSheetByName) Get a simple sheet object by name

[getRow](#getRow) Get row information

[listSheets](#listSheets) List all sheets

[listRows](#listRows) List rows in a sheet

[update](#update) Update a sheet

[sdk](#sdk) Get direct SDK access

### <a name="configuration"></a>Configuration options

```js
const app = new Reshuffle()
const smartsheetConnector = new SmaetsheetConnector(app, {
  apiKey: process.env.SMARTSHEET_API_KEY,
  baseURL: process.env.RESHUFFLE_RUNTIME_BASE_URL, // optional but required
                                                   // for events
})
```

### Connector events

#### <a name="sheetChanged"></a> Sheet Changed event

_Example:_

```js
async (event) => {
  console.log('Smartsheet event:', event)
})
```

This event is fired when a Smartsheet webhook is triggered. Triggers include
sheet update, row update, cell update and more.

See
[event.js](https://github.com/reshufflehq/reshuffle-smartsheet-connector/examples/events.js)
for an example of defining and handling sheet events.

### Connector actions

#### <a name="addRows"></a> Add Rows action

Add rows to a sheet.

_Definition:_

```ts
(
  sheetId: number | string,
  rows: object,
) => void
```

_Usage:_

```js
await smartsheetConnector.addRows(4583173393803140, [
  {
    toTop: true,
    cells: [
      {
        columnId: 7960873114331012,
        value: true,
      },
      {
        columnId: 642523719853956,
        value: 'New status',
        strict: false,
      },
    ],
  },
  {
    toBottom: true,
    cells: [
      {
        columnId: 7960873114331012,
        value: true,
      },
      {
        columnId: 642523719853956,
        value: 'New status',
        strict: false,
      },
    ],
  },
])
```

#### <a name="addRowToBottom"></a> Add Row To Bottom action

Add one row after the last row of a sheet.

_Definition:_

```ts
(
  sheetId: number | string,
  cells: object[],
) => void
```

_Usage:_

```js
await smartsheetConnector.addRowToBottom(4583173393803140, {
  { columnId: 7960873114331012, value: true },
  { columnId: 642523719853956, value: 'New status' }
})
```

#### <a name="addRowToTop"></a> Add Row To Top action

Add one row before the first row of a sheet.

_Definition:_

```ts
(
  sheetId: number | string,
  cells: object[],
) => void
```

_Usage:_

```js
await smartsheetConnector.addRowToTop(4583173393803140, {
  { columnId: 7960873114331012, value: true },
  { columnId: 642523719853956, value: 'New status' }
})
```

#### <a name="createSheet"></a> Create Sheet action

Create a new sheet.

_Definition:_

```ts
(
  name: string,
  columns: object[]
) => object
```

_Usage:_

```js
await smartsheetConnector.createSheet('My Sheet', [
  { title: 'Name', type: 'TEXT_NUMBER', primary: true },
  { title: 'City', type: 'TEXT_NUMBER' },
])
```

#### <a name="deleteRow"></a> Delete Row action

Delete a single row from the specified sheet.

_Definition:_

```ts
(
  sheetId: number | string,
  rowId: number | string,
) => void
```

_Usage:_

```js
await smartsheetConnector.deleteRow(4583173393803140, 1234567890123456)
```

#### <a name="findOrCreateSheet"></a> Find Or Create Sheet action

This action offers the same interface as [createSheet](#createSheet) above,
but checks first whether a sheet with the specified `name` exists. If so,
that sheet is returned. Otherwise, a new one is created.

The action returns an object with the following fields:

```ts
  accessLevel: string
  columns: object[]
  created: boolean
  name: string
  permalink: string
  sheetId: number
```

_Definition:_

```ts
(
  sheetId: number | string,
  rowId: number | string,
) => object
```

_Usage:_

```js
await smartsheetConnector.findOrCreateSheet('My Sheet', [
  { title: 'Name', type: 'TEXT_NUMBER', primary: true },
  { title: 'City', type: 'TEXT_NUMBER' },
])
```

#### <a name="getImage"></a> Get Image action

Get an image stored in a sheet cell. `sheetId` and `rowId` specify the
specific row to query. `columnIdOrIndex` is treated as an index if it is
a number smaller than 1024, otherwise it is treated as a column id.

The returned image data includes a unique ID, the alternative text (usually the
original file name) and a download URL. The URL is valid for half an hour.

Use the optional `width` and `height` arguments to get a link to a resized
image.

_Definition:_

```ts
(
  sheetId: number | string,
  rowId: number | string,
  columnIdOrIndex: number | string,
  width?: number,
  height?: number,
) => object
```

_Usage:_

```js
const img = await smartsheetConnector.getImage(
  4583173393803140,
  000000000000000,
  3,
)
console.log(img.id, img.text, img.url)
```

#### <a name="getSheetById"></a> Get Sheet By ID action

Get full [sheet data](https://smartsheet-platform.github.io/api-docs/?javascript#get-sheet)
for the sheet with the specified `id`.

_Definition:_

```ts
(
  sheetId: number | string,
) => object
```

_Usage:_

```js
const sheetData = await smartsheetConnector.getSheetById(4583173393803140)
```

#### <a name="getSheetIdByName"></a> Get Sheet ID By Name action

Lookup the sheet ID for the sheet with the specified name. If a sheet
with that name is not found then an Error is thrown.

_Definition:_

```ts
(
  name: string,
) => number
```

_Usage:_

```js
const sheetId = await smartsheetConnector.getSheetIdByName('My Sheet')
```

#### <a name="getSheetByName"></a> Get Sheet By Name action

Get full [sheet data](https://smartsheet-platform.github.io/api-docs/?javascript#get-sheet)
for the sheet with the specified `name`. If a sheet with that name is not
found then an Error is thrown.

_Definition:_

```ts
(
  name: string,
) => object
```

_Usage:_

```js
const sheetData = await smartsheetConnector.getSheetByName('My Sheet')
```

#### <a name="getSimpleSheetById"></a>Get Simple Sheet By ID action

Get a `SimpleSheet` object representing the sheet with the specified
`id`. This object provides the following methods:

```ts
getColumnIdByTitle(
  columnTitle: string,
): number // Get column ID by column title
getUpdater(): object // Create an updater object
pivot(
  pivotColumn: string,
  property: string,
  matchColumns: string[],
  includeRowIDs?: boolean,
): object // Build a pivot table
toSCV(): string // Create a CSV representation
```

An updater object provides the following methods:

```ts
addUpdate(
  columnTitle: string,
  rowId: number | string,
  value: string,
) // Add a cell value to be updated
getSheetId(): number // Get the sheet ID
getUpdates(): object // Get the updates for using with the update action
```

_Definition:_

```ts
(
  sheetId: number | string,
) => object
```

_Usage:_

```js
const sheet = await smartsheetConnector.getSimpleSheetById(4583173393803140)
const updater = sheet.getUpdater()
updater.addUpdate('My Column', 000000000000000, 'New Value')
await smartsheetConnector.update(updater.getSheetId(), updater.getUpdates())
```

#### <a name="getSimpleSheetByName"></a> Get Simple Sheet By Name action

Get a `SimpleSheet` object representing the sheet with the specified
`name`. See [getSimpleSheetById](#getSimpleSheetById) for details.

_Definition:_

```ts
(
  name: string,
) => object
```

#### <a name="getRow"></a> Get Row action

Get information about the specified row in the specified sheet. Row
information is detailed [here](https://smartsheet-platform.github.io/api-docs/#get-row).

_Definition:_

```ts
(
  sheetId: number | string,
  rowId: number | string,
) => object
```

_Usage:_

```js
const row = await smartsheetConnector.getRow(
  4583173393803140,
  1234567890123456,
)
```

#### <a name="listRows"></a> List Rows action

Get a list of row Ids in the specified sheet.

_Definition:_

```ts
(
  sheetId: number | string,
) => number[]
```

_Usage:_

```js
const rowIds = await smartsheetConnector.listRows(4583173393803140)
```

#### <a name="listSheets"></a> List Sheets action

Get a list of all sheets in the connected Smartsheet account. For each sheet,
the following information is returned:

* *id* - Sheet ID
* *name* - Sheet name
* *accessLevel* - Usually 'OWNER'
* *permalink* - Link to the sheet's online page
* *createdAt* - Creation time stamp
* *modifiedAt* - Modification time stamp

_Definition:_

```ts
() => object[]
```

_Usage:_

```js
const sheets = await smartsheetConnector.listSheets()
```

#### <a name="update"></a> Update action

Update the data in a sheet. The update object uses the format defined
[here](https://smartsheet-platform.github.io/api-docs/?javascript#update-rows). 
You can use the [Simple Sheet object](#getSimpleSheetByName) to create
an updater object that will construct the rows array.

_Definition:_

```ts
(
  sheetId: number | string,
  rows: object[],
) => void
```

_Usage:_

```js
await smartsheetConnector.update(
  4583173393803140,
  [
    {
      id: '0000000000000000',
      cells: [
        {
          columnId: '0000000000000000',
          value: 'My Value',
        },
      ],
    },
  ],
)
```

#### <a name="sdk"></a> sdk action

Get the underlying SDK object.

_Definition:_

```ts
() => object
```

_Usage:_

```js
const client = await smartsheetConnector.sdk()
```


Teamwork Connector

# reshuffle-teamwork-connectors

[Code](https://github.com/reshufflehq/reshuffle-teamwork-connectors) |
[npm](https://www.npmjs.com/package/reshuffle-teamwork-connectors) |


`npm install reshuffle-teamwork-connectors`

### Reshuffle Teamwork Connector

This package contains a [Reshuffle](https://github.com/reshufflehq/reshuffle)
connector to connect [Teamwork Online app APIs](https://github.com/moshie/teamwork-api).

The following example exposes an endpoint to return the data of a Task after an Update action.

```js
const { Reshuffle } = require('reshuffle')
const { TeamworkConnector } = require('reshuffle-teamwork-connectors')

const app = new Reshuffle()

const connector = new TeamworkConnector(app,  {
  apiKey: YOUR_API_KEY,
  subdomain: YOUR_SUB_DOMAIN,
  webhookPath: '/webhooks/teamwork'
})

connector.on({ type: 'TASK.UPDATED' }, async (event, app) => {
  console.log('Task updated on Teamwork YOUR_SUB_DOMAIN')
  console.log(event.eventCreator.id)
  console.log(event.taskList.name)
  console.log(event.task)
})

app.start()
```

### Table of Contents

[Configuration Options](#configuration)

#### Connector Events

[Listening to Teamwork events](#listen)

#### Connector Actions

[SDK](#sdk) - Retrieve a full Teamwork sdk object


### <a name="configuration"></a> Configuration options

```js
const app = new Reshuffle()
const connector = new TeamworkConnector(app, {
  apiKey: YOUR_API_KEY, 
  subdomain: YOUR_SUB_DOMAIN, 
  webhookPath: WEBHOOK_PATH 
})
```

- apiKey - How to find the [API key](https://developer.teamwork.com/projects/apikey/key)
- subdomain - https://[subdomain].teamwork.com/
- webhookPath - The path component of the Webhook Endpoint URI for this project. The default value is '/webhooks/teamwork'.


More details about the fields are described in [teamwork-api](https://github.com/moshie/teamwork-api)

You can use the `webhookPath` to configure the url that Teamwork hits when it makes its calls to Reshuffle.
For example - having the Reshuffle runtime URL `https://my-reshuffle.com` and `webhookPath=/webhook` will result in a complete webhook path of `https://my-reshuffle.com/webhook`.
If you do not provide a `webhookPath`, Reshuffle will use the default webhook path for the connector which is `/webhooks/teamwork`.
You will need to register this webhook with Teamwork. See [instructions](https://developer.teamwork.com/projects/webhooks/setup).


### <a name="events"></a> Events

#### <a name="listen"></a> Listening to Teamwork events

To listen to events happening in Teamwork, you'll need to capture them with the connector's `on`
function, providing a `TeamworkConnectorEventOptions` to it.


```typescript
interface TeamworkConnectorEventOptions {
  type: TeamworkEventType // See bellow 
}

// Where...
type TeamworkEventType =
  | 'CALENDAREVENT.CREATED'
  | 'CALENDAREVENT.DELETED'
  | 'CALENDAREVENT.REMINDER'
  | 'CALENDAREVENT.UPDATED'
  | 'CARD.CREATED'
  | 'CARD.DELETED'
  | 'CARD.UPDATED'
  | 'COLUMN.CREATED'
  | 'COLUMN.DELETED'
  | 'COLUMN.UPDATED'
  | 'COMMENT.CREATED'
  | 'COMMENT.DELETED'
  | 'COMMENT.UPDATED'
  | 'COMPANY.CREATED'
  | 'COMPANY.DELETED'
  | 'COMPANY.UPDATED'
  | 'EXPENSE.CREATED'
  | 'EXPENSE.DELETED'
  | 'EXPENSE.UPDATED'
  | 'FILE.CREATED'
  | 'FILE.DELETED'
  | 'FILE.DOWNLOADED'
  | 'FILE.TAGGED'
  | 'FILE.UNTAGGED'
  | 'FILE.UPDATED'
  | 'INVOICE.COMPLETED'
  | 'INVOICE.CREATED'
  | 'INVOICE.DELETED'
  | 'INVOICE.REOPENED'
  | 'INVOICE.UPDATED'
  | 'LINK.CREATED'
  | 'LINK.DELETED'
  | 'LINK.TAGGED'
  | 'LINK.UNTAGGED'
  | 'LINK.UPDATED'
  | 'MESSAGE.CREATED'
  | 'MESSAGE.DELETED'
  | 'MESSAGE.TAGGED'
  | 'MESSAGE.UNTAGGED'
  | 'MESSAGE.UPDATED'
  | 'MESSAGEREPLY.CREATED'
  | 'MESSAGEREPLY.DELETED'
  | 'MESSAGEREPLY.UPDATED'
  | 'MILESTONE.COMPLETED'
  | 'MILESTONE.CREATED'
  | 'MILESTONE.DELETED'
  | 'MILESTONE.REMINDER'
  | 'MILESTONE.REOPENED'
  | 'MILESTONE.TAGGED'
  | 'MILESTONE.UNTAGGED'
  | 'MILESTONE.UPDATED'
  | 'NOTEBOOK.CREATED'
  | 'NOTEBOOK.DELETED'
  | 'NOTEBOOK.TAGGED'
  | 'NOTEBOOK.UNTAGGED'
  | 'NOTEBOOK.UPDATED'
  | 'PORTFOLIOBOARD.CREATED'
  | 'PORTFOLIOBOARD.DELETED'
  | 'PORTFOLIOBOARD.UPDATED'
  | 'PORTFOLIOCARD.CREATED'
  | 'PORTFOLIOCARD.DELETED'
  | 'PORTFOLIOCARD.MOVED'
  | 'PORTFOLIOCARD.REOPENED'
  | 'PORTFOLIOCARD.UPDATED'
  | 'PORTFOLIOCOLUMN.CREATED'
  | 'PORTFOLIOCOLUMN.DELETED'
  | 'PORTFOLIOCOLUMN.UPDATED'
  | 'PROJECT.ARCHIVED'
  | 'PROJECT.COMPLETED'
  | 'PROJECT.COPIED'
  | 'PROJECT.CREATED'
  | 'PROJECT.DELETED'
  | 'PROJECT.REOPENED'
  | 'PROJECT.TAGGED'
  | 'PROJECT.UNTAGGED'
  | 'PROJECT.UPDATED'
  | 'PROJECTUPDATE.CREATED'
  | 'PROJECTUPDATE.DELETED'
  | 'PROJECTUPDATE.UPDATED'
  | 'RISK.CREATED'
  | 'RISK.DELETED'
  | 'RISK.UPDATED'
  | 'ROLE.CREATED'
  | 'ROLE.DELETED'
  | 'ROLE.UPDATED'
  | 'STATUS.CREATED'
  | 'STATUS.DELETED'
  | 'STATUS.UPDATED'
  | 'TASK.COMPLETED'
  | 'TASK.CREATED'
  | 'TASK.DELETED'
  | 'TASK.MOVED'
  | 'TASK.REMINDER'
  | 'TASK.REOPENED'
  | 'TASK.TAGGED'
  | 'TASK.UNTAGGED'
  | 'TASK.UPDATED'
  | 'TASKLIST.COMPLETED'
  | 'TASKLIST.CREATED'
  | 'TASKLIST.CREATEDFROMTEMPLATE'
  | 'TASKLIST.DELETED'
  | 'TASKLIST.REOPENED'
  | 'TASKLIST.UPDATED'
  | 'TIME.CREATED'
  | 'TIME.DELETED'
  | 'TIME.TAGGED'
  | 'TIME.UNTAGGED'
  | 'TIME.UPDATED'
  | 'USER.CREATED'
  | 'USER.DELETED'
  | 'USER.UPDATED'
```

Events require that an integration webhook is configured in Teamwork. 

The connector triggers events of many types, you can get more details about them [here](https://developer.teamwork.com/projects/api-v1/ref)


_Example:_

```typescript
connector.on({ type: 'TASK.UPDATED' }, async (event, app) => {
  console.log('Task updated on Teamwork YOUR_SUB_DOMAIN')
  console.log(event.eventCreator.id)
  console.log(event.taskList.name)
  console.log(event.task)
})
```

The description of fields and events can be found [here](https://developer.teamwork.com/projects/webhooks/events)

### <a name="actions"></a> Actions

The actions are provided via the [sdk](#sdk).

#### <a name="sdk"></a> sdk

Returns an object providing full access to the Teamwork APIs.
Full list of available actions, requests and responses can be found [here](https://developer.teamwork.com/projects/api-v1)

```typescript
const sdk = await connector.sdk()
```

_Example:_

```typescript
const sdk = await connector.sdk()
const taskLists = await sdk.tasklist.get()
console.log('Tasklists:', JSON.stringify(taskLists))
const task = await sdk.tasks.get({}, YOUR_TASK_ID))
console.log('Task YOUR_TASK_ID:', JSON.stringify(task))
```

Toggl Connector

# reshuffle-toggl-connector
[Code](https://github.com/reshufflehq/reshuffle-toggl-connector) |  [npm](https://www.npmjs.com/package/reshuffle-toggl-connector) | [Code sample](https://github.com/reshufflehq/reshuffle/tree/master/examples/toggl)

`npm install reshuffle-toggl-connector`

This connector uses [Official Node Toggl Client](https://www.npmjs.com/package/toggl-api) package.

### Reshuffle Toggl Connector


_ES6 import_: `import { TogglConnector } from 'reshuffle-toggl-connector'` 

This is a [Reshuffle](https://github.com/reshufflehq/reshuffle) connector that provides an Interface to the Toggl Client.

You need to get your Toggl API Token from your account. 
See more details [here](https://github.com/toggl/toggl_api_docs#api-token)

The following example creates an API endpoint to list all entries in Toggl between from/to dates:

```js
const { HttpConnector, Reshuffle } = require('reshuffle')
const { TogglConnector } = require('reshuffle-toggle-connectors')

const app = new Reshuffle()
const togglConnector = new TogglConnector(app, { token: 'YOUR_TOGGL_TOKEN' })
const httpConnector = new HttpConnector(app)

httpConnector.on({ method: 'GET', path: '/list' }, async (event) => {
  const keys = await togglConnector.getTimeEntries('2020-11-01T09:00:00.000Z', '2020-11-05T17:00:00.000Z')
  event.res.json(keys)
})

app.start(8000)
```

#### Table of Contents

[Configuration](#configuration) Configuration options

[DataTypes](#dataTypes) Data Types

_Connector events_:

[TimeEntryAdded](#TimeEntryAdded) TimeTracker Added

[TimeEntryModified](#TimeEntryModified) TimeTracker Modified

[TimeEntryRemoved](#TimeEntryRemoved) TimeTracker Removed

_Connector actions_:

[getTimeEntries](#getTimeEntries) Get TimeEntries objects

[getCurrentTimeEntry](#getCurrentTimeEntry) Get current running TimeEntries

[getTimeEntryData](#getTimeEntryData) Get TimeEntry Data

[createTimeEntry](#createTimeEntry) Create TimeEntry

[startTimeEntry](#startTimeEntry) Start TimeEntry

[stopTimeEntry](#stopTimeEntry) Stop TimeEntry

[updateTimeEntry](#updateTimeEntry) Update TimeEntry

[updateTimeEntriesTags](#updateTimeEntriesTags) Update TimeEntries Tags

[deleteTimeEntry](#deleteTimeEntry) Delete TimeEntry

[getUserData](#getUserData) Get UserData

[updateUserData](#updateUserData) Update UserData

[resetApiToken](#resetApiToken) Reset Api Token

[changeUserPassword](#changeUserPassword) Change User Password

[createClient](#createClient) Create Client

[getClients](#getClients) Get Clients

[getClientData](#getClientData) Get Client's Data

[updateClient](#updateClient) Update Client

[deleteClient](#deleteClient) Delete Client



_SDK_:

[sdk](#sdk) Get direct SDK access

##### <a name="configuration"></a>Configuration options

```typescript
const app = new Reshuffle()
const togglConnector = new TogglConnector(app, {
  token: string
})
```

##### <a name="dataTypes"></a>DataTypes

<a name="_TimeEntry:_"></a>_TimeEntry:_

```ts
{
  id: number,
  wid: null | number, // Workspace ID required if pid or tid not supplied
  pid: null | number, // Project ID
  pid: null | number, // Task ID
  billable: boolean, // Default false, available for pro workspaces
  start: string, // ISO 8601 date and time e.g. '2021-01-21T09:00:00Z'
  stop: string, // ISO 8601 date and time
  duration: number,
  description: string,
  tags: Array<string>,
  at: string
}
```
More details about TimeEntry available [here](https://github.com/toggl/toggl_api_docs/blob/master/chapters/time_entries.md) 

_UserData:_

```ts
{
  id: number,
  email: string,
  password: string,
  timezone: string,
  fullname: string,
  send_product_emails: boolean
  send_weekly_report: boolean
  send_timer_notifications: boolean
  store_start_and_stop_time: boolean
  beginning_of_week: number // in the range of 0-6
  timeofday_format: string, // Two formats are supported:
                            // "H:mm" for 24-hour format
                            // "h:mm A" for 12-hour format (AM/PM)
  date_format: string // possible values: "YYYY-MM-DD", "DD.MM.YYYY", "DD-MM-YYYY", "MM/DD/YYYY", "DD/MM/YYYY", "MM-DD-YYYY"
}
```
More details about UserData available [here](https://github.com/toggl/toggl_api_docs/blob/master/chapters/users.md) 

_ClientData:_

```ts
{
  id: number,
  name: string,
  wid: null | number,
  notes: string,
  at: string
}
```
More details about ClientData available [here](https://github.com/toggl/toggl_api_docs/blob/master/chapters/clients.md) 


_ProjectData:_

```ts
{
  id: number,
  name: string,
  wid: null | number,
  cid: null | number,
  active: boolean,
  is_private: boolean,
  template: boolean,
  template_id: number,
  billable: boolean,
  auto_estimates: boolean,
  estimated_hours: number,
  at: string,
  color: string,
  rate: number, 
  created_at: string
}
```
More details about ProjectData available [here](https://github.com/toggl/toggl_api_docs/blob/master/chapters/projects.md) 


#### Connector events

##### All the events are triggered based on changes that occurred only in TimeEntries that started during the last 9 days.


##### <a name="TimeEntryAdded"></a>TimeEntry Added event

_Event parameters:_

```
type: 'TimeEntryAdded' - Event type for added TimeEntry
```

_Example:_

```js
connector.on({ type: 'TimeEntryAdded' }, async (event, app) => {
  console.log('TimeEntry Added:')
  console.log('  Id:', event.id)
  console.log('  Start:', event.start)
  console.log('  Stop:', event.stop)
  console.log('  Description:', event.description)
})
```

This event is triggered once whenever a new TimeEntry is added to the Toggl board.

The `timeEntry` argument has the [following format](_TimeEntry:_)

##### <a name="TimeEntryModified"></a>TimeEntry Modified event

_Event parameters:_

```
type: 'TimeEntryModified' - Event type for modified TimeEntry
```

_Example:_

```js
connector.on({ type: 'TimeEntryModified' }, async (event, app) => {
  console.log('TimeEntry Modified:')
  console.log('  Id:', event.id)
  console.log('  Start:', event.start)
  console.log('  Stop:', event.stop)
  console.log('  Description:', event.description)
})
```

This event is triggered once whenever the content of a TimeEntry in the
Toggl board is modified.

The `timeEntry` argument has the [following format](_TimeEntry:_)


##### <a name="TimeEntryRemoved"></a>TimeEntry Removed event

_Event parameters:_

```
type: 'TimeEntryRemoved' - Event type for removed TimeEntry
```

_Example:_

```js
connector.on({ type: 'TimeEntryRemoved' }, async (event, app) => {
  console.log('TimeEntry Removed:')
  console.log('  Id:', event.id)
  console.log('  Start:', event.start)
  console.log('  Stop:', event.stop)
  console.log('  Description:', event.description)
})
```

This event is triggered once whenever a TimeEntry is removed from the
Toggl board.

The `timeEntry` argument has the [following format](_TimeEntry:_)

#### Connector actions

##### <a name="getTimeEntries"></a>Get TimeEntries action

_Definition:_

```ts
( startDate?: string | number | Date | Moment, 
  endDate?: string | number | Date | Moment
) => object[]
```

_Usage:_

```js
const timeEntries = await togglConnector.getTimeEntries('2021-01-01T09:00:00.000Z', '2021-01-05T17:00:00.000Z')
```

Get a list of [TimeEntries](_TimeEntry:_) in Toggl board.
If start_date and end_date are not specified, time entries started during the last 9 days are returned. 
The limit of returned time entries is 1000.

##### <a name="getCurrentTimeEntry"></a>Get current running TimeEntries action

_Definition:_

```ts
() => object
```

_Usage:_

```js
const timeEntry = await togglConnector.getCurrentTimeEntry()
```

Get the current running [TimeEntry](_TimeEntry:_).

##### <a name="getTimeEntryData"></a>Get TimeEntry Data action

_Definition:_

```ts
(teId: number | string) => object
```

_Usage:_

```js
const timeEntry = await togglConnector.getTimeEntryData(1783760282)
```

Get a [TimeEntry](_TimeEntry:_) data by ID.

##### <a name="createTimeEntry"></a>Create TimeEntry action

_Definition:_

```ts
(timeEntry: TimeEntry) => object
```

_Usage:_

```js
const timeEntry = await togglConnector.createTimeEntry({
    start:'2020-11-20T09:00:00.000Z',
    duration : 360,
    description : 'Design meeting',
    tags : ["Design", "Meetings"]})
```

Create a new [TimeEntry](_TimeEntry:_).

##### <a name="startTimeEntry"></a>Start TimeEntry action

_Definition:_

```ts
(timeEntry: TimeEntry) => object
```

_Usage:_

```js
const timeEntry = await togglConnector.startTimeEntry({
    start:'2020-11-20T09:00:00.000Z',
    stop : '2020-11-20T11:00:00.000Z',
    description : 'Design meeting',
    tags : ["Design", "Meetings"]})
```

Start a new [TimeEntry](_TimeEntry:_).

##### <a name="stopTimeEntry"></a>Stop TimeEntry action

_Definition:_

```ts
(teId: number | string) => object
```

_Usage:_

```js
const timeEntry = await togglConnector.stopTimeEntry(1778035860)
```

Stop running [TimeEntry](_TimeEntry:_).


##### <a name="updateTimeEntry"></a>Update TimeEntry action

_Definition:_

```ts
(teId: number | string, timeEntry: TimeEntry) => object
```

_Usage:_

```js
const timeEntry = await togglConnector.updateTimeEntry(1778035860, {
    start:'2020-11-21T09:00:00.000Z',
    stop : '2020-11-21T11:00:00.000Z',
    description : 'Postponed Design meeting',
    tags : ["Design", "Meetings"]})
```

Update [TimeEntry](_TimeEntry:_) data.


##### <a name="updateTimeEntriesTags"></a>Update TimeEntries Tags action

_Definition:_

```ts
(teIds: number[] | string[], tags: string[], action: string) => object
```

_Usage:_

```js
const timeEntry = await togglConnector.updateTimeEntriesTags([1778035860, 1778035860],['tag-1','tag-2'], 'add')
```

Assign and remove tags from [timeEntries](_TimeEntry:_).
action: possible values: add, remove


##### <a name="deleteTimeEntry"></a>Delete TimeEntry action

_Definition:_

```ts
(teId: number | string) => object
```

_Usage:_

```js
const timeEntry = await togglConnector.deleteTimeEntry(1778035860)
```

Delete [timeEntry](_TimeEntry:_).





##### <a name="getUserData"></a>Get UserData action

_Definition:_

```ts
() => object
```

_Usage:_

```js
const userData = await togglConnector.getUserData()
```

Get current [UserData](https://github.com/toggl/toggl_api_docs/blob/master/chapters/users.md).


##### <a name="updateUserData"></a>Update UserData action

_Definition:_

```ts
(userData: UserData) => object
```

_Usage:_

```js
const userData = await togglConnector.updateUserData({
    id: 4898995,
    email: 'user@gmail.com',
    send_product_emails: true,
    send_weekly_report: true,
    send_timer_notifications: true
  })
```

Update current [UserData](_UserData:_).


##### <a name="resetApiToken"></a>Reset Api Token action

_Definition:_

```ts
() => string
```

_Usage:_

```js
const token = await togglConnector.resetApiToken()
```

Reset current [UserData](_UserData:_) API Token.

##### <a name="changeUserPassword"></a>Change User Password action

_Definition:_

```ts
() => object
```

_Usage:_

```js
const userData = await togglConnector.changeUserPassword(currentPassword: string, password: string)
```


##### <a name="createClient"></a>Create Client action

_Definition:_

```ts
(clientData: ClientData) => object
```

_Usage:_

```js
const clientData = await togglConnector.createClient({
    name: 'Builders LTD',
    notes: 'Important client',
    wid: 4869303
  })
```

Create new [Client](ClientData:_).


##### <a name="getClients"></a>Get Clients action

_Definition:_

```ts
() => object
```

_Usage:_

```js
const clientsData = await togglConnector.getClients()
```

Get all [Clients](ClientData:_) data.


##### <a name="getClientData"></a>Get Client Data action

_Definition:_

```ts
(clientId: number | string) => object
```

_Usage:_

```js
const clientData = await togglConnector.getClientData(5869111)
```

Get [Client](ClientData:_) data by ID.

##### <a name="updateClient"></a>Update Client Data action

_Definition:_

```ts
(clientId: number | string, clientData: ClientData) => object
```

_Usage:_

```js
const clientData = await togglConnector.updateClient(5869111, {
    name: 'Builders One LTD',
    notes: 'Very important client',
    wid: 4869303
  })
```

Update [Client](ClientData:_) data.

##### <a name="deleteClient"></a>Delete Client Data action

_Definition:_

```ts
(clientId: number) => object
```

_Usage:_

```js
const clientData = await togglConnector.deleteClient(5869111)
```

Delete [Client](ClientData:_).

#### SDK

##### <a name="sdk"></a>sdk
_Definition:_

```ts
(options ?: object) => object
```

_Usage:_

```js
const toggl = await togglConnector.sdk()
```

Get the underlying SDK object. You can specify additional options to override
or add to the required fields in the connector's configuration.


Twilio Connector

# reshuffle-twilio-connector

[Code](https://github.com/reshufflehq/reshuffle-twilio-connector) |  [npm](https://www.npmjs.com/package/reshuffle-twilio-connector) | [Code sample](https://github.com/reshufflehq/reshuffle/tree/master/examples/message)

`npm install reshuffle-twilio-connector`

### Reshuffle Twilio Connector

This package is a [Reshuffle](https://github.com/reshufflehq/reshuffle) connector that provides access to the Twilio service. This connector can be used to send SMS and MMS out.
It can also trigger your code (through handlers) on incoming messages.

The following example listens to an incoming SMS and responds back to the service:
```js
const { Reshuffle } = require('reshuffle')
const { TwilioConnector } = require('reshuffle-twilio-connector')
const app = new Reshuffle()

// Create w Twilio account in few minutes for free: https://www.twilio.com/
const twilioConnector = new TwilioConnector(app, {
  accountSid: '<accountSid>',
  authToken: '<authToken>',
  twilioNumber: '<twilioNumber>',
})

// Reply to an incoming message on <twilioNumber>
twilioConnector.on({ method: 'POST', path: '/sms' }, (event, app) => {
  const messageReceived = event.req.body.Body
  const fromPhoneNumber = event.req.body.From
  console.log(`New SMS received from ${fromPhoneNumber}: ${messageReceived}`)

  if (messageReceived.includes('test')) {
    event.res.end('test successful')
  } else {
    event.res.end('Thanks for your message')
  }
})

app.start()
```

#### Configuration Options:
```typescript
interface TwilioConnectorConfigOptions {
    accountSid: string
    authToken: string
    opts?: Twilio.TwilioClientOptions
    twilioNumber?: string
}
```

#### Connector events

##### new messages
This event is fired when new messages are delivered to a `<twilioNumber>`.

For setting up webhooks in Twilio:
- go to https://www.twilio.com/console/phone-numbers/incoming
- select the phone number you'd like to use
- scroll all the way down to messaging
- create a new webhook with method and path
- save

You can now trigger a handler on incoming messages.

##### Usage:
```js
twilioConnector.on({method:'POST', path:'/sms'}, (event, app) => {
  console.log(event.req.body)
  // Example of console output for event.req.body:
  // {
  //   ToCountry = "US"
  //   ToState = "ID"
  //   SmsMessageSid = "SM9aca55a393c120f964cc49d91bfec52e"
  //   NumMedia = "0"
  //   ToCity = "DESMET"
  //   FromZip = "85004"
  //   SmsSid = "SM9aca55a393c120f964cc49d91bfec52e"
  //   FromState = "AZ"
  //   SmsStatus = "received"
  //   FromCity = "PHOENIX"
  //   Body = "msg line 1 line 2 line 3"
  //   FromCountry = "US"
  //   To = "+12082685987"
  //   ToZip = "99128"
  //   NumSegments = "1"
  //   MessageSid = "SM9aca55a393c120f964cc49d91bfec52e"
  //   AccountSid = "AC43820350f399443f2ab9a80ce59dc797"
  //   From = "+19282275501"
  //   ApiVersion = "2010-04-01"
  // }

  const messageReceived = event.req.body.Body
  const fromPhoneNumber = event.req.body.From
  console.log(`New SMS received from ${fromPhoneNumber}: ${messageReceived}`)

  if(messageReceived.includes('test')) {
    event.res.end("test successful")
  } else {
    event.res.end("Thanks for your message")
  }
})
```

#### Connector actions
This connector provides 2 types of actions for sending SMS or MMS via Twilio

##### sendSMS
send a message via Twilio:
```js
myTwilioConnector.sendSMS('<your-message>', '<to-phone-number>' )
```

##### sendMMS
send a media message via Twilio:
```js
myTwilioConnector.sendMMS('<your-message>', '<media-url>','<to-phone-number>' )
```

##### sdk
returns a Twilio client (using the connector config options)

See documentation in Twilio github: https://github.com/twilio/twilio-node

Example on how to use this connector can be [found here](https://github.com/reshufflehq/reshuffle/blob/master/examples/message/TwilioSendMessageExample.js).


Twitter Connector

# reshuffle-twitter-connector

[Code](https://github.com/reshufflehq/reshuffle-twitter-connector) |
[npm](https://www.npmjs.com/package/reshuffle-twitter-connector) |
[Code sample](https://github.com/reshufflehq/reshuffle-twitter-connector/tree/master/examples)

`npm install reshuffle-twitter-connector`

### Reshuffle Twitter Connector

This package contains a [Reshuffle](https://github.com/reshufflehq/reshuffle)
connector for connecting to Twitter as a
[Twitter Developer App](https://developer.twitter.com/en/docs/apps/overview).

The following example follows [Taylor Swift](https://twitter.com/taylorswift13) on
Twitter. When running it, every Swift tweet is printed to the
console:

```js
const { Reshuffle } = require('reshuffle')
const { TwitterConnector } = require('reshuffle-twitter-connector')

const app = new Reshuffle()
const twitter = new TwitterConnector(app, {
  customerKey: process.env.TWITTER_CUSTOMER_KEY,
  customerSecret: process.env.TWITTER_CUSTOMER_SECRET,
})

twitter.on({ follow: 'taylorswift13' }, async (event, app) => {
  for (const tweet of event.tweets) {
    console.log(tweet.text)
  }
})

app.start()

```

### Table of Contents

[Configuration](#configuration) Configuration options

#### Connector events:

[follow](#follow) Follow a user on Twitter

[search](#search) Track expressions in tweets

#### REST Operations:

[GET](#GET) Direct REST GET

[POST](#POST) Direct REST POST

##### <a name="configuration"></a>Configuration options

Note: You will need to sign up as a
[Twitter developer](https://developer.twitter.com/en/docs/developer-portal/overview) and proceed to create a
[Developer App](https://developer.twitter.com/en/docs/apps/overview). Then
navigate to the **Keys and Tokens** page to retrieve your **Customer API keys**.

```js
const app = new Reshuffle()
const twitter = new TwitterConnector(app, {
  customerKey: process.env.TWITTER_CUSTOMER_KEY,
  customerSecret: process.env.TWITTER_CUSTOMER_SECRET,
})
```

#### Connector events

##### <a name="follow"></a>Follow event

_Options:_

* `follow: string` A Twitter handle to follow, e.g. "taylorswift13" or "@taylorswift13"

_Example:_ Process tweets generated by a specific user

```js
async (event, app) => {
  for (const tweet of event.tweets) {
    console.log(tweet.text)
  }
})
```

The `event` object includes a single field named `tweets`, which is an array
of objects similar to this:

```js
{
  created_at: 'Sat Oct 17 15:01:59 +0000 2020',
  id: 1317480984862879700,
  id_str: '1317480984862879749',
  text: 'Along with the signed cd, some lucky purchasers of these items may even receive complimentary cat hair stuck inside… https://t.co/aQ139uxVJf',
  truncated: true,
  entities: { hashtags: [], symbols: [], user_mentions: [], urls: [ [Object] ] },
  source: '<a href="http://twitter.com/download/iphone" rel="nofollow">Twitter for iPhone</a>',
  in_reply_to_status_id: null,
  in_reply_to_status_id_str: null,
  in_reply_to_user_id: null,
  in_reply_to_user_id_str: null,
  in_reply_to_screen_name: null,
  user: {
    id: 17919972,
    id_str: '17919972',
    name: 'Taylor Swift',
    screen_name: 'taylorswift13',
    location: '',
    description: 'you drew stars around my scars',
    url: 'https://t.co/9Cbc2ywlrl',
    entities: { url: [Object], description: [Object] },
    protected: false,
    followers_count: 87316619,
    friends_count: 0,
    listed_count: 112877,
    created_at: 'Sat Dec 06 10:10:54 +0000 2008',
    favourites_count: 1031,
    utc_offset: null,
    time_zone: null,
    geo_enabled: false,
    verified: true,
    statuses_count: 528,
    lang: null,
    contributors_enabled: false,
    is_translator: false,
    is_translation_enabled: false,
    profile_background_color: 'C0DEED',
    profile_background_image_url: 'http://abs.twimg.com/images/themes/theme1/bg.png',
    profile_background_image_url_https: 'https://abs.twimg.com/images/themes/theme1/bg.png',
    profile_background_tile: false,
    profile_image_url: 'http://pbs.twimg.com/profile_images/1286270219980242945/70DWScEH_normal.jpg',
    profile_image_url_https: 'https://pbs.twimg.com/profile_images/1286270219980242945/70DWScEH_normal.jpg',
    profile_banner_url: 'https://pbs.twimg.com/profile_banners/17919972/1595563550',
    profile_link_color: '0084B4',
    profile_sidebar_border_color: 'FFFFFF',
    profile_sidebar_fill_color: 'DDEEF6',
    profile_text_color: '333333',
    profile_use_background_image: false,
    has_extended_profile: false,
    default_profile: false,
    default_profile_image: false,
    following: null,
    follow_request_sent: null,
    notifications: null,
    translator_type: 'regular'
  },
  geo: null,
  coordinates: null,
  place: null,
  contributors: null,
  is_quote_status: false,
  retweet_count: 19509,
  favorite_count: 157344,
  favorited: false,
  retweeted: false,
  possibly_sensitive: false,
  lang: 'en'
}
```

##### <a name="search"></a>Search event

_Options:_

* `search: string` Search term, e.g. "#music"

_Example:_ Process tweets containing the specified search term. 
(See [follow](#follow) for details of the event object)


```js
async (event, app) => {
  for (const tweet of event.tweets) {
    console.log(tweet.user.name, 'says:', tweet.text)
  }
})
```


#### REST Operations

##### <a name="GET"></a>GET action

_Definition:_

```ts
(
  path: string,
  qs?: object,
) => object | text
```

_Usage:_

```js
const response = await twitter.GET('statuses/user_timeline.json')
```

Send a GET request. Authenticate using the configured credentials, and
check for errors before returning the response data.

##### <a name="POST"></a>POST action

_Definition:_

```ts
(
  path: string,
  qs?: object,
  body?: object,
) => object | text
```

_Usage:_

```js
const response = await twitter.POST('friendships/create')
```

Send a POST request. Authenticate using the configured credentials, and
check for errors before returning the response data.

Note that most POST requests may require user level authorization and are
not supported by this connector at the moment.


Wix Connector

# reshuffle-wix-connector

[Code](https://github.com/reshufflehq/reshuffle-wix-connector) |
[npm](https://www.npmjs.com/package/reshuffle-wix-connector) |
[Code sample](https://github.com/reshufflehq/wix-external-collection)

`npm install reshuffle-wix-connector`

### Reshuffle Wix Connector

This package contains a [Reshuffle](https://github.com/reshufflehq/reshuffle)
connector to connect an external database collection for Wix as described in [Wix External Collections](https://www.wix.com/corvid/reference/spis/external-database-collections/external-database-collections).

The following example exposes an endpoint to return the number of items in the external collection.
It uses a postgres database configured with a Reshuffle pgsql connector

```js
const { Reshuffle } = require('reshuffle')
const { WixConnector } = require('@reshuffle/wix-connector')
const { PgsqlConnector } = require('reshuffle-pgsql-connector')

const app = new Reshuffle()

// The collection (or table) name
const COLLECTION = 'tasks'

const pg = new PgsqlConnector(app, {
  url: process.env.WIX_DB_URL
})

const wix = new WixConnector(app, {
  secret: process.env.RESHUFFLE_WIX_SECRET,
})

wix.on({ action: 'data/count' }, async (event, app) => {
  const { collectionName, filter } = event.request.body
  if (collectionName === COLLECTION) {
    const todos = await pg.query(`SELECT * from ${COLLECTION}`)
    event.response.status(200).json({ totalCount: todos.rowCount })
  } else {
    event.response.status(400).json({ 'message': 'Bad request. We only have todos' })
  }
})

app.start()
```

### Table of Contents

[Configuration Options](#configuration)

[Events](#events)

[Actions](#actions)

[Utility Functions](#utils)

### <a name="configuration"></a> Configuration options

```js
const app = new Reshuffle()
const wix = new WixConnector(app, {
  secret: process.env.RESHUFFLE_WIX_SECRET,
  webhookPath: process.env.RESHUFFLE_WIX_WEBHOOK,
})
```
Both `secret` and `webhookPath` are optional.

The secret is a string containing a shared secret as described in [Wix Authentication](https://www.wix.com/corvid/reference/spis/external-database-collections/external-database-collections/authentication)

When configuring the external database collection on Wix, you can define a `settings` object that is sent from Wix to the connector with every request.

To use (the optional) secret, configure the settings object to include:
```json
{
  "secret": ".....your secret....."
}
```
Wix then includes it in the incoming request like so:
```json
{
    "requestContext": {
        "settings": {
            "secret": ".....your secret....."
        },
        "instanceId": "...",
        "installationId": "...",
        "memberId": "...",
        "role": "..."
  }
}
``` 
If you do not define a secret in the connector configuration, then it will not expect one.

You can use the `webhookPath` to configure the url that Wix hits when it makes its calls to
your external database collection. The value of `webhookPath` will be appended to your runtime's
base url.
Left unprovided, `webhookPath` defaults to `/webhooks/wix`, so if your runtime runs at `https://example.com/` then
your full webhook path is `https://example.com/webhooks/wix`. This is the path you'll need
to register with Wix when defining a new external collection. See [Wix External Datbase instructions](https://support.wix.com/en/article/corvid-adding-and-deleting-an-external-database-collection).

### <a name="events"></a> Events

When Wix makes a call to the external collection, the connector captures these calls. 
It then triggers the corresponding event.

To listen to events coming from Wix, you'll need to capture them with the connector's `on`
function, providing a `WixEventConfiguration` to it.

```typescript
interface WixConnectorEventOptions {
  action: WixAction // See below
}

// Where...
type WixAction =
  'provision'
  | 'schemas/find'
  | 'schemas/list'
  | 'data/get'
  | 'data/count'
  | 'data/find'
  | 'data/insert'
  | 'data/update'
```
The connector triggers events of the following type:

```typescript
interface WixEvent {
  requestContext: WixRequestContext
  collectionName?: string
  filter?: string
  sort?: any
  skip?: number
  limit?: number
  itemId?: string
  item?: any
  body?: any
  action: WixAction
  request: Request // The http request from Wix
  response: Response // The http response object 
}

interface WixRequestContext {
  settings: Record<string, any>
  instanceId: string
  installationId: string
  memberId: string
  role: string
}
```
The description of all fields and events can be found [here](https://www.wix.com/corvid/reference/spis/external-database-collections/external-database-collections)

### <a name="actions"></a> Actions

This connector provides no actions.

### <a name="utils"></a> Utility Functions

The Wix connector provides some utility functions to help converting data between Wix and a database.
To use these functions, import them from the WixConnector package:
```js
const { parseFilter, wrapDates, unwrapDates } = require('@reshuffle/wix-connector')
```
#### `parseFilter`
Used to convert a `filter` object from Wix [See here](https://www.wix.com/corvid/reference/spis/external-database-collections/external-database-collections/data/find-items) to a PostgreSQL `WHERE` statement.

#### `unwrapDates`
Used to convert a date-structure coming in from Wix to a flat structure on the item object.
For example:
```typescript
// This is an item coming in from Wix:
const item = {
    "_id": "12345678-abcd-9876-fedc-a9876543210",
    "_owner": "77aa88bb-2c2c-d3d3-4e4e-ff55aa66bb77",
    "make": "BMW",
    "model": "i8",
    "year": 2020,
    "date_added": {
        "$date": "2020-01-01T21:00:00.000Z"
    }
}

const unwrapped = unwrapDates(item)
console.log(unwrapped)
//
{
    "_id": "12345678-abcd-9876-fedc-a9876543210",
    "_owner": "77aa88bb-2c2c-d3d3-4e4e-ff55aa66bb77",
    "make": "BMW",
    "model": "i8",
    "year": 2020,
    "date_added": "2020-01-01T21:00:00.000Z"
}
``` 

#### `wrapDates`
Used to convert a date-containing flat structure of an item object to
the date-structure Wix is expecting.

For example:
```typescript
// This is an item coming in from Wix:
const item = {
    "_id": "12345678-abcd-9876-fedc-a9876543210",
    "_owner": "77aa88bb-2c2c-d3d3-4e4e-ff55aa66bb77",
    "make": "BMW",
    "model": "i8",
    "year": 2020,
    "date_added": "2020-01-01T21:00:00.000Z"
}

const wrapped = wrapDates(item)
console.log(wrapped)
//
{
    "_id": "12345678-abcd-9876-fedc-a9876543210",
    "_owner": "77aa88bb-2c2c-d3d3-4e4e-ff55aa66bb77",
    "make": "BMW",
    "model": "i8",
    "year": 2020,
    "date_added": {
        "$date": "2020-01-01T21:00:00.000Z"
    }
}
``` 


Reshuffle Open Source on Elastic Beanstalk


This tutorial describes how to use the Elastic Beanstalk Command Line
Interface (EB CLI) to deploy and monitor a Node.js application.

## Prerequisites
Have the following installed:
-   Git
-   [EB CLI](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/eb-cli3-install.html)

## Steps to Deploy

Run the following commands from your project directory.
1.  Create an Elastic Beanstalk environment - setup a new EB application by executing the following command

    `$ eb init`
    
    You will be prompted to select the following details:

    a. A Region you would like to deploy the application in

    b. Provide user credentials

    c. Select a platform (Node.js)

    d. Set up SSH for your instances

2.  Deploy

    In this step you will create and deploy the application on EB using the CLI. The application will be deployed to one Amazon EC2 instance in an Auto Scaling group and use an Elastic Load Balancer.
    
    `$ eb create`
    
    You will be prompted to select the following details:

    a. Environment Name

    b. DNS name

    c. Load Balancer type

3.  Monitor your application
    You can open the application, monitor it and view health by using the following commands
   
    ```
    $ eb open 
    $ eb status 
    $ eb health
    ```

4.  Re-deploy
    In order to deploy an update you should commit your code locally and run the eb deploy command
    
    ```
    $ git add . 
    $ git commit -m "Your change."
    $ eb deploy
    ```

5.  Terminate your application
    The following command will delete the running resources and the application

    `$ eb terminate --all` 


More details can be found in the following links

* [Deploying Node.js applications to Elastic Beanstalk](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/create_deploy_nodejs.html)

* [Deploy and Monitor an Application from the Command Line](https://aws.amazon.com/getting-started/hands-on/deploy-app-command-line-elastic-beanstalk/)

* [EB CLI](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/eb-cli3-configuration.html)

Reshuffle Open Source on Azure


This tutorial describes how to use the Azure command line interface to deploy a Node.js application.

## Prerequisites
* An Azure subscription
* Git
* Node.js and npm 6.x or higher
* [Azure CLI](https://docs.microsoft.com/en-us/cli/azure/install-azure-cli)

## Steps to Deploy
1. Login to your Azure account

    `$ az login`

2. Create the Azure App Service to host your app code
    
    a. Create a resource group in a data center
    
    `$ az group create --name [RESOURCE_GROUP] --location [DATA_CENTRE_LOCATION]`

    The locations list can be found by running 

      `$ az account list-locations`
        
     e.g. `westus`

    b. Set the default resource group and region for subsequent commands

     `$ az configure --defaults group=[RESOURCE_GROUP] location=[DATA_CENTRE_LOCATION]`

    c. Create an app service plan that defines the underlying virtual machine used by the App Service

     `$ az appservice plan create --name [PLAN_NAME] --sku F1`

    The command above specifies a free hosting plan,`--sku F1`, which uses a shared virtual machine, and names the plan `[PLAN_NAME]` 
    
    Additional values for `--sku` can be found by typing 

    `$ az appservice list-locations --help`

    d. Create the App Service

    `$ az webapp create --name [APP_NAME] --plan [PLAN_NAME] --runtime "[NODE_VERSION]"`

    `[PLAN_NAME]`should be a unique name that eventually will be part of the app URL.
    Choose `[NODE_VERSION]` from the list when running `az webapp list-runtimes` e.g. `node|12-lts`

3. Deploy the App
In this step, you deploy your Node.js app code to Azure App Service using a basic process of pushing your local Git repository to Azure.
Please note that in order to pass the PORT to reshuffle, send it when starting the app
    ```
    const app = new Reshuffle()
    ...
    app.start(process.env.PORT)
    ```
    a. Initialize a local Git repository and make an initial commit
    ```
    $ git init 
    $ git add -A 
    $ git commit -m "Initial Commit"
    ```
    b. Set up deployment credentials in Azure, replacing `[USERNAME]` and `[PASSWORD]` with your credentials

    `$ az webapp deployment user set --user-name [USERNAME] --password [PASSWORD]`

    c. Retrieve the Git endpoint to which we want to push the app code

    `$ az webapp deployment source config-local-git --name [APP_NAME]`

    The output from the command is similar to the following:
    ```
    {
       "url": "https://username@msdocs-node-cli.scm.azurewebsites.net/msdocs-node-cli.git"
    }
    ```
    d. Set a new remote in Git named azure, using the URL from the previous step omitting the username. 

    `$ git remote add azure https://msdocs-node-cli.scm.azurewebsites.net/msdocs-node-cli.git`

    e. Deploy the app code from the Git repository to the App Service.

    `$ git push azure master`
    
4. View the App

    `$ az webapp browse --name [APP_NAME]`

5. View logs

    Enable and start logging

    `$ az webapp log tail --name [APP_NAME]`

    In order to view more detailed logs you can run

    `$ az webapp log config --name [APP_NAME] --resource-group [RESOURCE_GROUP] --detailed-error-messages true --level verbose`

6. Changes and redeploy
    Commit your code changes to the local Git repository, and then redeploy by pushing to Azure.
    ```
    $ git commit -a -m "Commit message"
    $ git push azure master
    ```

7. Cleanup
    Clean up the resources by running
    
    `$ az group delete --name [RESOURCE_GROUP]`

More details can be found in the following 
* [Deploy using Azure CLI](linkshttps://docs.microsoft.com/en-us/azure/developer/javascript/tutorial-vscode-azure-cli-node-01)
* [(CLI) documentation](https://docs.microsoft.com/en-us/cli/azure/?view=azure-cli-latest)


Building your own Reshuffle Connector

Reshuffle comes with several connectors that connect to common systems.
It is also extendable and lets you create your own connector.
You will want to create a connector when you need to integrate with a homegrown system,
or a service that does not have a connector yet.

The easiest way to create a new connector is you use the template in our
reshuffle-example-connector repo (coming soon!). You can also install and
extend the reshuffle-base-connector repo without using our example. Lastly,
if you like to do things all by yourself, you just need to create a class
and implement the following methods.

### The Connector class

```js
class MyConnector{

constructor(app, connectorOptions, id) {...}

start(app) {...}

stop() {...}

update(connectorOptions) {...}

on(eventOptions, handler, eventId) {...}
}
```

#### The `constructor(app, options, id)`

This method returns a new instance of this class.  
**Params:**

- **app** - a Reshuffle object that serves as the runtime.
- **options** - these are parameters that lets your connector know how to connect to the 3rd party service. You can pass the URL for that service for example.
- **id** - the identifier of this connector instance, after this connector is registered to a Reshuffle app, it can be accessed using this id from anywhere.

#### The `start(app)` method

This method is called by the reshuffle app object when the app itself starts.
When this method returns, this connector should be connected to the 3rd party service and ready to emit the relevant events and enable the specific actions.

**Params:**

- **app** - this is the Reshuffle app object, you can use this object to access app methods (see, _Reshuffle `app` methods, your controller can use_). Most importantly, your connector can use this `app` object to fire events using the `app.handleEvent(...)` method.

#### The `stop()` method

This method is called by the app when the service should stop. When this method returns, the service should disconnect from the service.

#### The `update(options)` method

This method is called when a connector information to a service changes. For example an update the a user password when connecting to an email server.

**Params:**

- **options** - these are parameters that lets your connector know how to connect to the 3rd party service. You can pass the URL for that service for example.

#### The `on(options, handler, eventid)` method

The on method configures events that this connector should emmit. Developers will use this method to define which events should a connector emit, after the `start(app)` method is called.
At the minimum, this method should create an EventConfiguration object, store it locally for future use, and return it at the end of this method call.
At the appropriate time after `start()` is called, the connector should emit events using the `app.handleEvent(eventName, event)` method (see, _Reshuffle `app` methods, your controller can use_).

**Params:**

- **options** - these are parameters that lets your connector know how to connect to the 3rd party service. You can pass the URL for that service for example.
- **handler** - this is the event listener function for this event configuration. You should pass this funtion to the `app` object using the `when(eventConfiguration, handler)` method.
- **eventid** - controllers should use this eventId when emitting this event using the `app.handleEvent(eventId, event)` method.
  Reshuffle uses this id to trigger the logic that is listening to this event. (see, _Reshuffle `app` methods, your controller can use_)

**Returns:**

- **EventConfiguration object** event configuration is a object that encapsulates all the information needed by the Connector to emit the relevant event.
  see EventConfiguration.js in this package for more information.

### Reshuffle `app` methods your controller can use.

The Reshuffle object, passed as an `app` in the `start(app)` method is very useful for developing a connector, because it provides several methods that the connector can use.

#### The `app.handleEvent(eventId, event)`

Connectors use this method to emit events when a preconfigured event happens in the 3rd service.
**Params:**

- **eventId** - this is an identifier of the event. Reshuffle uses that event name to trigger the right business logic.
  This event id is passed to the controller in the `on(options, eventid)` method, when the developer is configuring the event.
- **event** - this is a container that the controller can use to pass any information to the logic that is triggered as a result of this event.

##### _This is slightly complex so lets see an example:_

Lets say you are building an server monitor connector - your connector might emit the following events types:

- **server-down** - emits when a monitored server is down.
- **server-up** - emits when a monitored server that was down is back up.

here is how a developer will configure such an event to their logic:

```js
const { Reshuffle } = require('reshuffle')
const { MonitorConnector } = require('my-package')

const app = new Reshuffle()

const monitor = new MonitorConnector(app, { ip: '194.24.23.56' })

monitor.on(
  { type: 'server-down' },
  (event, app) => {
    console.log('server is down- ' + event.server_ip)
  },
  'server-crashed'
)

app.start()
```

When the `monitor.on({type:"server-down"},"server-crashed")` is called, the monitor controller register the EventConfiguration, stores the fact that it needs to monitor the server for that type of event, and returns the EventConfiguration object:

```js
on(options, handler, eventId) {
    if (!eventId) {
      eventId = `monitor/${options.ip}/${this.id}`
    }

    const event = new EventConfiguration(eventId, this, options)
    this.serverDownEventConfigurations[event.id] = event;
    // add the handler with the Reshuffle engine
    this.app.when(event,handler)
    return event
}
```

Next, when `app.start()` is called, the Reshuffle app object calls the monitor `start(app)` method, the monitor start monitoring the server.
When the server is down the monitor connector will call the `app.handleEvent(eventId, event)`:

```js
if (serverIsDown) {
  // go over all the event configuration for server down and trigger the event
  serverDownEventConfigurations.forEach((serverDownEventConfiguration) => {
    this.app.handleEvent(serverDownEventConfiguration.id, {
      server_ip: this.options.ip,
    })
  })
}
```

Reshuffle will then route the event, based on the eventId to the right logic that will print out `server is down- 194.24.23.56`, and the magic happens.

#### The `app.registerHTTPDelegate(path, delegate)`

Many connectors need to listen for HTTP calls. For example, a Slack connector needs to listen to incoming HTTP events emitted by the Slack events API.
Reshuffle helps you register to these calls and removes the need from the Connector to run it's own HTTP server.
At any time your controller call this method to regiter a delegate (most commonly itself) as a handler to that path.

```js
app.registerHTTPDelegate('/foo/bar', this)
```

The delegate object (in this case the controller itself) must implement a `async handle(req, res, next)` method that will be called by Reshuffle when this HTTP path is hit.

#### The `app.getPersistentStore()` method

Storing persistent information is a common need for many connectors.
Reshuffle abstracts the implementation of how the data is stored, provides several implementations the developer can choose from, and provides a standard interface for the connector.

More information on how to use the persistent store [can be found here](/docs/persistency).

If you have any questions, please feel free to contact us at [dev@reshuffle.com](mailto:dev@reshuffle.com)



Happy coding!

Reshuffle Connectors


Reshuffle is a framework that lets you connect to services, create integrations between systems, and build workflows using these services and systems.

Reshuffle achieves this by using **Connectors** as the connection mechanism to a 3rd party service or system. Each system Reshuffle connects to has their own connector. If you want to connect to Salesforce, for example, you would use the Salesforce connector.

Reshuffle ships with an existing ecosystem comprising several connectors you can use to connect to common systems. A list of these Reshuffle-provided connectors can be found in this page, and their code can be found in the various repositories [here](https://github.com/reshufflehq/).

The framework is extendable, meaning you can create connectors to services you use or even your own proprietary systems.
The process for building new connectors is described in the [manual](https://reshuffle.com/docs/connectors).

## Reshuffle Connectors

- [Twilio Connector](/docs/TwilioConnector)
- [NLP Connector](/docs/NLPConnector)
- [Slack Connector](/docs/SlackConnector)
- [SMTP Connector](/docs/SMTPConnector)
- [IMAP Connector](/docs/IMAPConnector)
- [Cron Connector](/docs/CronConnector)
- [Http Connector](/docs/HttpConnector)
- [Google Language Connector](/docs/GoogleLanguageConnector)
- [Google Sheets Connector](/docs/GoogleSheetsConnector)
- [AWS Elastic Transcoder Connector](/docs/AWSElasticTranscoderConnector)
- [AWS Lambda Connector](/docs/AWSLambdaConnector)
- [AWS S3 Connector](/docs/AWSS3Connector)
- [EIDR Connector](/docs/EIDRConnector)
- [Movies Anywhere Connector](/docs/MoviesAnywhereConnector)
- [Twitter Connector](/docs/TwitterConnector)


Deploying Reshuffle Open Source on Elastic Beanstalk


This tutorial describes how to use the Elastic Beanstalk Command Line
Interface (EB CLI) to deploy and monitor a Node.js application.

## Prerequisites

Have to following installed:
- Git
- [EB CLI](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/eb-cli3-install.html)

## Steps to Deploy

Run the following commands from your project directory.

1.  Create an Elastic Beanstalk environment - setup a new EB application by executing the following command

    `$ eb init`

    You will be prompted to select the following details:

        a. A Region you would like to deploy the application in

        b. Provide user credentials

        c. Select a platform (Node.js)

        d. Set up SSH for your instances

2.  Deploy

    In this step you will create and deploy the application on EB using the CLI. The application will be deployed to one Amazon EC2 instance in an Auto Scaling group and use an Elastic Load Balancing load balancer.

   `$ eb create`

    You will be prompted to select the following details:

        a. Environment Name

        b. DNS name

        c. Load Balancer type

3.  Monitor your application

    You can open the application, monitor it and view helth by using the following commands

    `$ eb open `

    `$ eb status `

    `$ eb health`

4.  Re-deploy

    In order to deploy an update you should commit locally your code and run the eb deploy command

    `$ git add . `

    `$ git commit -m "Your change."`

    `$ eb deploy`

5.  Terminate your application

    The following command will delete the running resources and the application

    `$ eb terminate --all` 

More details can be found in the following links

<https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/create_deploy_nodejs.html>

<https://aws.amazon.com/getting-started/hands-on/deploy-app-command-line-elastic-beanstalk/>

<https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/eb-cli3-configuration.html>


Getting Started


In this tutorial we will:

1. Install Reshuffle

2. Run a `Hello World` example

3. Create a Reshuffle app

## Installation

Reshuffle is a [Node.js](https://nodejs.org/en/) module available through the
[npm registry](https://www.npmjs.com/).

Before installing, [download and install Node.js](https://nodejs.org/en/download/).
Node.js 12 or higher is required.

If this is a brand new project, make sure to create a `package.json` first with
the [`npm init` command](https://docs.npmjs.com/creating-a-package-json-file).

Installation is done using the
[`npm install` command](https://docs.npmjs.com/getting-started/installing-npm-packages-locally):

```bash
$ npm install reshuffle
```

**_Done!_**

If you are familiar with npm, and are an advanced node programmer, you can skip the rest of this page,
and go straight to our [examples](https://github.com/reshufflehq/reshuffle/tree/master/examples) and connectors [documentation](https://reshuffle.com/docs/connectors).

### Run a `Hello World` example

This Hello World code is a super simple example on how to use Reshuffle.

```js
const { HttpConnector, Reshuffle } = require('reshuffle')

const app = new Reshuffle()

const connector = new HttpConnector(app)

connector.on({ method: 'GET', path: '/test' }, (event, app) => {
  event.res.end('Hello World!')
})

app.start()
```

Create or [copy](https://github.com/reshufflehq/reshuffle/tree/master/examples/http) the `HTTPExample.js` into your own `/example` folder.

#### Init npm:

```bash
$ npm init
```

_Note: No need to change the init wizard defaults_

### Install Reshuffle:

```bash
$ npm install reshuffle
```

### Run

```bash
$ node HTTPExample.js
```

got to http://localhost:8000/test

**Done!** More examples can be found in the `/examples` [folder](https://github.com/reshufflehq/reshuffle/tree/master/examples)

## Create your own app - add connectors to your Reshuffle app

Reshuffle apps are all about integrating 3rd party service and creating workflows out of them.

Connectors are NPM packages, so you can install [connectors](https://reshuffle.com/docs/connectors) to 3rd party systems, or [create your own connector](https://reshuffle.com/docs/building-connectors) to your own home grown system


Reshuffle Open Source on Google App Engine


Reshuffle Open Source on Google App Engine

This tutorial describes how to use the gcloud command line interface to deploy a Node.js application.

## Prerequisites
* [`gcloud` command-line tool](https://cloud.google.com/sdk)
* Google Cloud Platform billing account

## Steps to Deploy
1. Update the Cloud SDK
`$ gcloud components update`
2. Login to your Google account
`$ gcloud auth login`
3. Create a new project
`$ gcloud projects create [YOUR_PROJECT_ID] --set-as-default`
Replace `[YOUR_PROJECT_ID]` with a [string of characters](https://cloud.google.com/sdk/gcloud/reference/projects/create#PROJECT_ID) that uniquely identifies your project.
4. Verify that the project was created
`$ gcloud projects describe [YOUR_PROJECT_ID]`
5. Initialize your App Engine app with your project and choose its region
`$ gcloud app create --project=[YOUR_PROJECT_ID]`
Make sure billing is enabled for your project. A billing account needs to be linked to your project in order for the application to be deployed to App Engine.
6. Deploy the app
Change to the project directory and add an app.yaml file with the service’s configuration. As an example you can just add the following line, this will result in an automatic scaling service.
`runtime: nodejs12`
Deploy the app by running:
`$ gcloud app deploy`
7. View the live app at `https://PROJECT_ID.REGION_ID.r.appspot.com` or type
`$ gcloud app browse`
8. Cleanup
Delete the project from Google App Engine
`$ gcloud projects delete [YOUR_PROJECT_ID]`
Read more details about [deleting a project](https://reshuffle.atlassian.net/wiki/spaces/RES/pages/522878985/Enterprise+API+Engine+-+1+API+to+rule+them+all)

The above example is for automatic scaling, such a service can not be shutdown without a configuration change. For a manual scaling service, change the yaml file and deploy the app. The following is an example for a manual scaling configuration:
 ```
 runtime: nodejs
env: flex
manual_scaling:
  instances: 1
  ```
More details can be found in the following links:
1. [Quickstart](https://cloud.google.com/appengine/docs/standard/nodejs/quickstart)
2. [gcloud reference](https://cloud.google.com/sdk/gcloud/reference)

Intro to Reshuffle


[Reshuffle](https://www.npmjs.com/package/reshuffle) is a lightweight and open source integration framework. With Reshuffle, you can build integrations, workflows, and connect systems.

Here is a simple workflow that listens to a cron event that runs every 5 sec:

```js
const { Reshuffle, CronConnector } = require('reshuffle')
const app = new Reshuffle()
const cronConnector = new CronConnector(app)

cronConnector.on({ interval: 5000 }, (event, app) => {
  console.log('Hello World!')
})

app.start()
```

## Installation

```bash
$ npm install reshuffle
```

For a full step by step tutorial on how to install and use Reshuffle please visit [this page](https://reshuffle.com/docs/getting-started)

## Reshuffle Core Features

- Simple Express-style event handling model
- Separation of configuration and execution
- [Connectors](https://reshuffle.com/docs/connectors) to many SaaS services
- Highly extensible
- Focus on high performance

## Basic concepts

### Event Based System

At its core Reshuffle is an event-based engine, very similar to programming with a web server. You only need to define a function that will be called when an event is triggered.

[Events](https://reshuffle.com/docs/the-event-class) can be anything from a file change, S3 bucket update, a cron job timer, your own custom event, or even an HTTP call.

Here is an example of listening to an HTTP GET event on /test, using the HTTP connector:

```js
const { Reshuffle, HttpConnector } = require('reshuffle')
const app = new Reshuffle()
const httpConnector = new HttpConnector(app)

httpConnector.on({ method: 'GET', path: '/test' }, (event, app) => {
  event.res.end('Hello World!')
})
```

[Connectors](https://reshuffle.com/docs/the-connector-class) act _like_ [node eventEmitter](https://nodejs.org/api/events.html), so when the event is emitted the function is called. We will discuss Connectors in the next section.

More examples [are found here](https://github.com/reshufflehq/reshuffle/tree/master/examples)

### Reshuffle Connectors

A critical aspect of building integrations is configuring how to connect to different services we need to integrate with. With Reshuffle, you can configure Connector objects and inject them into your code.

Let's expand the example above and send a message to a Slack ‘reports’ channel every time someone triggers the 'HTTP/GET/test' event:

```js
const { Reshuffle, HttpConnector, SlackConnector } = require('reshuffle')
const app = new Reshuffle()

// the httpConnector does not require any config
const httpConnector = new HttpConnector(app)

// Slack connection configuration
const slackConnectionOptions = {
  APIToken: process.env.SLACK_AUTH_KEY,
  team: 'ourTeam',
}
// the 3rd parameter is used to identify the connector later on
const slackConnector = new SlackConnector(
  app,
  slackConnectionOptions,
  'connectors/Slack'
)

httpConnector.on({ method: 'GET', path: '/test' }, (event, app) => {
  app
    .getConnector('connectors/Slack')
    .send('Somebody triggered this event!', '#reports')
})

app.start()
```

Connector objects expose the API and Events that the external connector (connecting to anything from a DB to an ERP) provides. You can specify a connector id by providing an identifier in the connector constructor, and then access that connector using the `app.getConnector(connectorId)` method.

You noticed in the code sample above important information on how to connect to the 3rd party system (Slack in this case). Connectors are a way to separate the connection configuration from your code, configure a connection to a connector once and use it anywhere.

You can use the Connector object to take action on a remote service (such as adding a row to a CRM) and configure events that trigger when something happens in that system. We will show you how to do that in the next section.

You can read more about the connector class [here](https://reshuffle.com/docs/the-connector-class)

A full list of Connectors, and how to create your own Connector [can be found here](https://reshuffle.com/docs/connectors)

### Events

As we saw, connectors are basically adapters that connect external systems, such as Slack, Database, CRM, or any other system.
Connectors can be configured to emit a Reshuffle event, when a preconfigured thing happens in these systems.
To configure an event, use the `on(eventOptions, handler)` method of the relevant connector.

Here is how you would configure a SlackConnector to listen to a message from Slack:

```js
const { Reshuffle, SlackConnector } = require('reshuffle')
const app = new Reshuffle()

const connectionOptions = {
  APIToken: process.env.SLACK_AUTH_KEY,
  team: 'ourTeam',
}

const slackConnector = new SlackConnector(
  app,
  connectionOptions,
  'connectors/Slack'
)

const eventOptions = {
  event_type: 'new_message',
  channel: 'C6646754636',
  type: 'new_message',
}

slackConnector.on(eventOptions, (event, app) => {
  app.getConnector('connectors/Slack').reply('Thank you for your message!')
})

app.start()
```

It is the responsibility of the SlackConnector to listen to the messages in Slack and emit corresponding events in Reshuffle. Your code can listen to these events and run business logic.

As you can see, both the event creation and the business logic, use the same Connector configuration. This makes configuration easier to manage.

You can read more about the Event class [here](https://reshuffle.com/docs/the-event-class)

## Examples

Examples can be found in the `/examples` [folder](https://github.com/reshufflehq/reshuffle/tree/master/examples)


Reshuffle Datastore


The Reshuffle Datastore is a simple mechanism for managing state in services
and event handlers. It provides a simple key-value inteface and supports
multiple backends for data storage.

Datastore is used by different services to track state in systems they
connect to. For example, the Twitter API offers a stream of tweets generated
by users. The Twitter service uses datastore to track its last read position
in the stream, so as to avoid generating duplicate events for new tweets.
Another example is the AWS S3 service, which uses datastore to track the
contents of various S3 buckets, so that it can fire events when objects are
added or removed from them.

## Configuring Datastore
By default Reshuffle come with a in memory datastore (easy to use for dev and test,
 but not very persistent). You can set a file or a database persistent adapter like this:
```js
const { Pool } = require('pg')
const pool = new Pool()
const persistentStore = new SQLStoreAdapter(pool, 'reshuffledb')
app.setPersistentStore(persistentStore)
```
## Accessing the Datastore

After you set a persistent store, you can access it from any connector using the `app.getPersistentStore()`
method, or in the event handle logic using the `app.getPersistentStore()` method.

A code example of how to use the store can be found [here](https://github.com/reshufflehq/reshuffle/tree/master/examples/hello-world-persistent). 

Remember, if no store adapter in set, the default in-memory implementation is used.


## <a name="usingdatastore"></a>Using Datastore

Datastore provides a simple key-value interface, with a few additions that
make it possible to share data between servers. The following methods are
supported:

* `get` Retrieve a value for a specific key
* `set` Set the value for a specific key
* `update` Atomicalliy rean-modify-write a single key
* `remove` Delete a key from the datastore
* `list` List all keys

Datastore keys are simple JavaScript strings. You can read more about key
naming guidelines [below](#keynamespaces). Datastore values can be any
JSON-serializable JavaScript values, and cannot be `undefined`.

Following is a detailed description of datastore methods:

### Get method

_Definition_:

```ts
datastore.get(key: string) => any|undefined
```

_Usage_:

```js
const myValue = datastore.get('myKey')
```

Retrieve a single value from the datastore. If `key` does not exist in the
datastore, then `get` returns `undefined`.

### Set method

_Definition_:

```ts
datastore.set(key: string, value: any) => any
```

_Usage_:

```js
const myValue = datastore.get('myKey', 'myValue')
```

Set a single value in the datastore. `value` must be JSON-serializable and
cannot be `undefined`. For convenience, `set` returns the same value it
stores to allow chaining.

Note that if you wish to read, modify and write back a value to the datastore,
you should be using `update` instead of the combination of `get` and `set`.
Using this combination is not atomic, and my result in unexpected behavior in
cases Reshuffle is scaled to multiple servers.

### Update method

_Definition_:

```ts
type Updater = (currentValue: any|undefined) => any|undefined
datastore.update(key: string, updater: Updater) => any
```

_Usage_:

```js
const [OldCount, newCount] = datastore.update(
  'myCounter',
  (currentValue) => currentValue + 1,
)
```

Atomically update one value in the datastore. Instead of receiving the value
directly (like `set` does), `update` uses an updater method to calculate
the new value from the current value.

The updater function receives a single argument with the current value
associated with `key`. If the key does not exist in the datastore, the
updater is passed the value of `undefined`. The function then calculates
and returns the new value for the key. If no change is desired, the
function should return `undefined`.

This function can safely be used to read-modify-write values in the datastore.
Behind the scenes it uses locks and transactions to assure consistency, even
if called simultaneously by multiple Reshuffle servers. For example, if the
counter above is updated by two servers at the same time, `update` gurantees
that its value will increase by two (which is not guaranteed if using `get`
followed by a `set`).

The updater fucntion is allowed to perform IO operations, like accessing
remote APIs, while calculating the new value. Note that the datastore will
lock access to the key while the updater is running, so all other operations
on the key will block unil it is finished. Do not use overly lengthy
operations like invoking event handlers from inside the updater function.

### Remove method

_Definition_:

```ts
datastore.remove(key: string) => void
```

_Usage_:

```js
datastore.remove('myKey')
```

Delete `key` from the datastore.

### List method

_Definition_:

```ts
datastore.list() => string[]
```

_Usage_:

```js
for (const key of datastore.list()) {
  console.log(key)
}
```

List all keys in the datastore.



The Connector Class


Reshuffle have a wide rage of connectors that exposes events and action on 3rd party services. 

### Registering event handlers
A common use case of integrations and workflows is to register code that will be called when an event happens 
on a 3rd party system. Example can be an handler that is called when an email comes through a POP3 server, 
or a new customer is added to Salesforce. 

Using the appropriate service connector, you can register a handler using the `on(options, handler, eventId?)`method.

#### The  `on(options, handler, eventId?)` method
* ***options***: parameters used to define the event for example, in the CronService `{interval:5000}` will tell the connector to emit an event every 5 sec.
* ***handler***: this is the code of the event handler, when this event is emitted, the handler is called. 
* ***eventId***: an optional identifier that will be the key the Reshuffle app uses to map the event to the handler, automatically generated if not supplied.  

The `on` method is use to register event handlers, here is an example:
```js
const s3Connector = new AWSS3Connector(app, {
  accessKeyId: process.env.AWS_ACCESS_KEY_ID,
  secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
  bucket: process.env.AWS_BUCKET,
})

s3Connector.on({ type: 'ObjectAdded' }, async (event, app) => {
  console.log(event)
})
```
When a connector emits more than one event type, you must use the `{type:eventType}` to specify which type of event you are subscribing to. 

### Expose service actions
Each service may expose different actions you can preform on the remote service. 
Here is an example of exposing an endpoint that lists S3 object keys:

```js
httpConnector.on({ method: 'GET', path: '/list' }, async (event, app) => {
  const keys = await s3Connector.listObjectKeys()
  event.res.json(keys)
})
```
### Starting and stopping a connector. 
Each connector supports starting and stopping a connection to a service. 
In most use cases you do not need to call start or stop - the Reshuffle class automatically calls it when you call it's `start()` method,
and all connectors stop when the app execution end. 


The Event Class

 
 Reshuffle apps are **event driven**, so the event object plays a key role in the reshuffle app architecture. 
 
 The event class server to pass information from the connector into your event handler code:
 ```js
s3Connector.on({ type: 'ObjectAdded' }, async (event, app) => {
  console.log(event)
})
```
By convention, event information passed from the controller to the handler resided in a `event` parameter. 

Here is how an HTTPConnector event handler accesses the http `res` object:
```js
connector.on({ method: 'GET', path: '/test' }, (event, app) => {
  event.res.end('Hello World!')
})
``` 

Another common task for the event handler is to access the Reshuffle common services, through the app object:

Here is how an event handler accesses the common datastore from the event object:
```js
connector.on({ expression: '*/5 * * * * *' }, async (event, app) => {
  let store = app.getPersistentStore()
  // single server setup
  let times = (await store.get('scripts/times-said-hello')) || 0
  console.log(`Hello World! ${times} times.`)
  times++
  await store.set('scripts/times-said-hello', times)
})
``` 

Here is and example of a handler accessing the logger:
```js
connector.on({ expression: '*/5 * * * * *' }, (event, app) => {
  logger.info('an info')
  logger.warn('a warning')
  logger.error('an error')
})
```



The Reshuffle Class


The Reshuffle Class provides common services to Reshuffle connectors and event handlers.
It also serves as the event bus, routing events emitted from the connector and invoking the event handlers.

## Reshuffle class common services

### Common Datastore

Many times you need to store information as part of running your integration business logic.
The Reshuffle Class provides access to a common datastore.

#### Methods:

This method sets the datastore:

```js
setPersistentStore(persistentStore)
```

This method returns the datastore:

```js
getPersistentStore(persistentStore)
```

_Note:_ event handlers have a utility method attached to the Event they receive as a parameter, to access the datastore:
`app.getPersistentStore()`

#### Example:

Here is an example of how to use the datastore:

```js
const { Reshuffle, CronConnector, SQLStoreAdapter } = require('../..')
const { Pool } = require('pg')
const app = new Reshuffle()

const connector = new CronConnector(app)

// see https://node-postgres.com/features/connecting on how to configure the pool
const pool = new Pool()
const persistentStore = new SQLStoreAdapter(pool, 'reshuffledb')
app.setPersistentStore(persistentStore)

connector.on({ expression: '*/5 * * * * *' }, async (event, app) => {
  let store = app.getPersistentStore()
  // single server setup
  let times = (await store.get('scripts/times-said-hello')) || 0
  console.log(`Hello World! ${times} times.`)
  times++
  await store.set('scripts/times-said-hello', times)

  // for destributed setup with many reshuffle servers set() should be replaced with update()
  let safe_count_times =
    (await store.get('scripts/times-said-hello-safe_count_times')) || 0
  console.log(`Hello World! safe count = ${safe_count_times} times.`)
  await store.update(
    'scripts/times-said-hello-safe_count_times',
    (safe_count_times) => {
      return safe_count_times === undefined ? 1 : safe_count_times + 1
    }
  )
})

app.start()
```

More information about Reshuffle's datastore can be [found here](https://reshuffle.com/docs/persistency)

### Common Logging

The Reshuffle class can facilitate standard logging across Connectors and event handlers.

#### Example:

Here is how you would use the logging in a event handle:

```js
const { Reshuffle, CronConnector } = require('reshuffle')
const app = new Reshuffle()

const connector = new CronConnector(app)

const logger = app.getLogger()

// eslint-disable-next-line no-unused-vars
connector.on({ expression: '*/5 * * * * *' }, (event, app) => {
  logger.info('an info')
  logger.warn('a warning')
  logger.error('an error')
})

app.start()
```

### HTTP routing

Many connectors need to listen for HTTP calls. For example, a Slack connector needs to listen to incoming HTTP events emitted by the Slack events API.
Reshuffle helps you register to these calls and removes the need from the Connector to run it's own HTTP server.

#### Example:

At any time your controller can call this method to register a delegate (most commonly itself) as a handler to that path.

```js
app.registerHTTPDelegate('/foo/bar', delegate)
```

### Event Handling - handler execution

The Reshuffle class works as an event bus,
aggregating all the events coming from different services via the connectors, and executing the event handlers.

#### Example:

Here is how a connector emits an event to the Reshuffle event bus:

```js
this.app?.handleEvent(event.id, event)
```

The event ID is the identifier that maps to the right event handler, the event object is a `{"key":"value"}` to be passed to the event handler.

### Starting and stopping all the connectors

The `start(port)` and the `stop()` method serve to control the initialization and finalization of all the connectors in the system.
You should call `app.start()` to get connectors to work. See [the examples folder](https://github.com/reshufflehq/reshuffle/tree/master/examples)

Happy coding!


Documentation

Introduction

Classes

Connectors

Deployment

IMAP Connector

reshuffle-imap-connector

Reshuffle IMAP Connector

Configuration Options:

Connector events

Email Received (default)

Email Received Event configuration