Merge branch 'master' into export-links-field

Author: marcel corso gonzalez

.travis.yml

@@ -1,10 +1,10 @@
 language: go
-
 go:
+  - 1.7
   - 1.8
+  - 1.9
   - stable
   - master
-
 matrix:
   allow_failures:
     - go: master

README.md

@@ -7,7 +7,7 @@ This repository contains the open source Go client for MessageBird's REST API. D
 Requirements
 ------------
 - [Sign up](https://www.messagebird.com/en/signup) for a free MessageBird account
-- Create a new access key in the developers sections
+- Create a new access key in the [dashboard](https://dashboard.messagebird.com/en-us/developers/access).
 - An application written in Go to make use of this API
 
 Installation
@@ -26,51 +26,104 @@ Here is a quick example on how to get started. Assuming the **go get** installat
 import "github.com/messagebird/go-rest-api"
 ```
 
-Then, create an instance of **messagebird.Client**:
+Then, create an instance of **messagebird.Client**. It can be used to access the MessageBird APIs.
 
 ```go
-client := messagebird.New("test_gshuPaZoeEG6ovbc8M79w0QyM")
-```
+// Access keys can be managed through our dashboard.
+accessKey := "your-access-key"
 
-Now you can query the API for information or send data. For example, if we want to request our balance information you'd do something like this:
+// Create a client.
+client := messagebird.New(accessKey)
 
-```go
-// Request the balance information, returned as a Balance object.
+// Request the balance information, returned as a balance.Balance object.
 balance, err := balance.Read(client)
 if err != nil {
-	switch errResp := err.(type) {
-	case messagebird.ErrorResponse:
-		for _, mbError := range errResp.Errors {
-			fmt.Printf("Error: %#v\n", mbError)
-		}
-	}
-
+	// Handle error.
 	return
 }
 
-fmt.Println("  payment :", balance.Payment)
-fmt.Println("  type    :", balance.Type)
-fmt.Println("  amount  :", balance.Amount)
+// Display the results.
+fmt.Println("Payment: ", balance.Payment)
+fmt.Println("Type:", balance.Type)
+fmt.Println("Amount:", balance.Amount)
 ```
 
 This will give you something like:
-```shell
+
+```bash
 $ go run example.go
-  payment : prepaid
-  type    : credits
-  amount  : 9
+Payment: prepaid
+Type: credits
+Amount: 9
 ```
 
 Please see the other examples for a complete overview of all the available API calls.
 
+Errors
+------
+When something goes wrong, our APIs can return more than a single error. They are therefore returned by the client as "error responses" that contain a slice of errors.
+
+It is important to notice that the Voice API returns errors with a format that slightly differs from other APIs.
+For this reason, errors returned by the `voice` package are of type `voice.ErrorResponse`. It contains `voice.Error` structs. All other packages return `messagebird.ErrorResponse` structs that contain a slice of `messagebird.Error`.
+
+An example of "simple" error handling is shown in the example above. Let's look how we can gain more in-depth insight in what exactly went wrong:
+
+```go
+import "github.com/messagebird/go-rest-api"
+import "github.com/messagebird/go-rest-api/sms"
+
+// ...
+
+_, err := sms.Read(client, "some-id")
+if err != nil {
+	mbErr, ok := err.(messagebird.ErrorResponse)
+	if !ok {
+		// A non-MessageBird error occurred (no connection, perhaps?) 
+		return err
+	}
+	
+	fmt.Println("Code:", mbErr.Errors[0].Code)
+	fmt.Println("Description:", mbErr.Errors[0].Description)
+	fmt.Println("Parameter:", mbErr.Errors[0].Parameter)
+}
+```
+
+`voice.ErrorResponse` is very similar, except that it holds `voice.Error` structs - those contain only `Code` and `Message` (not description!) fields:
+
+```go
+import "github.com/messagebird/go-rest-api/voice"
+
+// ...
+
+_, err := voice.CallFlowByID(client, "some-id")
+if err != nil {
+	vErr, ok := err.(voice.ErrorResponse)
+	if !ok {
+    		// A non-MessageBird (Voice) error occurred (no connection, perhaps?) 
+    		return err
+    }
+	
+	fmt.Println("Code:", vErr.Errors[0].Code)
+	fmt.Println("Message:", vErr.Errors[0].Message)
+}
+```
+
+Conversations WhatsApp Sandbox
+-------------
+To use the whatsapp sandbox you need to enable the `FeatureConversationsAPIWhatsAppSandbox` feature.
+
+```go
+	client.EnableFeatures(messagebird.FeatureConversationsAPIWhatsAppSandbox)
+```
+
 Documentation
 -------------
 Complete documentation, instructions, and examples are available at:
 [https://developers.messagebird.com](https://developers.messagebird.com).
 
 Upgrading
 ---------
-If you're upgrading from older versions, please read the [Messagebird `go-rest-api` uprading guide](UPGRADING.md).
+If you're upgrading from older versions, please read the [Messagebird `go-rest-api` upgrading guide](UPGRADING.md).
 
 License
 -------

client.go

@@ -20,31 +20,45 @@ import (
 	"net/url"
 	"runtime"
 	"strings"
+	"sync"
 	"time"
 )
 
 const (
 	// ClientVersion is used in User-Agent request header to provide server with API level.
-	ClientVersion = "5.1.1"
+	ClientVersion = "5.4.0"
 
 	// Endpoint points you to MessageBird REST API.
 	Endpoint = "https://rest.messagebird.com"
 
 	// httpClientTimeout is used to limit http.Client waiting time.
 	httpClientTimeout = 15 * time.Second
+
+	// voiceHost is the host name for the Voice API.
+	voiceHost = "voice.messagebird.com"
 )
 
 var (
 	// ErrUnexpectedResponse is used when there was an internal server error and nothing can be done at this point.
 	ErrUnexpectedResponse = errors.New("The MessageBird API is currently unavailable")
 )
 
+// A Feature can be enabled
+type Feature int
+
+const (
+	// FeatureConversationsAPIWhatsAppSandbox Enables the WhatsApp sandbox for conversations API.
+	FeatureConversationsAPIWhatsAppSandbox Feature = iota
+)
+
 // Client is used to access API with a given key.
 // Uses standard lib HTTP client internally, so should be reused instead of created as needed and it is safe for concurrent use.
 type Client struct {
-	AccessKey  string       // The API access key
-	HTTPClient *http.Client // The HTTP client to send requests on
-	DebugLog   *log.Logger  // Optional logger for debugging purposes
+	AccessKey     string           // The API access key.
+	HTTPClient    *http.Client     // The HTTP client to send requests on.
+	DebugLog      *log.Logger      // Optional logger for debugging purposes.
+	features      map[Feature]bool // Enabled features.
+	featuresMutex sync.RWMutex     // Mutex for accessing feature map.
 }
 
 type contentType string
@@ -55,14 +69,50 @@ const (
 	contentTypeFormURLEncoded contentType = "application/x-www-form-urlencoded"
 )
 
+// errorReader reads the provided byte slice into an appropriate error.
+type errorReader func([]byte) error
+
+var voiceErrorReader errorReader
+
 // New creates a new MessageBird client object.
 func New(accessKey string) *Client {
 	return &Client{
 		AccessKey: accessKey,
 		HTTPClient: &http.Client{
 			Timeout: httpClientTimeout,
 		},
+		features: make(map[Feature]bool),
+	}
+}
+
+// SetVoiceErrorReader takes an errorReader that must parse raw JSON errors
+// returned from the Voice API.
+func SetVoiceErrorReader(r errorReader) {
+	voiceErrorReader = r
+}
+
+// EnableFeatures enables a feature.
+func (c *Client) EnableFeatures(feature Feature) {
+	c.featuresMutex.Lock()
+	defer c.featuresMutex.Unlock()
+	c.features[feature] = true
+}
+
+// DisableFeatures disables a feature.
+func (c *Client) DisableFeatures(feature Feature) {
+	c.featuresMutex.Lock()
+	defer c.featuresMutex.Unlock()
+	c.features[feature] = false
+}
+
+// IsFeatureEnabled checks if a feature is enabled.
+func (c *Client) IsFeatureEnabled(feature Feature) bool {
+	c.featuresMutex.RLock()
+	defer c.featuresMutex.RUnlock()
+	if enabled, ok := c.features[feature]; ok {
+		return enabled
 	}
+	return false
 }
 
 // Request is for internal use only and unstable.
@@ -135,6 +185,10 @@ func (c *Client) Request(v interface{}, method, path string, data interface{}) e
 		return ErrUnexpectedResponse
 	default:
 		// Anything else than a 200/201/204/500 should be a JSON error.
+		if uri.Host == voiceHost && voiceErrorReader != nil {
+			return voiceErrorReader(responseBody)
+		}
+
 		var errorResponse ErrorResponse
 		if err := json.Unmarshal(responseBody, &errorResponse); err != nil {
 			return err

contact/contact.go

@@ -32,8 +32,8 @@ type Contact struct {
 		TotalCount int
 		HRef       string
 	}
-	CreatedDatetime time.Time
-	UpdatedDatetime time.Time
+	CreatedDatetime *time.Time
+	UpdatedDatetime *time.Time
 }
 
 type ContactList struct {