api.md

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
  • .BusyError
    • new exports.BusyError([message])
  • .FormNotFoundError
    • new exports.FormNotFoundError([message])
  • .I18nError
    • new exports.I18nError([message])
  • .QueryNotFoundError
    • new exports.QueryNotFoundError([message])
  • .SessionError
    • new exports.SessionError([message])

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])
  • .getForms() ⇒ Array.<Form>
  • .addForm(name, queries, [options]) ⇒ Form
  • .processForm(name, chatID, ref, [options])
  • .process(chatID, text, ref)
  • .cancel(chatID)
  • ._emitQuery(question, ref)

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)]	function	Internationalization function.

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

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

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).catch(function(error) {
    assert.ok(error instanceof mau.errors.FormNotFoundError);
});

Example (BusyError)

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

formSet.process(chatID, text, ref)

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 thrown.

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

Example

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

formSet.cancel(chatID)

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

formSet._emitQuery(question, ref)

Emits the query event.

Kind: instance method of FormSet

Param	Type	Description
question	Object	Query
ref	Object	Reference

---

QueryController

Kind: global class

• QueryController
  • new QueryController()
  • new QueryController(formset, form, session, ref)
  • .getAnswers() ⇒ Object
  • .getAnswer([name], [defaultValue]) ⇒ *
  • .setAnswer([name], val)
  • .unsetAnswer([name])
  • .skip()
  • .goto(name)
  • .retry([text])
  • .post()
  • .text(id, [ctx])
  • .stop()
  • .do(name)
  • .send(id)
  • .setText(id)

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()

Skip the current query.

Kind: instance method of QueryController

queryController.goto(name)

Skip to the query with name.

Kind: instance method of QueryController

Param	Type	Description
name	String	Name of query

queryController.retry([text])

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

queryController.post()

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

Kind: instance method of QueryController

queryController.text(id, [ctx])

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

queryController.stop()

Stop processing form at the current query.

Kind: instance method of QueryController

queryController.do(name)

Skip to the form with name.

Kind: instance method of QueryController
Todo

• Test this method!

Param	Type	Description
name	String	Name of form

queryController.send(id)

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

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
  • .get(sid) ⇒ Promise.<Session>
  • .put(sid, session, options) ⇒ Promise.<void>
  • .del(sid) ⇒ Promise.<boolean>

sessionStore.get(sid) ⇒ Promise.<Session>

Retrieve the session.

Kind: instance method of SessionStore

Param	Type	Description
sid	String	Session ID

sessionStore.put(sid, session, options) ⇒ Promise.<void>

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.

sessionStore.del(sid) ⇒ Promise.<boolean>

Destroy session.

Kind: instance method of SessionStore
Returns: Promise.<boolean> - Resolves to a boolean indicating whether the session has been removed.

Param	Type	Description
sid	String	Session ID