fizzy

package
v0.2.4 Latest Latest
Warning

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

 Go to latest Published: Jul 24, 2026 License: MIT Imports: 22 Imported by: 0

Documentation

Overview

Code generated from openapi.json — DO NOT EDIT.

Code generated from openapi.json — DO NOT EDIT.

Code generated from openapi.json — DO NOT EDIT.

Code generated from openapi.json — DO NOT EDIT.

Code generated from openapi.json — DO NOT EDIT.

Code generated from openapi.json — DO NOT EDIT.

Code generated from openapi.json — DO NOT EDIT.

Package fizzy provides a Go SDK for the Fizzy API.

Code generated from openapi.json — DO NOT EDIT.

Code generated from openapi.json — DO NOT EDIT.

Code generated from openapi.json — DO NOT EDIT.

Code generated from openapi.json — DO NOT EDIT.

Code generated from openapi.json — DO NOT EDIT.

Code generated from openapi.json — DO NOT EDIT.

Code generated from openapi.json — DO NOT EDIT.

Code generated from openapi.json — DO NOT EDIT.

Code generated from openapi.json — DO NOT EDIT.

Code generated from openapi.json — DO NOT EDIT.

Code generated from openapi.json — DO NOT EDIT.

Code generated from openapi.json — DO NOT EDIT.

Index

Constants

View Source 
const (
	CodeUsage      = "usage"
	CodeNotFound   = "not_found"
	CodeAuth       = "auth_required"
	CodeForbidden  = "forbidden"
	CodeRateLimit  = "rate_limit"
	CodeNetwork    = "network"
	CodeAPI        = "api_error"
	CodeValidation = "validation"
	CodeAmbiguous  = "ambiguous"
)

Error codes for API responses.

View Source 
const (
	ExitOK         = 0 // Success
	ExitUsage      = 1 // Invalid arguments or flags
	ExitNotFound   = 2 // Resource not found
	ExitAuth       = 3 // Not authenticated
	ExitForbidden  = 4 // Access denied (scope issue)
	ExitRateLimit  = 5 // Rate limited (429)
	ExitNetwork    = 6 // Connection/DNS/timeout error
	ExitAPI        = 7 // Server returned error
	ExitAmbiguous  = 8 // Multiple matches for name
	ExitValidation = 9 // Validation error (422)
)

Exit codes for CLI tools.

View Source 
const (
	DefaultMaxRetries = 3
	DefaultBaseDelay  = 1 * time.Second
	DefaultMaxJitter  = 100 * time.Millisecond
	DefaultTimeout    = 30 * time.Second
	DefaultMaxPages   = 10000
)

Default values for HTTP client configuration. These can be overridden using functional options.

View Source 
const (
	// MaxResponseBodyBytes is the maximum size for successful API response bodies (50 MB).
	MaxResponseBodyBytes int64 = 50 * 1024 * 1024
	// MaxErrorBodyBytes is the maximum size for error response bodies (1 MB).
	MaxErrorBodyBytes int64 = 1 * 1024 * 1024
	// MaxErrorMessageBytes is the maximum length for error messages included in errors (500 bytes).
	MaxErrorMessageBytes = 500
)

Response body size limits.

View Source 
const APIVersion = "2026-03-01"

APIVersion is the Fizzy API version this SDK targets.

View Source 
const DefaultUserAgent = "fizzy-sdk-go/" + Version + " (api:" + APIVersion + ")"

DefaultUserAgent is the default User-Agent header value.

View Source 
const Version = "0.2.4"

Version is the current version of the Fizzy Go SDK.

Variables

View Source 
var (
	// ErrCircuitOpen is returned when the circuit breaker is open.
	ErrCircuitOpen = errors.New("circuit breaker is open")
	// ErrBulkheadFull is returned when the bulkhead has no available slots.
	ErrBulkheadFull = errors.New("bulkhead is full")
	// ErrRateLimited is returned when the rate limiter rejects a request.
	ErrRateLimited = errors.New("rate limit exceeded")
)

Resilience errors for circuit breaker, bulkhead, and rate limiting.

View Source 
var OperationRegistry = map[string]string{}/* 112 elements not displayed */

OperationRegistry maps every OpenAPI operationId to its Go service method. The drift check script (scripts/check-service-drift.sh) verifies this registry stays in sync with openapi.json.

To update: run 'go run ./cmd/generate-services/' from the go directory.

Functions

func ComputeWebhookSignature 

func ComputeWebhookSignature(payload []byte, secret string) string

ComputeWebhookSignature computes the HMAC-SHA256 signature for a webhook payload.

func ExitCodeFor 

func ExitCodeFor(code string) int

ExitCodeFor returns the exit code for a given error code.

func GetAPIProvenance 

func GetAPIProvenance() map[string]APIProvenance

GetAPIProvenance returns the provenance metadata for the API, keyed by app name (e.g., "fizzy").

func NormalizeBaseURL 

func NormalizeBaseURL(url string) string

NormalizeBaseURL ensures consistent URL format (no trailing slash).

func RedactHeaders 

func RedactHeaders(headers http.Header) http.Header

RedactHeaders returns a copy of the headers with sensitive values replaced by "[REDACTED]".

func RequireSecureEndpoint 

func RequireSecureEndpoint(rawURL string) error

RequireSecureEndpoint validates that an endpoint URL is secure. Secure means HTTPS, or localhost (including .localhost TLD per RFC 6761) which is trusted for local development.

func URLPathByOperation added in v0.2.2 

func URLPathByOperation(operationID string, params map[string]string) (string, bool)

URLPathByOperation returns the API path for an operation with path parameters applied. The path comes from the generated route table and uses URL-escaped parameter values.

func VerifyWebhookSignature 

func VerifyWebhookSignature(payload []byte, signature, secret string) bool

VerifyWebhookSignature checks that the given payload matches the HMAC-SHA256 signature. Returns false if secret or signature is empty.

func WithIdempotent 

func WithIdempotent(ctx context.Context) context.Context

WithIdempotent returns a context that marks the request as idempotent, enabling retry for POST requests that are naturally idempotent (e.g. toggle operations).

func WithNoRetry 

func WithNoRetry(ctx context.Context) context.Context

WithNoRetry returns a context that disables retry for the request.

Types

type APIProvenance 

type APIProvenance struct {
	Repo   string            `json:"repo"`
	Branch string            `json:"branch"`
	Paths  map[string]string `json:"paths,omitempty"`
}

APIProvenance tracks the upstream source of the API specification.

type AccessTokensService 

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

AccessTokensService handles access token operations (account-independent).

func NewAccessTokensService 

func NewAccessTokensService(client *Client) *AccessTokensService

NewAccessTokensService creates a new AccessTokensService.

func (*AccessTokensService) Create 

func (s *AccessTokensService) Create(ctx context.Context, req *generated.CreateAccessTokenRequest) (*generated.AccessToken, *Response, error)

Create creates an access token.

func (*AccessTokensService) Delete 

func (s *AccessTokensService) Delete(ctx context.Context, accessTokenID string) (*Response, error)

Delete deletes an access token.

func (*AccessTokensService) List 

func (s *AccessTokensService) List(ctx context.Context) ([]generated.AccessToken, *Response, error)

List returns access tokens.

type AccountClient 

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

AccountClient is an HTTP client bound to a specific Fizzy account. Create an AccountClient using Client.ForAccount(accountID). AccountClient is safe for concurrent use.

The Fizzy API requires an account ID in the URL path. AccountClient shares the parent Client's generated API client and HTTP resources. Creating multiple AccountClients via ForAccount is lightweight.

func (*AccountClient) Account 

func (ac *AccountClient) Account() *AccountService

Account returns the AccountService for account settings and management.

func (*AccountClient) AccountID 

func (ac *AccountClient) AccountID() string

AccountID returns the account ID this client is bound to.

func (*AccountClient) Boards 

func (ac *AccountClient) Boards() *BoardsService

Boards returns the BoardsService for board operations.

func (*AccountClient) Cards 

func (ac *AccountClient) Cards() *CardsService

Cards returns the CardsService for card operations.

func (*AccountClient) Columns 

func (ac *AccountClient) Columns() *ColumnsService

Columns returns the ColumnsService for column operations.

func (*AccountClient) Comments 

func (ac *AccountClient) Comments() *CommentsService

Comments returns the CommentsService for comment operations.

func (*AccountClient) Delete 

func (ac *AccountClient) Delete(ctx context.Context, path string) (*Response, error)

Delete performs an account-scoped DELETE request.

func (*AccountClient) Get 

func (ac *AccountClient) Get(ctx context.Context, path string) (*Response, error)

Get performs an account-scoped GET request.

func (*AccountClient) GetAll 

func (ac *AccountClient) GetAll(ctx context.Context, path string) ([]json.RawMessage, error)

GetAll fetches all pages for an account-scoped paginated resource.

func (*AccountClient) GetAllWithLimit 

func (ac *AccountClient) GetAllWithLimit(ctx context.Context, path string, limit int) ([]json.RawMessage, error)

GetAllWithLimit fetches pages for an account-scoped paginated resource up to a limit.

func (*AccountClient) Notifications 

func (ac *AccountClient) Notifications() *NotificationsService

Notifications returns the NotificationsService for notification operations.

func (*AccountClient) Patch 

func (ac *AccountClient) Patch(ctx context.Context, path string, body any) (*Response, error)

Patch performs an account-scoped PATCH request with a JSON body.

func (*AccountClient) Pins 

func (ac *AccountClient) Pins() *PinsService

Pins returns the PinsService for pin operations.

func (*AccountClient) Post 

func (ac *AccountClient) Post(ctx context.Context, path string, body any) (*Response, error)

Post performs an account-scoped POST request with a JSON body.

func (*AccountClient) Put 

func (ac *AccountClient) Put(ctx context.Context, path string, body any) (*Response, error)

Put performs an account-scoped PUT request with a JSON body.

func (*AccountClient) Reactions 

func (ac *AccountClient) Reactions() *ReactionsService

Reactions returns the ReactionsService for reaction operations.

func (*AccountClient) Search 

func (ac *AccountClient) Search() *SearchService

Search returns the SearchService for search operations.

func (*AccountClient) Steps 

func (ac *AccountClient) Steps() *StepsService

Steps returns the StepsService for step operations.

func (*AccountClient) Tags 

func (ac *AccountClient) Tags() *TagsService

Tags returns the TagsService for tag operations.

func (*AccountClient) Uploads 

func (ac *AccountClient) Uploads() *UploadsService

Uploads returns the UploadsService for upload operations.

func (*AccountClient) Users 

func (ac *AccountClient) Users() *UsersService

Users returns the UsersService for user operations.

func (*AccountClient) Webhooks 

func (ac *AccountClient) Webhooks() *WebhooksService

Webhooks returns the WebhooksService for webhook operations.

type AccountService 

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

AccountService handles account settings and management operations.

func NewAccountService 

func NewAccountService(client *AccountClient) *AccountService

NewAccountService creates a new AccountService.

func (*AccountService) CreateExport 

func (s *AccountService) CreateExport(ctx context.Context) (*generated.AccountExport, *Response, error)

CreateExport creates an export.

func (*AccountService) GetExport 

func (s *AccountService) GetExport(ctx context.Context, exportID string) (*generated.AccountExport, *Response, error)

GetExport returns an export.

func (*AccountService) GetJoinCode 

func (s *AccountService) GetJoinCode(ctx context.Context) (*generated.JoinCode, *Response, error)

GetJoinCode returns a join code.

func (*AccountService) GetSettings 

func (s *AccountService) GetSettings(ctx context.Context) (*generated.AccountSettings, *Response, error)

GetSettings returns settings.

func (*AccountService) ResetJoinCode 

func (s *AccountService) ResetJoinCode(ctx context.Context) (*Response, error)

ResetJoinCode performs the ResetJoinCode operation on an account.

func (*AccountService) UpdateEntropy 

func (s *AccountService) UpdateEntropy(ctx context.Context, req *generated.UpdateAccountEntropyRequest) (*generated.AccountSettings, *Response, error)

UpdateEntropy updates an entropy.

func (*AccountService) UpdateJoinCode 

func (s *AccountService) UpdateJoinCode(ctx context.Context, req *generated.UpdateJoinCodeRequest) (*Response, error)

UpdateJoinCode updates a join code.

func (*AccountService) UpdateSettings 

func (s *AccountService) UpdateSettings(ctx context.Context, req *generated.UpdateAccountSettingsRequest) (*Response, error)

UpdateSettings updates settings.

type AuthManager 

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

AuthManager handles session token management for Fizzy.

func NewAuthManager 

func NewAuthManager(cfg *Config) *AuthManager

NewAuthManager creates a new auth manager.

func NewAuthManagerWithStore 

func NewAuthManagerWithStore(cfg *Config, store *CredentialStore) *AuthManager

NewAuthManagerWithStore creates an auth manager with a custom credential store.

func (*AuthManager) AccessToken 

func (m *AuthManager) AccessToken(ctx context.Context) (string, error)

AccessToken returns a valid access token. If FIZZY_TOKEN env var is set, it's used directly.

func (*AuthManager) GetUserID 

func (m *AuthManager) GetUserID() string

GetUserID returns the stored user ID.

func (*AuthManager) IsAuthenticated 

func (m *AuthManager) IsAuthenticated() bool

IsAuthenticated checks if there are valid credentials.

func (*AuthManager) Logout 

func (m *AuthManager) Logout() error

Logout removes stored credentials.

func (*AuthManager) SaveSessionToken 

func (m *AuthManager) SaveSessionToken(token string) error

SaveSessionToken stores a session token obtained from login.

func (*AuthManager) SetUserID 

func (m *AuthManager) SetUserID(userID string) error

SetUserID stores the user ID.

func (*AuthManager) Store 

func (m *AuthManager) Store() *CredentialStore

Store returns the credential store.

type AuthStrategy 

type AuthStrategy interface {
	// Authenticate applies authentication to the given HTTP request.
	Authenticate(ctx context.Context, req *http.Request) error
}

AuthStrategy controls how authentication is applied to HTTP requests. The default strategy is BearerAuth, which uses a TokenProvider to set the Authorization header with a Bearer token.

Custom strategies can implement alternative auth schemes such as cookie-based auth or API keys.

type BearerAuth 

type BearerAuth struct {
	TokenProvider TokenProvider
}

BearerAuth implements AuthStrategy using Bearer tokens. This is the default authentication strategy.

func (*BearerAuth) Authenticate 

func (b *BearerAuth) Authenticate(ctx context.Context, req *http.Request) error

Authenticate sets the Authorization header with a Bearer token.

type BoardsService 

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

BoardsService handles board operations.

func NewBoardsService 

func NewBoardsService(client *AccountClient) *BoardsService

NewBoardsService creates a new BoardsService.

func (*BoardsService) Create 

func (s *BoardsService) Create(ctx context.Context, req *generated.CreateBoardRequest) (*generated.Board, *Response, error)

Create creates a board.

func (*BoardsService) Delete 

func (s *BoardsService) Delete(ctx context.Context, boardID string) (*Response, error)

Delete deletes a board.

func (*BoardsService) Get 

func (s *BoardsService) Get(ctx context.Context, boardID string) (*generated.Board, *Response, error)

Get returns a board.

func (*BoardsService) List 

func (s *BoardsService) List(ctx context.Context, path string) ([]generated.Board, *Response, error)

List returns boards.

func (*BoardsService) ListBoardAccesses added in v0.1.3 

func (s *BoardsService) ListBoardAccesses(ctx context.Context, boardID string, page *int64) (*generated.BoardAccesses, *Response, error)

ListBoardAccesses returns board accesses.

func (*BoardsService) ListClosed 

func (s *BoardsService) ListClosed(ctx context.Context, boardID string, path string) ([]generated.Card, *Response, error)

ListClosed returns closed cards.

func (*BoardsService) ListPostponed 

func (s *BoardsService) ListPostponed(ctx context.Context, boardID string, path string) ([]generated.Card, *Response, error)

ListPostponed returns postponed cards.

func (*BoardsService) ListStream 

func (s *BoardsService) ListStream(ctx context.Context, boardID string, path string) ([]generated.Card, *Response, error)

ListStream returns streams.

func (*BoardsService) Publish 

func (s *BoardsService) Publish(ctx context.Context, boardID string) (*Response, error)

Publish performs the Publish operation on a board.

func (*BoardsService) Unpublish 

func (s *BoardsService) Unpublish(ctx context.Context, boardID string) (*Response, error)

Unpublish performs the Unpublish operation on a board.

func (*BoardsService) Update 

func (s *BoardsService) Update(ctx context.Context, boardID string, req *generated.UpdateBoardRequest) (*generated.Board, *Response, error)

Update updates a board.

func (*BoardsService) UpdateEntropy 

func (s *BoardsService) UpdateEntropy(ctx context.Context, boardID string, req *generated.UpdateBoardEntropyRequest) (*generated.Board, *Response, error)

UpdateEntropy updates an entropy.

func (*BoardsService) UpdateInvolvement 

func (s *BoardsService) UpdateInvolvement(ctx context.Context, boardID string, req *generated.UpdateBoardInvolvementRequest) (*Response, error)

UpdateInvolvement updates an involvement.

type BulkheadConfig 

type BulkheadConfig struct {
	// MaxConcurrent is the maximum number of parallel requests.
	// Default: 10
	MaxConcurrent int

	// MaxWait is the maximum time to wait for a slot.
	// If zero, requests are rejected immediately when the bulkhead is full.
	// Default: 5s
	MaxWait time.Duration
}

BulkheadConfig configures concurrency limiting.

func DefaultBulkheadConfig 

func DefaultBulkheadConfig() *BulkheadConfig

DefaultBulkheadConfig returns production-ready defaults.

type Cache 

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

Cache provides ETag-based HTTP caching.

func NewCache 

func NewCache(dir string) *Cache

NewCache creates a new cache with the given directory.

func (*Cache) Clear 

func (c *Cache) Clear() error

Clear removes all cached data.

func (*Cache) GetBody 

func (c *Cache) GetBody(key string) []byte

GetBody returns the cached response body for a key, or nil if not found.

func (*Cache) GetETag 

func (c *Cache) GetETag(key string) string

GetETag returns the cached ETag for a key, or empty string if not found.

func (*Cache) Invalidate 

func (c *Cache) Invalidate(key string) error

Invalidate removes cached data for a specific key.

func (*Cache) Key 

func (c *Cache) Key(url, accountID, token string) string

Key generates a cache key for a URL, account, and token. The key includes a token hash to ensure different auth contexts don't share cache.

func (*Cache) Set 

func (c *Cache) Set(key string, body []byte, etag string) error

Set stores a response body and ETag for a key.

type CardsService 

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

CardsService handles card operations.

func NewCardsService 

func NewCardsService(client *AccountClient) *CardsService

NewCardsService creates a new CardsService.

func (*CardsService) Assign 

func (s *CardsService) Assign(ctx context.Context, cardNumber string, req *generated.AssignCardRequest) (*Response, error)

Assign performs the Assign operation on a card.

func (*CardsService) Close 

func (s *CardsService) Close(ctx context.Context, cardNumber string) (*Response, error)

Close performs the Close operation on a card.

func (*CardsService) Create 

func (s *CardsService) Create(ctx context.Context, req *generated.CreateCardRequest) (*generated.Card, *Response, error)

Create creates a card.

func (*CardsService) Delete 

func (s *CardsService) Delete(ctx context.Context, cardNumber string) (*Response, error)

Delete deletes a card.

func (*CardsService) DeleteImage 

func (s *CardsService) DeleteImage(ctx context.Context, cardNumber string) (*Response, error)

DeleteImage deletes an image.

func (*CardsService) Get 

func (s *CardsService) Get(ctx context.Context, cardNumber string) (*generated.Card, *Response, error)

Get returns a card.

func (*CardsService) Gold 

func (s *CardsService) Gold(ctx context.Context, cardNumber string) (*Response, error)

Gold performs the Gold operation on a card.

func (*CardsService) List 

func (s *CardsService) List(ctx context.Context, path string) ([]generated.Card, *Response, error)

List returns cards.

func (*CardsService) ListActivities added in v0.1.3 

func (s *CardsService) ListActivities(ctx context.Context, path string) ([]generated.Activity, *Response, error)

ListActivities returns activities.

func (*CardsService) ListColumnCards added in v0.1.3 

func (s *CardsService) ListColumnCards(ctx context.Context, boardID string, columnID string, path string) ([]generated.Card, *Response, error)

ListColumnCards returns cards.

func (*CardsService) MarkRead 

func (s *CardsService) MarkRead(ctx context.Context, cardNumber string) (*Response, error)

MarkRead performs the MarkRead operation on a card.

func (*CardsService) MarkUnread 

func (s *CardsService) MarkUnread(ctx context.Context, cardNumber string) (*Response, error)

MarkUnread performs the MarkUnread operation on a card.

func (*CardsService) Move 

func (s *CardsService) Move(ctx context.Context, cardNumber string, req *generated.MoveCardRequest) (*generated.Card, *Response, error)

Move performs the Move operation on a card.

func (*CardsService) Pin 

func (s *CardsService) Pin(ctx context.Context, cardNumber string) (*Response, error)

Pin performs the Pin operation on a card.

func (*CardsService) Postpone 

func (s *CardsService) Postpone(ctx context.Context, cardNumber string) (*Response, error)

Postpone performs the Postpone operation on a card.

func (*CardsService) Publish 

func (s *CardsService) Publish(ctx context.Context, cardNumber string) (*Response, error)

Publish performs the Publish operation on a card.

func (*CardsService) Reopen 

func (s *CardsService) Reopen(ctx context.Context, cardNumber string) (*Response, error)

Reopen performs the Reopen operation on a card.

func (*CardsService) SelfAssign 

func (s *CardsService) SelfAssign(ctx context.Context, cardNumber string) (*Response, error)

SelfAssign performs the SelfAssign operation on a card.

func (*CardsService) Tag 

func (s *CardsService) Tag(ctx context.Context, cardNumber string, req *generated.TagCardRequest) (*Response, error)

Tag performs the Tag operation on a card.

func (*CardsService) Triage 

func (s *CardsService) Triage(ctx context.Context, cardNumber string, req *generated.TriageCardRequest) (*Response, error)

Triage performs the Triage operation on a card.

func (*CardsService) UnTriage 

func (s *CardsService) UnTriage(ctx context.Context, cardNumber string) (*Response, error)

UnTriage performs the UnTriage operation on a card.

func (*CardsService) Ungold 

func (s *CardsService) Ungold(ctx context.Context, cardNumber string) (*Response, error)

Ungold performs the Ungold operation on a card.

func (*CardsService) Unpin 

func (s *CardsService) Unpin(ctx context.Context, cardNumber string) (*Response, error)

Unpin performs the Unpin operation on a card.

func (*CardsService) Unwatch 

func (s *CardsService) Unwatch(ctx context.Context, cardNumber string) (*Response, error)

Unwatch performs the Unwatch operation on a card.

func (*CardsService) Update 

func (s *CardsService) Update(ctx context.Context, cardNumber string, req *generated.UpdateCardRequest) (*generated.Card, *Response, error)

Update updates a card.

func (*CardsService) Watch 

func (s *CardsService) Watch(ctx context.Context, cardNumber string) (*Response, error)

Watch performs the Watch operation on a card.

type ChainHooks 

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

ChainHooks combines multiple Hooks implementations. Start events are called in order, end events are called in reverse order. This allows proper nesting of spans/traces.

func (*ChainHooks) OnOperationEnd 

func (c *ChainHooks) OnOperationEnd(ctx context.Context, op OperationInfo, err error, duration time.Duration)

OnOperationEnd calls all hooks in reverse order.

func (*ChainHooks) OnOperationGate 

func (c *ChainHooks) OnOperationGate(ctx context.Context, op OperationInfo) (context.Context, error)

OnOperationGate calls the first GatingHooks implementation in the chain.

func (*ChainHooks) OnOperationStart 

func (c *ChainHooks) OnOperationStart(ctx context.Context, op OperationInfo) context.Context

OnOperationStart calls all hooks in order.

func (*ChainHooks) OnRequestEnd 

func (c *ChainHooks) OnRequestEnd(ctx context.Context, info RequestInfo, result RequestResult)

OnRequestEnd calls all hooks in reverse order.

func (*ChainHooks) OnRequestStart 

func (c *ChainHooks) OnRequestStart(ctx context.Context, info RequestInfo) context.Context

OnRequestStart calls all hooks in order.

func (*ChainHooks) OnRetry 

func (c *ChainHooks) OnRetry(ctx context.Context, info RequestInfo, attempt int, err error)

OnRetry calls all hooks in order.

type CircuitBreakerConfig 

type CircuitBreakerConfig struct {
	// FailureThreshold is the number of failures before the circuit opens.
	// Default: 5
	FailureThreshold int

	// SuccessThreshold is the number of successes to close from half-open.
	// Default: 2
	SuccessThreshold int

	// OpenTimeout is the time before transitioning from open to half-open.
	// Default: 30s
	OpenTimeout time.Duration

	// FailureRateThreshold is the percentage failure rate to trigger opening.
	// Only evaluated when SlidingWindowSize requests have been made.
	// Default: 50 (meaning 50%)
	FailureRateThreshold float64

	// SlidingWindowSize is the number of requests to consider for rate calculation.
	// Default: 10
	SlidingWindowSize int

	// Now is a function that returns the current time. Used for testing.
	// If nil, time.Now is used.
	Now func() time.Time
}

CircuitBreakerConfig configures the circuit breaker.

func DefaultCircuitBreakerConfig 

func DefaultCircuitBreakerConfig() *CircuitBreakerConfig

DefaultCircuitBreakerConfig returns production-ready defaults.

type Client 

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

Client is an HTTP client for the Fizzy API. Client holds shared resources and is used to create AccountClient instances for specific Fizzy accounts via the ForAccount method.

Client is safe for concurrent use after construction. Do not modify the Config after the client is in use by multiple goroutines.

func NewClient 

func NewClient(cfg *Config, tokenProvider TokenProvider, opts ...ClientOption) *Client

NewClient creates a new API client with spec-driven defaults.

The client automatically:

  • Retries idempotent requests (GET/PUT/PATCH/DELETE) with exponential backoff
  • Does NOT retry POST on 429/5xx (to avoid duplicating data)
  • Respects Retry-After headers on 429 responses
  • Follows pagination via Link headers

func (*Client) AccessTokens 

func (c *Client) AccessTokens() *AccessTokensService

AccessTokens returns the AccessTokensService for access token operations.

func (*Client) Config 

func (c *Client) Config() Config

Config returns a copy of the client configuration.

func (*Client) Delete 

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

Delete performs a DELETE request.

func (*Client) Devices 

func (c *Client) Devices() *DevicesService

Devices returns the DevicesService for device operations.

func (*Client) FollowPagination 

func (c *Client) FollowPagination(ctx context.Context, httpResp *http.Response, firstPageCount, limit int) ([]json.RawMessage, error)

FollowPagination fetches additional pages following Link headers from an HTTP response. This is used after calling the generated client for the first page. The httpResp should be from the generated client's *WithResponse method. firstPageCount is the number of items already collected from the first page. limit is the maximum total items to return (0 = unlimited). Returns raw JSON items from subsequent pages only (first page items are handled by caller).

Fizzy does not emit X-Total-Count headers. Pagination relies solely on Link headers.

Security: Link headers are resolved against the current page URL and validated for same-origin against the original request to prevent SSRF and token leakage.

func (*Client) ForAccount 

func (c *Client) ForAccount(accountID string) *AccountClient

ForAccount returns an AccountClient bound to the specified Fizzy account. The accountID can be a numeric ID or an account slug. ForAccount panics if the accountID is empty.

func (*Client) Get 

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

Get performs a GET request.

func (*Client) GetAll 

func (c *Client) GetAll(ctx context.Context, path string) ([]json.RawMessage, error)

GetAll fetches all pages for a paginated resource.

func (*Client) GetAllWithLimit 

func (c *Client) GetAllWithLimit(ctx context.Context, path string, limit int) ([]json.RawMessage, error)

GetAllWithLimit fetches pages for a paginated resource up to a limit.

func (*Client) Identity 

func (c *Client) Identity() *IdentityService

Identity returns the IdentityService for identity operations.

func (*Client) Patch 

func (c *Client) Patch(ctx context.Context, path string, body any) (*Response, error)

Patch performs a PATCH request with a JSON body.

func (*Client) Post 

func (c *Client) Post(ctx context.Context, path string, body any) (*Response, error)

Post performs a POST request with a JSON body.

func (*Client) Put 

func (c *Client) Put(ctx context.Context, path string, body any) (*Response, error)

Put performs a PUT request with a JSON body.

func (*Client) Sessions 

func (c *Client) Sessions() *SessionsService

Sessions returns the SessionsService for session operations.

type ClientOption 

type ClientOption func(*Client)

ClientOption configures a Client.

func WithAuthStrategy 

func WithAuthStrategy(strategy AuthStrategy) ClientOption

WithAuthStrategy sets a custom authentication strategy. The default strategy is BearerAuth. Use CookieAuth for session-based auth.

func WithBaseDelay 

func WithBaseDelay(d time.Duration) ClientOption

WithBaseDelay sets the initial backoff delay.

func WithBulkhead 

func WithBulkhead(cfg *BulkheadConfig) ClientOption

WithBulkhead enables only the bulkhead (concurrency limiter).

func WithCache 

func WithCache(cache *Cache) ClientOption

WithCache sets a custom cache.

func WithCircuitBreaker 

func WithCircuitBreaker(cfg *CircuitBreakerConfig) ClientOption

WithCircuitBreaker enables only the circuit breaker.

func WithHTTPClient 

func WithHTTPClient(c *http.Client) ClientOption

WithHTTPClient sets a custom HTTP client.

func WithHooks 

func WithHooks(hooks Hooks) ClientOption

WithHooks sets the observability hooks for the client. Pass nil to disable hooks (uses NoopHooks).

func WithLogger 

func WithLogger(l *slog.Logger) ClientOption

WithLogger sets a custom slog logger for debug output.

func WithMaxJitter 

func WithMaxJitter(d time.Duration) ClientOption

WithMaxJitter sets the maximum random jitter to add to delays.

func WithMaxPages 

func WithMaxPages(n int) ClientOption

WithMaxPages sets the maximum pages to fetch in GetAll.

func WithMaxRetries 

func WithMaxRetries(n int) ClientOption

WithMaxRetries sets the maximum number of retry attempts for retryable requests.

func WithRateLimit 

func WithRateLimit(cfg *RateLimitConfig) ClientOption

WithRateLimit enables only client-side rate limiting.

func WithResilience 

func WithResilience(cfg *ResilienceConfig) ClientOption

WithResilience enables circuit breaker, bulkhead, and rate limiting. Pass nil to use DefaultResilienceConfig().

func WithTimeout 

func WithTimeout(d time.Duration) ClientOption

WithTimeout sets the HTTP request timeout.

func WithTransport 

func WithTransport(t http.RoundTripper) ClientOption

WithTransport sets a custom HTTP transport.

func WithUserAgent 

func WithUserAgent(ua string) ClientOption

WithUserAgent sets the User-Agent header.

type ColumnsService 

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

ColumnsService handles column operations.

func NewColumnsService 

func NewColumnsService(client *AccountClient) *ColumnsService

NewColumnsService creates a new ColumnsService.

func (*ColumnsService) Create 

func (s *ColumnsService) Create(ctx context.Context, boardID string, req *generated.CreateColumnRequest) (*generated.Column, *Response, error)

Create creates a column.

func (*ColumnsService) Delete 

func (s *ColumnsService) Delete(ctx context.Context, boardID string, columnID string) (*Response, error)

Delete deletes a column.

func (*ColumnsService) Get 

func (s *ColumnsService) Get(ctx context.Context, boardID string, columnID string) (*generated.Column, *Response, error)

Get returns a column.

func (*ColumnsService) List 

func (s *ColumnsService) List(ctx context.Context, boardID string) ([]generated.Column, *Response, error)

List returns columns.

func (*ColumnsService) MoveLeft 

func (s *ColumnsService) MoveLeft(ctx context.Context, columnID string) (*Response, error)

MoveLeft performs the MoveLeft operation on a column.

func (*ColumnsService) MoveRight 

func (s *ColumnsService) MoveRight(ctx context.Context, columnID string) (*Response, error)

MoveRight performs the MoveRight operation on a column.

func (*ColumnsService) Update 

func (s *ColumnsService) Update(ctx context.Context, boardID string, columnID string, req *generated.UpdateColumnRequest) (*generated.Column, *Response, error)

Update updates a column.

type CommentsService 

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

CommentsService handles comment operations.

func NewCommentsService 

func NewCommentsService(client *AccountClient) *CommentsService

NewCommentsService creates a new CommentsService.

func (*CommentsService) Create 

func (s *CommentsService) Create(ctx context.Context, cardNumber string, req *generated.CreateCommentRequest) (*generated.Comment, *Response, error)

Create creates a comment.

func (*CommentsService) Delete 

func (s *CommentsService) Delete(ctx context.Context, cardNumber string, commentID string) (*Response, error)

Delete deletes a comment.

func (*CommentsService) Get 

func (s *CommentsService) Get(ctx context.Context, cardNumber string, commentID string) (*generated.Comment, *Response, error)

Get returns a comment.

func (*CommentsService) List 

func (s *CommentsService) List(ctx context.Context, cardNumber string, path string) ([]generated.Comment, *Response, error)

List returns comments.

func (*CommentsService) Update 

func (s *CommentsService) Update(ctx context.Context, cardNumber string, commentID string, req *generated.UpdateCommentRequest) (*generated.Comment, *Response, error)

Update updates a comment.

type Config 

type Config struct {
	// BaseURL is the API base URL (e.g., "https://fizzy.do").
	BaseURL string `json:"base_url"`

	// Account is the default account identifier.
	Account string `json:"account"`

	// CacheDir is the directory for HTTP cache storage.
	CacheDir string `json:"cache_dir"`

	// CacheEnabled controls whether HTTP caching is enabled.
	CacheEnabled bool `json:"cache_enabled"`
}

Config holds the resolved configuration for API access.

func DefaultConfig 

func DefaultConfig() *Config

DefaultConfig returns a Config with sensible defaults.

func LoadConfig 

func LoadConfig(path string) (*Config, error)

LoadConfig loads configuration from a JSON file.

func (*Config) LoadConfigFromEnv 

func (c *Config) LoadConfigFromEnv()

LoadConfigFromEnv loads configuration from environment variables. Environment variables override any values already set in the config.

type CookieAuth 

type CookieAuth struct {
	TokenProvider TokenProvider
}

CookieAuth implements AuthStrategy using session cookies. Sets Cookie: session_token=<value> header for session-based auth.

func (*CookieAuth) Authenticate 

func (c *CookieAuth) Authenticate(ctx context.Context, req *http.Request) error

Authenticate sets the Cookie header with a session token.

type CreateSessionRequest 

type CreateSessionRequest struct {
	Email string `json:"email"`
}

CreateSessionRequest is the request body for creating a session.

type CreateSessionResponse 

type CreateSessionResponse struct {
	Message string `json:"message"`
}

CreateSessionResponse is the response from creating a session.

type CredentialStore 

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

CredentialStore handles secure credential storage.

func NewCredentialStore 

func NewCredentialStore(fallbackDir string) *CredentialStore

NewCredentialStore creates a credential store. It prefers the system keyring if available, falling back to file storage.

func (*CredentialStore) Delete 

func (s *CredentialStore) Delete(origin string) error

Delete removes credentials for the given origin.

func (*CredentialStore) Load 

func (s *CredentialStore) Load(origin string) (*Credentials, error)

Load retrieves credentials for the given origin.

func (*CredentialStore) Save 

func (s *CredentialStore) Save(origin string, creds *Credentials) error

Save stores credentials for the given origin.

func (*CredentialStore) UsingKeyring 

func (s *CredentialStore) UsingKeyring() bool

UsingKeyring returns true if the store is using the system keyring.

type Credentials 

type Credentials struct {
	SessionToken string `json:"session_token"`
	UserID       string `json:"user_id,omitempty"`
}

Credentials holds session tokens and metadata.

type DevicesService 

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

DevicesService handles device registration operations (account-independent).

func NewDevicesService 

func NewDevicesService(client *Client) *DevicesService

NewDevicesService creates a new DevicesService.

func (*DevicesService) Register 

func (s *DevicesService) Register(ctx context.Context, accountID string, req *generated.RegisterDeviceRequest) (*Response, error)

Register performs the Register operation on a device.

func (*DevicesService) Unregister 

func (s *DevicesService) Unregister(ctx context.Context, accountID string, deviceToken string) (*Response, error)

Unregister performs the Unregister operation on a device.

type Error 

type Error struct {
	Code       string
	Message    string
	Hint       string
	HTTPStatus int
	Retryable  bool
	RequestID  string
	Cause      error
}

Error is a structured error with code, message, and optional hint.

func AsError 

func AsError(err error) *Error

AsError attempts to convert an error to an *Error. If the error is not an *Error, it wraps it in one.

func ErrAPI 

func ErrAPI(status int, msg string) *Error

ErrAPI creates an API error with an HTTP status code.

func ErrAmbiguous 

func ErrAmbiguous(resource string, matches []string) *Error

ErrAmbiguous creates an ambiguous match error.

func ErrAuth 

func ErrAuth(msg string) *Error

ErrAuth creates an authentication error.

func ErrForbidden 

func ErrForbidden(msg string) *Error

ErrForbidden creates a forbidden error.

func ErrForbiddenScope 

func ErrForbiddenScope() *Error

ErrForbiddenScope creates a forbidden error due to insufficient scope.

func ErrNetwork 

func ErrNetwork(cause error) *Error

ErrNetwork creates a network error.

func ErrNotFound 

func ErrNotFound(resource, identifier string) *Error

ErrNotFound creates a not-found error.

func ErrNotFoundHint 

func ErrNotFoundHint(resource, identifier, hint string) *Error

ErrNotFoundHint creates a not-found error with a hint.

func ErrRateLimit 

func ErrRateLimit(retryAfter int) *Error

ErrRateLimit creates a rate-limit error.

func ErrUsage 

func ErrUsage(msg string) *Error

ErrUsage creates a usage error.

func ErrUsageHint 

func ErrUsageHint(msg, hint string) *Error

ErrUsageHint creates a usage error with a hint.

func (*Error) Error 

func (e *Error) Error() string

Error implements the error interface.

func (*Error) ExitCode 

func (e *Error) ExitCode() int

ExitCode returns the appropriate exit code for this error.

func (*Error) Unwrap 

func (e *Error) Unwrap() error

Unwrap returns the underlying cause for errors.Is/As support.

type GatingHooks 

type GatingHooks interface {
	Hooks
	// OnOperationGate is called before OnOperationStart.
	// Returns a new context and an error. Return non-nil error to reject the operation.
	OnOperationGate(ctx context.Context, op OperationInfo) (context.Context, error)
}

GatingHooks extends Hooks with request gating capability. Implementations can reject operations before they execute, enabling patterns like circuit breakers, bulkheads, and rate limiters.

type HTTPOptions 

type HTTPOptions struct {
	// Timeout is the request timeout (default: 30s).
	Timeout time.Duration

	// MaxRetries is the maximum retry attempts for retryable requests (default: 3).
	// GET, PUT, PATCH, DELETE, and HEAD are always retryable. POST is retryable
	// only when marked idempotent via WithIdempotent(ctx).
	MaxRetries int

	// BaseDelay is the initial backoff delay (default: 1s).
	BaseDelay time.Duration

	// MaxJitter is the maximum random jitter to add to delays (default: 100ms).
	MaxJitter time.Duration

	// MaxPages is the maximum pages to fetch in GetAll (default: 10000).
	MaxPages int

	// Transport is the HTTP transport to use. If nil, a default transport
	// with sensible connection pooling is created.
	Transport http.RoundTripper
}

HTTPOptions configures the HTTP client behavior.

func DefaultHTTPOptions 

func DefaultHTTPOptions() HTTPOptions

DefaultHTTPOptions returns HTTPOptions with sensible defaults.

type Hooks 

type Hooks interface {
	// OnOperationStart is called when a semantic SDK operation begins.
	OnOperationStart(ctx context.Context, op OperationInfo) context.Context

	// OnOperationEnd is called when a semantic SDK operation completes.
	OnOperationEnd(ctx context.Context, op OperationInfo, err error, duration time.Duration)

	// OnRequestStart is called before an HTTP request is sent.
	OnRequestStart(ctx context.Context, info RequestInfo) context.Context

	// OnRequestEnd is called after an HTTP request completes.
	OnRequestEnd(ctx context.Context, info RequestInfo, result RequestResult)

	// OnRetry is called before a retry attempt.
	OnRetry(ctx context.Context, info RequestInfo, attempt int, err error)
}

Hooks provides observability callbacks for SDK operations. Implementations can use these hooks for logging, metrics, tracing, etc.

There are two levels of hooks:

  • Operation-level: OnOperationStart/OnOperationEnd for semantic SDK operations
  • Request-level: OnRequestStart/OnRequestEnd for HTTP requests

func NewChainHooks 

func NewChainHooks(hooks ...Hooks) Hooks

NewChainHooks creates a ChainHooks from the given hooks. Nil hooks are filtered out. If all hooks are nil, returns NoopHooks.

type IdentityService 

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

IdentityService handles identity operations (account-independent).

func NewIdentityService 

func NewIdentityService(client *Client) *IdentityService

NewIdentityService creates a new IdentityService.

func (*IdentityService) GetMyIdentity 

func (s *IdentityService) GetMyIdentity(ctx context.Context) (*generated.Identity, *Response, error)

GetMyIdentity returns an identity.

func (*IdentityService) UpdateMyTimezone added in v0.2.2 

func (s *IdentityService) UpdateMyTimezone(ctx context.Context, accountID string, req *generated.UpdateMyTimezoneRequest) (*Response, error)

UpdateMyTimezone updates my timezone.

type ListMeta 

type ListMeta struct{}

ListMeta contains pagination metadata from list operations. Fizzy does not emit X-Total-Count headers; pagination relies on Link headers.

type MagicLinkFlow 

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

MagicLinkFlow orchestrates passwordless login via magic links. The flow is:

  1. CreateSession — sends a magic link to the user's email
  2. User clicks the magic link in their email
  3. RedeemMagicLink — exchanges the magic link token for a session token

func NewMagicLinkFlow 

func NewMagicLinkFlow(baseURL string, httpClient *http.Client) *MagicLinkFlow

NewMagicLinkFlow creates a new magic link flow.

func (*MagicLinkFlow) CreateSession 

func (f *MagicLinkFlow) CreateSession(ctx context.Context, email string) (*CreateSessionResponse, error)

CreateSession initiates the magic link flow by sending a magic link email.

func (*MagicLinkFlow) Login 

func (f *MagicLinkFlow) Login(ctx context.Context, authManager *AuthManager, magicLinkToken string) error

Login performs the full magic link login flow and stores the session token. After calling CreateSession, the caller must obtain the magic link token (e.g., by prompting the user to check their email), then call RedeemMagicLink. This method handles the final step of storing the token. 

func (f *MagicLinkFlow) RedeemMagicLink(ctx context.Context, token string) (*RedeemMagicLinkResponse, error)

RedeemMagicLink exchanges a magic link token for a session token.

type NoopHooks 

type NoopHooks struct{}

NoopHooks is a no-op implementation of Hooks. All methods are empty and designed to be inlined by the compiler, resulting in zero overhead when no observability is needed.

func (NoopHooks) OnOperationEnd 

func (NoopHooks) OnOperationEnd(context.Context, OperationInfo, error, time.Duration)

OnOperationEnd does nothing.

func (NoopHooks) OnOperationStart 

func (NoopHooks) OnOperationStart(ctx context.Context, _ OperationInfo) context.Context

OnOperationStart does nothing and returns the context unchanged.

func (NoopHooks) OnRequestEnd 

func (NoopHooks) OnRequestEnd(context.Context, RequestInfo, RequestResult)

OnRequestEnd does nothing.

func (NoopHooks) OnRequestStart 

func (NoopHooks) OnRequestStart(ctx context.Context, _ RequestInfo) context.Context

OnRequestStart does nothing and returns the context unchanged.

func (NoopHooks) OnRetry 

func (NoopHooks) OnRetry(context.Context, RequestInfo, int, error)

OnRetry does nothing.

type NotificationsService 

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

NotificationsService handles notification operations.

func NewNotificationsService 

func NewNotificationsService(client *AccountClient) *NotificationsService

NewNotificationsService creates a new NotificationsService.

func (*NotificationsService) BulkRead 

func (s *NotificationsService) BulkRead(ctx context.Context, req *generated.BulkReadNotificationsRequest) (*Response, error)

BulkRead performs the BulkRead operation on a notification.

func (*NotificationsService) GetSettings 

func (s *NotificationsService) GetSettings(ctx context.Context) (*generated.NotificationSettings, *Response, error)

GetSettings returns settings.

func (*NotificationsService) GetTray 

func (s *NotificationsService) GetTray(ctx context.Context, includeRead *bool) ([]generated.Notification, *Response, error)

GetTray returns a tray.

func (*NotificationsService) List 

func (s *NotificationsService) List(ctx context.Context, path string) ([]generated.Notification, *Response, error)

List returns notifications.

func (*NotificationsService) Read 

func (s *NotificationsService) Read(ctx context.Context, notificationID string) (*Response, error)

Read performs the Read operation on a notification.

func (*NotificationsService) Unread 

func (s *NotificationsService) Unread(ctx context.Context, notificationID string) (*Response, error)

Unread performs the Unread operation on a notification.

func (*NotificationsService) UpdateSettings 

func (s *NotificationsService) UpdateSettings(ctx context.Context, req *generated.UpdateNotificationSettingsRequest) (*Response, error)

UpdateSettings updates settings.

type OperationInfo 

type OperationInfo struct {
	// Service is the logical service (e.g., "Cards", "Boards").
	Service string
	// Operation is the specific method (e.g., "List", "Create", "Close").
	Operation string
	// ResourceType is the Fizzy resource type (e.g., "card", "board").
	ResourceType string
	// IsMutation indicates if this operation modifies state.
	IsMutation bool
	// ResourceID is the specific resource ID if applicable.
	ResourceID int64
}

OperationInfo describes a semantic SDK operation.

type PinsService 

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

PinsService handles pin operations.

func NewPinsService 

func NewPinsService(client *AccountClient) *PinsService

NewPinsService creates a new PinsService.

func (*PinsService) List 

func (s *PinsService) List(ctx context.Context) ([]generated.Card, *Response, error)

List returns pins.

type RateLimitConfig 

type RateLimitConfig struct {
	// RequestsPerSecond is the sustained rate of requests allowed.
	// Default: 50
	RequestsPerSecond float64

	// BurstSize is the maximum number of requests allowed in a burst.
	// Default: 10
	BurstSize int

	// RespectRetryAfter honors 429 Retry-After headers by blocking requests
	// until the server-specified time has passed.
	// Default: true
	RespectRetryAfter bool

	// Now is a function that returns the current time. Used for testing.
	// If nil, time.Now is used.
	Now func() time.Time
}

RateLimitConfig configures client-side rate limiting.

func DefaultRateLimitConfig 

func DefaultRateLimitConfig() *RateLimitConfig

DefaultRateLimitConfig returns production-ready defaults.

type ReactionsService 

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

ReactionsService handles reaction operations.

func NewReactionsService 

func NewReactionsService(client *AccountClient) *ReactionsService

NewReactionsService creates a new ReactionsService.

func (*ReactionsService) CreateCard 

func (s *ReactionsService) CreateCard(ctx context.Context, cardNumber string, req *generated.CreateCardReactionRequest) (*generated.Reaction, *Response, error)

CreateCard creates a reaction.

func (*ReactionsService) CreateComment 

func (s *ReactionsService) CreateComment(ctx context.Context, cardNumber string, commentID string, req *generated.CreateCommentReactionRequest) (*generated.Reaction, *Response, error)

CreateComment creates a reaction.

func (*ReactionsService) DeleteCard 

func (s *ReactionsService) DeleteCard(ctx context.Context, cardNumber string, reactionID string) (*Response, error)

DeleteCard deletes a reaction.

func (*ReactionsService) DeleteComment 

func (s *ReactionsService) DeleteComment(ctx context.Context, cardNumber string, commentID string, reactionID string) (*Response, error)

DeleteComment deletes a reaction.

func (*ReactionsService) ListCard 

func (s *ReactionsService) ListCard(ctx context.Context, cardNumber string) ([]generated.Reaction, *Response, error)

ListCard returns reactions.

func (*ReactionsService) ListComment 

func (s *ReactionsService) ListComment(ctx context.Context, cardNumber string, commentID string) ([]generated.Reaction, *Response, error)

ListComment returns reactions.

type RedeemMagicLinkRequest 

type RedeemMagicLinkRequest struct {
	Token string `json:"token"`
}

RedeemMagicLinkRequest is the request body for redeeming a magic link.

type RedeemMagicLinkResponse 

type RedeemMagicLinkResponse struct {
	SessionToken string `json:"session_token"`
	UserID       string `json:"user_id"`
}

RedeemMagicLinkResponse is the response from redeeming a magic link.

type RequestInfo 

type RequestInfo struct {
	Method string
	URL    string
	// Attempt is the current attempt number (1-indexed).
	Attempt int
}

RequestInfo contains information about an HTTP request.

type RequestResult 

type RequestResult struct {
	// StatusCode is the HTTP status code (0 if request failed before response).
	StatusCode int
	// Duration is the time taken for the request.
	Duration time.Duration
	// Error is non-nil if the request failed.
	Error error
	// FromCache indicates the response was served from cache.
	FromCache bool
	// Retryable indicates whether this error will be retried.
	Retryable bool
	// RetryAfter is the Retry-After header value in seconds (0 if not present).
	RetryAfter int
}

RequestResult contains the result of an HTTP request.

type ResilienceConfig 

type ResilienceConfig struct {
	// CircuitBreaker configuration. If nil, circuit breaker is disabled.
	CircuitBreaker *CircuitBreakerConfig

	// Bulkhead configuration. If nil, bulkhead is disabled.
	Bulkhead *BulkheadConfig

	// RateLimit configuration. If nil, rate limiting is disabled.
	RateLimit *RateLimitConfig
}

ResilienceConfig combines all resilience settings. Use DefaultResilienceConfig() for production-ready defaults.

func DefaultResilienceConfig 

func DefaultResilienceConfig() *ResilienceConfig

DefaultResilienceConfig returns production-ready defaults for all resilience features.

type Response 

type Response struct {
	Data       json.RawMessage
	StatusCode int
	Headers    http.Header
	FromCache  bool
}

Response wraps an API response.

func (*Response) UnmarshalData 

func (r *Response) UnmarshalData(v any) error

UnmarshalData unmarshals the response data into the given value.

type SearchService 

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

SearchService handles search operations.

func NewSearchService 

func NewSearchService(client *AccountClient) *SearchService

NewSearchService creates a new SearchService.

func (*SearchService) Search 

func (s *SearchService) Search(ctx context.Context, q *string) ([]generated.Card, *Response, error)

Search performs the Search operation on a search.

type SessionsService 

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

SessionsService handles session operations (account-independent).

func NewSessionsService 

func NewSessionsService(client *Client) *SessionsService

NewSessionsService creates a new SessionsService.

func (*SessionsService) CompleteJoin 

func (s *SessionsService) CompleteJoin(ctx context.Context, req *generated.CompleteJoinRequest) (*Response, error)

CompleteJoin performs the CompleteJoin operation on a session.

func (*SessionsService) CompleteSignup 

func (s *SessionsService) CompleteSignup(ctx context.Context, req *generated.CompleteSignupRequest) (*Response, error)

CompleteSignup performs the CompleteSignup operation on a session.

func (*SessionsService) Create 

func (s *SessionsService) Create(ctx context.Context, req *generated.CreateSessionRequest) (*generated.PendingAuthentication, *Response, error)

Create creates a session.

func (*SessionsService) Destroy 

func (s *SessionsService) Destroy(ctx context.Context) (*Response, error)

Destroy performs the Destroy operation on a session. 

func (s *SessionsService) RedeemMagicLink(ctx context.Context, req *generated.RedeemMagicLinkRequest) (*generated.SessionAuthorization, *Response, error)

RedeemMagicLink performs the RedeemMagicLink operation on a session.

type SlogHooks 

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

SlogHooks is a Hooks implementation that logs to a *slog.Logger. It provides structured logging for all SDK operations (both semantic and HTTP).

func NewSlogHooks 

func NewSlogHooks(logger *slog.Logger, opts ...SlogHooksOption) *SlogHooks

NewSlogHooks creates a new SlogHooks that logs to the given logger. If logger is nil, uses slog.Default().

func (*SlogHooks) OnOperationEnd 

func (h *SlogHooks) OnOperationEnd(ctx context.Context, op OperationInfo, err error, duration time.Duration)

OnOperationEnd logs the completion of a semantic SDK operation.

func (*SlogHooks) OnOperationStart 

func (h *SlogHooks) OnOperationStart(ctx context.Context, op OperationInfo) context.Context

OnOperationStart logs the start of a semantic SDK operation.

func (*SlogHooks) OnRequestEnd 

func (h *SlogHooks) OnRequestEnd(ctx context.Context, info RequestInfo, result RequestResult)

OnRequestEnd logs the completion of an HTTP request.

func (*SlogHooks) OnRequestStart 

func (h *SlogHooks) OnRequestStart(ctx context.Context, info RequestInfo) context.Context

OnRequestStart logs the start of an HTTP request.

func (*SlogHooks) OnRetry 

func (h *SlogHooks) OnRetry(ctx context.Context, info RequestInfo, attempt int, err error)

OnRetry logs a retry attempt.

type SlogHooksOption 

type SlogHooksOption func(*SlogHooks)

SlogHooksOption configures a SlogHooks instance.

func WithLevel 

func WithLevel(level slog.Level) SlogHooksOption

WithLevel sets the log level for SlogHooks. Default is slog.LevelDebug.

type StaticTokenProvider 

type StaticTokenProvider struct {
	Token string
}

StaticTokenProvider provides a fixed token (e.g., from FIZZY_TOKEN env var).

func (*StaticTokenProvider) AccessToken 

func (p *StaticTokenProvider) AccessToken(ctx context.Context) (string, error)

AccessToken returns the static token.

type StepsService 

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

StepsService handles step operations.

func NewStepsService 

func NewStepsService(client *AccountClient) *StepsService

NewStepsService creates a new StepsService.

func (*StepsService) Create 

func (s *StepsService) Create(ctx context.Context, cardNumber string, req *generated.CreateStepRequest) (*generated.Step, *Response, error)

Create creates a step.

func (*StepsService) Delete 

func (s *StepsService) Delete(ctx context.Context, cardNumber string, stepID string) (*Response, error)

Delete deletes a step.

func (*StepsService) Get 

func (s *StepsService) Get(ctx context.Context, cardNumber string, stepID string) (*generated.Step, *Response, error)

Get returns a step.

func (*StepsService) List 

func (s *StepsService) List(ctx context.Context, cardNumber string) ([]generated.Step, *Response, error)

List returns steps.

func (*StepsService) Update 

func (s *StepsService) Update(ctx context.Context, cardNumber string, stepID string, req *generated.UpdateStepRequest) (*generated.Step, *Response, error)

Update updates a step.

type TagsService 

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

TagsService handles tag operations.

func NewTagsService 

func NewTagsService(client *AccountClient) *TagsService

NewTagsService creates a new TagsService.

func (*TagsService) List 

func (s *TagsService) List(ctx context.Context, path string) ([]generated.Tag, *Response, error)

List returns tags.

type TokenProvider 

type TokenProvider interface {
	// AccessToken returns a valid access token.
	AccessToken(ctx context.Context) (string, error)
}

TokenProvider is the interface for obtaining access tokens.

type URLRoute 

type URLRoute struct {
	Pattern    string                   `json:"pattern"`
	APIPath    string                   `json:"api_path"`
	Resource   string                   `json:"resource"`
	Operations map[string]string        `json:"operations"`
	Params     map[string]URLRouteParam `json:"params"`
}

URLRoute describes a single API route pattern.

func URLRouteByOperation 

func URLRouteByOperation(operationID string) (URLRoute, bool)

URLRouteByOperation returns the route pattern for the given operation ID.

func URLRoutes 

func URLRoutes() []URLRoute

URLRoutes returns the list of all API route patterns. The data is parsed once from the embedded url-routes.json.

type URLRouteParam 

type URLRouteParam struct {
	Role string `json:"role"`
	Type string `json:"type"`
}

URLRouteParam describes a path parameter in a route pattern.

type UploadsService 

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

UploadsService handles upload operations.

func NewUploadsService 

func NewUploadsService(client *AccountClient) *UploadsService

NewUploadsService creates a new UploadsService.

func (*UploadsService) CreateDirectUpload 

func (s *UploadsService) CreateDirectUpload(ctx context.Context, req *generated.CreateDirectUploadRequest) (*generated.DirectUpload, *Response, error)

CreateDirectUpload creates an upload.

type UsersService 

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

UsersService handles user operations.

func NewUsersService 

func NewUsersService(client *AccountClient) *UsersService

NewUsersService creates a new UsersService.

func (*UsersService) ConfirmEmailAddressChange added in v0.1.3 

func (s *UsersService) ConfirmEmailAddressChange(ctx context.Context, userID string, emailAddressToken string) (*Response, error)

ConfirmEmailAddressChange performs the ConfirmEmailAddressChange operation on a user.

func (*UsersService) CreatePushSubscription 

func (s *UsersService) CreatePushSubscription(ctx context.Context, userID string, req *generated.CreatePushSubscriptionRequest) (*Response, error)

CreatePushSubscription creates a push subscription.

func (*UsersService) CreateUserDataExport added in v0.1.3 

func (s *UsersService) CreateUserDataExport(ctx context.Context, userID string) (*generated.DataExport, *Response, error)

CreateUserDataExport creates a user data export.

func (*UsersService) Deactivate 

func (s *UsersService) Deactivate(ctx context.Context, userID string) (*Response, error)

Deactivate performs the Deactivate operation on a user.

func (*UsersService) DeleteAvatar 

func (s *UsersService) DeleteAvatar(ctx context.Context, userID string) (*Response, error)

DeleteAvatar deletes an avatar.

func (*UsersService) DeletePushSubscription 

func (s *UsersService) DeletePushSubscription(ctx context.Context, userID string, pushSubscriptionID string) (*Response, error)

DeletePushSubscription deletes a push subscription.

func (*UsersService) Get 

func (s *UsersService) Get(ctx context.Context, userID string) (*generated.User, *Response, error)

Get returns a user.

func (*UsersService) GetUserDataExport added in v0.1.3 

func (s *UsersService) GetUserDataExport(ctx context.Context, userID string, exportID string) (*generated.DataExport, *Response, error)

GetUserDataExport returns a user data export.

func (*UsersService) List 

func (s *UsersService) List(ctx context.Context, path string) ([]generated.User, *Response, error)

List returns users.

func (*UsersService) RequestEmailAddressChange added in v0.1.3 

func (s *UsersService) RequestEmailAddressChange(ctx context.Context, userID string, req *generated.RequestEmailAddressChangeRequest) (*Response, error)

RequestEmailAddressChange performs the RequestEmailAddressChange operation on a user.

func (*UsersService) Update 

func (s *UsersService) Update(ctx context.Context, userID string, req *generated.UpdateUserRequest) (*generated.User, *Response, error)

Update updates a user.

func (*UsersService) UpdateRole 

func (s *UsersService) UpdateRole(ctx context.Context, userID string, req *generated.UpdateUserRoleRequest) (*Response, error)

UpdateRole updates a role.

type WebhooksService 

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

WebhooksService handles webhook operations.

func NewWebhooksService 

func NewWebhooksService(client *AccountClient) *WebhooksService

NewWebhooksService creates a new WebhooksService.

func (*WebhooksService) Activate 

func (s *WebhooksService) Activate(ctx context.Context, boardID string, webhookID string) (*Response, error)

Activate performs the Activate operation on a webhook.

func (*WebhooksService) Create 

func (s *WebhooksService) Create(ctx context.Context, boardID string, req *generated.CreateWebhookRequest) (*generated.Webhook, *Response, error)

Create creates a webhook.

func (*WebhooksService) Delete 

func (s *WebhooksService) Delete(ctx context.Context, boardID string, webhookID string) (*Response, error)

Delete deletes a webhook.

func (*WebhooksService) Get 

func (s *WebhooksService) Get(ctx context.Context, boardID string, webhookID string) (*generated.Webhook, *Response, error)

Get returns a webhook.

func (*WebhooksService) List 

func (s *WebhooksService) List(ctx context.Context, boardID string) ([]generated.Webhook, *Response, error)

List returns webhooks.

func (*WebhooksService) ListWebhookDeliveries added in v0.1.3 

func (s *WebhooksService) ListWebhookDeliveries(ctx context.Context, boardID string, webhookID string, path string) ([]generated.WebhookDelivery, *Response, error)

ListWebhookDeliveries returns webhook deliveries.

func (*WebhooksService) Update 

func (s *WebhooksService) Update(ctx context.Context, boardID string, webhookID string, req *generated.UpdateWebhookRequest) (*generated.Webhook, *Response, error)

Update updates a webhook.

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.