runapi-core 0.2.6 → 0.2.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b0f298f55ee5728667cb83a8db61391cd20bdc64582faec2207d5db9ce79c384
-  data.tar.gz: fe0c644ac7dd1377e0c4b0c0fb4b545afc0ff175ac83c3c3886b5219d93aed4a
+  metadata.gz: f165d79fca32b409a50b34fc13a629eb666e063a1fc2a72e51bd63f1dcf91534
+  data.tar.gz: 338918ccaeff5eb66a9366f2e56e868f55e8b728580064989453d6942c5babe1
 SHA512:
-  metadata.gz: 5d473dc453e4dba6a452c54901ad2274453464de990d34c3c2c685a92d24cdb8fb9b07d6e57086913e560f034f11e5a5deea40f030bf1c1909a02724907ac4af
-  data.tar.gz: 47ef6424ffd81307922ef8adfc7c42286b6b3cd69527478b28f0674ac23332f212c10682564da8ad23bdd3b5dc0728ae7f0ce678f8814ae4f7e40736392ffdc8
+  metadata.gz: 59a92208fc80fbaeede0a56af09e4a8d41c91a40bdbbd8242635bf762985c1177b340253de20dad30dc44b3a4fd4d76587102c00ceb80b84194c4594a5892b72
+  data.tar.gz: 96b6055a8ff2a405b500c76418fc91c9b7ebdae676b6832e59052b0700b2500b39813faadcb13204ace7ecea6b754765245c04193b7d31dcf92c95dd0c30a2ad

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/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.7"
   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.7
 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: