clerk

README

Clerk Go SDK

This is still a work in progress. The current stable release is v1. See the main branch for the stable release.

The official Go client library for accessing the Clerk Backend API.

License

This SDK is licensed under the MIT license found in the LICENSE file.

---

Clerk is Hiring!

Would you like to work on Open Source software and help maintain this repository? Apply today!

---

Documentation

Overview

Package clerk provides a way to communicate with the Clerk API. Includes types for Clerk API requests, responses and all available resources.

Index

• Constants
• func Int64(v int64) *int64
• func JoinPath(base string, elem ...string) (string, error)
• func SetBackend(b Backend)
• func SetKey(key string)
• func String(v string) *string
• type APIErrorResponse
  • func (resp *APIErrorResponse) Error() string
• type APIParams
  • func (params *APIParams) ToQuery() url.Values
• type APIRequest
  • func NewAPIRequest(method, path string) *APIRequest
  • func (req *APIRequest) SetParams(params Params)
• type APIResource
  • func (r *APIResource) Read(response *APIResponse)
• type APIResponse
  • func NewAPIResponse(resp *http.Response, body json.RawMessage) *APIResponse
  • func (resp *APIResponse) Success() bool
• type ActorToken
• type Backend
  • func GetBackend() Backend
  • func NewBackend(config *BackendConfig) Backend
• type BackendConfig
• type CNAMETarget
• type DeletedResource
• type Domain
• type DomainList
• type Error
• type ListParams
  • func (params ListParams) ToQuery() url.Values
• type Params
• type ResponseReader

Constants

const (
	// APIURL is the base URL for the Clerk API.
	APIURL string = "https://api.clerk.com"
)

Functions

func Int64

func Int64(v int64) *int64

Int64 returns a pointer to the provided int64 value.

func JoinPath

func JoinPath(base string, elem ...string) (string, error)

JoinPath returns a URL string with the provided path elements joined with the base path.

func SetBackend

func SetBackend(b Backend)

SetBackend sets the Backend that will be used to make requests to the Clerk API. Use this method if you need to override the default Backend configuration.

func SetKey

func SetKey(key string)

SetKey sets the Clerk API key.

func String

func String(v string) *string

String returns a pointer to the provided string value.

Types

type APIErrorResponse

type APIErrorResponse struct {
	APIResource

	Errors []Error `json:"errors"`

	HTTPStatusCode int    `json:"status,omitempty"`
	TraceID        string `json:"clerk_trace_id,omitempty"`
}

APIErrorResponse is used for cases where requests to the Clerk API result in error responses.

func (*APIErrorResponse) Error

func (resp *APIErrorResponse) Error() string

Error returns the marshaled representation of the APIErrorResponse.

type APIParams

type APIParams struct {
}

APIParams implements functionality that's common to all types that can be used as API request parameters. It is recommended to embed this type to all types that will be used for API operation parameters.

func (*APIParams) ToQuery

func (params *APIParams) ToQuery() url.Values

ToQuery can be used to transform the params to querystring values. It is currently a no-op, but is defined so that all types that describe API operation parameters implement the Params interface.

type APIRequest

type APIRequest struct {
	Method string
	Path   string
	Params Params
}

APIRequest describes requests to the Clerk API.

func NewAPIRequest

func NewAPIRequest(method, path string) *APIRequest

NewAPIRequest creates an APIRequest with the provided HTTP method and path.

func (*APIRequest) SetParams

func (req *APIRequest) SetParams(params Params)

SetParams sets the APIRequest.Params.

type APIResource

type APIResource struct {
	Response *APIResponse `json:"-"`
}

APIResource describes a Clerk API resource and contains fields and methods common to all resources.

func (*APIResource) Read

func (r *APIResource) Read(response *APIResponse)

Read sets the response on the resource.

type APIResponse

type APIResponse struct {
	Header     http.Header
	Status     string // e.g. "200 OK"
	StatusCode int    // e.g. 200

	// TraceID is a unique identifier for tracing the origin of the
	// response.
	// Useful for debugging purposes.
	TraceID string
	// RawJSON contains the response body as raw bytes.
	RawJSON json.RawMessage
}

APIResponse describes responses coming from the Clerk API. Exposes some commonly used HTTP response fields along with the raw data in the response body.

func NewAPIResponse

func NewAPIResponse(resp *http.Response, body json.RawMessage) *APIResponse

NewAPIResponse creates an APIResponse from the passed http.Response and the raw response body.

func (*APIResponse) Success

func (resp *APIResponse) Success() bool

Success returns true for API response status codes in the 200-399 range, false otherwise.

type ActorToken

type ActorToken struct {
	APIResource
	Object    string          `json:"object"`
	ID        string          `json:"id"`
	UserID    string          `json:"user_id"`
	Actor     json.RawMessage `json:"actor"`
	Token     string          `json:"token,omitempty"`
	Status    string          `json:"status"`
	CreatedAt int64           `json:"created_at"`
	UpdatedAt int64           `json:"updated_at"`
}

type Backend

type Backend interface {
	// Call makes requests to the Clerk API.
	Call(context.Context, *APIRequest, ResponseReader) error
}

Backend is the primary interface for communicating with the Clerk API.

func GetBackend

func GetBackend() Backend

GetBackend returns the library's supported backend for the Clerk API.

func NewBackend

func NewBackend(config *BackendConfig) Backend

NewBackend returns a default backend implementation with the provided configuration. Please note that the return type is an interface because the Backend is not supposed to be used directly.

type BackendConfig

type BackendConfig struct {
	// HTTPClient is an HTTP client instance that will be used for
	// making API requests.
	// If it's not set a default HTTP client will be used.
	HTTPClient *http.Client
	// URL is the base URL to use for API endpoints.
	// If it's not set, the default value for the Backend will be used.
	URL *string
}

BackendConfig is used to configure a new Clerk Backend.

type CNAMETarget

type CNAMETarget struct {
	Host  string `json:"host"`
	Value string `json:"value"`
}

type DeletedResource

type DeletedResource struct {
	APIResource
	ID      string `json:"id,omitempty"`
	Slug    string `json:"slug,omitempty"`
	Object  string `json:"object"`
	Deleted bool   `json:"deleted"`
}

DeletedResource describes an API resource that is no longer available. It's usually encountered as a result of delete API operations.

type Domain

type Domain struct {
	APIResource
	ID                string        `json:"id"`
	Object            string        `json:"object"`
	Name              string        `json:"name"`
	IsSatellite       bool          `json:"is_satellite"`
	FrontendAPIURL    string        `json:"frontend_api_url"`
	AccountPortalURL  *string       `json:"accounts_portal_url,omitempty"`
	ProxyURL          *string       `json:"proxy_url,omitempty"`
	CNAMETargets      []CNAMETarget `json:"cname_targets,omitempty"`
	DevelopmentOrigin string        `json:"development_origin"`
}

type DomainList

type DomainList struct {
	APIResource
	Domains    []*Domain `json:"data"`
	TotalCount int64     `json:"total_count"`
}

type Error

type Error struct {
	Code        string          `json:"code"`
	Message     string          `json:"message"`
	LongMessage string          `json:"long_message"`
	Meta        json.RawMessage `json:"meta,omitempty"`
}

Error is a representation of a single error that can occur in the Clerk API.

type ListParams

type ListParams struct {
	Limit  *int64 `json:"limit,omitempty"`
	Offset *int64 `json:"offset,omitempty"`
}

ListParams holds fields that are common for list API operations.

func (ListParams) ToQuery

func (params ListParams) ToQuery() url.Values

ToQuery returns url.Values with the ListParams values in the querystring.

type Params

type Params interface {
	ToQuery() url.Values
}

Params can add parameters to url.Values. Useful for constructing a request query string.

type ResponseReader

type ResponseReader interface {
	Read(*APIResponse)
}

ResponseReader reads Clerk API responses.