api

package
v0.1.4 Latest Latest
Warning

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

 Go to latest Published: Feb 3, 2026 License: MIT Imports: 15 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	CircuitBreakerThreshold = 5
	CircuitBreakerResetTime = 30 * time.Second
)
View Source 
const (
	BaseURL     = "https://api2.frontapp.com"
	UserAgent   = "frontcli/0.1.0"
	ContentType = "application/json"
)
View Source 
const (
	ExitSuccess   = 0
	ExitError     = 1
	ExitUsage     = 2
	ExitAuth      = 3
	ExitNotFound  = 4
	ExitRateLimit = 5
)
View Source 
const (
	MaxRateLimitRetries   = 3
	Max5xxRetries         = 1
	RateLimitBaseDelay    = 1 * time.Second
	ServerErrorRetryDelay = 2 * time.Second
)

Variables

View Source 
var (
	ErrNotAuthenticated = errors.New("not authenticated")
	ErrRateLimited      = errors.New("rate limit exceeded")
	ErrNotFound         = errors.New("not found")
)
View Source 
var ResourcePrefixes = map[string]string{
	"cnv_": "conversation",
	"msg_": "message",
	"cmt_": "comment",
	"tea_": "teammate",
	"tag_": "tag",
	"inb_": "inbox",
	"chn_": "channel",
	"ctc_": "contact",
	"acc_": "account",
	"rul_": "rule",
	"lnk_": "link",
	"shf_": "shift",
	"sig_": "signature",
	"evt_": "event",
	"drf_": "draft",
	"top_": "topic",
}

ResourcePrefixes maps ID prefixes to human-readable resource names. Front API IDs follow the pattern: prefix_base36id (e.g., cnv_abc123).

Functions

func ExtractPrefix added in v0.1.3 

func ExtractPrefix(id string) string

ExtractPrefix returns the prefix portion of a Front ID (e.g., "cnv_" from "cnv_abc123"). Returns empty string if no valid prefix found.

func FormatTimestamp 

func FormatTimestamp(ts float64) string

Helper to format Unix timestamp as string

func GetExpectedPrefixForResource added in v0.1.3 

func GetExpectedPrefixForResource(resourceType string) string

GetExpectedPrefixForResource returns the prefix for a resource type name.

func GetResourceType added in v0.1.3 

func GetResourceType(id string) string

GetResourceType returns the resource type for a given ID based on its prefix. Returns empty string if the prefix is not recognized.

func ParseStatus added in v0.1.2 

func ParseStatus(status string) []string

ParseStatus converts a user-friendly status to API statuses. "open" expands to ["assigned", "unassigned"].

func UnixToTime 

func UnixToTime(ts float64) time.Time

Helper to convert Unix timestamp to time.Time

func ValidateIDPrefix added in v0.1.3 

func ValidateIDPrefix(id, expectedPrefix string) error

ValidateIDPrefix checks if an ID has the expected prefix. Returns a WrongResourceTypeError if the ID has a recognized but incorrect prefix. Returns nil if the ID has the correct prefix or an unrecognized format.

Types

type APIError 

type APIError struct {
	StatusCode       int
	Message          string
	Details          string
	RequestedID      string // The ID used in the request (for hint generation)
	ExpectedResource string // Expected resource type (e.g., "conversation")
}

func (*APIError) Error 

func (e *APIError) Error() string

func (*APIError) ExitCode 

func (e *APIError) ExitCode() int

type Attachment 

type Attachment struct {
	ID          string `json:"id,omitempty"`
	Filename    string `json:"filename"`
	URL         string `json:"url,omitempty"`
	ContentType string `json:"content_type,omitempty"`
	Size        int64  `json:"size,omitempty"`
}

Attachment represents a message attachment.

type AuthError 

type AuthError struct {
	Err error
}

func (*AuthError) Error 

func (e *AuthError) Error() string

func (*AuthError) Unwrap 

func (e *AuthError) Unwrap() error

type Author 

type Author struct {
	ID        string `json:"id,omitempty"`
	Email     string `json:"email,omitempty"`
	Username  string `json:"username,omitempty"`
	FirstName string `json:"first_name,omitempty"`
	LastName  string `json:"last_name,omitempty"`
	IsBot     bool   `json:"is_bot,omitempty"`
	Links     Links  `json:"_links,omitempty"` //nolint:tagliatelle // Front API
}

Author represents the author of a message or comment.

type Channel 

type Channel struct {
	ID        string `json:"id"`
	Name      string `json:"name,omitempty"`
	Type      string `json:"type"` // email, sms, intercom, custom, etc.
	Address   string `json:"address,omitempty"`
	SendAs    string `json:"send_as,omitempty"`
	IsPrivate bool   `json:"is_private,omitempty"`
	IsValid   bool   `json:"is_valid,omitempty"`
	Links     Links  `json:"_links,omitempty"` //nolint:tagliatelle // Front API
}

Channel represents a Front channel.

type CircuitBreaker 

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

func NewCircuitBreaker 

func NewCircuitBreaker() *CircuitBreaker

func (*CircuitBreaker) IsOpen 

func (cb *CircuitBreaker) IsOpen() bool

func (*CircuitBreaker) RecordFailure 

func (cb *CircuitBreaker) RecordFailure() bool

func (*CircuitBreaker) RecordSuccess 

func (cb *CircuitBreaker) RecordSuccess()

type CircuitBreakerError 

type CircuitBreakerError struct{}

func (*CircuitBreakerError) Error 

func (e *CircuitBreakerError) Error() string

type Client 

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

Client is the Front API client.

func NewClient 

func NewClient(ts oauth2.TokenSource) *Client

NewClient creates a new API client with the given token source.

func NewClientFromAuth 

func NewClientFromAuth(clientName, email string) (*Client, error)

NewClientFromAuth creates a client using stored auth credentials.

func NewClientWithBaseURL 

func NewClientWithBaseURL(ts oauth2.TokenSource, baseURL string) *Client

NewClientWithBaseURL creates a new API client with a custom base URL.

func (*Client) Delete 

func (c *Client) Delete(ctx context.Context, path string) error

Delete performs a DELETE request.

func (*Client) Download 

func (c *Client) Download(ctx context.Context, path string, w io.Writer) error

Download performs a GET request and writes the response body to the writer.

func (*Client) Get 

func (c *Client) Get(ctx context.Context, path string, out interface{}) error

Get performs a GET request.

func (*Client) GetChannel 

func (c *Client) GetChannel(ctx context.Context, id string) (*Channel, error)

GetChannel gets a single channel by ID.

func (*Client) GetContact 

func (c *Client) GetContact(ctx context.Context, id string) (*Contact, error)

GetContact gets a single contact by ID.

func (*Client) GetConversation 

func (c *Client) GetConversation(ctx context.Context, id string) (*Conversation, error)

GetConversation gets a single conversation by ID.

func (*Client) GetInbox 

func (c *Client) GetInbox(ctx context.Context, id string) (*Inbox, error)

GetInbox gets a single inbox by ID.

func (*Client) GetMessage 

func (c *Client) GetMessage(ctx context.Context, id string) (*Message, error)

GetMessage gets a single message by ID.

func (*Client) GetTag 

func (c *Client) GetTag(ctx context.Context, id string) (*Tag, error)

GetTag gets a single tag by ID.

func (*Client) GetTeammate 

func (c *Client) GetTeammate(ctx context.Context, id string) (*Teammate, error)

GetTeammate gets a single teammate by ID.

func (*Client) ListChannels 

func (c *Client) ListChannels(ctx context.Context) (*ListResponse[Channel], error)

ListChannels lists all channels.

func (*Client) ListContacts 

func (c *Client) ListContacts(ctx context.Context, limit int) (*ListResponse[Contact], error)

ListContacts lists contacts.

func (*Client) ListContactsPage added in v0.1.1 

func (c *Client) ListContactsPage(ctx context.Context, pageURL string) (*ListResponse[Contact], error)

ListContactsPage fetches a page of contacts using a page token.

func (*Client) ListConversationMessages 

func (c *Client) ListConversationMessages(ctx context.Context, convID string, limit int) (*ListResponse[Message], error)

ListConversationMessages lists messages in a conversation.

func (*Client) ListConversations 

func (c *Client) ListConversations(ctx context.Context, opts ListConversationsOptions) (*ListResponse[Conversation], error)

ListConversations lists conversations with optional filters.

func (*Client) ListInboxes 

func (c *Client) ListInboxes(ctx context.Context) (*ListResponse[Inbox], error)

ListInboxes lists all inboxes.

func (*Client) ListTags 

func (c *Client) ListTags(ctx context.Context) (*ListResponse[Tag], error)

ListTags lists all tags.

func (*Client) ListTeammates 

func (c *Client) ListTeammates(ctx context.Context) (*ListResponse[Teammate], error)

ListTeammates lists all teammates.

func (*Client) Me 

func (c *Client) Me(ctx context.Context) (*Me, error)

Me returns the authenticated user's info.

func (*Client) Patch 

func (c *Client) Patch(ctx context.Context, path string, body interface{}, out interface{}) error

Patch performs a PATCH request.

func (*Client) Post 

func (c *Client) Post(ctx context.Context, path string, body interface{}, out interface{}) error

Post performs a POST request.

type Comment 

type Comment struct {
	ID       string  `json:"id"`
	Author   *Author `json:"author,omitempty"`
	Body     string  `json:"body"`
	PostedAt float64 `json:"posted_at"`
	Links    Links   `json:"_links,omitempty"` //nolint:tagliatelle // Front API
}

Comment represents an internal comment on a conversation.

type Contact 

type Contact struct {
	ID           string                 `json:"id"`
	Name         string                 `json:"name,omitempty"`
	Description  string                 `json:"description,omitempty"`
	AvatarURL    string                 `json:"avatar_url,omitempty"`
	IsSpammer    bool                   `json:"is_spammer,omitempty"`
	Links        Links                  `json:"_links,omitempty"` //nolint:tagliatelle // Front API
	Handles      []Handle               `json:"handles,omitempty"`
	Groups       []Group                `json:"groups,omitempty"`
	CustomFields map[string]interface{} `json:"custom_fields,omitempty"`
	CreatedAt    float64                `json:"created_at,omitempty"`
	UpdatedAt    float64                `json:"updated_at,omitempty"`
}

Contact represents a Front contact.

type ContactNote 

type ContactNote struct {
	ID        string  `json:"id"`
	Body      string  `json:"body"`
	Author    *Author `json:"author,omitempty"`
	CreatedAt float64 `json:"created_at,omitempty"`
	Links     Links   `json:"_links,omitempty"` //nolint:tagliatelle // Front API
}

ContactNote represents a note on a contact.

type Conversation 

type Conversation struct {
	ID           string     `json:"id"`
	Subject      string     `json:"subject"`
	Status       string     `json:"status"` // open, archived, snoozed, trashed
	Assignee     *Teammate  `json:"assignee,omitempty"`
	Recipient    *Recipient `json:"recipient,omitempty"`
	Tags         []Tag      `json:"tags,omitempty"`
	Inboxes      []Inbox    `json:"inboxes,omitempty"`
	CreatedAt    float64    `json:"created_at"` // Unix timestamp
	WaitingSince float64    `json:"waiting_since,omitempty"`
	Links        Links      `json:"_links,omitempty"` //nolint:tagliatelle // Front API //nolint:tagliatelle // Front API uses underscore prefix
}

Conversation represents a Front conversation.

type Draft 

type Draft struct {
	ID          string       `json:"id"`
	Version     int          `json:"version"`
	Body        string       `json:"body"`
	Author      *Author      `json:"author,omitempty"`
	To          []string     `json:"to,omitempty"`
	CC          []string     `json:"cc,omitempty"`
	BCC         []string     `json:"bcc,omitempty"`
	Subject     string       `json:"subject,omitempty"`
	Attachments []Attachment `json:"attachments,omitempty"`
	CreatedAt   float64      `json:"created_at"`
	UpdatedAt   float64      `json:"updated_at,omitempty"`
	Links       Links        `json:"_links,omitempty"` //nolint:tagliatelle // Front API //nolint:tagliatelle // Front API uses underscore prefix
}

Draft represents a draft message.

type Group 

type Group struct {
	ID   string `json:"id"`
	Name string `json:"name"`
}

Group represents a contact group.

type Handle 

type Handle struct {
	Handle string `json:"handle"`
	Source string `json:"source"` // email, phone, twitter, etc.
}

Handle represents a contact handle (email, phone, etc).

type Inbox 

type Inbox struct {
	ID           string                 `json:"id"`
	Name         string                 `json:"name"`
	IsPrivate    bool                   `json:"is_private,omitempty"`
	IsPublic     bool                   `json:"is_public,omitempty"`
	CustomFields map[string]interface{} `json:"custom_fields,omitempty"`
	Links        Links                  `json:"_links,omitempty"` //nolint:tagliatelle // Front API
}

Inbox represents a Front inbox. 

type Links struct {
	Self    string            `json:"self,omitempty"`
	Related map[string]string `json:"related,omitempty"`
}

Links contains HATEOAS links.

type ListConversationsOptions 

type ListConversationsOptions struct {
	InboxID   string
	TagID     string
	Statuses  []string // assigned, unassigned, archived, trashed, snoozed
	Limit     int
	PageToken string
	SortOrder string // asc, desc (default: desc = most recent first)
}

ListConversationsOptions contains options for listing conversations.

func (ListConversationsOptions) Query 

func (o ListConversationsOptions) Query() string

type ListResponse 

type ListResponse[T any] struct {
	Results    []T        `json:"_results"`              //nolint:tagliatelle // Front API
	Pagination Pagination `json:"_pagination,omitempty"` //nolint:tagliatelle // Front API
	Links      Links      `json:"_links,omitempty"`      //nolint:tagliatelle // Front API
}

ListResponse is the generic response for list endpoints.

type Me 

type Me struct {
	ID          string `json:"id"`
	Email       string `json:"email"`
	Username    string `json:"username,omitempty"`
	FirstName   string `json:"first_name,omitempty"`
	LastName    string `json:"last_name,omitempty"`
	IsAdmin     bool   `json:"is_admin,omitempty"`
	IsAvailable bool   `json:"is_available,omitempty"`
	Links       Links  `json:"_links,omitempty"` //nolint:tagliatelle // Front API
}

Me represents the authenticated user.

type Message 

type Message struct {
	ID          string       `json:"id"`
	Type        string       `json:"type"` // email, sms, intercom, custom, etc.
	IsInbound   bool         `json:"is_inbound"`
	CreatedAt   float64      `json:"created_at"`
	Blurb       string       `json:"blurb"`
	Author      *Author      `json:"author,omitempty"`
	Recipients  []Recipient  `json:"recipients,omitempty"`
	Body        string       `json:"body"`
	Text        string       `json:"text"`
	Subject     string       `json:"subject,omitempty"`
	Attachments []Attachment `json:"attachments,omitempty"`
	Links       Links        `json:"_links,omitempty"` //nolint:tagliatelle // Front API //nolint:tagliatelle // Front API uses underscore prefix
}

Message represents a message in a conversation.

type NotFoundError 

type NotFoundError struct {
	Resource string
	ID       string
}

func (*NotFoundError) Error 

func (e *NotFoundError) Error() string

type Pagination 

type Pagination struct {
	Next string `json:"next,omitempty"`
	Prev string `json:"prev,omitempty"`
}

Pagination represents cursor-based pagination.

type RateLimitError 

type RateLimitError struct {
	RetryAfter int // seconds
}

func (*RateLimitError) Error 

func (e *RateLimitError) Error() string

type RateLimiter 

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

func NewRateLimiter 

func NewRateLimiter() *RateLimiter

func (*RateLimiter) UpdateFromHeaders 

func (r *RateLimiter) UpdateFromHeaders(h http.Header)

func (*RateLimiter) Wait 

func (r *RateLimiter) Wait(ctx context.Context) error

type Recipient 

type Recipient struct {
	Handle string `json:"handle,omitempty"`
	Role   string `json:"role,omitempty"`   // to, cc, bcc, from
	Links  Links  `json:"_links,omitempty"` //nolint:tagliatelle // Front API
}

Recipient represents a message recipient.

type RetryTransport 

type RetryTransport struct {
	Base           http.RoundTripper
	MaxRetries429  int
	MaxRetries5xx  int
	BaseDelay      time.Duration
	CircuitBreaker *CircuitBreaker
}

RetryTransport wraps an http.RoundTripper with retry logic for rate limits (429) and server errors (5xx).

func NewRetryTransport 

func NewRetryTransport(base http.RoundTripper) *RetryTransport

func (*RetryTransport) RoundTrip 

func (t *RetryTransport) RoundTrip(req *http.Request) (*http.Response, error)

type Tag 

type Tag struct {
	ID          string  `json:"id"`
	Name        string  `json:"name"`
	Description string  `json:"description,omitempty"`
	Highlight   string  `json:"highlight,omitempty"` // color
	IsPrivate   bool    `json:"is_private,omitempty"`
	ParentTagID string  `json:"parent_tag_id,omitempty"`
	CreatedAt   float64 `json:"created_at,omitempty"`
	UpdatedAt   float64 `json:"updated_at,omitempty"`
	Links       Links   `json:"_links,omitempty"` //nolint:tagliatelle // Front API //nolint:tagliatelle // Front API uses underscore prefix
}

Tag represents a Front tag.

type Teammate 

type Teammate struct {
	ID          string `json:"id"`
	Email       string `json:"email"`
	Username    string `json:"username,omitempty"`
	FirstName   string `json:"first_name,omitempty"`
	LastName    string `json:"last_name,omitempty"`
	IsAdmin     bool   `json:"is_admin,omitempty"`
	IsAvailable bool   `json:"is_available,omitempty"`
	IsBlocked   bool   `json:"is_blocked,omitempty"`
	Links       Links  `json:"_links,omitempty"` //nolint:tagliatelle // Front API
}

Teammate represents a Front teammate.

type Template 

type Template struct {
	ID                string       `json:"id"`
	Name              string       `json:"name"`
	Subject           string       `json:"subject,omitempty"`
	Body              string       `json:"body"`
	IsAvailableForAll bool         `json:"is_available_for_all,omitempty"`
	Attachments       []Attachment `json:"attachments,omitempty"`
	Links             Links        `json:"_links,omitempty"` //nolint:tagliatelle // Front API
}

Template represents a canned response template.

type WrongResourceTypeError added in v0.1.3 

type WrongResourceTypeError struct {
	ExpectedType string // e.g., "conversation"
	ActualType   string // e.g., "message"
	ID           string // The ID that was provided
}

WrongResourceTypeError indicates the user provided an ID of the wrong resource type.

func (*WrongResourceTypeError) Error added in v0.1.3 

func (e *WrongResourceTypeError) Error() string

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.