golexa

README

golexa

A little Go library to easily handle Alexa custom skill requests, conforming to the official Alexa Skill Kit JSON reference. golexa handles all the heavy lifting, so you can concentrate on building great apps within minutes.

Install

go get github.com/b00giZm/golexa

or, if you prefer Glide

glide get github.com/b00giZm/golexa

Examples

Quickstart

Your first Alexa app in less than 10 lines of code.

import "github.com/b00giZm/golexa"

app := golexa.Default()
app.OnLaunch(func(a *golexa.Alexa, req *golexa.Request, session *golexa.Session) *golexa.Response {
        return a.Response().AddPlainTextSpeech("Welcome to my awesome app")
})

response := app.Process(json)

You can attach several handlers to deal with the different Alexa request types:

LaunchRequest handler

app.OnLaunch(func(a *Alexa, req *Request, session *Session) *Response) { ... })

IntentRequest handler

app.OnIntent(func(a *Alexa, intent *Intent, req *Request, session *Session) *Response) { ... })

SessionEndedRequest handler

app.OnSessionEnded(func(a *Alexa, req *Request, session *Session) *Response) { ... })

Every handler has a *golexa.Alexa pointer as first parameter, which gives you access to several convenience methods for quickly building response objects.

Your Own Handler Types

When building bigger apps, using the built-in callback handlers can be a bit cumbersome, especially if you have lots of different intents. For this special case, golexa provides several interfaces to implement for your own handlers:

type Handler interface{}

type LaunchHandler interface {
	Handler
	HandleLaunch(a *Alexa, req *Request, session *Session) *Response
}

type IntentHandler interface {
	Handler
	HandleIntent(a *Alexa, intent *Intent, req *Request, session *Session) *Response
}

type SessionEndedHandler interface {
	Handler
	HandleSessionEnded(a *Alexa, req *Request, session *Session) *Response
}

With these interfaces and the Init() method of golexa.Alexa, you can have one handler for each intent, which is a much cleaner solution than having a big handler with lots of if else statements:

myHandlers := []golexa.Handler{
        myFooIntentHandler,
        myBarIntentHandler,
        ...
}

app := golexa.Init(myHandlers)
response := app.Process(json)

Those handlers are processed in the order in which they were provided. The processing goes on until one of the handlers return a valid *golexa.Reponse. If a handler can't handle a specific request, it can just return nil and the next consecutive handler is called.

(by the way: You can of course provide your own handlers for LaunchRequest and SessionEndedRequest inside the Init() slice, but remember that there can be only one LaunchRequest handler and just one SessionEndedRequest handler, which means that if you provide several of them, all but the very last one will be discarded.)

Apex Usage

The main motivation for this library was to have something which plays nicely with the awesome Apex toolchain and their Golang bridge for AWS Lambda:

package main

import (
        "github.com/apex/go-apex"
        "github.com/b00giZm/golexa"
)

func main() {
        apex.HandleFunc(func(event json.RawMessage, ctx *apex.Context) (interface{}, error) {
                app := golexa.Default()
                app.OnLaunch(func(a *golexa.Alexa, req *golexa.Request, session *golexa.Session) *golexa.Response {
                        return a.Response().AddPlainTextSpeech("Welcome to my awesome app")
                })
        
                return app.Process(event)
        })
}

Boom! Done 🎉

Development

Prerequisites:

• Go >= 1.6.2
• Glide >= 0.10.2

Fork and clone this repository

cd $GOATH/src/github.com/b00giZm
git clone https://github.com/b00giZm/golexa.git

Install dependencies via Glide

glide install

Run tests

go test

Maintainer

Pascal Cremer

• Email: hello@codenugget.co
• Twitter: @b00gizm
• Web: http://codenugget.co

License

The MIT License (MIT)

Copyright (c) 2016 Pascal Cremer

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Documentation

Index

• Constants
• type Alexa
  • func Default() *Alexa
  • func Init(handlers []Handler) *Alexa
  • func (a *Alexa) OnIntent(...)
  • func (a *Alexa) OnLaunch(handler func(a *Alexa, req *Request, session *Session) *Response)
  • func (a *Alexa) OnSessionEnded(handler func(a *Alexa, req *Request, session *Session) *Response)
  • func (a *Alexa) Process(msg json.RawMessage) (*Response, error)
  • func (a *Alexa) Response() *Response
• type Card
• type Event
• type Handler
• type Intent
• type IntentHandler
• type IntentHandlerFunc
  • func (fn IntentHandlerFunc) HandleIntent(a *Alexa, intent *Intent, req *Request, session *Session) *Response
• type LaunchHandler
• type LaunchHandlerFunc
  • func (fn LaunchHandlerFunc) HandleLaunch(a *Alexa, req *Request, session *Session) *Response
• type OutputSpeech
• type Reprompt
• type Request
• type Response
  • func (r *Response) AddLinkAccountCard() *Response
  • func (r *Response) AddPlainTextReprompt(text string) *Response
  • func (r *Response) AddPlainTextSpeech(text string) *Response
  • func (r *Response) AddSSMLReprompt(ssml string) *Response
  • func (r *Response) AddSSMLSpeech(ssml string) *Response
  • func (r *Response) AddSessionAttributes(attributes SessionAttributes) *Response
  • func (r *Response) AddSimpleCard(title, content string) *Response
  • func (r *Response) AddStandardCard(title, text, smallImageUrl, largeImageUrl string) *Response
  • func (r *Response) KeepSessionAlive() *Response
• type Session
• type SessionAttributes
• type SessionEndedHandler
• type SessionEndedHandlerFunc
  • func (fn SessionEndedHandlerFunc) HandleSessionEnded(a *Alexa, req *Request, session *Session) *Response
• type Slot

Constants

const (
	REQUEST_TYPE_LAUNCH = "LaunchRequest"
	REQUEST_TYPE_INTENT = "IntentRequest"
	REQUEST_TYPE_ENDED  = "SessionEndedRequest"

	REASON_USER_INITIATED         = "USER_INITIATED"
	REASON_ERROR                  = "ERROR"
	REASON_EXCEEDED_MAX_REPROMPTS = "EXCEEDED_MAX_REPROMPTS"
)

const (
	OUTPUT_SPEECH_TYPE_PLAIN = "PlainText"
	OUTPUT_SPEECH_TYPE_SSML  = "SSML"

	CARD_TYPE_SIMPLE       = "Simple"
	CARD_TYPE_STANDARD     = "Standard"
	CARD_TYPE_LINK_ACCOUNT = "LinkAccount"
)

Types

type Alexa

type Alexa struct {
	// contains filtered or unexported fields
}

func Default

func Default() *Alexa

func Init

func Init(handlers []Handler) *Alexa

func (*Alexa) OnIntent

func (a *Alexa) OnIntent(handler func(a *Alexa, intent *Intent, req *Request, session *Session) *Response)

func (*Alexa) OnLaunch

func (a *Alexa) OnLaunch(handler func(a *Alexa, req *Request, session *Session) *Response)

func (*Alexa) OnSessionEnded

func (a *Alexa) OnSessionEnded(handler func(a *Alexa, req *Request, session *Session) *Response)

func (*Alexa) Process

func (a *Alexa) Process(msg json.RawMessage) (*Response, error)

func (*Alexa) Response

func (a *Alexa) Response() *Response

type Card

type Card struct {
	Type      string     `json:"type"`
	Title     string     `json:"title,omitempty"`
	Content   string     `json:"content,omitempty"`
	Text      string     `json:"text,omitempty"`
	ImageUrls *imageUrls `json:"image,omitempty"`
}

type Event

type Event struct {
	Version string  `json:"version"`
	Session Session `json:"session"`
	Request Request `json:"request"`
}

type Handler

type Handler interface{}

type Intent

type Intent struct {
	Name  string          `json:"name"`
	Slots map[string]Slot `json:"slots"`
}

type IntentHandler

type IntentHandler interface {
	Handler
	HandleIntent(a *Alexa, intent *Intent, req *Request, session *Session) *Response
}

type IntentHandlerFunc

type IntentHandlerFunc func(a *Alexa, intent *Intent, req *Request, session *Session) *Response

func (IntentHandlerFunc) HandleIntent

func (fn IntentHandlerFunc) HandleIntent(a *Alexa, intent *Intent, req *Request, session *Session) *Response

type LaunchHandler

type LaunchHandler interface {
	Handler
	HandleLaunch(a *Alexa, req *Request, session *Session) *Response
}

type LaunchHandlerFunc

type LaunchHandlerFunc func(a *Alexa, req *Request, session *Session) *Response

func (LaunchHandlerFunc) HandleLaunch

func (fn LaunchHandlerFunc) HandleLaunch(a *Alexa, req *Request, session *Session) *Response

type OutputSpeech

type OutputSpeech struct {
	Type string `json:"type"`
	Text string `json:"text,omitempty"`
	SSML string `json:"ssml,omitempty"`
}

type Reprompt

type Reprompt struct {
	OutputSpeech OutputSpeech `json:"outputSpeech,omitempty"`
}

type Request

type Request struct {
	Id        string    `json:"requestId"`
	Type      string    `json:"type"`
	Timestamp timestamp `json:"timestamp"`
	Intent    Intent    `json:"intent,omitempty"`
	Reason    string    `json:"reason,omitempty"`
}

type Response

type Response struct {
	Version           string            `json:"version"`
	SessionAttributes SessionAttributes `json:"sessionAttributes,omitempty"`
	Response          innerResponse     `json:"response"`
}

func (*Response) AddLinkAccountCard

func (r *Response) AddLinkAccountCard() *Response

func (*Response) AddPlainTextReprompt

func (r *Response) AddPlainTextReprompt(text string) *Response

func (*Response) AddPlainTextSpeech

func (r *Response) AddPlainTextSpeech(text string) *Response

func (*Response) AddSSMLReprompt

func (r *Response) AddSSMLReprompt(ssml string) *Response

func (*Response) AddSSMLSpeech

func (r *Response) AddSSMLSpeech(ssml string) *Response

func (*Response) AddSessionAttributes

func (r *Response) AddSessionAttributes(attributes SessionAttributes) *Response

func (*Response) AddSimpleCard

func (r *Response) AddSimpleCard(title, content string) *Response

func (*Response) AddStandardCard

func (r *Response) AddStandardCard(title, text, smallImageUrl, largeImageUrl string) *Response

func (*Response) KeepSessionAlive

func (r *Response) KeepSessionAlive() *Response

type Session

type Session struct {
	Id          string            `json:"sessionId"`
	IsNew       bool              `json:"new"`
	Attributes  SessionAttributes `json:"attributes"`
	Application application       `json:"application"`
	User        user              `json:"user"`
}

type SessionAttributes

type SessionAttributes map[string]interface{}

type SessionEndedHandler

type SessionEndedHandler interface {
	Handler
	HandleSessionEnded(a *Alexa, req *Request, session *Session) *Response
}

type SessionEndedHandlerFunc

type SessionEndedHandlerFunc func(a *Alexa, req *Request, session *Session) *Response

func (SessionEndedHandlerFunc) HandleSessionEnded

func (fn SessionEndedHandlerFunc) HandleSessionEnded(a *Alexa, req *Request, session *Session) *Response

type Slot

type Slot struct {
	Name  string `json:"name"`
	Value string `json:"value"`
}