runapi-core 0.2.6 → 0.2.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b0f298f55ee5728667cb83a8db61391cd20bdc64582faec2207d5db9ce79c384
-  data.tar.gz: fe0c644ac7dd1377e0c4b0c0fb4b545afc0ff175ac83c3c3886b5219d93aed4a
+  metadata.gz: 66cc8586f64564c496bb7c4008f5cbaf0a30d1b1528cea036db368a3f9bdc307
+  data.tar.gz: 43cb58a1644f09209e1da2e14c6128cf1a334fa245d0d285499b5e4e892a411f
 SHA512:
-  metadata.gz: 5d473dc453e4dba6a452c54901ad2274453464de990d34c3c2c685a92d24cdb8fb9b07d6e57086913e560f034f11e5a5deea40f030bf1c1909a02724907ac4af
-  data.tar.gz: 47ef6424ffd81307922ef8adfc7c42286b6b3cd69527478b28f0674ac23332f212c10682564da8ad23bdd3b5dc0728ae7f0ce678f8814ae4f7e40736392ffdc8
+  metadata.gz: 957bcd8962bcde64fd16281a2b21876ba93b505546277d5e61a0bd898cb9b1ec6369b34ffcbeb0b79df42e5a56fbe1ff1dc8531872f8cd29b49375c5c46a37a7
+  data.tar.gz: 43261e4cdcaef883977a9efc32ed752b9000b05602671cabc7471b000a2f01065666746ae09c4be7eeceae622cb7162f84562170eb22214b11b4b1c483e43b0d

data/README.md

@@ -12,12 +12,39 @@ 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://example.com/photo.jpg"})
+upload = client.files.create(source: {type: "url", url: "https://cdn.runapi.ai/public/samples/image.jpg"})
 puts upload.url
 ```
 

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

@@ -54,6 +54,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

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.6"
+    VERSION = "0.2.8"
   end
 
   VERSION = Core::VERSION

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: runapi-core
 version: !ruby/object:Gem::Version
-  version: 0.2.6
+  version: 0.2.8
 platform: ruby
 authors:
 - RunAPI
@@ -56,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: