fix: further improvements

Author: varonix0

.yardopts

@@ -0,0 +1,5 @@
+--markup markdown
+lib/**/*.rb
+-
+README.md
+LICENSE

Gemfile

@@ -8,4 +8,5 @@ group :development, :test do
   gem "rspec", "~> 3.13"
   gem "rubocop", "~> 1.65"
   gem "webmock", "~> 3.23"
+  gem "yard", "~> 0.9"
 end

README.md

@@ -41,8 +41,13 @@ secrets.each { |secret| puts "#{secret.secret_key}=#{secret.secret_value}" }
 ### Authentication
 
 ```ruby
-# Universal Auth (machine identity client id/secret)
-client.auth.universal_auth_login(client_id: "...", client_secret: "...")
+# Universal Auth (machine identity client id/secret). Returns the full
+# credential, so you can build your own token refresh on top of it.
+credential = client.auth.universal_auth_login(client_id: "...", client_secret: "...")
+credential.access_token       # the token this client now uses
+credential.expires_in         # seconds until it expires
+credential.access_token_max_ttl
+credential.token_type         # "Bearer"
 
 # Or use a token you already have
 client.auth.access_token("existing-access-token")
@@ -64,6 +69,29 @@ client.secrets.update("DATABASE_URL", project_id: "...", environment: "dev", sec
 client.secrets.delete("DATABASE_URL", project_id: "...", environment: "dev")
 ```
 
+### Error handling
+
+Every error raised by the SDK inherits from `Infisical::Error`. API failures
+raise `Infisical::APIError` (with `status`, `url`, `method`, and `request_id`
+readers), and well-known statuses raise a dedicated subclass:
+
+```ruby
+begin
+  client.secrets.get("DATABASE_URL", project_id: "...", environment: "dev")
+rescue Infisical::NotFoundError        # 404
+  # secret does not exist
+rescue Infisical::AuthenticationError  # 401: bad or expired credentials
+  # re-authenticate
+rescue Infisical::APIError => e        # anything else the API rejected
+  # e.status, e.url, e.method, e.request_id
+end
+```
+
+Also available: `Infisical::PermissionError` (403), `Infisical::RateLimitError`
+(429, raised only after automatic retries are exhausted), and
+`Infisical::ServerError` (5xx). Network-level failures (timeouts, DNS,
+connection resets) raise `Infisical::RequestError` after retries.
+
 ### Self-hosted instances
 
 ```ruby

lib/infisical.rb

@@ -4,5 +4,6 @@
 require_relative "infisical/errors"
 require_relative "infisical/client"
 
+# Official Infisical SDK for Ruby. See {Client} to get started.
 module Infisical
 end

lib/infisical/auth.rb

@@ -1,29 +1,44 @@
 # frozen_string_literal: true
 
+require_relative "models/machine_identity_credential"
+
 module Infisical
   # Authenticates the underlying HTTP client. Every other resource client
   # shares that same HTTP client, so a successful login here authenticates
-  # the whole `Client` instance.
+  # the whole {Client} instance.
   class Auth
     UNIVERSAL_AUTH_LOGIN_PATH = "api/v1/auth/universal-auth/login"
 
+    # @api private Obtain instances via {Client#auth} instead.
     def initialize(http_client)
       @http_client = http_client
     end
 
     # Logs in with Universal Auth (machine identity client id/secret) and
-    # returns the resulting access token.
+    # authenticates this client with the resulting access token. The full
+    # credential is returned so callers can track `expires_in` and re-login
+    # (or renew) before the token lapses.
+    #
+    # @param client_id [String] machine identity client id
+    # @param client_secret [String] machine identity client secret
+    # @return [Models::MachineIdentityCredential] the credential now used by
+    #   this client
+    # @raise [AuthenticationError] if the credentials are rejected
     def universal_auth_login(client_id:, client_secret:)
       response = @http_client.post(
         UNIVERSAL_AUTH_LOGIN_PATH,
         body: { clientId: client_id, clientSecret: client_secret }
       )
 
       access_token(response["accessToken"])
+      Models::MachineIdentityCredential.from_api(response)
     end
 
     # Authenticates with an access token obtained out-of-band, skipping
     # the login request entirely.
+    #
+    # @param token [String] a valid Infisical access token
+    # @return [String] the token, now used by this client
     def access_token(token)
       @http_client.access_token = token
       token

lib/infisical/client.rb

@@ -7,21 +7,38 @@
 require_relative "secrets"
 
 module Infisical
-  # Entry point for the SDK. Construct one, authenticate via `auth`, then
-  # use `secrets` (and future resource clients) to talk to Infisical.
+  # Entry point for the SDK. Construct one, authenticate via {#auth}, then
+  # use {#secrets} (and future resource clients) to talk to Infisical.
+  #
+  # @example Fetch a secret
+  #   client = Infisical::Client.new
+  #   client.auth.universal_auth_login(client_id: "...", client_secret: "...")
+  #   secret = client.secrets.get("DATABASE_URL", project_id: "...", environment: "dev")
+  #   secret.secret_value # => "postgres://..."
   class Client
     DEFAULT_SITE_URL = "https://app.infisical.com"
     ALLOWED_SCHEMES = %w[http https].freeze
 
+    # @param site_url [String] base URL of the Infisical instance; defaults to
+    #   Infisical Cloud, so only self-hosted deployments need to set it
+    # @param timeout [Numeric] open/read timeout in seconds for each request
+    # @raise [ArgumentError] if site_url is not an http(s) URL
     def initialize(site_url: DEFAULT_SITE_URL, timeout: HTTPClient::DEFAULT_TIMEOUT)
       validate_site_url!(site_url)
       @http_client = HTTPClient.new(base_url: site_url, timeout: timeout)
     end
 
+    # Authentication operations. Logging in through this authenticates the
+    # whole client, since all resource clients share one HTTP client.
+    #
+    # @return [Auth]
     def auth
       @auth ||= Auth.new(@http_client)
     end
 
+    # Secret CRUD operations.
+    #
+    # @return [Secrets]
     def secrets
       @secrets ||= Secrets.new(@http_client)
     end

lib/infisical/errors.rb

@@ -1,13 +1,49 @@
 # frozen_string_literal: true
 
 module Infisical
-  # Base class for all errors raised by this SDK.
+  # Base class for all errors raised by this SDK. Rescue this to catch
+  # anything Infisical-related.
   class Error < StandardError; end
 
-  # Raised when the Infisical API responds with a non-2xx status.
+  # Raised when the Infisical API responds with a non-2xx status. Well-known
+  # statuses raise a subclass ({AuthenticationError}, {PermissionError},
+  # {NotFoundError}, {RateLimitError}, {ServerError}); rescuing this class
+  # catches them all.
   class APIError < Error
-    attr_reader :status, :url, :method, :request_id
+    # @return [Integer] HTTP status code of the failed response
+    attr_reader :status
 
+    # @return [String] full URL the failed request was sent to
+    attr_reader :url
+
+    # @return [String] uppercase HTTP method of the failed request, e.g. "GET"
+    attr_reader :method
+
+    # @return [String, nil] server-assigned request id, when the response carried one
+    attr_reader :request_id
+
+    # Returns the error class that best matches an HTTP status, falling back
+    # to {APIError} itself. Constants are resolved at call time, so the
+    # subclasses defined below are visible here.
+    #
+    # @param status [Integer] HTTP status code
+    # @return [Class<APIError>]
+    def self.for_status(status)
+      case status
+      when 401 then AuthenticationError
+      when 403 then PermissionError
+      when 404 then NotFoundError
+      when 429 then RateLimitError
+      when 500..599 then ServerError
+      else self
+      end
+    end
+
+    # @param message [String] human-readable error detail from the API
+    # @param status [Integer] HTTP status code
+    # @param url [String] full URL the request was sent to
+    # @param method [String] HTTP method of the request
+    # @param request_id [String, nil] server-assigned request id, if any
     def initialize(message, status:, url:, method:, request_id: nil)
       @status = status
       @url = url
@@ -21,9 +57,26 @@ def initialize(message, status:, url:, method:, request_id: nil)
     end
   end
 
+  # Raised on HTTP 401: missing, expired, or invalid credentials.
+  class AuthenticationError < APIError; end
+
+  # Raised on HTTP 403: the authenticated identity lacks permission for the
+  # requested resource or action.
+  class PermissionError < APIError; end
+
+  # Raised on HTTP 404: the secret, project, environment, or path does not
+  # exist (or is not visible to the authenticated identity).
+  class NotFoundError < APIError; end
+
+  # Raised on HTTP 429, after the client has exhausted its automatic retries.
+  class RateLimitError < APIError; end
+
+  # Raised on HTTP 5xx: the Infisical server failed to process the request.
+  class ServerError < APIError; end
+
   # Raised when the request itself fails (network/timeout) before a
   # response is received. Always raised from inside a `rescue` for the
   # underlying network exception, so Ruby's built-in `Exception#cause`
-  # already carries it through — no need to track it ourselves.
+  # already carries it through; no need to track it ourselves.
   class RequestError < Error; end
 end

lib/infisical/http_client.rb

@@ -11,6 +11,8 @@ module Infisical
   # Thin wrapper around Net::HTTP that knows how to talk to the Infisical
   # API: bearer token auth, JSON (de)serialization, and retrying transient
   # failures with exponential backoff + jitter.
+  #
+  # @api private Internal plumbing; use {Client} instead.
   class HTTPClient
     DEFAULT_TIMEOUT = 10 # seconds
     DEFAULT_MAX_RETRIES = 4
@@ -155,14 +157,15 @@ def parse_retry_after(value)
 
     def build_api_error(response, status, method, uri)
       data = parse_body(response.body)
-      message = data.is_a?(Hash) ? (data["message"] || data["error"] || response.body) : response.body
+      data = {} unless data.is_a?(Hash)
+      message = data["message"] || data["error"] || response.body
 
-      APIError.new(
+      APIError.for_status(status).new(
         message.to_s,
         status: status,
         url: uri.to_s,
         method: method.to_s.upcase,
-        request_id: response["x-request-id"]
+        request_id: data["reqId"]
       )
     end
 

lib/infisical/models/machine_identity_credential.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Infisical
+  module Models
+    # Credential material issued by a machine identity login. Exposes the
+    # token's lifetime so callers can build their own refresh logic.
+    #
+    # @!attribute access_token
+    #   @return [String] bearer token used to authenticate API requests
+    # @!attribute expires_in
+    #   @return [Integer] seconds until the token expires, from issue time
+    # @!attribute access_token_max_ttl
+    #   @return [Integer] hard ceiling in seconds on the token's total
+    #     lifetime across renewals
+    # @!attribute token_type
+    #   @return [String] token scheme, e.g. "Bearer"
+    MachineIdentityCredential = Struct.new(
+      :access_token, :expires_in, :access_token_max_ttl, :token_type,
+      keyword_init: true
+    ) do
+      # Builds a credential from an API response hash (camelCase keys).
+      #
+      # @api private
+      def self.from_api(data)
+        new(
+          access_token: data["accessToken"],
+          expires_in: data["expiresIn"],
+          access_token_max_ttl: data["accessTokenMaxTTL"],
+          token_type: data["tokenType"]
+        )
+      end
+    end
+  end
+end

lib/infisical/models/secret.rb

@@ -1,14 +1,41 @@
 # frozen_string_literal: true
 
 module Infisical
+  # Value objects returned by the resource clients.
   module Models
-    # Immutable value object representing a single Infisical secret.
+    # Value object representing a single Infisical secret.
+    #
+    # @!attribute id
+    #   @return [String] unique id of the secret
+    # @!attribute workspace
+    #   @return [String] id of the project the secret belongs to
+    # @!attribute environment
+    #   @return [String] environment slug the secret belongs to
+    # @!attribute version
+    #   @return [Integer] version number, incremented on every update
+    # @!attribute type
+    #   @return [String] "shared" or "personal"
+    # @!attribute secret_key
+    #   @return [String] the secret's name
+    # @!attribute secret_value
+    #   @return [String] the secret's value
+    # @!attribute secret_comment
+    #   @return [String, nil] comment stored with the secret
+    # @!attribute secret_path
+    #   @return [String, nil] folder path the secret lives at
+    # @!attribute created_at
+    #   @return [String, nil] ISO 8601 creation timestamp
+    # @!attribute updated_at
+    #   @return [String, nil] ISO 8601 last-update timestamp
     Secret = Struct.new(
       :id, :workspace, :environment, :version, :type,
       :secret_key, :secret_value, :secret_comment, :secret_path,
       :created_at, :updated_at,
       keyword_init: true
     ) do
+      # Builds a Secret from an API response hash (camelCase keys).
+      #
+      # @api private
       def self.from_api(data)
         new(
           id: data["id"],