api

README

Cierge API Library

Complete API library for the Cierge API.

Usage

Create a new client by calling the NewClient function. This accepts the following parameters:

• An http.Client that will be used as the underlying HTTP client that is used to make requests, otherwise a new http.Client is used.
• URL of the Cierge server
• User's API key that is used for authentication

With the Client, you can then use it to call any of the methods provided by this library.

Documentation

Overview

Go library for the Cierge API

Index

• Constants
• Variables
• type AuthCookies
• type AuthMethod
• type Client
  • func NewClient(httpClient *http.Client, host string, apiKey string) (*Client, error)
  • func (c *Client) CancelJob(jobId uuid.UUID) error
  • func (c *Client) ChangePassword(oldPassword string, newPassword string) error
  • func (c *Client) CreateDropConfig(restaurantId uuid.UUID, daysInAdvance int16, dropTime string) (DropConfig, error)
  • func (c *Client) CreateJob(jobCreationReq JobCreationRequest) (Job, error)
  • func (c *Client) CreatePlatformToken(platform string, token any) (PlatformToken, error)
  • func (c *Client) Do(req *http.Request, v any) error
  • func (c *Client) GenerateAPIKey() (string, error)
  • func (c *Client) GetDropConfigs(restaurantId uuid.UUID) ([]DropConfig, error)
  • func (c *Client) GetHealth() (Health, error)
  • func (c *Client) GetJobs(upcomingOnly bool) ([]Job, error)
  • func (c *Client) GetMe() (*User, error)
  • func (c *Client) GetPlatformTokens(platform *string) ([]PlatformToken, error)
  • func (c *Client) GetRestaurant(id uuid.UUID) (Restaurant, error)
  • func (c *Client) GetRestaurantByPlatform(platform string, platformId string) (Restaurant, error)
  • func (c *Client) Login(email string, password string) (*AuthCookies, error)
  • func (c *Client) NewJsonRequest(method string, url string, jsonValue any) (*http.Request, error)
• type DropConfig
• type Health
• type Job
• type JobCreationRequest
• type JobStatus
• type PlatformToken
• type Restaurant
• type User

Constants

const (
	LocalAuthMethod = AuthMethod("local")
	OIDCAuthMethod  = AuthMethod("oidc")
)

Variables

var (
	ErrNoAPIKey      = errors.New("no API key was returned by the server")
	ErrNoAuthCookies = errors.New("no auth cookies were found")
)

var (
	ErrBadRequest       = errors.New("bad or malformed request")
	ErrConflict         = errors.New("conflict")
	ErrFailedDependency = errors.New("failed dependency")
	ErrNotFound         = errors.New("not found")
	ErrServerError      = errors.New("server encountered internal error")
	ErrUnauthenticated  = errors.New("unauthenticated")
	ErrUnauthorized     = errors.New("unauthorized")
	ErrUnhandledStatus  = errors.New("unhandled status code returned")
	ErrInvalidHost      = errors.New("invalid host value provided")
)

Types

type AuthCookies

type AuthCookies struct {
	AccessToken  string
	RefreshToken string
}

type AuthMethod

type AuthMethod string

type Client

type Client struct {
	// contains filtered or unexported fields
}

func NewClient

func NewClient(httpClient *http.Client, host string, apiKey string) (*Client, error)

Creates a new Cierge API client. It accepts an `http.Client` value that will be used as the base HTTP client and will have the authentication added to. If nil is provided, `http.DefaultClient` is used. The host value represents the hostname and optionally scheme, of the Cierge instance to interact with. If no scheme is provided, HTTPS will be assumed The API key is the user's API key to use to create an authenticated client. If no API key is provided, the client will not be authenticated.

func (*Client) CancelJob

func (c *Client) CancelJob(jobId uuid.UUID) error

Cancel an existing job

func (*Client) ChangePassword

func (c *Client) ChangePassword(oldPassword string, newPassword string) error

Change a user's password NOTE: Password requirements: upper case, number, special character, min 8, max 128

func (*Client) CreateDropConfig

func (c *Client) CreateDropConfig(restaurantId uuid.UUID, daysInAdvance int16, dropTime string) (DropConfig, error)

Creates a new drop config and returns the drop config object and an error that is nil if successful NOTE: The drop time value must be in HH:mm format otherwise the server will return an error

func (*Client) CreateJob

func (c *Client) CreateJob(jobCreationReq JobCreationRequest) (Job, error)

Create a new job Returns the created job and an error that is nil if successful

func (*Client) CreatePlatformToken

func (c *Client) CreatePlatformToken(platform string, token any) (PlatformToken, error)

Create a new platform token for the specified platform using the specified token The token structure must match that of the platform and is validated server-side

func (*Client) Do

func (c *Client) Do(req *http.Request, v any) error

Do performs an API request, handles the response, and unmarshals the response into a given interface. The value to unmarshal must be a pointer to an interface. If a pointer to a byte array is provided, the returned value will be the value of the body.

func (*Client) GenerateAPIKey

func (c *Client) GenerateAPIKey() (string, error)

Generates a new API key for a user NOTE: Requires authentication (if using cookie auth it must be set separately) NOTE: This will replace the existing API key and as such will invalidate any past API keys. Highly recommend fetching the user and checking if they have an active API key first and if so, getting explicit confirmation.

func (*Client) GetDropConfigs

func (c *Client) GetDropConfigs(restaurantId uuid.UUID) ([]DropConfig, error)

Retrieves all drop configs for a specified restaurant, ordered by confidence in descending order The confidence value represents how many times a drop config has been used to schedule a job for the given restaurant If none exist, an empty slice is returned

func (*Client) GetHealth

func (c *Client) GetHealth() (Health, error)

Retrieve the health of the server

func (*Client) GetJobs

func (c *Client) GetJobs(upcomingOnly bool) ([]Job, error)

Retrieve jobs for the user If upcomingOnly is set to true, only upcoming jobs are returned

func (*Client) GetMe

func (c *Client) GetMe() (*User, error)

Returns a User pointer representing the authenticated user making the request

func (*Client) GetPlatformTokens

func (c *Client) GetPlatformTokens(platform *string) ([]PlatformToken, error)

Retrieve's a users platform tokens for either the specified platform or all platforms if platform is nil

func (*Client) GetRestaurant

func (c *Client) GetRestaurant(id uuid.UUID) (Restaurant, error)

Retrieves a restaurant by its ID

func (*Client) GetRestaurantByPlatform

func (c *Client) GetRestaurantByPlatform(platform string, platformId string) (Restaurant, error)

Retrieves a restaurant with a given platform ID for a specified platform

func (*Client) Login

func (c *Client) Login(email string, password string) (*AuthCookies, error)

Login and get a user's authentication cookies if successful This is designed to be used for providing a smooth way of retrieving a user's API key if they don't already have it NOTE: Only supports username:password auth at this time

func (*Client) NewJsonRequest

func (c *Client) NewJsonRequest(method string, url string, jsonValue any) (*http.Request, error)

Wraps the http.NewRequest function to marshal a provided JSON value and set it as the request body. Also sets the content type to JSON.

type DropConfig

type DropConfig struct {
	ID uuid.UUID `json:"id"`

	DaysInAdvance int16  `json:"days_in_advance"`
	DropTime      string `json:"drop_time"`
	Confidence    int16  `json:"confidence"`

	CreatedAt time.Time `json:"created_at"`
}

type Health

type Health struct {
	Status string
	Server string
}

type Job

type Job struct {
	ID           uuid.UUID `json:"id"`
	UserID       uuid.UUID `json:"user_id"`
	RestaurantID uuid.UUID `json:"restaurant_id"`
	Platform     string    `json:"platform"`

	ReservationDate string   `json:"reservation_date"` // YYYY-MM-DD
	PartySize       int16    `json:"party_size"`
	PreferredTimes  []string `json:"preferred_times"` // HH:mm

	ScheduledAt  time.Time `json:"scheduled_at"`
	DropConfigID uuid.UUID `json:"drop_config_id"`
	Callbacked   bool      `json:"callbacked"`

	Status      JobStatus  `json:"status"`
	StartedAt   *time.Time `json:"started_at,omitempty"`
	CompletedAt *time.Time `json:"completed_at,omitempty"`

	ReservedTime *time.Time `json:"reserved_time,omitempty"`
	Confirmation *string    `json:"confirmation,omitempty"`
	ErrorMessage *string    `json:"error_message,omitempty"`
	Logs         *string    `json:"logs,omitempty"`

	CreatedAt time.Time `json:"created_at"`
	UpdatedAt time.Time `json:"updated_at"`
}

type JobCreationRequest

type JobCreationRequest struct {
	RestaurantID    uuid.UUID `json:"restaurant_id"`
	ReservationDate string    `json:"reservation_date"` // YYYY-MM-DD
	PartySize       int16     `json:"party_size"`
	PreferredTimes  []string  `json:"preferred_times"` // HH:mm
	DropConfigID    uuid.UUID `json:"drop_config_id"`
}

Request type for a new job

type JobStatus

type JobStatus string

const (
	JobStatusCreated   JobStatus = "created"
	JobStatusScheduled JobStatus = "scheduled"
	JobStatusSuccess   JobStatus = "success"
	JobStatusFailed    JobStatus = "failed"
	JobStatusCancelled JobStatus = "cancelled"
)

type PlatformToken

type PlatformToken struct {
	ID               uuid.UUID  `json:"id"`
	UserID           uuid.UUID  `json:"user_id"`
	Platform         string     `json:"platform"`
	ExpiresAt        *time.Time `json:"expires_at"`
	HasRefresh       bool       `json:"has_refresh"`
	RefreshExpiresAt *time.Time `json:"refresh_expires_at"`
	CreatedAt        time.Time  `json:"created_at"`
}

NOTE: Token values are not retrievable via the API

type Restaurant

type Restaurant struct {
	ID         uuid.UUID `json:"id"`
	Platform   string    `json:"platform"`
	PlatformID string    `json:"platform_id"`
	Name       string    `json:"name"`
	Address    *string   `json:"address,omitempty"`
	City       *string   `json:"city,omitempty"`
	State      *string   `json:"state,omitempty"`
	Timezone   string    `json:"timezone,omitempty"`
	Rating     *float32  `json:"rating,omitempty"`
	CreatedAt  time.Time `json:"created_at"`
	UpdatedAt  time.Time `json:"updated_at"`
}

type User

type User struct {
	ID          uuid.UUID  `json:"id"`
	Email       string     `json:"email"`
	HasApiKey   bool       `json:"has_api_key"`
	IsAdmin     bool       `json:"is_admin"`
	AuthMethod  AuthMethod `json:"auth_method"`
	LastLoginAt *time.Time `json:"last_login_at,omitempty"`
	CreatedAt   time.Time  `json:"created_at"`
}