runapi-core 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ac730f3383d61bc33ade1919255a2cefb32dfd194f486c53db53cbbc4ce13da4
+  data.tar.gz: 4cd216b5432076999c28f3c90fbc73082318d08865236e90dcb0a7e6fe0f04a7
+SHA512:
+  metadata.gz: fd05422a84596bc05e34bfd9b43b307bfad36377c6674daad1a9f0aa8df8e6e8b2751bdd9a628ae6f95b06765a66d617d43e566133e4d19bc689d3f4ce1e39db
+  data.tar.gz: 3baeb19bd5d4e9ff253b43187e1dd95647d75619af2d4fec0a4c87b541fa0ed8fa18e8d7d21e0b73f727757e9c33428dfa49077359c45839656327b22f537b23

data/LICENSE

@@ -0,0 +1,201 @@
+                              Apache License
+                        Version 2.0, January 2004
+                     http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+   "License" shall mean the terms and conditions for use, reproduction,
+   and distribution as defined by Sections 1 through 9 of this document.
+
+   "Licensor" shall mean the copyright owner or entity authorized by
+   the copyright owner that is granting the License.
+
+   "Legal Entity" shall mean the union of the acting entity and all
+   other entities that control, are controlled by, or are under common
+   control with that entity. For the purposes of this definition,
+   "control" means (i) the power, direct or indirect, to cause the
+   direction or management of such entity, whether by contract or
+   otherwise, or (ii) ownership of fifty percent (50%) or more of the
+   outstanding shares, or (iii) beneficial ownership of such entity.
+
+   "You" (or "Your") shall mean an individual or Legal Entity
+   exercising permissions granted by this License.
+
+   "Source" form shall mean the preferred form for making modifications,
+   including but not limited to software source code, documentation
+   source, and configuration files.
+
+   "Object" form shall mean any form resulting from mechanical
+   transformation or translation of a Source form, including but
+   not limited to compiled object code, generated documentation,
+   and conversions to other media types.
+
+   "Work" shall mean the work of authorship, whether in Source or
+   Object form, made available under the License, as indicated by a
+   copyright notice that is included in or attached to the work
+   (an example is provided in the Appendix below).
+
+   "Derivative Works" shall mean any work, whether in Source or Object
+   form, that is based on (or derived from) the Work and for which the
+   editorial revisions, annotations, elaborations, or other modifications
+   represent, as a whole, an original work of authorship. For the purposes
+   of this License, Derivative Works shall not include works that remain
+   separable from, or merely link (or bind by name) to the interfaces of,
+   the Work and Derivative Works thereof.
+
+   "Contribution" shall mean any work of authorship, including
+   the original version of the Work and any modifications or additions
+   to that Work or Derivative Works thereof, that is intentionally
+   submitted to Licensor for inclusion in the Work by the copyright owner
+   or by an individual or Legal Entity authorized to submit on behalf of
+   the copyright owner. For the purposes of this definition, "submitted"
+   means any form of electronic, verbal, or written communication sent
+   to the Licensor or its representatives, including but not limited to
+   communication on electronic mailing lists, source code control systems,
+   and issue tracking systems that are managed by, or on behalf of, the
+   Licensor for the purpose of discussing and improving the Work, but
+   excluding communication that is conspicuously marked or otherwise
+   designated in writing by the copyright owner as "Not a Contribution."
+
+   "Contributor" shall mean Licensor and any individual or Legal Entity
+   on behalf of whom a Contribution has been received by Licensor and
+   subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of
+   this License, each Contributor hereby grants to You a perpetual,
+   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+   copyright license to reproduce, prepare Derivative Works of,
+   publicly display, publicly perform, sublicense, and distribute the
+   Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of
+   this License, each Contributor hereby grants to You a perpetual,
+   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+   (except as stated in this section) patent license to make, have made,
+   use, offer to sell, sell, import, and otherwise transfer the Work,
+   where such license applies only to those patent claims licensable
+   by such Contributor that are necessarily infringed by their
+   Contribution(s) alone or by combination of their Contribution(s)
+   with the Work to which such Contribution(s) was submitted. If You
+   institute patent litigation against any entity (including a
+   cross-claim or counterclaim in a lawsuit) alleging that the Work
+   or a Contribution incorporated within the Work constitutes direct
+   or contributory patent infringement, then any patent licenses
+   granted to You under this License for that Work shall terminate
+   as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the
+   Work or Derivative Works thereof in any medium, with or without
+   modifications, and in Source or Object form, provided that You
+   meet the following conditions:
+
+   (a) You must give any other recipients of the Work or
+       Derivative Works a copy of this License; and
+
+   (b) You must cause any modified files to carry prominent notices
+       stating that You changed the files; and
+
+   (c) You must retain, in the Source form of any Derivative Works
+       that You distribute, all copyright, patent, trademark, and
+       attribution notices from the Source form of the Work,
+       excluding those notices that do not pertain to any part of
+       the Derivative Works; and
+
+   (d) If the Work includes a "NOTICE" text file as part of its
+       distribution, then any Derivative Works that You distribute must
+       include a readable copy of the attribution notices contained
+       within such NOTICE file, excluding those notices that do not
+       pertain to any part of the Derivative Works, in at least one
+       of the following places: within a NOTICE text file distributed
+       as part of the Derivative Works; within the Source form or
+       documentation, if provided along with the Derivative Works; or,
+       within a display generated by the Derivative Works, if and
+       wherever such third-party notices normally appear. The contents
+       of the NOTICE file are for informational purposes only and
+       do not modify the License. You may add Your own attribution
+       notices within Derivative Works that You distribute, alongside
+       or as an addendum to the NOTICE text from the Work, provided
+       that such additional attribution notices cannot be construed
+       as modifying the License.
+
+   You may add Your own copyright statement to Your modifications and
+   may provide additional or different license terms and conditions
+   for use, reproduction, or distribution of Your modifications, or
+   for any such Derivative Works as a whole, provided Your use,
+   reproduction, and distribution of the Work otherwise complies with
+   the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise,
+   any Contribution intentionally submitted for inclusion in the Work
+   by You to the Licensor shall be under the terms and conditions of
+   this License, without any additional terms or conditions.
+   Notwithstanding the above, nothing herein shall supersede or modify
+   the terms of any separate license agreement you may have executed
+   with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade
+   names, trademarks, service marks, or product names of the Licensor,
+   except as required for reasonable and customary use in describing the
+   origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or
+   agreed to in writing, Licensor provides the Work (and each
+   Contributor provides its Contributions) on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+   implied, including, without limitation, any warranties or conditions
+   of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+   PARTICULAR PURPOSE. You are solely responsible for determining the
+   appropriateness of using or redistributing the Work and assume any
+   risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory,
+   whether in tort (including negligence), contract, or otherwise,
+   unless required by applicable law (such as deliberate and grossly
+   negligent acts) or agreed to in writing, shall any Contributor be
+   liable to You for damages, including any direct, indirect, special,
+   incidental, or consequential damages of any character arising as a
+   result of this License or out of the use or inability to use the
+   Work (including but not limited to damages for loss of goodwill,
+   work stoppage, computer failure or malfunction, or any and all
+   other commercial damages or losses), even if such Contributor
+   has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing
+   the Work or Derivative Works thereof, You may choose to offer,
+   and charge a fee for, acceptance of support, warranty, indemnity,
+   or other liability obligations and/or rights consistent with this
+   License. However, in accepting such obligations, You may act only
+   on Your own behalf and on Your sole responsibility, not on behalf
+   of any other Contributor, and only if You agree to indemnify,
+   defend, and hold each Contributor harmless for any liability
+   incurred by, or claims asserted against, such Contributor by reason
+   of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work.
+
+   To apply the Apache License to your work, attach the following
+   boilerplate notice, with the fields enclosed by brackets "[]"
+   replaced with your own identifying information. (Don't include
+   the brackets!)  The text should be enclosed in the appropriate
+   comment syntax for the file format. We also recommend that a
+   file or class name and description of purpose be included on the
+   same "printed page" as the copyright notice for easier
+   identification within third-party archives.
+
+Copyright [yyyy] [name of copyright owner]
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

data/lib/runapi/core/auth.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module RunApi
+  module Core
+    # API key resolution helpers.
+    module Auth
+      ENV_VAR_NAME = "RUNAPI_API_KEY"
+
+      MISSING_KEY_MESSAGE = "API key is required. Pass api_key or set the RUNAPI_API_KEY environment variable."
+
+      # Resolve the API key from (in priority order):
+      #   1. the explicit argument
+      #   2. RunApi.api_key (global configuration)
+      #   3. the RUNAPI_API_KEY environment variable
+      #
+      # All sources are trimmed; blank values are treated as missing.
+      # Raises {RunApi::Core::AuthenticationError} when no source yields a value.
+      #
+      # @param explicit [String, nil] API key passed directly to a client constructor.
+      # @return [String] the resolved API key
+      def self.resolve_api_key(explicit = nil)
+        resolved = normalize(explicit) ||
+          normalize(RunApi.respond_to?(:api_key) ? RunApi.api_key : nil) ||
+          normalize(ENV[ENV_VAR_NAME])
+
+        raise AuthenticationError, MISSING_KEY_MESSAGE unless resolved
+
+        resolved
+      end
+
+      def self.normalize(value)
+        return nil unless value.is_a?(String)
+
+        trimmed = value.strip
+        trimmed.empty? ? nil : trimmed
+      end
+      private_class_method :normalize
+    end
+  end
+end

data/lib/runapi/core/base_model.rb

@@ -0,0 +1,257 @@
+# frozen_string_literal: true
+
+module RunApi
+  module Core
+    # Lightweight response model with typed field declarations and recursive coercion.
+    class BaseModel
+      Field = Struct.new(:name, :required, :type, :item_type, :enum, keyword_init: true)
+
+      class << self
+        def fields
+          @fields ||= begin
+            parent_fields = superclass.respond_to?(:fields) ? superclass.fields : {}
+            parent_fields.transform_values(&:dup)
+          end
+        end
+
+        def required(name, type = nil, enum: nil)
+          define_field(name, type, required: true, enum: enum)
+        end
+
+        def optional(name, type = nil, enum: nil)
+          define_field(name, type, required: false, enum: enum)
+        end
+
+        def from_hash(payload)
+          return payload if payload.is_a?(self)
+
+          unless payload.is_a?(Hash)
+            raise TypeError, "Expected Hash for #{name}, got #{payload.class}"
+          end
+
+          new(payload)
+        end
+
+        def coerce(value, as: DynamicModel)
+          target_model = resolve_type(as)
+
+          case value
+          when nil
+            nil
+          when BaseModel
+            if target_model && target_model <= BaseModel && !value.is_a?(target_model)
+              target_model.from_hash(value.to_h)
+            else
+              value
+            end
+          when Hash
+            model = (target_model && target_model <= BaseModel) ? target_model : DynamicModel
+            model.from_hash(value)
+          when Array
+            value.map { |item| coerce(item, as: target_model || DynamicModel) }
+          else
+            value
+          end
+        end
+
+        private
+
+        def define_field(name, type, required:, enum:)
+          key = name.to_s
+
+          field_type = type
+          item_type = nil
+          if type.is_a?(Array)
+            raise ArgumentError, "Array field type must contain exactly one item type" unless type.size == 1
+
+            field_type = Array
+            item_type = type.first
+          end
+
+          fields[key] = Field.new(
+            name: key,
+            required: required,
+            type: field_type,
+            item_type: item_type,
+            enum: enum
+          )
+
+          define_method(name) { @attributes[key] } unless method_defined?(name)
+        end
+
+        def resolve_type(type)
+          type.respond_to?(:call) ? type.call : type
+        end
+      end
+
+      def initialize(attributes = {})
+        source = normalize_input(attributes)
+        @attributes = {}
+
+        assign_declared_fields!(source)
+        assign_extra_fields!(source)
+      end
+
+      def [](key)
+        @attributes[key.to_s]
+      end
+
+      def dig(*keys)
+        current = self
+        keys.each do |key|
+          current = case current
+          when BaseModel
+            current[key]
+          when Hash
+            current[key] || current[key.to_s] || current[key.to_sym]
+          when Array
+            key.is_a?(Integer) ? current[key] : nil
+          end
+          return nil if current.nil?
+        end
+        current
+      end
+
+      def to_h
+        @attributes.each_with_object({}) do |(key, value), out|
+          out[key] = serialize(value)
+        end
+      end
+      alias_method :to_hash, :to_h
+
+      def ==(other)
+        case other
+        when BaseModel
+          to_h == other.to_h
+        when Hash
+          to_h == stringify_keys(other)
+        else
+          super
+        end
+      end
+
+      private
+
+      def assign_declared_fields!(source)
+        self.class.fields.each_value do |field|
+          if source.key?(field.name)
+            assign_attribute(field.name, coerce_declared_value(source.delete(field.name), field))
+            next
+          end
+
+          raise ValidationError, "#{field.name} is required" if field.required
+        end
+      end
+
+      def assign_extra_fields!(source)
+        source.each do |key, value|
+          assign_attribute(key, coerce_dynamic_value(value))
+          define_dynamic_reader!(key)
+        end
+      end
+
+      def assign_attribute(key, value)
+        @attributes[key.to_s] = value
+      end
+
+      def coerce_declared_value(value, field)
+        coerced =
+          if field.type == Array && value.is_a?(Array)
+            value.map { |item| coerce_with_type(item, field.item_type) }
+          else
+            coerce_with_type(value, field.type)
+          end
+
+        validate_enum!(field, coerced)
+        coerced
+      end
+
+      def coerce_with_type(value, type)
+        return coerce_dynamic_value(value) if type.nil?
+
+        resolved_type = self.class.send(:resolve_type, type)
+
+        if resolved_type && resolved_type <= BaseModel && value.is_a?(Hash)
+          return resolved_type.from_hash(value)
+        end
+
+        return coerce_dynamic_value(value) if resolved_type.nil?
+
+        value
+      end
+
+      def validate_enum!(field, value)
+        return if value.nil? || field.enum.nil?
+
+        allowed = field.enum.respond_to?(:call) ? field.enum.call : field.enum
+        return unless allowed
+
+        invalid_value = Array(value).find do |item|
+          allowed.none? { |candidate| candidate == item || candidate.to_s == item.to_s }
+        end
+        return unless invalid_value
+
+        raise ValidationError, "Invalid #{field.name}: #{invalid_value}. Must be one of: #{allowed.join(", ")}"
+      end
+
+      def coerce_dynamic_value(value)
+        case value
+        when Hash
+          DynamicModel.from_hash(value)
+        when Array
+          value.map { |item| coerce_dynamic_value(item) }
+        else
+          value
+        end
+      end
+
+      def serialize(value)
+        case value
+        when BaseModel
+          value.to_h
+        when Array
+          value.map { |item| serialize(item) }
+        else
+          value
+        end
+      end
+
+      def normalize_input(attributes)
+        return {} if attributes.nil?
+
+        unless attributes.is_a?(Hash)
+          raise TypeError, "Expected Hash, got #{attributes.class}"
+        end
+
+        attributes.each_with_object({}) do |(key, value), out|
+          out[key.to_s] = value
+        end
+      end
+
+      def stringify_keys(value)
+        case value
+        when Hash
+          value.each_with_object({}) do |(k, v), out|
+            out[k.to_s] = stringify_keys(v)
+          end
+        when Array
+          value.map { |item| stringify_keys(item) }
+        else
+          value
+        end
+      end
+
+      def define_dynamic_reader!(key)
+        name = key.to_s
+        return unless /\A[a-z_][a-zA-Z0-9_]*\z/.match?(name)
+        return if respond_to?(name)
+
+        define_singleton_method(name) { @attributes[name] }
+      end
+    end
+
+    # Generic response model used when no API-specific typed model is provided.
+    class DynamicModel < BaseModel
+    end
+  end
+end

data/lib/runapi/core/configuration.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module RunApi
+  class << self
+    attr_accessor :api_key, :base_url
+
+    def configure
+      yield self
+    end
+  end
+
+  self.base_url = Core::Constants::DEFAULT_BASE_URL
+end

data/lib/runapi/core/constants.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module RunApi
+  module Core
+    module Constants
+      TIMEOUTS = {
+        http_request: 900,
+        polling_interval: 2,
+        polling_max_wait: 900
+      }.freeze
+
+      RETRY_CONFIG = {
+        max_retries: 2,
+        base_delay: 0.5,
+        max_delay: 5.0
+      }.freeze
+
+      DEFAULT_BASE_URL = "https://runapi.ai"
+
+      SDK_USER_AGENT = "runapi-sdk-ruby/#{RunApi::VERSION}".freeze
+
+      IDEMPOTENT_METHODS = %w[GET HEAD PUT DELETE OPTIONS].freeze
+
+      RETRYABLE_STATUS_CODES = [ 429, 500, 502, 503, 504 ].freeze
+    end
+  end
+end

data/lib/runapi/core/errors.rb

@@ -0,0 +1,246 @@
+# frozen_string_literal: true
+
+require "time"
+
+module RunApi
+  module Core
+    # Base error class for all RunAPI SDK errors.
+    # Includes HTTP status, request ID, and response details.
+    class Error < StandardError
+      # @return [Integer, nil] HTTP status code if available.
+      attr_reader :status
+      # @return [String, nil] Request ID from response headers.
+      attr_reader :request_id
+      # @return [Hash, String, nil] Parsed response body or error details.
+      attr_reader :details
+
+      def initialize(message = nil, status: nil, request_id: nil, details: nil)
+        super(message)
+        @status = status
+        @request_id = request_id
+        @details = details
+      end
+
+      def to_h
+        {
+          error: self.class.name,
+          message: message,
+          status: status,
+          request_id: request_id,
+          details: details
+        }.compact
+      end
+
+      STATUS_MAP = {
+        400 => "ValidationError",
+        401 => "AuthenticationError",
+        402 => "InsufficientCreditsError",
+        404 => "NotFoundError",
+        409 => "ConflictError",
+        422 => "ValidationError",
+        429 => "RateLimitError",
+        451 => "ValidationError",
+        455 => "ServiceUnavailableError",
+        500 => "ServerError",
+        501 => "ServerError",
+        502 => "ServerError",
+        503 => "ServiceUnavailableError",
+        504 => "ServerError",
+        505 => "ServerError",
+        531 => "ServerError"
+      }.freeze
+
+      DEFAULT_MESSAGES = {
+        400 => "Bad request",
+        401 => "Unauthorized",
+        402 => "Insufficient credits",
+        404 => "Not found",
+        408 => "Request timeout",
+        409 => "Conflict",
+        413 => "Payload too large",
+        415 => "Unsupported media type",
+        422 => "Validation failed",
+        429 => "Too many requests",
+        451 => "Failed to fetch image",
+        455 => "Service unavailable (maintenance)",
+        503 => "Service unavailable"
+      }.freeze
+
+      class << self
+        # Constructs appropriate error class from HTTP response.
+        # Maps status codes to specific error types and extracts error messages.
+        #
+        # @param response [Net::HTTPResponse] HTTP response object
+        # @param body [String, nil] Response body as string
+        # @return [Error] Specific error instance based on status code
+        def from_response(response, body = nil)
+          status = response.code.to_i
+          request_id = response["x-request-id"]
+
+          parsed_body = parse_body(body)
+          message = extract_message(parsed_body) ||
+            DEFAULT_MESSAGES[status] ||
+            "Request failed"
+
+          retry_after = parse_retry_after(response["retry-after"])
+
+          error_class_name = STATUS_MAP[status]
+          error_class = if error_class_name
+            Core.const_get(error_class_name)
+          else
+            Error
+          end
+
+          kwargs = {
+            status: status,
+            request_id: request_id,
+            details: parsed_body
+          }
+          kwargs[:retry_after] = retry_after if error_class == RateLimitError
+
+          error_class.new(message, **kwargs)
+        end
+
+        private
+
+        def parse_body(body)
+          return nil if body.to_s.empty?
+          return extract_html_error(body) if body.match?(/<!doctype|<html/i)
+
+          JSON.parse(body)
+        rescue JSON::ParserError
+          body
+        end
+
+        def extract_html_error(html)
+          title = html[%r{<title>(.*?)</title>}mi, 1]
+          h1 = html[%r{<h1>(.*?)</h1>}mi, 1]
+
+          error_text = title || h1 || "HTML Error Page"
+
+          error_text = error_text.gsub(/&[a-z]+;/i, " ")
+            .gsub(/<[^>]+>/, "")
+            .strip
+
+          {
+            "error" => error_text,
+            "is_html_error" => true,
+            "message" => "Server returned HTML error page: #{error_text}"
+          }
+        end
+
+        def extract_message(body)
+          return nil unless body.is_a?(Hash)
+
+          (body["error"].is_a?(Hash) ? body.dig("error", "message") : body["error"]) ||
+            body.dig("errors", 0) ||
+            body["message"] ||
+            body["detail"] ||
+            body["errorMessage"] ||
+            body["msg"]
+        end
+
+        def parse_retry_after(value)
+          return nil if value.nil?
+
+          numeric = Float(value, exception: false)
+          return numeric if numeric
+
+          begin
+            Time.httpdate(value) - Time.now.utc
+          rescue ArgumentError
+            nil
+          end
+        end
+      end
+    end
+
+    # Raised when API key is missing or invalid (HTTP 401).
+    class AuthenticationError < Error
+      def initialize(message = "Unauthorized", **kwargs)
+        super(message, status: 401, **kwargs)
+      end
+    end
+
+    # Raised when rate limit is exceeded (HTTP 429). Includes retry-after delay.
+    class RateLimitError < Error
+      # @return [Numeric, nil] Suggested retry delay in seconds from Retry-After header.
+      attr_reader :retry_after
+
+      def initialize(message = "Too many requests", retry_after: nil, **kwargs)
+        super(message, status: 429, **kwargs)
+        @retry_after = retry_after
+      end
+    end
+
+    # Raised when account has insufficient credits (HTTP 402).
+    class InsufficientCreditsError < Error
+      def initialize(message = "Insufficient credits", **kwargs)
+        super(message, status: 402, **kwargs)
+      end
+    end
+
+    # Raised when requested resource does not exist (HTTP 404).
+    class NotFoundError < Error
+      def initialize(message = "Not found", **kwargs)
+        super(message, status: 404, **kwargs)
+      end
+    end
+
+    # Raised when request validation fails (HTTP 400, 422).
+    class ValidationError < Error
+      def initialize(message = "Validation failed", **kwargs)
+        super
+      end
+    end
+
+    # Raised when service is temporarily unavailable (HTTP 503).
+    class ServiceUnavailableError < Error
+      def initialize(message = "Service unavailable", **kwargs)
+        super(message, status: kwargs.delete(:status) || 503, **kwargs)
+      end
+    end
+
+    # Raised when network connection fails or request cannot be sent.
+    class NetworkError < Error
+      def initialize(message = "Network error", **kwargs)
+        super
+      end
+    end
+
+    # Raised when HTTP request exceeds configured timeout.
+    class TimeoutError < Error
+      def initialize(message = "Request timed out", **kwargs)
+        super
+      end
+    end
+
+    # Raised when polling for task completion exceeds maximum wait time.
+    class TaskTimeoutError < Error
+      def initialize(message = "Task polling timed out", **kwargs)
+        super
+      end
+    end
+
+    # Raised when async task fails during processing.
+    class TaskFailedError < Error
+      def initialize(message = "Task failed", **kwargs)
+        super
+      end
+    end
+
+    # Raised when request conflicts with current resource state (HTTP 409).
+    class ConflictError < Error
+      def initialize(message = "Conflict", **kwargs)
+        super(message, status: 409, **kwargs)
+      end
+    end
+
+    # Raised when server encounters an internal error (HTTP 5xx).
+    class ServerError < Error
+      def initialize(message = "Server error", **kwargs)
+        super(message, status: kwargs.delete(:status) || 500, **kwargs)
+      end
+    end
+  end
+end

data/lib/runapi/core/http_client.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module RunApi
+  module Core
+    class HttpClient
+      STALE_CONNECTION_ERRORS = [ Errno::EPIPE, EOFError, IOError, OpenSSL::SSL::SSLError ].freeze
+
+      def initialize(options)
+        @options = options
+        @pool = ConnectionPool.new(size: 5, timeout: 5) do
+          build_connection
+        end
+      end
+
+      def request(method, path, body: nil, options: nil)
+        uri = URI.join(@options.base_url, path)
+        req = build_request(method, uri, body, options)
+        max_retries = options&.max_retries || @options.max_retries
+        retries = 0
+        stale_retried = false
+
+        loop do
+          response = begin
+            @pool.with do |http|
+              http.start unless http.started?
+              http.request(req)
+            end
+          rescue *STALE_CONNECTION_ERRORS
+            unless stale_retried
+              stale_retried = true
+              next
+            end
+            raise NetworkError, "Connection lost"
+          rescue ::Net::OpenTimeout, ::Net::ReadTimeout => e
+            raise TimeoutError, e.message
+          rescue ::SocketError, ::Errno::ECONNREFUSED, ::Errno::ECONNRESET => e
+            raise NetworkError, e.message
+          end
+
+          return parse_body(response.body) if response.is_a?(Net::HTTPSuccess)
+
+          error = Error.from_response(response, response.body)
+
+          if retryable?(method, response.code.to_i) && retries < max_retries
+            retries += 1
+            sleep(retry_delay(retries, error))
+            stale_retried = false
+            next
+          end
+
+          raise error
+        end
+      end
+
+      private
+
+      def build_connection
+        uri = URI.parse(@options.base_url)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = (uri.scheme == "https")
+        http.verify_mode = OpenSSL::SSL::VERIFY_PEER
+        http.open_timeout = @options.timeout
+        http.read_timeout = @options.timeout
+        http
+      end
+
+      def build_request(method, uri, body, options)
+        klass = Net::HTTP.const_get(method.to_s.capitalize)
+        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
+        req
+      end
+
+      def retryable?(method, status)
+        Constants::IDEMPOTENT_METHODS.include?(method.to_s.upcase) &&
+          Constants::RETRYABLE_STATUS_CODES.include?(status)
+      end
+
+      def retry_delay(attempt, error)
+        if error.is_a?(RateLimitError) && error.retry_after&.positive?
+          return error.retry_after
+        end
+
+        base = @options.retry_base_delay * (2**(attempt - 1))
+        jitter = rand * base * 0.5
+        [ base + jitter, @options.retry_max_delay ].min
+      end
+
+      def parse_body(body)
+        return nil if body.nil? || body.empty?
+
+        JSON.parse(body)
+      rescue JSON::ParserError
+        body
+      end
+    end
+  end
+end

data/lib/runapi/core/polling.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module RunApi
+  module Core
+    module Polling
+      ACTIVE_STATUSES = %w[pending processing].freeze
+
+      def self.poll_until_complete(options = PollingOptions.new)
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + options.max_wait
+
+        loop do
+          response = yield
+          status = value_for(response, "status").to_s.downcase
+
+          return response if status == "completed"
+
+          if status == "failed"
+            message = value_for(response, "error") || "Task failed"
+            raise TaskFailedError.new(message, details: details_for(response))
+          end
+
+          if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
+            raise TaskTimeoutError, "Task polling timed out after #{options.max_wait}s"
+          end
+
+          unless ACTIVE_STATUSES.include?(status)
+            raise TaskFailedError.new("Unknown task status: #{status}", details: details_for(response))
+          end
+
+          sleep(options.poll_interval)
+        end
+      end
+
+      def self.value_for(response, key)
+        case response
+        when Core::BaseModel
+          response[key]
+        when Hash
+          response[key] || response[key.to_sym]
+        end
+      end
+      private_class_method :value_for
+
+      def self.details_for(response)
+        response.is_a?(Core::BaseModel) ? response.to_h : response
+      end
+      private_class_method :details_for
+    end
+  end
+end

data/lib/runapi/core/resource_helpers.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module RunApi
+  module Core
+    module ResourceHelpers
+      private
+
+      # Performs an HTTP request and coerces JSON responses into typed model objects.
+      # Keeps existing request signatures so current stubs and custom transports keep working.
+      def request(method, path, body: :__runapi_no_body__, options: nil, response_class: default_response_class)
+        response = if body == :__runapi_no_body__
+          if options
+            @http.request(method, path, options: options)
+          else
+            @http.request(method, path)
+          end
+        else
+          kwargs = { body: body }
+          kwargs[:options] = options if options
+          @http.request(method, path, **kwargs)
+        end
+
+        Core::BaseModel.coerce(response, as: response_class)
+      end
+
+      def compact_params(params)
+        params.reject { |_, v| v.nil? || (v.is_a?(String) && v.strip.empty?) }
+      end
+
+      def param(params, key)
+        return params[key] if params.key?(key)
+        params[key.to_s] if params.key?(key.to_s)
+      end
+
+      def validate_optional!(params, key, allowed)
+        value = param(params, key)
+        return unless value
+
+        unless allowed.include?(value)
+          raise Core::ValidationError, "Invalid #{key}: #{value}. Must be one of: #{allowed.join(", ")}"
+        end
+      end
+
+      def default_response_class
+        if self.class.const_defined?(:RESPONSE_CLASS, false)
+          self.class::RESPONSE_CLASS
+        else
+          Core::TaskResponse
+        end
+      end
+
+      # Run polling and, once the task reports `completed`, re-coerce the payload
+      # into the resource's narrowed response class (when defined). This lets
+      # `run()` callers rely on result fields being present without a nil check.
+      def poll_until_complete(polling_opts = Core::PollingOptions.new, &block)
+        response = Core::Polling.poll_until_complete(polling_opts, &block)
+        return response unless self.class.const_defined?(:COMPLETED_RESPONSE_CLASS, false)
+
+        completed_class = self.class::COMPLETED_RESPONSE_CLASS
+        return response if response.is_a?(completed_class)
+
+        payload = response.is_a?(Core::BaseModel) ? response.to_h : response
+        completed_class.from_hash(payload)
+      end
+    end
+  end
+end

data/lib/runapi/core/types.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module RunApi
+  module Core
+    # HTTP methods supported by the SDK.
+    HTTP_METHODS = %i[get post put patch delete head options].freeze
+
+    # Task status values returned by async operations.
+    TASK_STATUSES = %w[pending processing completed failed].freeze
+
+    # Status values for async task results (excludes 'pending').
+    ASYNC_TASK_STATUSES = %w[processing completed failed].freeze
+
+    # Configuration options for API clients.
+    #
+    # @example
+    #   options = ClientOptions.new(
+    #     api_key: "your-api-key",
+    #     base_url: "https://runapi.ai",
+    #     timeout: 60,
+    #     max_retries: 3
+    #   )
+    #
+    # @!attribute [rw] api_key
+    #   @return [String] API key for authentication. Required.
+    # @!attribute [rw] base_url
+    #   @return [String] Base URL for API requests. Defaults to RunApi.base_url.
+    # @!attribute [rw] timeout
+    #   @return [Integer] Request timeout in seconds. Defaults to 900 (15 minutes).
+    # @!attribute [rw] max_retries
+    #   @return [Integer] Maximum number of retry attempts. Defaults to 2.
+    # @!attribute [rw] retry_base_delay
+    #   @return [Float] Base delay between retries in seconds. Defaults to 0.5.
+    # @!attribute [rw] retry_max_delay
+    #   @return [Float] Maximum delay between retries in seconds. Defaults to 5.0.
+    # @!attribute [rw] http_client
+    #   @return [Object, nil] Custom HTTP transport object. Must respond to
+    #     `#request(method, path, body:, options:)` with the same interface as {HttpClient}.
+    #     When set, the SDK skips building its own {HttpClient} and delegates all HTTP calls
+    #     to this object.
+    ClientOptions = Struct.new(
+      :api_key,
+      :base_url,
+      :timeout,
+      :max_retries,
+      :retry_base_delay,
+      :retry_max_delay,
+      :http_client,
+      keyword_init: true
+    ) do
+      def initialize(**kwargs)
+        super
+        self.base_url ||= RunApi.base_url
+        self.timeout ||= Constants::TIMEOUTS[:http_request]
+        self.max_retries ||= Constants::RETRY_CONFIG[:max_retries]
+        self.retry_base_delay ||= Constants::RETRY_CONFIG[:base_delay]
+        self.retry_max_delay ||= Constants::RETRY_CONFIG[:max_delay]
+      end
+    end
+
+    # Per-request options that override client-level defaults.
+    #
+    # @example
+    #   client.text_to_image.run(
+    #     { prompt: "A sunset" },
+    #     options: RequestOptions.new(timeout: 30, headers: { "X-Custom" => "value" })
+    #   )
+    #
+    # @!attribute [rw] headers
+    #   @return [Hash<String, String>, nil] Additional HTTP headers. Merged with client-level headers.
+    # @!attribute [rw] timeout
+    #   @return [Integer, nil] Request timeout in seconds. Overrides client-level timeout.
+    # @!attribute [rw] max_retries
+    #   @return [Integer, nil] Maximum retry attempts. Overrides client-level max_retries.
+    RequestOptions = Struct.new(
+      :headers,
+      :timeout,
+      :max_retries,
+      keyword_init: true
+    )
+
+    # Options for polling async task completion.
+    # Used internally by resource `run` methods.
+    #
+    # @!attribute [rw] poll_interval
+    #   @return [Integer] Polling interval in seconds. Defaults to 2.
+    # @!attribute [rw] max_wait
+    #   @return [Integer] Maximum wait time in seconds. Defaults to 900 (15 minutes).
+    PollingOptions = Struct.new(
+      :poll_interval,
+      :max_wait,
+      keyword_init: true
+    ) do
+      def initialize(**kwargs)
+        super
+        self.poll_interval ||= Constants::TIMEOUTS[:polling_interval]
+        self.max_wait ||= Constants::TIMEOUTS[:polling_max_wait]
+      end
+    end
+
+    # Typed response structure for async task operations.
+    # Additional API-specific fields are preserved and exposed via dot notation.
+    #
+    # @!attribute [r] id
+    #   @return [String, nil] Task ID for tracking and retrieval.
+    # @!attribute [r] status
+    #   @return [String, nil] Current task status.
+    # @!attribute [r] error
+    #   @return [String, nil] Error message if task failed.
+    # @!attribute [r] data
+    #   @return [RunApi::Core::DynamicModel, nil] Task-specific result data.
+    class TaskResponse < BaseModel
+      module Status
+        PENDING = "pending"
+        PROCESSING = "processing"
+        COMPLETED = "completed"
+        FAILED = "failed"
+
+        ALL = [ PENDING, PROCESSING, COMPLETED, FAILED ].freeze
+      end
+
+      optional :id, String
+      optional :status, String
+      optional :error, String
+      optional :data, -> { DynamicModel }
+    end
+  end
+end

data/lib/runapi/core/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module RunApi
+  module Core
+    VERSION = "0.1.0"
+  end
+
+  VERSION = Core::VERSION
+end

data/lib/runapi/core.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "openssl"
+require "uri"
+require "securerandom"
+require "connection_pool"
+
+require_relative "core/version"
+require_relative "core/constants"
+require_relative "core/configuration"
+require_relative "core/base_model"
+require_relative "core/types"
+require_relative "core/errors"
+require_relative "core/auth"
+require_relative "core/http_client"
+require_relative "core/polling"
+require_relative "core/resource_helpers"

data/lib/runapi-core.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require "runapi/core"

metadata

@@ -0,0 +1,71 @@
+--- !ruby/object:Gem::Specification
+name: runapi-core
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- RunAPI
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: connection_pool
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.4'
+description: RunAPI core SDK for JavaScript, Ruby, and Go
+email:
+- contact@runapi.ai
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- lib/runapi-core.rb
+- lib/runapi/core.rb
+- lib/runapi/core/auth.rb
+- lib/runapi/core/base_model.rb
+- lib/runapi/core/configuration.rb
+- lib/runapi/core/constants.rb
+- lib/runapi/core/errors.rb
+- lib/runapi/core/http_client.rb
+- lib/runapi/core/polling.rb
+- lib/runapi/core/resource_helpers.rb
+- lib/runapi/core/types.rb
+- lib/runapi/core/version.rb
+homepage: https://runapi.ai/docs#runapi-sdks
+licenses:
+- Apache-2.0
+metadata:
+  homepage_uri: https://runapi.ai/docs#runapi-sdks
+  documentation_uri: https://runapi.ai/docs#runapi-sdks
+  source_code_uri: https://github.com/runapi-ai/core-sdk
+  changelog_uri: https://github.com/runapi-ai/core-sdk/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.6
+specification_version: 4
+summary: Shared SDK primitives for RunAPI JavaScript, Ruby, and Go SDKs.
+test_files: []