oz-agent-sdk 0.1.0

data/lib/oz/client.rb

@@ -0,0 +1,299 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require 'json'
+require 'time'
+require 'date'
+
+module Oz
+  # HTTP client for the Oz API.
+  #
+  #   client = Oz::Client.new(api_key: ENV["WARP_API_KEY"])
+  #   run = client.agent.run(prompt: "Fix the bug in auth.rb")
+  #   puts run.run_id
+  #
+  # The API key defaults to the +WARP_API_KEY+ environment variable and the base
+  # URL to +OZ_API_BASE_URL+ (falling back to https://app.warp.dev/api/v1).
+  # Transient failures (timeouts, connection errors, HTTP 408/409/429/5xx) are
+  # retried automatically with exponential backoff.
+  class Client
+    # Initial backoff before the first retry, in seconds.
+    INITIAL_RETRY_DELAY = 0.5
+    # Maximum backoff between retries, in seconds.
+    MAX_RETRY_DELAY = 8.0
+    # Statuses (besides 5xx) that trigger an automatic retry.
+    RETRYABLE_STATUSES = [408, 409, 429].freeze
+
+    attr_reader :api_key, :base_url, :timeout, :max_retries, :default_headers
+
+    # @param api_key [String, nil] Bearer token (defaults to +WARP_API_KEY+)
+    # @param base_url [String, nil] API base URL (defaults to +OZ_API_BASE_URL+)
+    # @param timeout [Integer, Float, nil] per-request timeout in seconds
+    # @param max_retries [Integer, nil] retries for transient failures
+    # @param default_headers [Hash, nil] extra headers for every request
+    # @param logger [Logger, nil] enables Faraday request/response logging
+    # @param adapter [Symbol, nil] Faraday adapter (defaults to net_http)
+    def initialize(api_key: nil, base_url: nil, timeout: nil, max_retries: nil,
+                   default_headers: nil, logger: nil, adapter: nil)
+      config = Oz.configuration
+      @api_key = api_key || ENV.fetch('WARP_API_KEY', nil) || config.api_key
+      @base_url = normalize_base_url(base_url || ENV.fetch('OZ_API_BASE_URL', nil) || config.base_url)
+      @timeout = timeout || config.timeout
+      @max_retries = max_retries || config.max_retries
+      @logger = logger || config.logger
+      @adapter = adapter || config.adapter || Faraday.default_adapter
+      @default_headers = build_default_headers(default_headers || config.default_headers)
+
+      if @api_key.nil? || @api_key.to_s.empty?
+        raise AuthenticationError,
+              'The api_key client option must be set either by passing api_key to the client ' \
+              'or by setting the WARP_API_KEY environment variable'
+      end
+
+      @connection = build_connection
+    end
+
+    # @return [Oz::Resources::Agent] the agent resource and its sub-resources.
+    def agent
+      @agent ||= Resources::Agent.new(self)
+    end
+
+    # @!group Low-level HTTP verbs
+
+    def get(path, query: nil, headers: nil)
+      request(:get, path, query: query, headers: headers)
+    end
+
+    def post(path, body: nil, query: nil, headers: nil)
+      request(:post, path, body: body, query: query, headers: headers)
+    end
+
+    def put(path, body: nil, query: nil, headers: nil)
+      request(:put, path, body: body, query: query, headers: headers)
+    end
+
+    def delete(path, query: nil, headers: nil)
+      request(:delete, path, query: query, headers: headers)
+    end
+
+    # @!endgroup
+
+    # Performs an HTTP request with automatic retries and returns the decoded
+    # response body (a Hash, Array, String, or nil for empty/204 responses).
+    # @raise [Oz::APIError] on transport failures and non-2xx responses.
+    def request(method, path, body: nil, query: nil, headers: nil)
+      attempt = 0
+      loop do
+        attempt += 1
+        begin
+          response = execute(method, path, body, query, headers)
+        rescue APIConnectionError
+          raise if attempt > @max_retries
+
+          sleep(retry_delay(attempt, nil))
+          next
+        end
+
+        if should_retry?(response.status) && attempt <= @max_retries
+          sleep(retry_delay(attempt, response))
+          next
+        end
+
+        return process_response(response)
+      end
+    end
+
+    def inspect
+      "#<Oz::Client base_url=#{@base_url.inspect} timeout=#{@timeout} max_retries=#{@max_retries}>"
+    end
+    alias to_s inspect
+
+    private
+
+    def execute(method, path, body, query, headers)
+      @connection.run_request(method, build_url(path), nil, nil) do |req|
+        apply_headers(req, headers)
+        apply_query(req, query)
+        apply_body(req, body)
+      end
+    rescue Faraday::TimeoutError => e
+      raise APITimeoutError, "Request timed out: #{e.message}"
+    rescue Faraday::ConnectionFailed, Faraday::SSLError => e
+      raise APIConnectionError, "Connection failed: #{e.message}"
+    end
+
+    def build_url(path)
+      "#{@base_url}/#{path.to_s.sub(%r{\A/+}, '')}"
+    end
+
+    def apply_headers(req, headers)
+      @default_headers.each { |key, value| req.headers[key.to_s] = value }
+      return unless headers
+
+      headers.each { |key, value| req.headers[key.to_s] = value }
+    end
+
+    def apply_query(req, query)
+      prepared = prepare_query(query)
+      req.params.update(prepared) unless prepared.empty?
+    end
+
+    def apply_body(req, body)
+      return if body.nil?
+
+      prepared = prepare_value(body)
+      req.body = prepared unless prepared.nil?
+    end
+
+    # Decoded 2xx body, or raises a mapped error for >= 400.
+    def process_response(response)
+      raise_error(response) if response.status >= 400
+      return nil if response.status == 204
+
+      body = response.body
+      return nil if body.nil? || (body.is_a?(String) && body.strip.empty?)
+
+      body
+    end
+
+    def raise_error(response)
+      status = response.status
+      body = response.body
+      klass = Oz.error_class_for(status)
+      raise klass.new(
+        error_message(status, body),
+        status_code: status,
+        body: body,
+        code: error_code(body),
+        request_id: response.headers['x-request-id'],
+        response: response
+      )
+    end
+
+    def error_message(status, body)
+      detail =
+        if body.is_a?(Hash)
+          body['detail'] || body['message'] || body['title'] || body['error']
+        elsif body.is_a?(String) && !body.strip.empty?
+          body.strip
+        end
+      base = "Oz API error (HTTP #{status})"
+      detail ? "#{base}: #{detail}" : base
+    end
+
+    def error_code(body)
+      return nil unless body.is_a?(Hash)
+
+      explicit = body['code'] || body['error_code']
+      return explicit if explicit
+
+      type = body['type']
+      return unless type.is_a?(String) && !type.empty?
+
+      segment = type.split('/').last
+      segment unless segment.nil? || segment.empty?
+    end
+
+    def should_retry?(status)
+      RETRYABLE_STATUSES.include?(status) || status >= 500
+    end
+
+    # Exponential backoff with jitter; honours a numeric +Retry-After+ header.
+    def retry_delay(attempt, response)
+      if response
+        retry_after = response.headers['retry-after']
+        seconds = retry_after.to_f if retry_after
+        return [seconds, MAX_RETRY_DELAY].min if seconds&.positive?
+      end
+
+      delay = INITIAL_RETRY_DELAY * (2**(attempt - 1))
+      delay = [delay, MAX_RETRY_DELAY].min
+      delay + (delay * 0.25 * rand)
+    end
+
+    # Recursively prepares a value for JSON encoding: drops nil hash values,
+    # serializes Time/Date as ISO-8601, and leaves everything else intact.
+    def prepare_value(value)
+      case value
+      when Hash
+        value.each_with_object({}) do |(key, val), acc|
+          prepared = prepare_value(val)
+          acc[key] = prepared unless prepared.nil?
+        end
+      when Array
+        value.map { |item| prepare_value(item) }
+      when Time
+        value.utc.iso8601
+      when Date # also matches DateTime (a Date subclass); #iso8601 keeps the time part
+        value.iso8601
+      else
+        value
+      end
+    end
+
+    def prepare_query(query)
+      return {} if query.nil? || query.empty?
+
+      query.each_with_object({}) do |(key, value), acc|
+        next if value.nil?
+
+        acc[key] = prepare_query_value(value)
+      end
+    end
+
+    def prepare_query_value(value)
+      case value
+      when Time then value.utc.iso8601
+      when DateTime, Date then value.iso8601
+      when Array then value.map { |item| prepare_query_value(item) }
+      else value
+      end
+    end
+
+    def normalize_base_url(url)
+      (url || Configuration::DEFAULT_BASE_URL).to_s.sub(%r{/+\z}, '')
+    end
+
+    def build_default_headers(custom)
+      headers = {
+        'Accept' => 'application/json',
+        'User-Agent' => "oz-agent-sdk-ruby/#{Oz::VERSION}",
+        'X-Stainless-Lang' => 'ruby',
+        'X-Stainless-Package-Version' => Oz::VERSION
+      }
+      headers.merge!(parse_env_headers(ENV.fetch('OZ_API_CUSTOM_HEADERS', nil)))
+      headers.merge!(stringify_headers(custom)) if custom
+      headers['Authorization'] = "Bearer #{@api_key}"
+      headers
+    end
+
+    # Parses OZ_API_CUSTOM_HEADERS: newline-separated "Key: Value" lines.
+    def parse_env_headers(raw)
+      return {} if raw.nil? || raw.empty?
+
+      raw.split("\n").each_with_object({}) do |line, acc|
+        colon = line.index(':')
+        next unless colon && colon >= 0
+
+        key = line[0...colon].strip
+        acc[key] = line[(colon + 1)..].strip unless key.empty?
+      end
+    end
+
+    def stringify_headers(headers)
+      headers.each_with_object({}) { |(key, value), acc| acc[key.to_s] = value }
+    end
+
+    def build_connection
+      Faraday.new(url: @base_url) do |conn|
+        conn.request :json
+        conn.response :json, content_type: /\bjson/
+        conn.options.timeout = @timeout
+        conn.options.open_timeout = [@timeout, 10].min
+        conn.options.params_encoder = Faraday::FlatParamsEncoder
+        conn.response :logger, @logger, headers: false, bodies: false if @logger
+        conn.adapter @adapter
+      end
+    end
+  end
+end

data/lib/oz/configuration.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Oz
+  # Global configuration for the SDK.
+  #
+  # Values set here act as defaults for every {Oz::Client} created without
+  # explicit overrides. Configure it once at boot time:
+  #
+  #   Oz.configure do |config|
+  #     config.api_key = ENV.fetch("WARP_API_KEY")
+  #     config.max_retries = 3
+  #   end
+  class Configuration
+    # Default base URL for the Oz API.
+    DEFAULT_BASE_URL = 'https://app.warp.dev/api/v1'
+    # Default request timeout, in seconds.
+    DEFAULT_TIMEOUT = 60
+    # Default number of automatic retries for transient failures.
+    DEFAULT_MAX_RETRIES = 2
+
+    # @return [String, nil] Bearer token used to authenticate requests.
+    attr_accessor :api_key
+    # @return [String] base URL the client points at.
+    attr_accessor :base_url
+    # @return [Integer, Float] per-request timeout in seconds.
+    attr_accessor :timeout
+    # @return [Integer] number of retries for retryable failures.
+    attr_accessor :max_retries
+    # @return [Hash] extra headers sent on every request.
+    attr_accessor :default_headers
+    # @return [Logger, nil] optional logger; enables Faraday request logging.
+    attr_accessor :logger
+    # @return [Symbol, nil] Faraday adapter override (defaults to net_http).
+    attr_accessor :adapter
+
+    def initialize
+      @api_key = nil
+      @base_url = DEFAULT_BASE_URL
+      @timeout = DEFAULT_TIMEOUT
+      @max_retries = DEFAULT_MAX_RETRIES
+      @default_headers = {}
+      @logger = nil
+      @adapter = nil
+    end
+  end
+end

data/lib/oz/cursor_page.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Oz
+  # An Enumerable page of results from a cursor-paginated endpoint
+  # (currently +GET /agent/runs+).
+  #
+  # Iterate a single page directly, or use {#auto_paging_each} to transparently
+  # walk every page:
+  #
+  #   page = client.agent.runs.list(limit: 50, state: ["INPROGRESS"])
+  #   page.each { |run| puts run.run_id }          # this page only
+  #   page.auto_paging_each { |run| ... }           # every page
+  #   page.next_page if page.next_page?
+  class CursorPage
+    include Enumerable
+
+    # @return [Array<Oz::Model>] the items on this page.
+    attr_reader :data
+    # @return [Boolean, nil] server hint on whether more pages exist.
+    attr_reader :has_next_page
+    # @return [String, nil] cursor to fetch the next page.
+    attr_reader :next_cursor
+    # @return [Hash] the raw decoded response body.
+    attr_reader :raw
+
+    # @param body [Hash] decoded +{ "runs" => [...], "page_info" => {...} }+
+    # @param resource [#list] the resource used to fetch subsequent pages
+    # @param params [Hash] the filter params used for this request
+    # @param items_key [String] the key under which items live in +body+
+    def initialize(body, resource:, params: {}, items_key: 'runs')
+      @raw = body.is_a?(Hash) ? body : {}
+      @resource = resource
+      @params = params || {}
+      @items_key = items_key
+      @data = Array(@raw[items_key]).map { |item| Model.build(item) }
+      page_info = @raw['page_info'] || {}
+      @has_next_page = page_info['has_next_page']
+      @next_cursor = page_info['next_cursor']
+    end
+
+    # Iterates over the items on this page only.
+    def each(&)
+      return enum_for(:each) unless block_given?
+
+      @data.each(&)
+    end
+
+    # @return [Boolean] whether a further page can be fetched.
+    def next_page?
+      return false if @has_next_page == false
+
+      !(@next_cursor.nil? || @next_cursor.to_s.empty?)
+    end
+
+    # Fetches the next page, reusing the original filters with the new cursor.
+    # @return [CursorPage]
+    # @raise [Oz::Error] if there is no next page.
+    def next_page
+      raise Oz::Error, 'No next page available' unless next_page?
+
+      @resource.list(**@params, cursor: @next_cursor)
+    end
+
+    # Iterates over every item across all pages, fetching them lazily.
+    # Returns an Enumerator when no block is given.
+    def auto_paging_each(&block)
+      return enum_for(:auto_paging_each) unless block_given?
+
+      page = self
+      loop do
+        page.each(&block)
+        break unless page.next_page?
+
+        page = page.next_page
+      end
+    end
+
+    # @return [Boolean] whether this page has no items.
+    def empty?
+      @data.empty?
+    end
+
+    # @return [Integer] number of items on this page.
+    def size
+      @data.size
+    end
+    alias length size
+  end
+end

data/lib/oz/errors.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Oz
+  # Base class for every error raised by the SDK.
+  class Error < StandardError; end
+
+  # Raised when the SDK is misconfigured before any request is made
+  # (e.g. a missing API key).
+  class ConfigurationError < Error; end
+
+  # Base class for all errors that originate from interacting with the API.
+  #
+  # Carries the HTTP status code, the (parsed) response body, a machine readable
+  # error +code+ when the API provides one, and the +request_id+ header so that
+  # failures can be correlated with server side logs.
+  class APIError < Error
+    attr_reader :status_code, :body, :code, :request_id, :response
+
+    def initialize(message = nil, status_code: nil, body: nil, code: nil, request_id: nil, response: nil)
+      super(message)
+      @status_code = status_code
+      @body = body
+      @code = code
+      @request_id = request_id
+      @response = response
+    end
+  end
+
+  # Raised when the request could not reach the API at all (DNS failure,
+  # connection refused, TLS error, ...).
+  class APIConnectionError < APIError; end
+
+  # Raised when a request exceeds the configured timeout.
+  class APITimeoutError < APIConnectionError; end
+
+  # Raised for any non-2xx response that is not mapped to a more specific
+  # subclass below.
+  class APIStatusError < APIError; end
+
+  # 400
+  class BadRequestError < APIStatusError; end
+  # 401 (also raised locally when no API key is configured)
+  class AuthenticationError < APIStatusError; end
+  # 403
+  class PermissionDeniedError < APIStatusError; end
+  # 404
+  class NotFoundError < APIStatusError; end
+  # 409
+  class ConflictError < APIStatusError; end
+  # 422
+  class UnprocessableEntityError < APIStatusError; end
+  # 429
+  class RateLimitError < APIStatusError; end
+  # 5xx
+  class InternalServerError < APIStatusError; end
+
+  # Maps an HTTP status code to the most specific error class.
+  STATUS_ERROR_CLASSES = {
+    400 => BadRequestError,
+    401 => AuthenticationError,
+    403 => PermissionDeniedError,
+    404 => NotFoundError,
+    409 => ConflictError,
+    422 => UnprocessableEntityError,
+    429 => RateLimitError
+  }.freeze
+
+  # Returns the error class that should be raised for +status+.
+  def self.error_class_for(status)
+    STATUS_ERROR_CLASSES[status] || (status >= 500 ? InternalServerError : APIStatusError)
+  end
+end

data/lib/oz/model.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module Oz
+  # A light-weight, read-only wrapper around the JSON returned by the API.
+  #
+  # Rather than hand-maintaining a class for every response shape, the SDK wraps
+  # decoded JSON objects in {Model}. Attributes are reachable both as methods and
+  # via +[]+, and nested objects/arrays are wrapped recursively:
+  #
+  #   run = client.agent.run(prompt: "Fix the bug")
+  #   run.run_id            # => "abc123"
+  #   run.state             # => "QUEUED"
+  #   run["task_id"]        # => "abc123"
+  #   run.at_capacity?      # => false  (predicate form for booleans)
+  #   run.to_h              # => plain Hash with string keys
+  #
+  # Unknown attributes return +nil+ instead of raising, because the API omits
+  # optional fields. Use {#key?} when you need to distinguish "absent" from
+  # "present but null".
+  class Model
+    include Enumerable
+
+    # Recursively wraps +value+: Hashes become {Model}, Arrays are mapped, and
+    # scalars are returned untouched.
+    def self.build(value)
+      case value
+      when Hash then new(value)
+      when Array then value.map { |item| build(item) }
+      else value # scalars and existing Models pass through unchanged
+      end
+    end
+
+    def initialize(attributes = {})
+      @attributes = {}
+      (attributes || {}).each do |key, value|
+        @attributes[key.to_s] = Model.build(value)
+      end
+    end
+
+    # @return [Object, nil] the value stored under +key+ (symbol or string).
+    def [](key)
+      @attributes[key.to_s]
+    end
+
+    # @return [Boolean] whether +key+ is present in the payload.
+    def key?(key)
+      @attributes.key?(key.to_s)
+    end
+    alias has_key? key?
+    alias member? key?
+
+    # @return [Array<String>] the attribute names present in the payload.
+    def keys
+      @attributes.keys
+    end
+
+    # Iterates over +[key, value]+ pairs (values stay wrapped).
+    def each(&)
+      return enum_for(:each) unless block_given?
+
+      @attributes.each(&)
+    end
+
+    # @return [Hash] a deep copy as plain Ruby Hashes/Arrays with string keys.
+    def to_h
+      @attributes.transform_values { |value| unwrap(value) }
+    end
+    alias to_hash to_h
+
+    def ==(other)
+      other.is_a?(Model) && other.to_h == to_h
+    end
+    alias eql? ==
+
+    def hash
+      to_h.hash
+    end
+
+    def inspect
+      pairs = @attributes.map { |key, value| "#{key}=#{value.inspect}" }
+      "#<Oz::Model #{pairs.join(' ')}>"
+    end
+    alias to_s inspect
+
+    def respond_to_missing?(name, include_private = false)
+      method = name.to_s
+      return true if method.end_with?('?')
+      return true if reader?(method)
+
+      super
+    end
+
+    def method_missing(name, *args)
+      method = name.to_s
+      return !!@attributes[method.chomp('?')] if method.end_with?('?') && args.empty?
+      return @attributes[method] if reader?(method) && args.empty?
+
+      super
+    end
+
+    private
+
+    # Plain attribute readers (snake/camel case, no assignment or punctuation).
+    def reader?(method)
+      method.match?(/\A[a-zA-Z_]\w*\z/)
+    end
+
+    def unwrap(value)
+      case value
+      when Model then value.to_h
+      when Array then value.map { |item| unwrap(item) }
+      else value
+      end
+    end
+  end
+end