runapi-core 0.2.4 → 0.2.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: df4b7518746af7dc568a3fbda315ef3b1f9e683fb1a7919431c2654cafb54f53
-  data.tar.gz: d2b57145c7d3d2855df5cd360e31a01614234a4d0ff9fde121ca7a1a7cd1ab7f
+  metadata.gz: b0f298f55ee5728667cb83a8db61391cd20bdc64582faec2207d5db9ce79c384
+  data.tar.gz: fe0c644ac7dd1377e0c4b0c0fb4b545afc0ff175ac83c3c3886b5219d93aed4a
 SHA512:
-  metadata.gz: 0e7b6a5a46d3170cdc14a3ee1046d1ca5efc3a5a068150e909a6130cd04ad28701e9904e161bd1f064c8637a911410e52d34f05dbbb14355644eac24f6d8836e
-  data.tar.gz: '0873f8ed32e8f8ac2aef057e784be881be9dc587abaa97eeb2773ab57309851dd97c59ed7005837e4794050a79fe301d4e98313d525e4945ff7375ea834cb18b'
+  metadata.gz: 5d473dc453e4dba6a452c54901ad2274453464de990d34c3c2c685a92d24cdb8fb9b07d6e57086913e560f034f11e5a5deea40f030bf1c1909a02724907ac4af
+  data.tar.gz: 47ef6424ffd81307922ef8adfc7c42286b6b3cd69527478b28f0674ac23332f212c10682564da8ad23bdd3b5dc0728ae7f0ce678f8814ae4f7e40736392ffdc8

data/README.md

@@ -0,0 +1,29 @@
+# RunAPI Core Ruby SDK
+
+The RunAPI Core Ruby SDK provides shared authentication, HTTP, retry, error, and polling primitives for RunAPI model gems. Install `runapi-core` only when you are building SDK infrastructure or shared Ruby tooling; application code should normally install a concrete model gem such as `runapi-suno`.
+
+## Install
+
+```bash
+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.
+
+## 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"})
+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/constants.rb

@@ -21,7 +21,7 @@ module RunApi
 
       IDEMPOTENT_METHODS = %w[GET HEAD PUT DELETE OPTIONS].freeze
 
-      RETRYABLE_STATUS_CODES = [ 429, 500, 502, 503, 504 ].freeze
+      RETRYABLE_STATUS_CODES = [429, 500, 502, 503, 504].freeze
     end
   end
 end

data/lib/runapi/core/errors.rb

@@ -39,15 +39,12 @@ module RunApi
         409 => "ConflictError",
         422 => "ValidationError",
         429 => "RateLimitError",
-        451 => "ValidationError",
-        455 => "ServiceUnavailableError",
         500 => "ServerError",
         501 => "ServerError",
         502 => "ServerError",
         503 => "ServiceUnavailableError",
         504 => "ServerError",
-        505 => "ServerError",
-        531 => "ServerError"
+        505 => "ServerError"
       }.freeze
 
       DEFAULT_MESSAGES = {
@@ -61,8 +58,6 @@ module RunApi
         415 => "Unsupported media type",
         422 => "Validation failed",
         429 => "Too many requests",
-        451 => "Failed to fetch image",
-        455 => "Service unavailable (maintenance)",
         503 => "Service unavailable"
       }.freeze
 

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

@@ -3,7 +3,7 @@
 module RunApi
   module Core
     class HttpClient
-      STALE_CONNECTION_ERRORS = [ Errno::EPIPE, EOFError, IOError, OpenSSL::SSL::SSLError ].freeze
+      STALE_CONNECTION_ERRORS = [Errno::EPIPE, EOFError, IOError, OpenSSL::SSL::SSLError].freeze
 
       def initialize(options)
         @options = options
@@ -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)
@@ -91,7 +122,7 @@ module RunApi
 
         base = @options.retry_base_delay * (2**(attempt - 1))
         jitter = rand * base * 0.5
-        [ base + jitter, @options.retry_max_delay ].min
+        [base + jitter, @options.retry_max_delay].min
       end
 
       def parse_body(body)

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

@@ -15,7 +15,7 @@ module RunApi
             @http.request(method, path)
           end
         else
-          kwargs = { body: body }
+          kwargs = {body: body}
           kwargs[:options] = options if options
           @http.request(method, path, **kwargs)
         end

data/lib/runapi/core/types.rb

@@ -107,8 +107,6 @@ module RunApi
     #   @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"
@@ -116,13 +114,12 @@ module RunApi
         COMPLETED = "completed"
         FAILED = "failed"
 
-        ALL = [ PENDING, PROCESSING, COMPLETED, FAILED ].freeze
+        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

@@ -2,7 +2,7 @@
 
 module RunApi
   module Core
-    VERSION = "0.2.4"
+    VERSION = "0.2.6"
   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.4
+  version: 0.2.6
 platform: ruby
 authors:
 - RunAPI
@@ -23,22 +23,31 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.4'
-description: RunAPI core SDK for JavaScript, Ruby, and Go
+description: The RunAPI Core Ruby SDK provides shared authentication, HTTP, retry,
+  error, and polling primitives for RunAPI model gems. Install `runapi-core` only
+  when you are building SDK infrastructure or shared Ruby tooling; application code
+  should normally install a concrete model gem such as `runapi-suno`.
 email:
 - contact@runapi.ai
 executables: []
 extensions: []
-extra_rdoc_files: []
+extra_rdoc_files:
+- README.md
 files:
 - LICENSE
+- 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
@@ -48,7 +57,7 @@ licenses:
 - Apache-2.0
 metadata:
   homepage_uri: https://runapi.ai/models
-  documentation_uri: https://github.com/runapi-ai/core-sdk/blob/main/README.md
+  documentation_uri: https://github.com/runapi-ai/core-sdk/blob/main/ruby/README.md
   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: []
@@ -67,5 +76,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.10
 specification_version: 4
-summary: Shared SDK primitives for RunAPI JavaScript, Ruby, and Go SDKs.
+summary: RunAPI Core Ruby SDK
 test_files: []