API Reference

Table of Contents:

constants
errors
FormSet
QueryController
SessionStore

constants

constants.SESSION_VERSION

Version of session used by the library. Different libraries may use same version of the session, allowing the sessions to be interchangeable between them.

Kind: static constant of constants

errors

errors

errors.BusyError

BusyError

Kind: static class of errors

new exports.BusyError([message])

Object busy doing something already. Usually thrown when a form is already being processed. Error code is "EBUSY".

Param	Type	Default
[message]	`String` \| `Error`	`Busy`

errors.FormNotFoundError

FormNotFoundError

Kind: static class of errors

new exports.FormNotFoundError([message])

Form not found. Error code is "ENOFORM".

Param	Type	Description
[message]	`String` \| `Error`	If string, should be name of form.

errors.I18nError

I18nError

Kind: static class of errors

new exports.I18nError([message])

Error occurred during internationalization. Error code is "E18N";

Param	Type	Default
[message]	`String` \| `Error`	`I18n failed`

errors.QueryNotFoundError

QueryError

Kind: static class of errors

new exports.QueryNotFoundError([message])

Query not found in form. Error code is "ENOQUERY".

Param	Type	Default
[message]	`String` \| `Error`	`Query not found`

errors.SessionError

SessionError

Kind: static class of errors

new exports.SessionError([message])

Session error. Error code is "ESESS".

Param	Type	Default
[message]	`String` \| `Error`	`Session error`

FormSet

Kind: global class

FormSet

new FormSet([options])

Emits query(question, ref) event.

Param	Type	Default	Description
[options]	`Object`
[options.prefix]	`String`	`"form:"`	Prefix for session ID
[options.store]	`SessionStore`	`MemorySessionStore`	Session store.
[options.ttl]	`Number`	`+Infinity`	Time-To-Live for sessions. Ensure that the session store you use does supports using TTL-ed sessions.

formSet.getForms() ⇒ `Array.<Form>`

Return the added forms.

Kind: instance method of FormSet

formSet.addForm(name, queries, [options]) ⇒ `Form`

Add a new form to this set.

Kind: instance method of FormSet
Returns: Form - created form

Param	Type	Description
name	`String`	Name of the form e.g. "profile"
queries	`Array`	Queries to be asked to user
[options]	`Object`	Options
[options.cb(answers, ref)]	`function`	Invoked with the final answers, when the form has been completed.
[options.i18n(text, ctx, ref, done)]	`function`	Internationalization function.

formSet.processForm(name, chatID, ref, [options], done)

Process the message using a certain form.

If chatID is a Number, it is converted to string, using .toString().

If ref is a Function, it is invoked once and its return value used as the actual reference.

Kind: instance method of FormSet
Throws:

BusyError if form is already being processed.
FormNotFoundError if form is not found.
SessionError if session is incompatible, or any error thrown by session store.

Param	Type	Description
name	`String`	Name of form
chatID	`String` \| `Number`	Unique identifier for the originating chat
ref	`Object` \| `function`	Reference
[options]	`Object`	Options
[options.answers]	`Object`	Initial answers hash
done	`function`

Example (chatID as Number)

// the two invocations below are 'similar'
formset.processForm(name, "12345", ref);
formset.processForm(name, 12345, ref);

Example (FormNotFoundError)

// Assuming there's no form with the name '404'.
formset.processForm("404", chatID, ref, function(error) {
    assert.ok(error instanceof mau.errors.FormNotFoundError);
});

Example (BusyError)

// Assuming there's a form already being processed.
formset.processForm(name, chatID, ref, function(error) {
    assert.ok(error instanceof mau.errors.BusyError);
});

formSet.process(chatID, text, ref, done)

Process a message. This is a variant of FormSet#processForm() method. It tries to service the message using an active form, which if not found, a FormNotFoundError error is passed to done.

Kind: instance method of FormSet
Throws:

FormNotFoundError if form is not found.
SessionError if session is incompatible, or any error thrown by session store.

Param	Type	Description
chatID	`String` \| `Number`	Unique identifier for the originating chat
text	`String`	Text of the message
ref	`Object` \| `function`	Reference
done	`function`

Example

// Assuming there's a form named 'hello'
formset.process(chatID, text, ref, function(error) {
    if (error && error instanceof mau.errors.FormNotFoundError) {
        // There's NO active form.
        // Let's trigger the 'hello' form.
        formset.processForm("hello", chatID, text, ref, done);
    }
    // ...
});

formSet.cancel(chatID, done)

Cancel current form processing for chat.

Kind: instance method of FormSet
Throws:

SessionError if fails to cancel form processing

Todo

Test this method!

Param	Type	Description
chatID	`String` \| `Number`	Unique identifier for the originating chat
done	`function`	callback(error, removed); `removed` is a boolean indicating whether the form was actually removed.

QueryController

Kind: global class

QueryController

new QueryController()

A query controller allows us to move from one query to the next; supporting operations such as skipping to a target query.

new QueryController(formset, form, session, ref)

Throws:

QueryNotFoundError if current query is not found.

Param	Type	Description
formset	`FormSet`	FormSet
form	`Form`	Form
session	`Session`	Session
ref	`Object`	Reference

queryController.getAnswers() ⇒ `Object`

Retrieve an object/hash containing all the answers.

Kind: instance method of QueryController
Returns: Object - answers

queryController.getAnswer([name], [defaultValue]) ⇒ `*`

Retrieve an answer. If name is omitted/falsey, it returns answer for the current query. To use defaultValue, name must be specified.

Kind: instance method of QueryController
Returns: * - value
Throws:

QueryNotFoundError If the current query is not found.

Param	Type	Description
[name]	`String`	Name of query. This is actually a path.
[defaultValue]	`*`	Default value

queryController.setAnswer([name], val)

Set an answer. If name is omitted, it sets the answer for the current query.

Kind: instance method of QueryController
Throws:

QueryNotFoundError if current query is not found.

Param	Type	Description
[name]	`String`	Name of query. This is actually a path.
val	`*`	New value

queryController.unsetAnswer([name])

Unset an answer. If name is omitted, it unsets the answer for the current query.

Kind: instance method of QueryController
Throws:

QueryNotFoundError if current query is not found

Param	Type	Description
[name]	`String`	Name of query. This is actually a path.

queryController.skip(done)

Skip the current query.

Kind: instance method of QueryController

Param	Type
done	`function`

queryController.goto(name, done)

Skip to the query with name.

Kind: instance method of QueryController

Param	Type	Description
name	`String`	Name of query
done	`function`

queryController.retry([text], done)

Retry the current query i.e. do not advance to the next query. This should ONLY be used in post hooks.

Kind: instance method of QueryController

Param	Type	Description
[text]	`String`	Text
done	`function`

queryController.post(done)

Execute the post hook and advance. This should ONLY be used in pre hooks.

Kind: instance method of QueryController

Param	Type
done	`function`

queryController.text(id, [ctx], done)

Return the internalized text, if possible. Return null if can not be performed.

Kind: instance method of QueryController
Throws:

I18nError if i18n is unavailable.

Param	Type	Description
id	`String`	ID of the i18n text
[ctx]	`Object`	Context to be used in interpolation
done	`function`	callback(error, text)

queryController.stop(done)

Stop processing form at the current query.

Kind: instance method of QueryController

Param	Type
done	`function`

queryController.do(name, done)

Skip to the form with name.

Kind: instance method of QueryController
Todo

Test this method!

Param	Type	Description
name	`String`	Name of form
done	`function`

queryController.send(id, done)

Send text message.

Kind: instance method of QueryController
Todo

Test this method!
Wait for the message to actually be sent! Currently, the query event is fired and we move on without waiting for the event handler to report status of the sending operation.

Param	Type	Description
id	`String`	ID of the i18n text
done	`function`

queryController.setText(id)

Set the current query's text.

Kind: instance method of QueryController
Todo

Test this method!

Param	Type	Description
id	`String`	ID of the i18n text

SessionStore

SessionStore

sessionStore.get(sid, done)

Retrieve the session.

Kind: instance method of SessionStore

Param	Type	Description
sid	`String`	Session ID
done	`function`	callback(error, session)

sessionStore.put(sid, session, options, done)

Save session.

Kind: instance method of SessionStore

Param	Type	Description
sid	`String`	Session ID
session	`Object`	Session object
options	`Object`
options.ttl	`Number`	Session TTL. Equals `+Infinity` to have the session stored indefinitely.
done	`function`	callback(error)

sessionStore.del(sid, done)

Destroy session.

Kind: instance method of SessionStore

Param	Type	Description
sid	`String`	Session ID
done	`function`	callback(error, removed) `removed` is a boolean indicating whether the session has been removed.