feather

package module
v0.0.0-...-469e08d Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 5, 2020 License: MIT Imports: 14 Imported by: 0

README

Feather Go Library

GoDoc Build Status Coverage Status

This library provides a convenient interface to the Feather API for applications running in a Go server environment.

Installation

$ go get -u github.com/feather-id/feather-go

Usage

Initialize a Feather client with your project's API key, available on the Feather Dashboard:

import "github.com/feather-id/feather-go"

client := feather.New("live_...")
A simple flow

The example below walks through a simple and common authentication flow:

  1. Create a credential given a username and password.
  2. Use the credential to create an authenticated session.
  3. Add custom metadata to the session user to save their current state.

Note this example ignores errors for brevity. You should not ignore errors in production code!

// 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.CredentialStatusRequiresVerificationCode:
	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

To run unit tests, simply call:

$ make test

More Information

Documentation

Overview

Package feather provides a convenient interface to the Feather API for applications running in a Go server environment.

For more information on Feather API, please check out our docs at https://feather.id/docs.

Example 
// Please note this example ignores errors for brevity.
// You should not ignore errors in production code.

// Initialize the client with your API key
client := feather.New("live_...")

// 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.CredentialStatusRequiresVerificationCode:
	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
}

// Create an authenticated session
session, _ := client.Sessions.Create(feather.SessionsCreateParams{
	CredentialToken: credential.Token,
})

// 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"])

Output:

Index

Examples

Constants

View Source 
const (
	// The provided authentication information was valid.
	CredentialStatusValid = "valid"

	// The provided authentication information was invalid.
	CredentialStatusInvalid = "invalid"

	// A one-time-code has been sent to the user and must be returned
	// to verify the provided authentication information.
	CredentialStatusRequiresVerificationCode = "requires_verification_code"
)
View Source 
const (
	// Only an email address was provided.
	CredentialTypeEmail = "email"

	// An email address and password were provided.
	CredentialTypeEmailPassword = "email|password"

	// A username and password were provided.
	CredentialTypeUsernamePassword = "username|password"
)
View Source 
const (
	// The session is currently active.
	SessionStatusActive = "active"

	// The session has expired.
	SessionStatusExpired = "expired"

	// The session has been revoked.
	SessionStatusRevoked = "revoked"
)

Variables

This section is empty.

Functions

func String 

func String(v string) *string

String returns a pointer to the provided string value.

func Time 

func Time(v time.Time) *time.Time

Time returns a pointer to the provided time.Time value.

func UInt32 

func UInt32(v uint32) *uint32

UInt32 returns a pointer to the provided uint32 value.

Types

type Client 

type Client struct {
	Credentials Credentials
	Sessions    Sessions
	Users       Users
}

A Client provides access to the Feather API core resources. You should instantiate and use a client to send requests to the Feather API.

func New 

func New(apiKey string, cfgs ...*Config) Client

New creates a new instance of the Feather client. If additional configuration is needed for the client instance, use the optional Config parameter to add the extra config.

type Config 

type Config struct {
	Protocol   *string
	Host       *string
	Port       *string
	BasePath   *string
	HTTPClient *http.Client
}

A Config provides extra configuration to intialize a Feather client with. This is typically only needed in a testing/development environment and should not be used in production code.

type Credential 

type Credential struct {
	ID        string           `json:"id"`
	Object    string           `json:"object"`
	CreatedAt time.Time        `json:"created_at"`
	ExpiresAt time.Time        `json:"expires_at"`
	Status    CredentialStatus `json:"status"`
	Token     *string          `json:"token"`
	Type      CredentialType   `json:"type"` // TODO make enum
}

Credential is a Feather credential object. https://feather.id/docs/reference/api#credentialObject

type CredentialStatus 

type CredentialStatus string

CredentialStatus represents the status of a credential.

type CredentialType 

type CredentialType string

CredentialType represents the type of the provided authentication information.

type Credentials 

type Credentials interface {
	Create(params CredentialsCreateParams) (*Credential, error)
	Update(id string, params CredentialsUpdateParams) (*Credential, error)
}

Credentials provides an interface for accessing Feather API credential objects. https://feather.id/docs/reference/api#credentials

type CredentialsCreateParams 

type CredentialsCreateParams struct {
	Type         CredentialType `json:"type"`
	Email        *string        `json:"email"`
	Username     *string        `json:"username"`
	Password     *string        `json:"password"`
	TemplateName *string        `json:"template_name"`
}

CredentialsCreateParams ...

type CredentialsUpdateParams 

type CredentialsUpdateParams struct {
	VerificationCode *string `json:"verification_code"`
}

CredentialsUpdateParams ...

type Error 

type Error struct {
	Object  string    `json:"object"`
	Type    ErrorType `json:"type"`
	Code    ErrorCode `json:"code"`
	Message string    `json:"message"`
}

Error is the Feather error object. https://feather.id/docs/reference/api#errors

func (Error) Error 

func (e Error) Error() string

type ErrorCode 

type ErrorCode string

ErrorCode provides a value which can be used to handle the error programmatically. 

const (
	ErrorCodeAPIKeyExpired                 ErrorCode = "api_key_expired"
	ErrorCodeAPIKeyInsufficientPermissions ErrorCode = "api_key_insufficient_permissions"
	ErrorCodeAPIKeyMissing                 ErrorCode = "api_key_missing"
	ErrorCodeAPIKeyInvalid                 ErrorCode = "api_key_invalid"
	ErrorCodeAPIKeyRevoked                 ErrorCode = "api_key_revoked"
	ErrorCodeBearerTokenInvalid            ErrorCode = "bearer_token_invalid"
	ErrorCodeCredentialAlreadyUsed         ErrorCode = "credential_already_used"
	ErrorCodeCredentialExpired             ErrorCode = "credential_expired"
	ErrorCodeCredentialInvalid             ErrorCode = "credential_invalid"
	ErrorCodeCredentialStatusNotValid      ErrorCode = "credential_status_not_valid"
	ErrorCodeCredentialStatusImmutable     ErrorCode = "credential_status_immutable"
	ErrorCodeCredentialTokenInvalid        ErrorCode = "credential_token_invalid"
	ErrorCodeCredentialTokenExpired        ErrorCode = "credential_token_expired"
	ErrorCodeHeaderEmpty                   ErrorCode = "header_empty"
	ErrorCodeHeaderMissing                 ErrorCode = "header_missing"
	ErrorCodeNotFound                      ErrorCode = "not_found"
	ErrorCodeOneTimeCodeInvalid            ErrorCode = "one_time_code_invalid"
	ErrorCodeOneTimeCodeUsed               ErrorCode = "one_time_code_used"
	ErrorCodeParsingFailed                 ErrorCode = "parsing_failed"
	ErrorCodeParameterEmpty                ErrorCode = "parameter_empty"
	ErrorCodeParameterInvalid              ErrorCode = "parameter_invalid"
	ErrorCodeParameterMissing              ErrorCode = "parameter_missing"
	ErrorCodeParameterUnknown              ErrorCode = "parameter_unknown"
	ErrorCodeParametersExclusive           ErrorCode = "parameters_exclusive"
	ErrorCodePasswordInvalid               ErrorCode = "password_invalid"
	ErrorCodePublicKeyNotFound             ErrorCode = "public_key_not_found"
	ErrorCodeSessionExpired                ErrorCode = "session_expired"
	ErrorCodeSessionInactive               ErrorCode = "session_inactive"
	ErrorCodeSessionRevoked                ErrorCode = "session_revoked"
	ErrorCodeSessionTokenInvalid           ErrorCode = "session_token_invalid"
	ErrorCodeSessionTokenExpired           ErrorCode = "session_token_expired"
	ErrorCodeUserBlocked                   ErrorCode = "user_blocked"
)

type ErrorType 

type ErrorType string

ErrorType represents the type of error produced. 

const (
	// Failed to connect to the Feather API.
	ErrorTypeAPIConnection ErrorType = "api_connection_error"

	// The API request did not have proper authentication.
	ErrorTypeAPIAuthentication ErrorType = "api_authentication_error"

	// Too many requests have been sent to quickly with this API key.
	ErrorTypeRateLimit ErrorType = "rate_limit_error"

	// The API request did not pass validation checks.
	ErrorTypeValidation ErrorType = "validation_error"

	// Any other type of error (eg temporary problem with the server).
	ErrorTypeAPI ErrorType = "api_error"
)

type ListMeta 

type ListMeta struct {
	Objet      string `json:"Object"`
	URL        string `json:"url"`
	TotalCount uint32 `json:"total_count"`
}

ListMeta ... https://feather.id/docs/reference/api#pagination

type ListParams 

type ListParams struct {
	Limit         *uint32 `json:"limit"`
	StartingAfter *string `json:"starting_after"`
	EndingBefore  *string `json:"ending_before"`
}

ListParams ... https://feather.id/docs/reference/api#pagination

type Session 

type Session struct {
	ID        string        `json:"id"`
	Object    string        `json:"object"`
	Status    SessionStatus `json:"status"`
	Token     *string       `json:"token"`
	UserID    string        `json:"user_id"`
	CreatedAt time.Time     `json:"created_at"`
	RevokedAt *time.Time    `json:"revoked_at"`
}

Session is the Feather session object. https://feather.id/docs/reference/api#sessionObject

type SessionList 

type SessionList struct {
	ListMeta
	Data []*Session `json:"data"`
}

SessionList is a list of Feather session objects. https://feather.id/docs/reference/api#pagination

type SessionStatus 

type SessionStatus string

SessionStatus represents the status of a session.

type Sessions 

type Sessions interface {
	Create(params SessionsCreateParams) (*Session, error)
	List(params SessionsListParams) (*SessionList, error)
	Retrieve(id string) (*Session, error)
	Revoke(id string, params SessionsRevokeParams) (*Session, error)
	Upgrade(id string, params SessionsUpgradeParams) (*Session, error)
	Validate(params SessionsValidateParams) (*Session, error)
}

Sessions provides an interface for accessing Feather API session objects. https://feather.id/docs/reference/api#sessions

type SessionsCreateParams 

type SessionsCreateParams struct {
	CredentialToken *string `json:"credential_token"`
}

SessionsCreateParams ...

type SessionsListParams 

type SessionsListParams struct {
	ListParams
	UserID *string `json:"user_id"`
}

SessionsListParams ...

type SessionsRevokeParams 

type SessionsRevokeParams struct {
	SessionToken *string `json:"session_token"`
}

SessionsRevokeParams ...

type SessionsUpgradeParams 

type SessionsUpgradeParams struct {
	CredentialToken *string `json:"credential_token"`
}

SessionsUpgradeParams ...

type SessionsValidateParams 

type SessionsValidateParams struct {
	SessionToken *string `json:"session_token"`
}

SessionsValidateParams ...

type User 

type User struct {
	ID              string            `json:"id"`
	Object          string            `json:"object"`
	Email           *string           `json:"email"`
	Username        *string           `json:"username"`
	IsAnonymous     bool              `json:"is_anonymous"`
	IsEmailVerified bool              `json:"is_email_verified"`
	Metadata        map[string]string `json:"metadata"`
	CreatedAt       time.Time         `json:"created_at"`
	UpdatedAt       time.Time         `json:"updated_at"`
	FirstActiveAt   *time.Time        `json:"first_active_at"`
	LastActiveAt    *time.Time        `json:"last_active_at"`
}

User is the Feather user object. https://feather.id/docs/reference/api#userObject

type UserList 

type UserList struct {
	ListMeta
	Data []*User `json:"data"`
}

UserList is a list of Feather user objects. https://feather.id/docs/reference/api#pagination

type Users 

type Users interface {
	List(params UsersListParams) (*UserList, error)
	Retrieve(id string) (*User, error)
	Update(id string, params UsersUpdateParams) (*User, error)
	UpdatePassword(id string, params UsersUpdatePasswordParams) (*User, error)
}

Users provides an interface for accessing Feather API user objects. https://feather.id/docs/reference/api#users

type UsersListParams 

type UsersListParams struct {
	ListParams
}

UsersListParams ...

type UsersUpdateParams 

type UsersUpdateParams struct {
	Email    *string            `json:"email"`
	Username *string            `json:"username"`
	Metadata *map[string]string `json:"metadata"`
}

UsersUpdateParams ...

type UsersUpdatePasswordParams 

type UsersUpdatePasswordParams struct {
	CredentialToken *string `json:"credential_token"`
	NewPassword     *string `json:"new_password"`
}

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.