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 app is initialized the similar way as express app:
transit = require('transit-im')
app = transit()
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:
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
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:
console.log req.user
console.log req.command
console.log req.data
console.log req.handlers
console.log req.handler
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()
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 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"
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: "<>"
app.use transit.commandParser()
app.use transit.doNotWaitForResponse()
app.use transit.echo()
app.use transit.html2txt()
Introduces sessions (TBD, see example of usage )
app.use transit.sessions()
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()