Module: Fizzy

Defined in:
lib/fizzy.rb,
lib/fizzy/http.rb,
lib/fizzy/cache.rb,
lib/fizzy/hooks.rb,
lib/fizzy/client.rb,
lib/fizzy/config.rb,
lib/fizzy/errors.rb,
lib/fizzy/version.rb,
lib/fizzy/bulkhead.rb,
lib/fizzy/security.rb,
lib/fizzy/noop_hooks.rb,
lib/fizzy/resilience.rb,
lib/fizzy/chain_hooks.rb,
lib/fizzy/cookie_auth.rb,
lib/fizzy/logger_hooks.rb,
lib/fizzy/rate_limiter.rb,
lib/fizzy/request_info.rb,
lib/fizzy/auth_strategy.rb,
lib/fizzy/operation_info.rb,
lib/fizzy/request_result.rb,
lib/fizzy/token_provider.rb,
lib/fizzy/circuit_breaker.rb,
lib/fizzy/generated/types.rb,
lib/fizzy/magic_link_flow.rb,
lib/fizzy/webhooks/verify.rb,
lib/fizzy/services/base_service.rb,
lib/fizzy/static_token_provider.rb,
lib/fizzy/generated/services/pins_service.rb,
lib/fizzy/generated/services/tags_service.rb,
lib/fizzy/generated/services/cards_service.rb,
lib/fizzy/generated/services/steps_service.rb,
lib/fizzy/generated/services/users_service.rb,
lib/fizzy/generated/services/boards_service.rb,
lib/fizzy/generated/services/columns_service.rb,
lib/fizzy/generated/services/devices_service.rb,
lib/fizzy/generated/services/uploads_service.rb,
lib/fizzy/generated/services/comments_service.rb,
lib/fizzy/generated/services/identity_service.rb,
lib/fizzy/generated/services/sessions_service.rb,
lib/fizzy/generated/services/webhooks_service.rb,
lib/fizzy/generated/services/reactions_service.rb,
lib/fizzy/generated/services/miscellaneous_service.rb,
lib/fizzy/generated/services/notifications_service.rb

Overview

These types provide structured access to API response data. Each type is a Data.define (Ruby 3.2+) with keyword initialization.

Defined Under Namespace

Modules: AuthStrategy, ErrorCode, ExitCode, Hooks, Security, Services, TokenProvider, Types, Webhooks Classes: APIError, AmbiguousError, AuthError, BearerAuth, Bulkhead, Cache, ChainHooks, CircuitBreaker, Client, Config, CookieAuth, Error, ForbiddenError, Http, LoggerHooks, MagicLinkFlow, NetworkError, NoopHooks, NotFoundError, OperationInfo, OperationResult, RateLimitError, RateLimiter, RequestInfo, RequestResult, ResilienceConfig, Response, StaticTokenProvider, UsageError, ValidationError

Constant Summary collapse

VERSION = 
"0.1.3"
API_VERSION = 
"2026-03-01"

Class Method Summary collapse

Class Method Details

.client(access_token: nil, auth: nil, base_url: Config::DEFAULT_BASE_URL, hooks: nil) ⇒ Client

Creates a new Fizzy client.

This is a convenience method that creates a Client with the given options.

Examples:

With access token

client = Fizzy.client(access_token: "abc123")
boards = client.boards.list.to_a

With custom auth strategy

client = Fizzy.client(auth: Fizzy::CookieAuth.new("session_value"))

Parameters:

  • access_token (String, nil) (defaults to: nil) —

    API access token

  • auth (AuthStrategy, nil) (defaults to: nil) —

    custom authentication strategy

  • base_url (String) (defaults to: Config::DEFAULT_BASE_URL) —

    Base URL for API requests

  • hooks (Hooks, nil) (defaults to: nil) —

    Observability hooks

Returns:

Raises:

  • (ArgumentError) 


77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
 
# File 'lib/fizzy.rb', line 77

def self.client(
  access_token: nil,
  auth: nil,
  base_url: Config::DEFAULT_BASE_URL,
  hooks: nil
)
  raise ArgumentError, "provide either access_token or auth, not both" if access_token && auth
  raise ArgumentError, "provide access_token or auth" if !access_token && !auth

  config = Config.new(base_url: base_url)

  if auth
    Client.new(config: config, auth_strategy: auth, hooks: hooks)
  else
    token_provider = StaticTokenProvider.new(access_token)
    Client.new(config: config, token_provider: token_provider, hooks: hooks)
  end
end

.error_from_response(status, body = nil, retry_after: nil) ⇒ Error

Maps an HTTP response to the appropriate error class.

Parameters:

  • status (Integer) —

    HTTP status code

  • body (String, nil) (defaults to: nil) —

    response body (will attempt JSON parse)

  • retry_after (Integer, nil) (defaults to: nil) —

    Retry-After header value

Returns:



252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
 
# File 'lib/fizzy/errors.rb', line 252

def self.error_from_response(status, body = nil, retry_after: nil)
  message = parse_error_message(body) || "Request failed"

  case status
  when 400, 422
    ValidationError.new(message, http_status: status)
  when 401
    AuthError.new(message)
  when 403
    ForbiddenError.new(message)
  when 404
    NotFoundError.new("Resource", "unknown")
  when 429
    RateLimitError.new(retry_after: retry_after)
  when 500
    APIError.new("Server error (500)", http_status: 500, retryable: true)
  when 502, 503, 504
    APIError.new("Gateway error (#{status})", http_status: status, retryable: true)
  else
    APIError.from_status(status, message)
  end
end

.parse_error_message(body) ⇒ String?

Parses error message from response body.

Parameters:

  • body (String, nil)

Returns:

  • (String, nil) 


278
279
280
281
282
283
284
285
286
287
288
289
290
 
# File 'lib/fizzy/errors.rb', line 278

def self.parse_error_message(body)
  return nil if body.nil? || body.empty?

  # Guard against oversized error bodies before parsing
  Fizzy::Security.check_body_size!(body, Fizzy::Security::MAX_ERROR_BODY_BYTES, "Error")

  data = JSON.parse(body)
  msg = data["error"] || data["message"]
  msg ? Fizzy::Security.truncate(msg) : nil
rescue JSON::ParserError, Fizzy::APIError
  # Return nil on parse errors or oversized bodies to preserve normal error type mapping
  nil
end