imubot/docs/adapters/development.md

A simple helpful bot.

---
layout: docs
permalink: /docs/adapters/development/index.html
---

# Adapter Basics

All adapters inherit from the Adapter class in the `src/adapter.coffee` file.  There are certain methods that you will want to override.  Here is a basic stub of what an extended Adapter class would look like:

```coffee
class Sample extends Adapter

  constructor: ->
    super
    @bot.logger.info "Constructor"

  send: (envelope, strings...) ->
    @bot.logger.info "Send"

  reply: (envelope, strings...) ->
    @bot.logger.info "Reply"

  run: ->
    @bot.logger.info "Run"
    @emit "connected"
    user = new User 1001, name: 'Sample User'
    message = new TextMessage user, 'Some Sample Message', 'MSG-001'
    @bot.receive message


exports.use = (bot) ->
  new Sample bot
```

# Setting Up Your Development Environment

1. Create a new folder for your adapter `mubot-sample`
  - `mkdir mubot-sample`
2. Change your working directory to `mubot-sample`
  - `cd mubot-sample`
3. Run `npm init` to create your package.json
  - make sure the entry point is `src/sample.coffee`
4. Add your `.gitignore` to include `node_modules`
5. Edit the `src/sample.coffee` file to include the above stub for your adapter
6. Edit the `package.json` to add a peer dependency on `mubot`

  ```json
  "dependencies": {
  },
  "peerDependencies": {
    "mubot": ">=2.0"
  },
  "devDependencies": {
    "coffee-script": ">=1.2.0"
  }
  ```
  
7. Generate your Mubot using the `yo mubot` [command](https://mubot.github.com/docs/)
8. Change working directories to the `mubot` you created in step 7.
9. Now perform an `npm link` to add your adapter to `mubot`
  - `npm link ../mubot-sample`
10. Run `mubot -a sample`

# Gotchas

There is a an open issue in the node community around [npm linked peer dependencies not working](https://github.com/npm/npm/issues/5875).  To get this working for our project you will need to do some minor changes to your code.

1. For the import in your `mubot-sample` adapter, add the following code
```coffee
try
  {Bot,Adapter,TextMessage,User} = require 'mubot'
catch
  prequire = require('parent-require')
  {Bot,Adapter,TextMessage,User} = prequire 'mubot'
  ```
2. In your `mubot-sample` folder, modify the `package.json` to include the following dependency so this custom import mechanism will work
```json
  "dependencies": {
    "parent-require": "^1.0.0"
  }
  ```
3. Now try running `mubot -a sample` again and see that the imports are properly loaded.
4. Once this is working properly, you can build out the functionality of your adapter as you see fit.  Take a look at some of the other adapters to get some ideas for your implementation.
  - Once packaged and deployed via `npm`, you won't need the dependency in `mubot` anymore since the peer dependency should work as an official module.