runapi-core 0.3.5 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 01303e8c4435de080fde0aa485b59ee5bca4ce29e532796b8d7d1540368f4b26
-  data.tar.gz: 39a789fb54bfa15a94475ac47ab50e6c815ac8561ab688acffccd2c92f3fbbc5
+  metadata.gz: ba473ca16c3bf3642549224cc1e8e2ace81c302f91a767afc10b06b93cde95ce
+  data.tar.gz: a01ba0a52c124fd881b45705ce8a7580e9b429ca776842693bc1ad262cf85804
 SHA512:
-  metadata.gz: 45a68064b4442e093ae896a7d65f1b0c8b30ce6d8d438b9ce7a90d62959134de1b62f25a19efbc6466b069cdd98515170fba2ed7742b2db0f17ea0f09821a784
-  data.tar.gz: 46d4313b136bd5f11a25bec4364b1f2c80f8ca7439668f7dc272514cb7807b7d52218e356218538fd3ec0666e6ea94961c259e190699712da95b44476b013f64
+  metadata.gz: 908a114d22a7113898f4ec49595c40b2f414c02c4c528dba774b3262a871a429627d2337b6516a1923ae25662b38ee3f1352a9b30b31900d0d91e4ab5ad1863c
+  data.tar.gz: 36a9539bb562174708f6d94354b2e4f2c4fe742773665d8603b8c77ff6ed6019e9c1c848ba0decf970e6cd96bec50def79d398057dc748a4bd8bc7ee97511d60

data/README.md

@@ -1,6 +1,6 @@
 # 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`.
+The RunAPI Core Ruby SDK provides shared authentication, HTTP, retry, error, Files, Uploads, 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
 
@@ -67,7 +67,7 @@ runapi_task_id = response.runapi_task_id
 runapi_task_id = response.response_headers["X-RunAPI-Task-Id"]
 ```
 
-## File Upload
+## Temporary File Upload
 
 ```ruby
 client = RunApi::NanoBanana::Client.new(api_key: ENV["RUNAPI_API_KEY"])
@@ -79,6 +79,25 @@ 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.
 
+## Persistent Files And Multipart Uploads
+
+The existing `files.create` method above keeps its temporary URL behavior. Use `create_file` for a persistent File object and `uploads` when sending one or more Parts:
+
+```ruby
+file = client.files.create_file(file: "./knowledge.pdf")
+content = client.files.content(file.id)
+
+upload = client.uploads.create(
+  bytes: 1_048_576,
+  filename: "archive.bin",
+  mime_type: "application/octet-stream"
+)
+part = client.uploads.add_part(upload.id, data: "./archive.part-01")
+completed = client.uploads.complete(upload.id, part_ids: [part.id])
+```
+
+Use `files.list`, `retrieve`, and `delete_file` for the remaining File lifecycle. See https://runapi.ai/docs/resources/files for limits and REST examples.
+
 ## License
 
 Licensed under the Apache License, Version 2.0.

data/lib/runapi/core/client.rb

@@ -3,18 +3,20 @@
 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, pricing) that
+    # HTTP client, and exposes the Universal Resources (Files, Uploads, account, pricing) 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.
+      # @return [Files] Persistent File lifecycle and temporary URL upload operations.
       attr_reader :files
       # @return [Account] Account info and balance operations.
       attr_reader :account
       # @return [Pricing] Live Price Schedule lookup and Price Quote operations.
       attr_reader :pricing
+      # @return [Uploads] Multipart Upload lifecycle operations.
+      attr_reader :uploads
 
       def initialize(api_key: nil, **options)
         @api_key = Core::Auth.resolve_api_key(api_key)
@@ -24,6 +26,7 @@ module RunApi
         @files = Files.new(@http)
         @account = Account.new(@http)
         @pricing = Pricing.new(@http)
+        @uploads = Uploads.new(@http)
       end
 
       # Closes the SDK-created HTTP client. Injected clients remain caller-owned.

data/lib/runapi/core/files.rb

@@ -10,6 +10,7 @@ module RunApi
       ENDPOINT = "/api/v1/files"
       PREPARE_ENDPOINT = "#{ENDPOINT}/prepare"
       CONFIRM_ENDPOINT = "#{ENDPOINT}/confirm"
+      PROTOCOL_ENDPOINT = "/v1/files"
 
       class UploadResponse < RunApi::Core::BaseModel
         required :file_name, String
@@ -20,6 +21,30 @@ module RunApi
         required :expires_at, String
       end
 
+      class FileObject < RunApi::Core::BaseModel
+        required :id, String
+        required :object, String
+        required :bytes, Integer
+        required :created_at, Integer
+        optional :expires_at, Integer
+        required :filename, String
+        required :purpose, String
+      end
+
+      class FileList < RunApi::Core::BaseModel
+        required :object, String
+        required :data, [FileObject]
+        optional :first_id, String
+        optional :last_id, String
+        required :has_more
+      end
+
+      class DeletedFile < RunApi::Core::BaseModel
+        required :id, String
+        required :object, String
+        required :deleted
+      end
+
       RESPONSE_CLASS = UploadResponse
 
       def initialize(http)
@@ -34,6 +59,33 @@ module RunApi
         request(:post, ENDPOINT, body: compact_params(source:, file_name:), options:)
       end
 
+      def create_file(file:, purpose: "user_data", file_name: nil, options: nil)
+        path = file_path(file)
+        body = MultipartBody.new(
+          fields: {purpose:},
+          files: {file: MultipartFile.new(path:, filename: file_name || File.basename(path))}
+        )
+        request(:post, PROTOCOL_ENDPOINT, body:, options:, response_class: FileObject)
+      end
+
+      def list(after_id: nil, limit: nil, order: nil, purpose: nil, options: nil)
+        query = URI.encode_www_form(compact_params(after: after_id, limit:, order:, purpose:))
+        path = query.empty? ? PROTOCOL_ENDPOINT : "#{PROTOCOL_ENDPOINT}?#{query}"
+        request(:get, path, options:, response_class: FileList)
+      end
+
+      def retrieve(file_id, options: nil)
+        request(:get, protocol_file_path(file_id), options:, response_class: FileObject)
+      end
+
+      def content(file_id, options: nil)
+        @http.request(:get, "#{protocol_file_path(file_id)}/content", options:, raw: true)
+      end
+
+      def delete_file(file_id, options: nil)
+        request(:delete, protocol_file_path(file_id), options:, response_class: DeletedFile)
+      end
+
       private
 
       def validate_source!(file:, source:)
@@ -71,6 +123,12 @@ module RunApi
 
         raise ArgumentError, "file must be a file path or respond to :path"
       end
+
+      def protocol_file_path(file_id)
+        raise ArgumentError, "file_id is required" if file_id.to_s.strip.empty?
+
+        "#{PROTOCOL_ENDPOINT}/#{URI.encode_www_form_component(file_id)}"
+      end
     end
   end
 end

data/lib/runapi/core/http_client.rb

@@ -12,7 +12,7 @@ module RunApi
         end
       end
 
-      def request(method, path, body: nil, options: nil)
+      def request(method, path, body: nil, options: nil, raw: false)
         uri = URI.join(@options.base_url, path)
         req = build_request(method, uri, body, options)
         max_retries = options&.max_retries || @options.max_retries
@@ -42,6 +42,8 @@ module RunApi
           end
 
           if response.is_a?(Net::HTTPSuccess)
+            return response.body if raw
+
             body = parse_body(response.body)
             return nil if body.nil?
             return body unless body.is_a?(Hash) || body.is_a?(Array)

data/lib/runapi/core/uploads.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module RunApi
+  module Core
+    class Uploads
+      include RunApi::Core::ResourceHelpers
+
+      ENDPOINT = "/v1/uploads"
+
+      class UploadObject < RunApi::Core::BaseModel
+        required :id, String
+        required :object, String
+        required :bytes, Integer
+        required :created_at, Integer
+        required :filename, String
+        required :purpose, String
+        required :status, String
+        required :expires_at, Integer
+        optional :file, -> { Files::FileObject }
+      end
+
+      class UploadPart < RunApi::Core::BaseModel
+        required :id, String
+        required :object, String
+        required :created_at, Integer
+        required :upload_id, String
+      end
+
+      RESPONSE_CLASS = UploadObject
+
+      def initialize(http)
+        @http = http
+      end
+
+      def create(bytes:, filename:, mime_type:, purpose: "user_data", options: nil)
+        request(:post, ENDPOINT, body: {bytes:, filename:, mime_type:, purpose:}, options:)
+      end
+
+      def add_part(upload_id, data:, file_name: nil, options: nil)
+        path = file_path(data)
+        body = MultipartBody.new(
+          files: {data: MultipartFile.new(path:, filename: file_name || File.basename(path))}
+        )
+        request(:post, "#{upload_path(upload_id)}/parts", body:, options:, response_class: UploadPart)
+      end
+
+      def complete(upload_id, part_ids:, options: nil)
+        request(:post, "#{upload_path(upload_id)}/complete", body: {part_ids:}, options:)
+      end
+
+      def cancel(upload_id, options: nil)
+        request(:post, "#{upload_path(upload_id)}/cancel", body: {}, options:)
+      end
+
+      private
+
+      def file_path(file)
+        return file if file.is_a?(String)
+        return file.path if file.respond_to?(:path)
+
+        raise ArgumentError, "data must be a file path or respond to :path"
+      end
+
+      def upload_path(upload_id)
+        raise ArgumentError, "upload_id is required" if upload_id.to_s.strip.empty?
+
+        "#{ENDPOINT}/#{URI.encode_www_form_component(upload_id)}"
+      end
+    end
+  end
+end

data/lib/runapi/core/version.rb

@@ -2,7 +2,7 @@
 
 module RunApi
   module Core
-    VERSION = "0.3.5"
+    VERSION = "0.4.1"
   end
 
   VERSION = Core::VERSION

data/lib/runapi/core.rb

@@ -20,6 +20,7 @@ require_relative "core/http_client"
 require_relative "core/polling"
 require_relative "core/resource_helpers"
 require_relative "core/files"
+require_relative "core/uploads"
 require_relative "core/account"
 require_relative "core/pricing"
 require_relative "core/client"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: runapi-core
 version: !ruby/object:Gem::Version
-  version: 0.3.5
+  version: 0.4.1
 platform: ruby
 authors:
 - RunAPI
@@ -30,9 +30,9 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '4'
 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`.
+  error, Files, Uploads, 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: []
@@ -59,6 +59,7 @@ files:
 - lib/runapi/core/resource_helpers.rb
 - lib/runapi/core/response.rb
 - lib/runapi/core/types.rb
+- lib/runapi/core/uploads.rb
 - lib/runapi/core/version.rb
 homepage: https://runapi.ai/models
 licenses: