magic

README

Magic Admin Golang SDK

The Magic Admin Golang SDK provides convenient ways for developers to interact with Magic API endpoints and an array of utilities to handle DID Token.

Table of Contents

• Documentation
• Quick Start
• Development
• Changelog
• License

Documentation

See the Magic doc!

Installation

The SDK requires Golang 1.13+ and Go Modules. To make sure your project is using Go Modules, you can look for go.mod file in your project's root directory. If it exits, then you are already using the Go Modules. If not, you can follow this guide to migrate to Go Modules.

Simply reference magic-admin-go in a Go program with an import of the SDK:

import (
    ...
    "github.com/ClubNFT/magic-admin-go"
    ...
)

Run any of the normal go commands (ex: build/install). The Go toolchain will take care of fetching the SDK automatically.

Alternatively, you can explicitly go get the package into a project:

go get github.com/ClubNFT/magic-admin-go

Command line utility

Command line utility is created for testing purposes and can be used for decoding and validating DID tokens. It also provides functionality to retrieve user info.

You can simply install it by the command:

go install github.com/ClubNFT/magic-admin-go/cmd/magic-cli

Current available command supported:

$ magic-cli -h
NAME:
   magic-cli - command line utility to make requests to api and validate tokens

USAGE:
   magic-cli [global options] command [command options] [arguments...]

COMMANDS:
   token, t   magic-cli token [decode|validate] --did <DID token>
   user, u    magic-cli -s <secret> user --did <DID token>
   help, h    Shows a list of commands or help for one command

GLOBAL OPTIONS:
   --secret value, -s value  Secret token which will be used for making request to backend api [$MAGIC_API_SECRET_KEY]
   --help, -h                show help (default: false)

Quick Start

Before you start, you will need an API secret key. You can get one from the Magic Dashboard. Once you have the API secret key, you can instantiate a Magic object.

Sample code to retrieve user info by a DID token:

package main

import (
    "log"
    "fmt"

    "github.com/ClubNFT/magic-admin-go"
    "github.com/ClubNFT/magic-admin-go/client"
)

func main() {
    m := client.New("<YOUR_API_SECRET_KEY>", magic.NewDefaultClient())
    userInfo, err := m.User.GetMetadataByToken("<DID_TOKEN>")
    if err != nil {
        log.Fatalf("Error: %s", err.Error())
    }

    fmt.Println(userInfo)
}

Sample code to validate a DID token and retrieve the claim and proof from the token:

package main

import (
    "log"
    "fmt"

    "github.com/ClubNFT/magic-admin-go/token"
)

func main() {
    tk, err := token.NewToken("<DID_TOKEN>")
    if err != nil {
        log.Fatalf("DID token is malformed: %s", err.Error())
    }
    
    if err := tk.Validate(); err != nil {
        log.Fatalf("DID token is invalid: %v", err)
    }

    fmt.Println(tk.GetClaim())
    fmt.Println(tk.GetProof())
}

Configure Network Strategy

The NewClientWithRetry method creates a client with retries, retryWait, timeout options. NewClientWithRetry returns a *resty.Client instance which can be used with the Magic client.

cl := magic.NewClientWithRetry(5, time.Second, 10 * time.Second)
m := client.New("<YOUR_API_SECRET_KEY>", cl)

Development

We would love to have you contribute to the SDK. To get started, you will need to clone this repository and fetch the dependencies.

To run the existing tests:

make test

To build and install magic-cli utility tool, you can run:

make install

To build magic-cli utility tool separately as a binary, you can run:

make build

Please also see our CONTRIBUTING guide for more information.

Changelog

See Changelog

License

See License

Documentation

Index

• Constants
• Variables
• func NewClient() *resty.Client
• func NewClientWithRetry(retries int, retryWait, timeout time.Duration) *resty.Client
• func NewDefaultClient() *resty.Client
• func WrapError(r *resty.Response, err *Error) error
• type APIConnectionError
  • func (e *APIConnectionError) Error() string
• type APIError
  • func (e *APIError) Error() string
• type AuthenticationError
  • func (e *AuthenticationError) Error() string
• type BadRequestError
  • func (e *BadRequestError) Error() string
• type Error
  • func (e *Error) Error() string
• type ErrorCode
• type ForbiddenError
  • func (e *ForbiddenError) Error() string
• type RateLimitingError
  • func (e *RateLimitingError) Error() string
• type Response
• type User
• type UserInfo
  • func (m *UserInfo) String() string

Constants

const (
	// APIVersion is the version of the library.
	APIVersion = "v0.1.0"

	// APIURL is the URL of the API service backend.
	APIURL = "https://api.magic.link"

	// APISecretHeader holds the header name for api authorization.
	APISecretHeader = "X-Magic-Secret-Key"
)

Variables

var (
	ErrRespQuotaExceeded = errors.New("quota exceeded")
)

Functions

func NewClient

func NewClient() *resty.Client

NewClient creates new backend client with default api url.

func NewClientWithRetry

func NewClientWithRetry(retries int, retryWait, timeout time.Duration) *resty.Client

NewClientWithRetry creates backend client with backoff retry configuration.

func NewDefaultClient

func NewDefaultClient() *resty.Client

NewDefaultClient creates backend client with default configuration of retries.

func WrapError

func WrapError(r *resty.Response, err *Error) error

Wraps error into appropriate type.

Types

type APIConnectionError

type APIConnectionError struct {
	Err error
}

APIConnectionError occurs if request is not permitted to be executed.

func (*APIConnectionError) Error

func (e *APIConnectionError) Error() string

Error serializes the error object to JSON and returns it as a string.

type APIError

type APIError struct {
	Err *Error
}

APIError default unrecognized by any other errors.

func (*APIError) Error

func (e *APIError) Error() string

Error serializes the error object to JSON and returns it as a string.

type AuthenticationError

type AuthenticationError struct {
	Err *Error
}

AuthenticationError occurs if request is not authorized to proceed.

func (*AuthenticationError) Error

func (e *AuthenticationError) Error() string

Error serializes the error object to JSON and returns it as a string.

type BadRequestError

type BadRequestError struct {
	Err *Error
}

BadRequestError occurs with not well formed request.

func (*BadRequestError) Error

func (e *BadRequestError) Error() string

Error serializes the error object to JSON and returns it as a string.

type Error

type Error struct {
	Response
}

func (*Error) Error

func (e *Error) Error() string

Error serializes the error object to JSON and returns it as a string.

type ErrorCode

type ErrorCode string

type ForbiddenError

type ForbiddenError struct {
	Err *Error
}

ForbiddenError occurs if request is not permitted to be executed.

func (*ForbiddenError) Error

func (e *ForbiddenError) Error() string

Error serializes the error object to JSON and returns it as a string.

type RateLimitingError

type RateLimitingError struct {
	Err *Error
}

RateLimitError occurs when in case if API is hit with too many requests.

func (*RateLimitingError) Error

func (e *RateLimitingError) Error() string

Error serializes the error object to JSON and returns it as a string.

type Response

type Response struct {
	Data      interface{} `json:"data"`
	ErrorCode ErrorCode   `json:"error_code"`
	Message   string      `json:"message"`
	Status    string      `json:"status"`
}

Default response data structure of magic backend server.

type User

type User interface {
	GetMetadataByIssuer(issuer string) (*UserInfo, error)
	GetMetadataByPublicAddress(pubAddr string) (*UserInfo, error)
	GetMetadataByToken(didToken string) (*UserInfo, error)

	LogoutByIssuer(issuer string) error
	LogoutByPublicAddress(pubAddr string) error
	LogoutByToken(didToken string) error
}

type UserInfo

type UserInfo struct {
	Email         string `json:"email"`
	Issuer        string `json:"issuer"`
	PublicAddress string `json:"public_address"`
}

func (*UserInfo) String

func (m *UserInfo) String() string