transit.doc.coffee

transit is a express-like framework for im bots. It allows to process the commands received by ICQ (or other IM service) then interpret them and respond somehow to the user. Also it may send some messages to the users in background, not only as response to the request.

In general it works the following way:

         'hello'   Middleware   (req, res)                 sendBack 'hi!'
Client -----------> Middleware -----------> User handler ---------------\
                     Middleware                                         |
                                                                        |
            '<b>HI!</b>'            Formatter                           |
Client <---------------------------- Formatter <------------------------/
                                      Formatter

Transit application initialization

transit app is initialized the similar way as express app:

transit = require('transit-im')
app = transit()

Clients

Client provides interface between end user and transit - receives messages and allows to send response back.

Client shall be registered with use method call. There shall be an object with several methods defined:

app.use {

install is called by transit

  install: (transit) ->
    transit.client @

The provided callback shall be called when external client sends a message to server Its signature is function(userId, data, callback)

  receive: (@callback) ->

start method shall start listening to the external clients and call provided callback

  start: ->

sendBack method is used to send data back to client

  sendBack: (userId, data, cb) ->
}

Learn more on example of command line client

There are 2 builtin clients:

1. Command line client
2. ICQ client

Middleware

Middleware is called on each request before your application logic. It could be used to perform some preliminary actions, extract something, and so on.

Middleware shall be registered with use method call. There are 2 ways to define middleware

function middleware

It accepts Request object, Response object and next callback. next callback shall be called anyway, otherwise message will not be processed.

app.use (req, res, next) ->

The following properties are available in request by default:

• user - user id (ICQ number, for example)
• command - special command sent by client. For example 'exit' is sent when user logs out
• data - string message from end-user. May be undefined in case of command.
• handlers - list of user handlers. Use it if you'd like to write your own command parser
• handler - is user handler that will be called to process this message

  console.log req.user
  console.log req.command
  console.log req.data
  console.log req.handlers
  console.log req.handler

• session - user's session object. Exists only when sessions middleware is included.

  console.log req.session

You may change properties of request or response objects, but not by direct assignment - instead you need to call 'attr' method

  req.data = "[" + req.data + "]"         # WRONG
  req.attr("data", "[" + req.data + "]")  # Right

With Response object you may send something back to user. You do not need to specify user id

  res.sendBack "Data received, processing..."

Do not forget to call the next()!

  next()

object middleware

You need to define 'install' method which shall return middleware function. Install method accepts transit application instance.

app.use {
  install: (transit) ->

You may use it to add new properties to request/response. Without this extension you'll get error if you call 'attr' with unknown attrbute name

    transit.extendRequest "myRequestProperty"
    (req, res, next) ->
      req.attr "myRequestProperty", "dummy"
      next()
}

User handler

User handler is what your application do on specific command.

Initially you may define global handler which is called on each command.

app.receive (req, res) ->
  res.sendBack "Echoed: #{req.data}"

Note that for user handler you do not have 'next' callback. Instead you need to call one of the Response object methods - sendBack if you'd like to send something to client or done if not.

If you set up special middleware for command parsing then you may provide user handlers for specific commands.

There is a builtin middleware for that purposes - command parser

app.use transit.commandParser
app.receive 'hello', (req, res) -> res.sendBack 'hi'
app.receive 'iam {name}', (req, res) -> res.sendBack "hi #{req.name}"
app.receive 'wishes {{list}}', (req, res) -> res.sendBack "your wish list has #{req.list.length} items"

Learn more

Formatter

Before sending data back to client you may want to format it somehow. You may define formatters for that purpose:

niceFormat = (data, options, callback) ->
  braces = options?.braces ? "[]"
  formattedData = braces[0] + data + braces[1]
  callback null, formattedData

app.formatOutput niceFormat

Then it will be used when you call sendBack

app.sendBack 11, "hi!", ->
app.receive (req, res) ->
  res.sendBack req.data, braces: "<>"

Or you may define several formatters with their own names and call them by name

app.formatOutput "niceFormat", niceFormat

app.sendBack.niceFormat 11, "hi!", ->
app.receive (req, res) ->
  res.niceFormat req.data, braces: "<>"

Learn more

Builtin middlewares/formatters

Command parser

app.use transit.commandParser()

Do not wait for response

app.use transit.doNotWaitForResponse()

Echoes all messages

app.use transit.echo()

Converts html to txt

app.use transit.html2txt()

Introduces sessions (TBD, see example of usage )

app.use transit.sessions()

Shows help on commands

app.use transit.autohelp()

Allows users to define aliases (TBD, see example of usage)

app.use transit.alias()

Allows to compose a chain of formatters

app.use transit.chain()

Examples

1. for ICQ, but it requires real ICQ account to use.
2. for command line client