runapi-core 0.2.5 → 0.2.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 43b27ac4a9c29db093d7efcad4686efe7730aa9ddb906a956c0f2a4b353e0ccd
-  data.tar.gz: a42105c4a366fa9a17642f519392ae6dd50978a32ae73fae6c62f38f8b02cb28
+  metadata.gz: f165d79fca32b409a50b34fc13a629eb666e063a1fc2a72e51bd63f1dcf91534
+  data.tar.gz: 338918ccaeff5eb66a9366f2e56e868f55e8b728580064989453d6942c5babe1
 SHA512:
-  metadata.gz: 9bee66f588446e79bbbf8eea48964bb2505bfee41c4dc9c68ce1622359e0a536e498a895c065ef8efb54c2ee41b5df19b8d7c55b8707d181c3585d2887cb29b5
-  data.tar.gz: bb4dc1ff3c4f564c89bc20e4838263864704d54a80f315f093dba9d77e6efabce80bc4087748b816aec20ac0674141e30b1d3ee632e6d92b1f006bb4c07d2b3b
+  metadata.gz: 59a92208fc80fbaeede0a56af09e4a8d41c91a40bdbbd8242635bf762985c1177b340253de20dad30dc44b3a4fd4d76587102c00ceb80b84194c4594a5892b72
+  data.tar.gz: 96b6055a8ff2a405b500c76418fc91c9b7ebdae676b6832e59052b0700b2500b39813faadcb13204ace7ecea6b754765245c04193b7d31dcf92c95dd0c30a2ad

data/README.md

@@ -12,6 +12,45 @@ gem install runapi-core
 
 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.
 
+## 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.
+
+```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({
+  prompt: "A chill lo-fi beat",
+  model: "suno-v4.5-plus",
+  vocal_mode: "instrumental"
+})
+
+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)
+```
+
+## File Upload
+
+```ruby
+client = RunApi::NanoBanana::Client.new(api_key: ENV["RUNAPI_API_KEY"])
+
+upload = client.files.create(source: {type: "url", url: "https://cdn.runapi.ai/public/samples/image.jpg"})
+puts upload.url
+```
+
+> [!IMPORTANT]
+> Uploaded file URLs expire 1 hour after creation. Pass them to a model promptly rather than storing them for later use.
+
 ## License
 
 Licensed under the Apache License, Version 2.0.

data/lib/runapi/core/account.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module RunApi
+  module Core
+    class Account
+      include RunApi::Core::ResourceHelpers
+
+      INFO_ENDPOINT = "/api/v1/me"
+      BALANCE_ENDPOINT = "/api/v1/me/balance"
+
+      class AccountRecord < RunApi::Core::BaseModel
+        required :id, Integer
+        required :name, String
+      end
+
+      class InfoResponse < RunApi::Core::BaseModel
+        required :id, Integer
+        required :name, String
+        required :email, String
+        required :account, AccountRecord
+      end
+
+      class BalanceResponse < RunApi::Core::BaseModel
+        required :balance_cents, Integer
+        required :paid_balance_cents, Integer
+        required :bonus_balance_cents, Integer
+        required :spent_cents_today, Integer
+        required :spent_cents_total, Integer
+      end
+
+      def initialize(http)
+        @http = http
+      end
+
+      def info(options: nil)
+        request(:get, INFO_ENDPOINT, options:, response_class: InfoResponse)
+      end
+
+      def balance(options: nil)
+        request(:get, BALANCE_ENDPOINT, options:, response_class: BalanceResponse)
+      end
+    end
+  end
+end

data/lib/runapi/core/client.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module RunApi
+  module Core
+    # Base class for every RunAPI client. Resolves the API key, builds the shared
+    # HTTP client, and exposes the Universal Resources (file upload, account) that
+    # are available on any client regardless of which model gem was required.
+    #
+    # Provider clients inherit from this and build their model resources from the
+    # protected +http+ reader.
+    class Client
+      # @return [Files] Temporary file upload operations.
+      attr_reader :files
+      # @return [Account] Account info and balance operations.
+      attr_reader :account
+
+      def initialize(api_key: nil, **options)
+        @api_key = Core::Auth.resolve_api_key(api_key)
+        client_options = Core::ClientOptions.new(api_key: @api_key, **options)
+        @http = client_options.http_client || Core::HttpClient.new(client_options)
+        @files = Files.new(@http)
+        @account = Account.new(@http)
+      end
+
+      protected
+
+      attr_reader :http
+    end
+  end
+end

data/lib/runapi/core/files.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module RunApi
+  module Core
+    class Files
+      include RunApi::Core::ResourceHelpers
+
+      ENDPOINT = "/api/v1/files"
+
+      class UploadResponse < RunApi::Core::BaseModel
+        required :file_name, String
+        required :url, String
+        required :size_bytes, Integer
+        required :mime_type, String
+        required :created_at, String
+        required :expires_at, String
+      end
+
+      RESPONSE_CLASS = UploadResponse
+
+      def initialize(http)
+        @http = http
+      end
+
+      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
+
+        request(:post, ENDPOINT, body:, options:)
+      end
+
+      private
+
+      def validate_source!(file:, source:)
+        source_count = [file, source].count { |value| !value.nil? }
+        return if source_count == 1
+
+        raise ArgumentError, "Exactly one source is required: file or source"
+      end
+
+      def multipart_body(file, file_name:)
+        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:)
+          }
+        )
+      end
+
+      def file_path(file)
+        return file if file.is_a?(String)
+        return file.path if file.respond_to?(:path)
+
+        raise ArgumentError, "file must be a file path or respond to :path"
+      end
+    end
+  end
+end

data/lib/runapi/core/http_client.rb

@@ -50,6 +50,8 @@ module RunApi
 
           raise error
         end
+      ensure
+        close_multipart_files(req)
       end
 
       private
@@ -69,16 +71,45 @@ module RunApi
         req = klass.new(uri.request_uri)
 
         req["Authorization"] = "Bearer #{@options.api_key}"
-        req["Content-Type"] = "application/json"
         req["Accept"] = "application/json"
         req["User-Agent"] = Constants::SDK_USER_AGENT
 
         options&.headers&.each { |k, v| req[k.to_s] = v }
 
-        req.body = JSON.generate(body) if body
+        if body.is_a?(MultipartBody)
+          req.set_form(multipart_parts(body), "multipart/form-data")
+        elsif body
+          req["Content-Type"] = "application/json"
+          req.body = JSON.generate(body)
+        end
         req
       end
 
+      def multipart_parts(body)
+        opened_files = []
+        field_parts = body.fields.map { |key, value| [key, value.to_s] }
+        file_parts = body.files.map do |key, file|
+          options = {filename: file.filename}
+          options[:content_type] = file.content_type if file.content_type
+          opened_files << File.open(file.path, "rb")
+          [key, opened_files.last, options]
+        end
+        field_parts + file_parts
+      rescue
+        opened_files.each { |file| file.close unless file.closed? }
+        raise
+      end
+
+      def close_multipart_files(request)
+        body_data = request&.instance_variable_get(:@body_data)
+        return unless body_data
+
+        body_data.each do |part|
+          file = part[1]
+          file.close if file.is_a?(File) && !file.closed?
+        end
+      end
+
       def retryable?(method, status)
         Constants::IDEMPOTENT_METHODS.include?(method.to_s.upcase) &&
           Constants::RETRYABLE_STATUS_CODES.include?(status)

data/lib/runapi/core/multipart_body.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module RunApi
+  module Core
+    MultipartFile = Struct.new(:path, :filename, :content_type, keyword_init: true)
+
+    class MultipartBody
+      attr_reader :fields, :files
+
+      def initialize(fields: {}, files: {})
+        @fields = stringify_keys(fields)
+        @files = stringify_keys(files)
+      end
+
+      private
+
+      def stringify_keys(hash)
+        hash.each_with_object({}) do |(key, value), result|
+          result[key.to_s] = value
+        end
+      end
+    end
+  end
+end

data/lib/runapi/core/resource_helpers.rb

@@ -41,6 +41,151 @@ module RunApi
         end
       end
 
+      # ---- Contract validation ------------------------------------------
+      # Validates request params against the generated contract: model
+      # membership, then per-field required/enum/integer/min/max/length, then
+      # declared cross-field rules. `schema` is one action entry from the generated
+      # per-package CONTRACT (CONTRACT["<action>"]).
+
+      def validate_contract!(schema, params)
+        model = param_value(params, "model")
+        models = schema["models"] || []
+        unless models.include?(model)
+          raise Core::ValidationError, "model must be one of: #{models.sort.join(", ")}"
+        end
+
+        fields = schema.dig("fields_by_model", model) || {}
+        fields.each do |field, rules|
+          validate_schema_field!(params, field, rules)
+        end
+
+        Array(schema["rules"]).each { |rule| enforce_contract_rule!(params, rule) }
+      end
+
+      def validate_schema_field!(params, field, rules)
+        present = field_present?(params, field)
+        raise Core::ValidationError, "#{field} is required" if rules["required"] && !present
+        return unless present
+
+        value = param_value(params, field)
+        if (enum = rules["enum"]) && !enum_value_allowed?(enum, value)
+          raise Core::ValidationError, "#{field} must be one of: #{enum.join(", ")}"
+        end
+
+        validate_schema_integer!(field, value, rules) if rules["type"] == "integer"
+        validate_schema_range!(field, value, rules) if rules.key?("min") || rules.key?("max")
+      end
+
+      # Mirrors GatewayEntry#validate_schema_integer!: a type: integer field
+      # rejects non-integer numbers (e.g. 11.5), which min/max alone admit.
+      def validate_schema_integer!(field, value, rules)
+        return if value.is_a?(Integer)
+
+        min = rules["min"]
+        max = rules["max"]
+        detail = (min && max) ? " between #{min} and #{max}" : ""
+        raise Core::ValidationError, "#{field} must be an integer#{detail}"
+      end
+
+      def validate_schema_range!(field, value, rules)
+        if rules["length"]
+          measured = value.to_s.length
+          unit = "characters"
+        else
+          raise Core::ValidationError, "#{field} must be a number" unless value.is_a?(Numeric)
+
+          measured = value
+          unit = nil
+        end
+
+        min = rules["min"]
+        max = rules["max"]
+        return if (min.nil? || measured >= min) && (max.nil? || measured <= max)
+
+        raise Core::ValidationError, schema_range_message(field, min, max, unit)
+      end
+
+      def schema_range_message(field, min, max, unit)
+        suffix = unit ? " #{unit}" : ""
+        if min && max
+          "#{field} must be between #{min} and #{max}#{suffix}"
+        elsif min
+          "#{field} must be at least #{min}#{suffix}"
+        else
+          "#{field} must be at most #{max}#{suffix}"
+        end
+      end
+
+      def enum_value_allowed?(enum, value)
+        enum.any? do |allowed|
+          if allowed.is_a?(Numeric)
+            value.is_a?(Numeric) && value == allowed
+          elsif value.is_a?(Numeric)
+            allowed == value
+          else
+            allowed.to_s == value.to_s
+          end
+        end
+      end
+
+      def enforce_contract_rule!(params, rule)
+        conditions = rule["when"] || {}
+        return unless conditions.all? { |field, value| rule_condition_met?(params, field, value) }
+
+        context = conditions.map { |field, value| "#{field} is #{value}" }.join(" and ")
+        Array(rule["required"]).each do |field|
+          next if field_present?(params, field)
+
+          raise Core::ValidationError, "#{field} is required when #{context}"
+        end
+        Array(rule["forbidden"]).each do |field|
+          next unless field_present?(params, field)
+
+          raise Core::ValidationError, "#{field} is not allowed when #{context}"
+        end
+      end
+
+      def rule_condition_met?(params, field, value)
+        return false unless param_key?(params, field)
+
+        param_value(params, field).to_s == value.to_s
+      end
+
+      def field_present?(params, field)
+        return false unless param_key?(params, field)
+
+        value = param_value(params, field)
+        case value
+        when false then true
+        when Array then value.any? { |item| present_value?(item) }
+        else present_value?(value)
+        end
+      end
+
+      def param_key?(params, field)
+        params.key?(field.to_sym) || params.key?(field.to_s)
+      end
+
+      # Indifferent value lookup for a string-or-symbol field across params that
+      # may be keyed either way.
+      def param_value(params, field)
+        if params.key?(field.to_sym)
+          params[field.to_sym]
+        elsif params.key?(field.to_s)
+          params[field.to_s]
+        end
+      end
+
+      def present_value?(value)
+        case value
+        when nil, false then false
+        when true then true
+        when String then !value.strip.empty?
+        when Array, Hash then !value.empty?
+        else true
+        end
+      end
+
       def default_response_class
         if self.class.const_defined?(:RESPONSE_CLASS, false)
           self.class::RESPONSE_CLASS

data/lib/runapi/core/version.rb

@@ -2,7 +2,7 @@
 
 module RunApi
   module Core
-    VERSION = "0.2.5"
+    VERSION = "0.2.7"
   end
 
   VERSION = Core::VERSION

data/lib/runapi/core.rb

@@ -14,6 +14,10 @@ require_relative "core/base_model"
 require_relative "core/types"
 require_relative "core/errors"
 require_relative "core/auth"
+require_relative "core/multipart_body"
 require_relative "core/http_client"
 require_relative "core/polling"
 require_relative "core/resource_helpers"
+require_relative "core/files"
+require_relative "core/account"
+require_relative "core/client"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: runapi-core
 version: !ruby/object:Gem::Version
-  version: 0.2.5
+  version: 0.2.7
 platform: ruby
 authors:
 - RunAPI
@@ -38,12 +38,16 @@ files:
 - README.md
 - lib/runapi-core.rb
 - lib/runapi/core.rb
+- lib/runapi/core/account.rb
 - lib/runapi/core/auth.rb
 - lib/runapi/core/base_model.rb
+- lib/runapi/core/client.rb
 - lib/runapi/core/configuration.rb
 - lib/runapi/core/constants.rb
 - lib/runapi/core/errors.rb
+- lib/runapi/core/files.rb
 - lib/runapi/core/http_client.rb
+- lib/runapi/core/multipart_body.rb
 - lib/runapi/core/polling.rb
 - lib/runapi/core/resource_helpers.rb
 - lib/runapi/core/types.rb
@@ -52,9 +56,11 @@ homepage: https://runapi.ai/models
 licenses:
 - Apache-2.0
 metadata:
+  runapi_slug: core
   homepage_uri: https://runapi.ai/models
   documentation_uri: https://github.com/runapi-ai/core-sdk/blob/main/ruby/README.md
   source_code_uri: https://github.com/runapi-ai/core-sdk
+  bug_tracker_uri: https://github.com/runapi-ai/core-sdk/issues
   changelog_uri: https://github.com/runapi-ai/core-sdk/blob/main/CHANGELOG.md
 rdoc_options: []
 require_paths: