runapi-core 0.2.7 → 0.2.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f165d79fca32b409a50b34fc13a629eb666e063a1fc2a72e51bd63f1dcf91534
-  data.tar.gz: 338918ccaeff5eb66a9366f2e56e868f55e8b728580064989453d6942c5babe1
+  metadata.gz: 952bc04d7631dd26161b8f055e0711a4574bf017f9ebf7c5a871c67af1a5c7dd
+  data.tar.gz: 44c1263fbe06f435878d2b2e7da5595921e1d4c3de5d2da789d4552c9b37884e
 SHA512:
-  metadata.gz: 59a92208fc80fbaeede0a56af09e4a8d41c91a40bdbbd8242635bf762985c1177b340253de20dad30dc44b3a4fd4d76587102c00ceb80b84194c4594a5892b72
-  data.tar.gz: 96b6055a8ff2a405b500c76418fc91c9b7ebdae676b6832e59052b0700b2500b39813faadcb13204ace7ecea6b754765245c04193b7d31dcf92c95dd0c30a2ad
+  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/files.rb

@@ -1,11 +1,15 @@
 # frozen_string_literal: true
 
+require "digest"
+
 module RunApi
   module Core
     class Files
       include RunApi::Core::ResourceHelpers
 
       ENDPOINT = "/api/v1/files"
+      PREPARE_ENDPOINT = "#{ENDPOINT}/prepare"
+      CONFIRM_ENDPOINT = "#{ENDPOINT}/confirm"
 
       class UploadResponse < RunApi::Core::BaseModel
         required :file_name, String
@@ -25,13 +29,9 @@ module RunApi
       def create(file: nil, source: nil, file_name: nil, options: nil)
         validate_source!(file:, source:)
 
-        body = if file
-          multipart_body(file, file_name:)
-        else
-          compact_params(source:, file_name:)
-        end
+        return upload_direct(file, file_name:, options:) if file
 
-        request(:post, ENDPOINT, body:, options:)
+        request(:post, ENDPOINT, body: compact_params(source:, file_name:), options:)
       end
 
       private
@@ -43,15 +43,26 @@ module RunApi
         raise ArgumentError, "Exactly one source is required: file or source"
       end
 
-      def multipart_body(file, file_name:)
+      # Local files upload straight to storage: ask for a pre-authorized target,
+      # PUT the bytes there (never through the API), then confirm. The caller still
+      # makes a single create call.
+      def upload_direct(file, file_name:, options:)
         path = file_path(file)
-        filename = file_name || File.basename(path)
-        Core::MultipartBody.new(
-          fields: compact_params(file_name: file_name),
-          files: {
-            file: Core::MultipartFile.new(path:, filename:)
-          }
+        bytes = File.binread(path)
+        prepared = @http.request(
+          :post,
+          PREPARE_ENDPOINT,
+          body: compact_params(
+            filename: file_name || File.basename(path),
+            byte_size: bytes.bytesize,
+            checksum: Digest::MD5.base64digest(bytes)
+          ),
+          options:
         )
+
+        @http.upload(prepared["upload_url"], headers: prepared["headers"], body: bytes)
+
+        request(:post, CONFIRM_ENDPOINT, body: {signed_id: prepared["signed_id"]}, options:)
       end
 
       def file_path(file)

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)
 
@@ -54,6 +60,30 @@ module RunApi
         close_multipart_files(req)
       end
 
+      # PUT bytes straight to a pre-authorized upload URL with the exact headers
+      # issued for it. Skips the base URL, auth, and retries: the URL is single-use
+      # and the body is not safe to replay.
+      def upload(url, headers:, body:)
+        uri = URI.parse(url)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = (uri.scheme == "https")
+        http.open_timeout = @options.timeout
+        http.read_timeout = @options.timeout
+
+        req = Net::HTTP::Put.new(uri.request_uri)
+        headers.each { |key, value| req[key.to_s] = value }
+        req.body = body
+
+        response = http.start { |connection| connection.request(req) }
+        return if response.is_a?(Net::HTTPSuccess)
+
+        raise Error.from_response(response, response.body)
+      rescue ::Net::OpenTimeout, ::Net::ReadTimeout => e
+        raise TimeoutError, e.message
+      rescue ::SocketError, ::Errno::ECONNREFUSED, ::Errno::ECONNRESET => e
+        raise NetworkError, e.message
+      end
+
       private
 
       def build_connection
@@ -132,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.7"
+    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.7
+  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