openrouter_client 0.1.0

data/lib/openrouter/api_key.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module OpenRouter
+  # Represents an API key and provides management operations.
+  # Provides helpers to list, create, update, and delete API keys.
+  class ApiKey
+    KEYS_PATH = "/keys"
+    AUTH_KEY_PATH = "/auth/key"
+
+    # @return [String] The key identifier
+    attr_reader :id
+    # @return [String, nil] The key name/label
+    attr_reader :name
+    # @return [String, nil] The key value (only available on creation)
+    attr_reader :key
+    # @return [Float, nil] Credit limit for this key
+    attr_reader :limit
+    # @return [Float, nil] Usage amount for this key
+    attr_reader :usage
+    # @return [Boolean, nil] Whether the key is disabled
+    attr_reader :disabled
+    # @return [String, nil] Created timestamp
+    attr_reader :created_at
+    # @return [String, nil] Updated timestamp
+    attr_reader :updated_at
+
+    # @param attributes [Hash] Raw attributes from OpenRouter API
+    # @param client [OpenRouter::Client] HTTP client
+    def initialize(attributes, client: OpenRouter.client)
+      @client = client
+      reset_attributes(attributes)
+    end
+
+    class << self
+      # Get information about the current API key being used.
+      # Corresponds to GET /api/v1/auth/key
+      # @param client [OpenRouter::Client] HTTP client
+      # @return [OpenRouter::ApiKey]
+      def current(client: OpenRouter.client)
+        response = client.get(AUTH_KEY_PATH)
+        new(response["data"] || response, client: client)
+      end
+
+      # List all API keys.
+      # @param client [OpenRouter::Client] HTTP client
+      # @return [Array<OpenRouter::ApiKey>]
+      def all(client: OpenRouter.client)
+        response = client.get(KEYS_PATH)
+        keys = Array(response && response["data"])
+        keys.map { |attributes| new(attributes, client: client) }
+      end
+
+      # Find an API key by ID.
+      # @param id [String] The key identifier
+      # @param client [OpenRouter::Client] HTTP client
+      # @return [OpenRouter::ApiKey, nil]
+      def find_by(id:, client: OpenRouter.client)
+        response = client.get("#{KEYS_PATH}/#{id}")
+        return nil unless response
+
+        new(response["data"] || response, client: client)
+      end
+
+      # Create a new API key.
+      # @param name [String] A name/label for the key
+      # @param limit [Float, nil] Credit limit for this key
+      # @param client [OpenRouter::Client] HTTP client
+      # @return [OpenRouter::ApiKey]
+      def create!(name:, limit: nil, client: OpenRouter.client)
+        payload = { name: name, limit: limit }.compact
+        response = client.post(KEYS_PATH, payload)
+        new(response["data"] || response, client: client)
+      end
+    end
+
+    # Update this API key.
+    # @param name [String, nil] New name for the key
+    # @param limit [Float, nil] New credit limit
+    # @param disabled [Boolean, nil] Whether to disable the key
+    # @return [OpenRouter::ApiKey]
+    def update!(name: nil, limit: nil, disabled: nil)
+      payload = { name: name, limit: limit, disabled: disabled }.compact
+      response = @client.patch("#{KEYS_PATH}/#{@id}", payload)
+      reset_attributes(response["data"] || response)
+      self
+    end
+
+    # Delete this API key.
+    # @return [Boolean] true if deletion was successful
+    def destroy!
+      @client.delete("#{KEYS_PATH}/#{@id}")
+      true
+    end
+
+    # Check if this key is active (not disabled).
+    # @return [Boolean]
+    def active?
+      !@disabled
+    end
+
+    # Check if this key has a limit set.
+    # @return [Boolean]
+    def limited?
+      !@limit.nil? && @limit.positive?
+    end
+
+    # Check if this key has exceeded its limit.
+    # @return [Boolean]
+    def exceeded_limit?
+      return false unless limited?
+
+      (@usage || 0) >= @limit
+    end
+
+    # Get remaining credit for this key.
+    # @return [Float, nil]
+    def remaining
+      return nil unless limited?
+
+      @limit - (@usage || 0)
+    end
+
+    private
+
+    def reset_attributes(attributes)
+      @id = attributes["id"] || attributes["hash"]
+      @name = attributes["name"] || attributes["label"]
+      @key = attributes["key"]
+      @limit = attributes["limit"]&.to_f
+      @usage = attributes["usage"]&.to_f
+      @disabled = attributes["disabled"]
+      @created_at = attributes["created_at"] || attributes["createdAt"]
+      @updated_at = attributes["updated_at"] || attributes["updatedAt"]
+    end
+  end
+end

data/lib/openrouter/client.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+module OpenRouter
+  class Client
+    attr_accessor :configuration
+
+    def initialize(configuration = OpenRouter.configuration)
+      @configuration = configuration || OpenRouter::Configuration.new
+    end
+
+    # Perform a POST request to the OpenRouter API.
+    # @param path [String]
+    # @param payload [Hash]
+    # @param headers [Hash]
+    # @return [Hash, nil]
+    def post(path, payload = {}, headers: {})
+      response = connection.post(build_url(path)) do |request|
+        configure_request_headers(request, headers)
+        request.body = payload.compact.to_json
+      end
+
+      handle_error(response) unless response.success?
+
+      parse_json(response.body)
+    end
+
+    # Perform a POST request with SSE streaming support.
+    # The provided on_data Proc will be used to receive chunked data.
+    # @param path [String]
+    # @param payload [Hash]
+    # @param on_data [Proc] called with chunks as they arrive
+    # @return [void]
+    def post_stream(path, payload = {}, on_data:)
+      url = build_url(path)
+      connection.post(url) do |request|
+        configure_request_headers(request, {})
+        request.headers["Accept"] = "text/event-stream"
+        request.headers["Cache-Control"] = "no-store"
+        request.body = payload.compact.to_json
+        request.options.on_data = on_data
+      end
+    end
+
+    # Perform a GET request to the OpenRouter API.
+    # @param path [String]
+    # @param query [Hash, nil]
+    # @param headers [Hash]
+    # @return [Hash, nil]
+    def get(path, query: nil, headers: {})
+      url = build_url(path)
+      url = "#{url}?#{URI.encode_www_form(query)}" if query && !query.empty?
+
+      response = connection.get(url) do |request|
+        configure_request_headers(request, headers)
+      end
+
+      handle_error(response) unless response.success?
+
+      parse_json(response.body)
+    end
+
+    # Perform a DELETE request to the OpenRouter API.
+    # @param path [String]
+    # @param headers [Hash]
+    # @return [Hash, nil]
+    def delete(path, headers: {})
+      response = connection.delete(build_url(path)) do |request|
+        configure_request_headers(request, headers)
+      end
+
+      handle_error(response) unless response.success?
+
+      parse_json(response.body)
+    end
+
+    # Perform a PATCH request to the OpenRouter API.
+    # @param path [String]
+    # @param payload [Hash]
+    # @param headers [Hash]
+    # @return [Hash, nil]
+    def patch(path, payload = {}, headers: {})
+      response = connection.patch(build_url(path)) do |request|
+        configure_request_headers(request, headers)
+        request.body = payload.compact.to_json
+      end
+
+      handle_error(response) unless response.success?
+
+      parse_json(response.body)
+    end
+
+    # Handle HTTP error responses by raising appropriate exceptions.
+    # @param response [Faraday::Response]
+    # @raise [OpenRouter::Error]
+    def handle_error(response)
+      error_message = extract_error_message(response)
+
+      case response.status
+      when 400
+        raise BadRequestError, error_message
+      when 401
+        raise UnauthorizedError, error_message
+      when 402
+        raise PaymentRequiredError, error_message
+      when 403
+        raise ForbiddenError, error_message
+      when 404
+        raise NotFoundError, error_message
+      when 429
+        raise RateLimitError, error_message
+      else
+        raise ServerError, error_message
+      end
+    end
+
+    private
+
+    def configure_request_headers(request, custom_headers)
+      request.headers["Authorization"] = "Bearer #{@configuration.api_key}" if @configuration.api_key
+      request.headers["Content-Type"] = "application/json"
+      request.headers["Accept"] = "application/json"
+      request.headers["HTTP-Referer"] = @configuration.site_url if @configuration.site_url
+      request.headers["X-Title"] = @configuration.site_name if @configuration.site_name
+      request.headers.merge!(custom_headers)
+    end
+
+    def extract_error_message(response)
+      body = parse_json(response.body)
+      if body.is_a?(Hash) && body["error"]
+        error_data = body["error"]
+        error_data.is_a?(Hash) ? error_data["message"] || response.body : error_data
+      else
+        response.body
+      end
+    rescue JSON::ParserError
+      response.body
+    end
+
+    def parse_json(body)
+      return nil if body.nil? || body.strip.empty?
+
+      JSON.parse(body)
+    end
+
+    def build_url(path)
+      "#{@configuration.api_base}#{path}"
+    end
+
+    def connection
+      Faraday.new do |faraday|
+        faraday.request :url_encoded
+        faraday.options.timeout = @configuration.request_timeout
+        faraday.options.open_timeout = @configuration.request_timeout
+      end
+    end
+  end
+end

data/lib/openrouter/completion.rb

@@ -0,0 +1,293 @@
+# frozen_string_literal: true
+
+module OpenRouter
+  # Represents a chat completion request and response from the OpenRouter API.
+  # Provides helpers to create completions, handle streaming, and access response data.
+  class Completion
+    COMPLETIONS_PATH = "/chat/completions"
+
+    # Role constants for messages.
+    module Role
+      SYSTEM = "system"
+      USER = "user"
+      ASSISTANT = "assistant"
+      TOOL = "tool"
+    end
+
+    # Finish reason constants.
+    module FinishReason
+      STOP = "stop"
+      LENGTH = "length"
+      TOOL_CALLS = "tool_calls"
+      CONTENT_FILTER = "content_filter"
+      ERROR = "error"
+    end
+
+    # @return [String] The completion identifier
+    attr_reader :id
+    # @return [String] The model used for this completion
+    attr_reader :model
+    # @return [Integer] Unix timestamp of when the completion was created
+    attr_reader :created
+    # @return [String] The object type (chat.completion or chat.completion.chunk)
+    attr_reader :object
+    # @return [Array<Hash>] The completion choices
+    attr_reader :choices
+    # @return [Hash, nil] Token usage information
+    attr_reader :usage
+    # @return [String, nil] System fingerprint from the provider
+    attr_reader :system_fingerprint
+
+    # @param attributes [Hash] Raw attributes from OpenRouter API
+    # @param client [OpenRouter::Client] HTTP client to use for subsequent calls
+    def initialize(attributes, client: OpenRouter.client)
+      @client = client
+      reset_attributes(attributes)
+    end
+
+    class << self
+      # Create a new chat completion.
+      # Corresponds to POST /api/v1/chat/completions
+      # @param messages [Array<Hash>] The messages to send
+      # @param model [String, nil] The model to use (optional, uses user's default if omitted)
+      # @param temperature [Float, nil] Sampling temperature (0-2)
+      # @param max_tokens [Integer, nil] Maximum tokens to generate
+      # @param top_p [Float, nil] Nucleus sampling parameter (0-1)
+      # @param top_k [Integer, nil] Top-k sampling parameter
+      # @param frequency_penalty [Float, nil] Frequency penalty (-2 to 2)
+      # @param presence_penalty [Float, nil] Presence penalty (-2 to 2)
+      # @param repetition_penalty [Float, nil] Repetition penalty (0-2)
+      # @param stop [String, Array<String>, nil] Stop sequences
+      # @param seed [Integer, nil] Random seed for reproducibility
+      # @param tools [Array<Hash>, nil] Tools available to the model
+      # @param tool_choice [String, Hash, nil] Tool choice preference
+      # @param response_format [Hash, nil] Response format specification
+      # @param transforms [Array<String>, nil] Message transforms to apply
+      # @param models [Array<String>, nil] Model fallback list
+      # @param route [String, nil] Routing strategy
+      # @param provider [Hash, nil] Provider preferences
+      # @param client [OpenRouter::Client] HTTP client
+      # @param options [Hash] Additional options (modalities, image_config, plugins, reasoning, etc.)
+      # @return [OpenRouter::Completion]
+      def create!(messages:, model: nil, temperature: nil, max_tokens: nil, top_p: nil,
+                  top_k: nil, frequency_penalty: nil, presence_penalty: nil, repetition_penalty: nil,
+                  stop: nil, seed: nil, tools: nil, tool_choice: nil, response_format: nil,
+                  transforms: nil, models: nil, route: nil, provider: nil, client: OpenRouter.client, **)
+        payload = build_payload(
+          messages: messages,
+          model: model,
+          temperature: temperature,
+          max_tokens: max_tokens,
+          top_p: top_p,
+          top_k: top_k,
+          frequency_penalty: frequency_penalty,
+          presence_penalty: presence_penalty,
+          repetition_penalty: repetition_penalty,
+          stop: stop,
+          seed: seed,
+          tools: tools,
+          tool_choice: tool_choice,
+          response_format: response_format,
+          transforms: transforms,
+          models: models,
+          route: route,
+          provider: provider,
+          stream: false,
+          **
+        )
+
+        attributes = client.post(COMPLETIONS_PATH, payload)
+        new(attributes, client: client)
+      end
+
+      # Stream a chat completion using SSE and yield response chunks as they arrive.
+      # Returns a Completion initialized with the final response data.
+      # @param messages [Array<Hash>] The messages to send
+      # @param model [String, nil] The model to use
+      # @param client [OpenRouter::Client] HTTP client
+      # @param options [Hash] Additional options (modalities, image_config, plugins, reasoning, etc.)
+      # @yield [chunk] yields each parsed chunk Hash from the stream
+      # @yieldparam chunk [Hash]
+      # @return [OpenRouter::Completion]
+      def stream!(messages:, model: nil, temperature: nil, max_tokens: nil, top_p: nil,
+                  top_k: nil, frequency_penalty: nil, presence_penalty: nil, repetition_penalty: nil,
+                  stop: nil, seed: nil, tools: nil, tool_choice: nil, response_format: nil,
+                  transforms: nil, models: nil, route: nil, provider: nil, client: OpenRouter.client, **, &block)
+        payload = build_payload(
+          messages: messages,
+          model: model,
+          temperature: temperature,
+          max_tokens: max_tokens,
+          top_p: top_p,
+          top_k: top_k,
+          frequency_penalty: frequency_penalty,
+          presence_penalty: presence_penalty,
+          repetition_penalty: repetition_penalty,
+          stop: stop,
+          seed: seed,
+          tools: tools,
+          tool_choice: tool_choice,
+          response_format: response_format,
+          transforms: transforms,
+          models: models,
+          route: route,
+          provider: provider,
+          stream: true,
+          **
+        )
+
+        last_data = nil
+        collected_content = ""
+        final_attributes = {}
+
+        Stream.new(path: COMPLETIONS_PATH, input: payload, client: client).each do |event|
+          data = event["data"]
+          next unless data
+
+          last_data = data
+          block&.call(data)
+
+          # Collect content from delta
+          collected_content += data["choices"].first["delta"]["content"] if data["choices"]&.first&.dig("delta", "content")
+
+          # Capture final attributes
+          final_attributes["id"] ||= data["id"]
+          final_attributes["model"] ||= data["model"]
+          final_attributes["created"] ||= data["created"]
+          final_attributes["object"] = "chat.completion"
+
+          # Capture usage if present (usually in the final chunk)
+          final_attributes["usage"] = data["usage"] if data["usage"]
+        end
+
+        # Build final response structure
+        final_attributes["choices"] = [{
+          "message" => {
+            "role" => "assistant",
+            "content" => collected_content
+          },
+          "finish_reason" => last_data&.dig("choices", 0, "finish_reason") || "stop"
+        }]
+
+        new(final_attributes, client: client)
+      end
+
+      private
+
+      def build_payload(messages:, model:, temperature:, max_tokens:, top_p:, top_k:,
+                        frequency_penalty:, presence_penalty:, repetition_penalty:,
+                        stop:, seed:, tools:, tool_choice:, response_format:,
+                        transforms:, models:, route:, provider:, stream:, **options)
+        {
+          messages: messages,
+          model: model,
+          temperature: temperature,
+          max_tokens: max_tokens,
+          top_p: top_p,
+          top_k: top_k,
+          frequency_penalty: frequency_penalty,
+          presence_penalty: presence_penalty,
+          repetition_penalty: repetition_penalty,
+          stop: stop,
+          seed: seed,
+          tools: tools,
+          tool_choice: tool_choice,
+          response_format: response_format,
+          transforms: transforms,
+          models: models,
+          route: route,
+          provider: provider,
+          stream: stream,
+          **options
+        }.compact
+      end
+    end
+
+    # Get the content from the first choice's message.
+    # @return [String, nil]
+    def content
+      @choices&.first&.dig("message", "content")
+    end
+
+    # Get the role from the first choice's message.
+    # @return [String, nil]
+    def role
+      @choices&.first&.dig("message", "role")
+    end
+
+    # Get the finish reason from the first choice.
+    # @return [String, nil]
+    def finish_reason
+      @choices&.first&.dig("finish_reason")
+    end
+
+    # Get tool calls from the first choice's message.
+    # @return [Array<Hash>, nil]
+    def tool_calls
+      @choices&.first&.dig("message", "tool_calls")
+    end
+
+    # Get images from the first choice's message (for image generation).
+    # @return [Array<Hash>, nil]
+    def images
+      @choices&.first&.dig("message", "images")
+    end
+
+    # Check if the completion includes images.
+    # @return [Boolean]
+    def images?
+      !images.nil? && !images.empty?
+    end
+
+    # Get the prompt tokens used.
+    # @return [Integer, nil]
+    def prompt_tokens
+      @usage&.dig("prompt_tokens")
+    end
+
+    # Get the completion tokens used.
+    # @return [Integer, nil]
+    def completion_tokens
+      @usage&.dig("completion_tokens")
+    end
+
+    # Get the total tokens used.
+    # @return [Integer, nil]
+    def total_tokens
+      @usage&.dig("total_tokens")
+    end
+
+    # Check if the completion finished due to stop sequence.
+    # @return [Boolean]
+    def stopped?
+      finish_reason == FinishReason::STOP
+    end
+
+    # Check if the completion was truncated due to length.
+    # @return [Boolean]
+    def truncated?
+      finish_reason == FinishReason::LENGTH
+    end
+
+    # Check if the completion includes tool calls.
+    # @return [Boolean]
+    def tool_calls?
+      finish_reason == FinishReason::TOOL_CALLS || !tool_calls.nil?
+    end
+
+    # Alias for backwards compatibility.
+    alias has_tool_calls? tool_calls?
+
+    private
+
+    def reset_attributes(attributes)
+      @id = attributes["id"]
+      @model = attributes["model"]
+      @created = attributes["created"]
+      @object = attributes["object"]
+      @choices = attributes["choices"]
+      @usage = attributes["usage"]
+      @system_fingerprint = attributes["system_fingerprint"]
+    end
+  end
+end

data/lib/openrouter/credit.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module OpenRouter
+  # Represents credit balance and usage information from the OpenRouter API.
+  # Provides helpers to check remaining credits.
+  class Credit
+    CREDITS_PATH = "/credits"
+
+    # @return [Float] Total credits available
+    attr_reader :total_credits
+    # @return [Float] Total credits used
+    attr_reader :total_usage
+    # @return [Float] Remaining credits
+    attr_reader :remaining
+
+    # @param attributes [Hash] Raw attributes from OpenRouter API
+    # @param client [OpenRouter::Client] HTTP client
+    def initialize(attributes, client: OpenRouter.client)
+      @client = client
+      reset_attributes(attributes)
+    end
+
+    class << self
+      # Fetch the current credit balance.
+      # Corresponds to GET /api/v1/credits
+      # @param client [OpenRouter::Client] HTTP client
+      # @return [OpenRouter::Credit]
+      def fetch(client: OpenRouter.client)
+        response = client.get(CREDITS_PATH)
+        new(response["data"] || response, client: client)
+      end
+
+      # Get remaining credits as a simple value.
+      # @param client [OpenRouter::Client] HTTP client
+      # @return [Float]
+      def remaining(client: OpenRouter.client)
+        fetch(client: client).remaining
+      end
+    end
+
+    # Check if credits are low (less than 10% remaining).
+    # @return [Boolean]
+    def low?
+      return false if @total_credits.nil? || @total_credits.zero?
+
+      (@remaining / @total_credits) < 0.1
+    end
+
+    # Check if credits are exhausted.
+    # @return [Boolean]
+    def exhausted?
+      @remaining.nil? || @remaining <= 0
+    end
+
+    # Get the usage percentage.
+    # @return [Float, nil]
+    def usage_percentage
+      return nil if @total_credits.nil? || @total_credits.zero?
+
+      (@total_usage / @total_credits) * 100
+    end
+
+    private
+
+    def reset_attributes(attributes)
+      @total_credits = attributes["total_credits"]&.to_f
+      @total_usage = attributes["total_usage"].to_f
+      @remaining = attributes["remaining"]&.to_f || (@total_credits.to_f - @total_usage.to_f)
+    end
+  end
+end