runapi-core 0.2.8 → 0.2.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 66cc8586f64564c496bb7c4008f5cbaf0a30d1b1528cea036db368a3f9bdc307
-  data.tar.gz: 43cb58a1644f09209e1da2e14c6128cf1a334fa245d0d285499b5e4e892a411f
+  metadata.gz: 952bc04d7631dd26161b8f055e0711a4574bf017f9ebf7c5a871c67af1a5c7dd
+  data.tar.gz: 44c1263fbe06f435878d2b2e7da5595921e1d4c3de5d2da789d4552c9b37884e
 SHA512:
-  metadata.gz: 957bcd8962bcde64fd16281a2b21876ba93b505546277d5e61a0bd898cb9b1ec6369b34ffcbeb0b79df42e5a56fbe1ff1dc8531872f8cd29b49375c5c46a37a7
-  data.tar.gz: 43261e4cdcaef883977a9efc32ed752b9000b05602671cabc7471b000a2f01065666746ae09c4be7eeceae622cb7162f84562170eb22214b11b4b1c483e43b0d
+  metadata.gz: 5f89ff25ea6c94689ce1fde2741a774ae7d0f5db82bd083284846136922518d5029bee0d918fa451cdf231a1d6b0523a1b123ef363cdefb90a3ab71156ec6c27
+  data.tar.gz: e72c1b9336e37e6abba3d701fd6bd9a954a773158d091c428415750bb4521031d1138be18eed217b9d109adcede94e5c4a7e36e2946f566491654700f9d1fedf

data/README.md

@@ -10,33 +10,32 @@ gem install runapi-core
 
 ## Notes
 
-Use the core gem for common client options, error classes, request helpers, and task polling behavior that model SDKs share. Public SDK docs live at https://runapi.ai/docs#runapi-sdks and the model catalog lives at https://runapi.ai/models.
+Use the core gem for common client options, error classes, request helpers, and task polling behavior that Provider Clients share. Public SDK docs live at https://runapi.ai/docs#runapi-sdks and the model catalog lives at https://runapi.ai/models.
 
 ## Request Identifiers
 
 RunAPI accepts an optional `X-Client-Request-Id` header on public API calls. Use printable ASCII values up to 512 characters. Accepted values are echoed in the response and stored with the RunAPI task for support and reconciliation.
 
-High-level Ruby model SDK methods currently return parsed response bodies. When an integration needs to send a client request id or read `X-RunAPI-Task-Id`, make the call through direct HTTP or a custom transport so response headers stay available.
+High-level Ruby Provider Client resource methods accept per-request options and keep response headers on the returned model object. This example uses the Suno Provider Client; install `runapi-suno` to run it.
 
 ```ruby
-require "json"
-require "net/http"
-require "uri"
-
-uri = URI("https://runapi.ai/api/v1/suno/text_to_music")
-request = Net::HTTP::Post.new(uri)
-request["Authorization"] = "Bearer #{ENV.fetch("RUNAPI_API_KEY")}"
-request["Content-Type"] = "application/json"
-request["X-Client-Request-Id"] = "order-123"
-request.body = JSON.generate({
+require "runapi/suno"
+
+client = RunApi::Suno::Client.new(api_key: ENV.fetch("RUNAPI_API_KEY"))
+options = RunApi::Core::RequestOptions.new(
+  headers: {"X-Client-Request-Id" => "order-123"}
+)
+
+response = client.text_to_music.create(
   prompt: "A chill lo-fi beat",
   model: "suno-v4.5-plus",
-  vocal_mode: "instrumental"
-})
+  vocal_mode: "instrumental",
+  options: options
+)
 
-response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(request) }
-runapi_task_id = response["X-RunAPI-Task-Id"]
-body = JSON.parse(response.body)
+runapi_task_id = response.runapi_task_id
+# Equivalent case-insensitive lookup:
+runapi_task_id = response.response_headers["X-RunAPI-Task-Id"]
 ```
 
 ## File Upload

data/lib/runapi/core/base_model.rb

@@ -40,7 +40,7 @@ module RunApi
             nil
           when BaseModel
             if target_model && target_model <= BaseModel && !value.is_a?(target_model)
-              target_model.from_hash(value.to_h)
+              target_model.from_hash(value.to_h).with_response_headers(value.response_headers)
             else
               value
             end
@@ -87,11 +87,27 @@ module RunApi
       def initialize(attributes = {})
         source = normalize_input(attributes)
         @attributes = {}
+        @response_headers = ResponseHeaders.new
 
         assign_declared_fields!(source)
         assign_extra_fields!(source)
       end
 
+      attr_reader :response_headers
+
+      def response_header(name)
+        response_headers[name]
+      end
+
+      def runapi_task_id
+        response_header("X-RunAPI-Task-Id")
+      end
+
+      def with_response_headers(headers)
+        @response_headers = headers.is_a?(ResponseHeaders) ? headers : ResponseHeaders.new(headers)
+        self
+      end
+
       def [](key)
         @attributes[key.to_s]
       end

data/lib/runapi/core/errors.rb

@@ -13,12 +13,23 @@ module RunApi
       attr_reader :request_id
       # @return [Hash, String, nil] Parsed response body or error details.
       attr_reader :details
+      # @return [ResponseHeaders] HTTP response headers when available.
+      attr_reader :response_headers
 
-      def initialize(message = nil, status: nil, request_id: nil, details: nil)
+      def initialize(message = nil, status: nil, request_id: nil, details: nil, response_headers: nil)
         super(message)
         @status = status
         @request_id = request_id
         @details = details
+        @response_headers = response_headers.is_a?(ResponseHeaders) ? response_headers : ResponseHeaders.new(response_headers)
+      end
+
+      def response_header(name)
+        response_headers[name]
+      end
+
+      def runapi_task_id
+        response_header("X-RunAPI-Task-Id")
       end
 
       def to_h
@@ -71,6 +82,7 @@ module RunApi
         def from_response(response, body = nil)
           status = response.code.to_i
           request_id = response["x-request-id"]
+          headers = response_headers(response)
 
           parsed_body = parse_body(body)
           message = extract_message(parsed_body) ||
@@ -89,7 +101,8 @@ module RunApi
           kwargs = {
             status: status,
             request_id: request_id,
-            details: parsed_body
+            details: parsed_body,
+            response_headers: headers
           }
           kwargs[:retry_after] = retry_after if error_class == RateLimitError
 
@@ -147,6 +160,14 @@ module RunApi
             nil
           end
         end
+
+        def response_headers(response)
+          return {} unless response.respond_to?(:each_header)
+
+          headers = {}
+          response.each_header { |key, value| headers[key] = value }
+          headers
+        end
       end
     end
 

data/lib/runapi/core/http_client.rb

@@ -37,7 +37,13 @@ module RunApi
             raise NetworkError, e.message
           end
 
-          return parse_body(response.body) if response.is_a?(Net::HTTPSuccess)
+          if response.is_a?(Net::HTTPSuccess)
+            body = parse_body(response.body)
+            return nil if body.nil?
+            return body unless body.is_a?(Hash) || body.is_a?(Array)
+
+            return Response.new(body:, headers: response_headers(response))
+          end
 
           error = Error.from_response(response, response.body)
 
@@ -156,6 +162,12 @@ module RunApi
       rescue JSON::ParserError
         body
       end
+
+      def response_headers(response)
+        headers = {}
+        response.each_header { |key, value| headers[key] = value }
+        headers
+      end
     end
   end
 end

data/lib/runapi/core/polling.rb

@@ -16,15 +16,27 @@ module RunApi
 
           if status == "failed"
             message = value_for(response, "error") || "Task failed"
-            raise TaskFailedError.new(message, details: details_for(response))
+            raise TaskFailedError.new(
+              message,
+              details: details_for(response),
+              response_headers: response_headers_for(response)
+            )
           end
 
           if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
-            raise TaskTimeoutError, "Task polling timed out after #{options.max_wait}s"
+            raise TaskTimeoutError.new(
+              "Task polling timed out after #{options.max_wait}s",
+              details: details_for(response),
+              response_headers: response_headers_for(response)
+            )
           end
 
           unless ACTIVE_STATUSES.include?(status)
-            raise TaskFailedError.new("Unknown task status: #{status}", details: details_for(response))
+            raise TaskFailedError.new(
+              "Unknown task status: #{status}",
+              details: details_for(response),
+              response_headers: response_headers_for(response)
+            )
           end
 
           sleep(options.poll_interval)
@@ -45,6 +57,11 @@ module RunApi
         response.is_a?(Core::BaseModel) ? response.to_h : response
       end
       private_class_method :details_for
+
+      def self.response_headers_for(response)
+        response.response_headers if response.respond_to?(:response_headers)
+      end
+      private_class_method :response_headers_for
     end
   end
 end

data/lib/runapi/core/resource_helpers.rb

@@ -20,7 +20,10 @@ module RunApi
           @http.request(method, path, **kwargs)
         end
 
-        Core::BaseModel.coerce(response, as: response_class)
+        payload = response.is_a?(Core::Response) ? response.body : response
+        result = Core::BaseModel.coerce(payload, as: response_class)
+        attach_response_headers(result, response.response_headers) if response.is_a?(Core::Response)
+        result
       end
 
       def compact_params(params)
@@ -205,7 +208,18 @@ module RunApi
         return response if response.is_a?(completed_class)
 
         payload = response.is_a?(Core::BaseModel) ? response.to_h : response
-        completed_class.from_hash(payload)
+        completed = completed_class.from_hash(payload)
+        completed.with_response_headers(response.response_headers) if response.is_a?(Core::BaseModel)
+        completed
+      end
+
+      def attach_response_headers(result, headers)
+        case result
+        when Core::BaseModel
+          result.with_response_headers(headers)
+        when Array
+          result.each { |item| attach_response_headers(item, headers) }
+        end
       end
     end
   end

data/lib/runapi/core/response.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module RunApi
+  module Core
+    class ResponseHeaders
+      include Enumerable
+
+      def initialize(headers = {})
+        @headers = {}
+        headers&.each { |key, value| @headers[normalize(key)] = value }
+      end
+
+      def [](key)
+        @headers[normalize(key)]
+      end
+
+      def fetch(key, *fallback, &block)
+        @headers.fetch(normalize(key), *fallback, &block)
+      end
+
+      def key?(key)
+        @headers.key?(normalize(key))
+      end
+
+      def each(&block)
+        @headers.each(&block)
+      end
+
+      def empty?
+        @headers.empty?
+      end
+
+      def to_h
+        @headers.dup
+      end
+
+      private
+
+      def normalize(key)
+        key.to_s.downcase
+      end
+    end
+
+    class Response < Hash
+      attr_reader :response_headers
+
+      def initialize(body:, headers: nil)
+        super()
+        @body = body unless body.is_a?(Hash)
+        @response_headers = headers.is_a?(ResponseHeaders) ? headers : ResponseHeaders.new(headers)
+        update(body) if body.is_a?(Hash)
+      end
+
+      alias_method :headers, :response_headers
+
+      def body
+        @body.nil? ? self : @body
+      end
+
+      def [](key)
+        return @body[key] if @body.respond_to?(:[])
+
+        super
+      end
+
+      def dig(*keys)
+        return @body.dig(*keys) if @body.respond_to?(:dig)
+
+        super
+      end
+
+      def to_h
+        return @body.to_h if !@body.nil? && @body.respond_to?(:to_h)
+
+        super
+      end
+
+      def ==(other)
+        if @body
+          @body == (other.is_a?(Response) ? other.body : other)
+        else
+          super(other.is_a?(Response) ? other.to_h : other)
+        end
+      end
+    end
+  end
+end

data/lib/runapi/core/types.rb

@@ -62,7 +62,9 @@ module RunApi
     #
     # @example
     #   client.text_to_image.run(
-    #     { prompt: "A sunset" },
+    #     prompt: "A sunset",
+    #     model: "z-image",
+    #     aspect_ratio: "1:1",
     #     options: RequestOptions.new(timeout: 30, headers: { "X-Custom" => "value" })
     #   )
     #

data/lib/runapi/core/version.rb

@@ -2,7 +2,7 @@
 
 module RunApi
   module Core
-    VERSION = "0.2.8"
+    VERSION = "0.2.9"
   end
 
   VERSION = Core::VERSION

data/lib/runapi/core.rb

@@ -10,6 +10,7 @@ require "connection_pool"
 require_relative "core/version"
 require_relative "core/constants"
 require_relative "core/configuration"
+require_relative "core/response"
 require_relative "core/base_model"
 require_relative "core/types"
 require_relative "core/errors"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: runapi-core
 version: !ruby/object:Gem::Version
-  version: 0.2.8
+  version: 0.2.9
 platform: ruby
 authors:
 - RunAPI
@@ -50,6 +50,7 @@ files:
 - lib/runapi/core/multipart_body.rb
 - lib/runapi/core/polling.rb
 - lib/runapi/core/resource_helpers.rb
+- lib/runapi/core/response.rb
 - lib/runapi/core/types.rb
 - lib/runapi/core/version.rb
 homepage: https://runapi.ai/models