Update the README and examples

Makefile

@@ -3,12 +3,13 @@ PKGS := $(shell go list ./... | grep -v /vendor | grep -v /config)
 .DEFAULT_GOAL := all
 
 # Make the repo
-all: test
+all: clean test
 
 # Run tests
 test:
 	go test -cover $(PKGS)
 
+# Generate test coverage report
 coverage:
 	go test -cover $(PKGS) -covermode=count -coverprofile=combined.coverprofile ./...
 

README.md

@@ -12,11 +12,67 @@ $ go get -u github.com/feather-id/feather-go
 
 ## Usage
 
-TODO
+Initialize a Feather client with your project's API key, available on the [Feather Dashboard](https://feather.id/dashboard).
+
+```go
+import "github.com/feather-id/feather-go"
+
+client := feather.New("live_...")
+```
+
+The example below will walk through a simple and common authentication flow:
+
+- Create a credential given a username and password from your user.
+- Create an authenticated session with the credential token.
+- Add custom metadata to the user to save their current state.
+
+Note this example ignores errors for brevity. You should not ignore errors in production code!
+
+```go
+// 1) Create a credential
+credential, _ := client.Credentials.Create(feather.CredentialsCreateParams{
+	Type:     feather.CredentialTypeUsernamePassword,
+	Username: feather.String("jdoe"),
+	Password: feather.String("pa$$w0rd"),
+})
+
+// Inform the user of their credential status
+switch credential.Status {
+case feather.CredentialStatusRequiresOneTimeCode:
+	log.Printf("Please check your email for a link to sign in")
+	return
+
+case feather.CredentialStatusInvalid:
+	log.Printf("Your username and password did not match")
+	return
+
+case feather.CredentialStatusValid:
+	// The username and password were valid!
+	break
+}
+
+// 2) Create an authenticated session
+session, _ := client.Sessions.Create(feather.SessionsCreateParams{
+  CredentialToken: credential.Token,
+})
+
+// 3) Add custom metadata to the user
+user, _ := client.Users.Update(session.UserID, feather.UsersUpdateParams{
+	Metadata: &map[string]string{
+		"highScore": "123",
+	},
+})
+
+log.Printf("Your high score is: %v", user.Metadata["highScore"])
+```
 
 ## Development
 
-TODO
+To run tests, simply call:
+
+```sh
+$ make test
+```
 
 ## More Information
 

example_test.go

@@ -11,10 +11,7 @@ func Example() {
 	// You should not ignore errors in production code.
 
 	// Initialize the client with your API key
-	client := feather.New("YOUR_API_KEY")
-
-	// Create an anonymous session
-	session, _ := client.Sessions.Create(feather.SessionsCreateParams{})
+	client := feather.New("live_...")
 
 	// Create a credential
 	credential, _ := client.Credentials.Create(feather.CredentialsCreateParams{
@@ -34,12 +31,12 @@ func Example() {
 		return
 
 	case feather.CredentialStatusValid:
-		// Life is good :)
+		// The username and password were valid!
 		break
 	}
 
-	// Upgrade the session
-	session, _ = client.Sessions.Upgrade(session.ID, feather.SessionsUpgradeParams{
+	// Create an authenticated session
+	session, _ := client.Sessions.Create(feather.SessionsCreateParams{
 		CredentialToken: credential.Token,
 	})