# Marusia API [![GoDoc](https://godoc.org/github.com/neonxp/marusia?status.svg)](https://godoc.org/github.com/neonxp/marusia)

Неофициальное SDK навыков для голосового ассистента [Маруси](http://marusia.mail.ru/).

Документация: [https://pkg.go.dev/github.com/neonxp/marusia](https://pkg.go.dev/github.com/neonxp/marusia)

Пример: [/example/main.go](/example/main.go)

## Использование

Импорт библиотеки:

```go
import "github.com/neonxp/marusia"
```

Создание функции обработчика (имплементирующий интерфейс [marusia.MessageHandler](https://pkg.go.dev/github.com/neonxp/marusia?tab=doc#MessageHandler) ):

```go
func messageHandler(ctx context.Context, req *marusia.Request) (*marusia.Response, error) {
	...
}
```

Создание экземпляра API и http сервера, обрабатывающего колбеки:

```go
m := marusia.New(messageHandler)
server := http.Server{
    Addr:    ":8080",
    Handler: m.Handler(),
}
if err := server.ListenAndServe(); err != http.ErrServerClosed {
    log.Fatal(err)
}
```

Суть работы с API заключается в том, что при получении колбека с запросом типа [*marusia.Request](https://pkg.go.dev/github.com/neonxp/marusia?tab=doc#Request) в течении максимум 10 секунд следует ответить вернув сформированный объект типа [*marusia.Response](https://pkg.go.dev/github.com/neonxp/marusia?tab=doc#Response).

## Содержимое запроса

```go
type Request struct {
	Command           string 
	OriginalUtterance string 
	Type              string 
	Payload           Payload
	Nlu               struct {
		Tokens   []string    
		Entities []interface{}
	}
}
```

* Command — служебное поле: запрос пользователя, преобразованный для внутренней обработки Марусей. В ходе преобразования текст, в частности, очищается от знаков препинания, а числительные преобразуются в числа. При завершении скилла по команде "стоп", "выход" и т.д. в скилл будет передано "on_interrupt", чтобы у скилла была возможность попрощаться с пользователем.
* OriginalUtterance — полный текст пользовательского запроса, максимум 1024 символа.
* Type — тип ввода, обязательное свойство. Возможные значения: "SimpleUtterance" — голосовой ввод, "ButtonPressed" — нажатие кнопки.
* Payload — JSON, полученный с нажатой кнопкой от обработчика скилла (в ответе на предыдущий запрос), максимум 4096 байт.
* Nlu.Tokens — слова и именованные сущности, которые Маруся извлекла из запроса пользователя.
* Nlu.Entities — здесь пока будет пустой массив или какие-то экспериментальные вещи, на которые не стоит смотреть.

## Содержимое ответа

```go
type Response struct {
	Text       string    
	TTS        string    
	Buttons    []*button 
	EndSession bool      
}
```

Методы:

* NewResponse(text string) *Response - конструктор объекта, где text - текст ответа пользователю
* Response.SetText(text string) *Response - задание текста ответа
* Response.SetTTS(tts string) *Response - текст с раставленными ударениями (знак "+")
* Response.SetEndSession(endSession bool) *Response - задает признак конца диалога
* Response.AddButton(title string, payload Payload, URL string) *Response - добавляет кнопку в диалог