cogbox 0.190.1

data/lib/cogbox/code_interpreter.rb

@@ -0,0 +1,360 @@
+# Copyright Daytona Platforms Inc.
+# Copyright Cognifyi
+# SPDX-License-Identifier: Apache-2.0
+
+# frozen_string_literal: true
+
+require 'json'
+require 'websocket-client-simple'
+require 'timeout'
+
+module Cogbox
+  # Handles code interpretation and execution within a Sandbox. Currently supports only Python.
+  #
+  # This class provides methods to execute code in isolated interpreter contexts,
+  # manage contexts, and stream execution output via callbacks. If subsequent code executions
+  # are performed in the same context, the variables, imports, and functions defined in
+  # the previous execution will be available.
+  #
+  # For other languages, use the `code_run` method from the `Process` interface,
+  # or execute the appropriate command directly in the sandbox terminal.
+  class CodeInterpreter
+    include Instrumentation
+
+    WEBSOCKET_TIMEOUT_CODE = 4008
+    WS_PORT = 2280
+    private_constant :WS_PORT
+
+    # @param sandbox_id [String]
+    # @param toolbox_api [CogboxToolboxApiClient::InterpreterApi]
+    # @param get_preview_link [Proc]
+    # @param otel_state [Cogbox::OtelState, nil]
+    def initialize(sandbox_id:, toolbox_api:, get_preview_link:, otel_state: nil)
+      @sandbox_id = sandbox_id
+      @toolbox_api = toolbox_api
+      @get_preview_link = get_preview_link
+      @otel_state = otel_state
+    end
+
+    # Execute Python code in the sandbox.
+    #
+    # By default, code runs in the default shared context which persists variables,
+    # imports, and functions across executions. To run in an isolated context,
+    # create a new context with `create_context` and pass it as the `context` argument.
+    #
+    # @param code [String] Code to execute
+    # @param context [CogboxToolboxApiClient::InterpreterContext, nil] Context to run code in
+    # @param on_stdout [Proc, nil] Callback for stdout messages (receives OutputMessage)
+    # @param on_stderr [Proc, nil] Callback for stderr messages (receives OutputMessage)
+    # @param on_error [Proc, nil] Callback for execution errors (receives ExecutionError)
+    # @param envs [Hash<String, String>, nil] Environment variables for this execution
+    # @param timeout [Integer, nil] Timeout in seconds. 0 means no timeout. Default is 10 minutes.
+    # @return [Cogbox::ExecutionResult]
+    # @raise [Cogbox::Sdk::Error]
+    #
+    # @example
+    #   def handle_stdout(msg)
+    #     print "STDOUT: #{msg.output}"
+    #   end
+    #
+    #   def handle_stderr(msg)
+    #     print "STDERR: #{msg.output}"
+    #   end
+    #
+    #   def handle_error(err)
+    #     puts "ERROR: #{err.name}: #{err.value}"
+    #   end
+    #
+    #   code = <<~PYTHON
+    #     import sys
+    #     import time
+    #     for i in range(5):
+    #         print(i)
+    #         time.sleep(1)
+    #     sys.stderr.write("Counting done!")
+    #   PYTHON
+    #
+    #   result = sandbox.code_interpreter.run_code(
+    #     code,
+    #     on_stdout: method(:handle_stdout),
+    #     on_stderr: method(:handle_stderr),
+    #     on_error: method(:handle_error),
+    #     timeout: 10
+    #   )
+    def run_code(code, context: nil, on_stdout: nil, on_stderr: nil, on_error: nil, envs: nil, timeout: nil) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength, Metrics/ParameterLists
+      # Get WebSocket URL via preview link
+      preview_link = @get_preview_link.call(WS_PORT)
+      url = URI.parse(preview_link.url)
+      url.scheme = url.scheme == 'https' ? 'wss' : 'ws'
+      url.path = '/process/interpreter/execute'
+      ws_url = url.to_s
+
+      result = ExecutionResult.new
+
+      # Create request payload
+      request = { code: }
+      request[:contextId] = context.id if context
+      request[:envs] = envs if envs
+      request[:timeout] = timeout if timeout
+
+      # Build headers with preview token
+      headers = @toolbox_api.api_client.default_headers.dup.merge(
+        'X-Cogbox-Preview-Token' => preview_link.token,
+        'Content-Type' => 'application/json',
+        'Accept' => 'application/json'
+      )
+
+      completion_queue = Queue.new
+      interpreter = self
+
+      puts "[DEBUG] Connecting to WebSocket: #{ws_url}" if ENV['DEBUG']
+
+      ws = WebSocket::Client::Simple.connect(ws_url, headers:) do |client|
+        client.on :open do
+          puts '[DEBUG] WebSocket opened, sending request' if ENV['DEBUG']
+          client.send(JSON.dump(request))
+        end
+
+        client.on :message do |msg|
+          puts "[DEBUG] Received message (length=#{msg.data.length}): #{msg.data.inspect[0..200]}" if ENV['DEBUG']
+
+          interpreter.send(:handle_message, msg.data, result, on_stdout, on_stderr, on_error, completion_queue)
+        end
+
+        client.on :error do |e|
+          puts "[DEBUG] WebSocket error: #{e.message}" if ENV['DEBUG']
+          completion_queue.push({ type: :error, error: e })
+        end
+
+        client.on :close do |e|
+          if ENV['DEBUG']
+            code = e&.code || 'nil'
+            reason = e&.reason || 'nil'
+            puts "[DEBUG] WebSocket closed: code=#{code}, reason=#{reason}"
+          end
+          error_info = interpreter.send(:handle_close, e)
+          if error_info
+            completion_queue.push({ type: :error_from_close, error: error_info })
+          else
+            completion_queue.push({ type: :close })
+          end
+        end
+      end
+
+      no_timeout = timeout.is_a?(Numeric) && timeout <= 0
+      max_wait = no_timeout ? nil : (timeout || 600) + 30
+      start_time = Time.now
+      completion_reason = nil
+
+      loop do
+        if max_wait
+          remaining = max_wait - (Time.now - start_time)
+          if remaining <= 0
+            ws.close
+            raise Sdk::TimeoutError,
+                  'Execution timed out: operation exceeded the configured `timeout`. Provide a larger value if needed.'
+          end
+        end
+
+        completion = completion_queue.pop(timeout: max_wait ? remaining : nil)
+
+        if completion.nil?
+          ws.close
+          raise Sdk::TimeoutError,
+                'Execution timed out: operation exceeded the configured `timeout`. Provide a larger value if needed.'
+        end
+
+        puts "[DEBUG] Got completion signal: #{completion[:type]}" if ENV['DEBUG']
+
+        if completion[:type] == :completed
+          completion_reason = :completed
+          break
+        elsif completion[:type] == :error_from_close
+          error_msg = completion[:error]
+          if error_msg.include?('timed out') || error_msg.include?('Execution timed out')
+            raise Sdk::TimeoutError, error_msg
+          end
+
+          raise Sdk::Error, error_msg
+        elsif completion[:type] == :close
+          elapsed = Time.now - start_time
+          if timeout && timeout > 0 && elapsed >= timeout && elapsed < (timeout + 2)
+            raise Sdk::TimeoutError,
+                  'Execution timed out: operation exceeded the configured `timeout`. Provide a larger value if needed.'
+          end
+          completion_reason = :close
+          break
+        elsif completion[:type] == :error
+          unless completion[:error].message.include?('stream closed')
+            raise Sdk::Error, "WebSocket error: #{completion[:error].message}"
+          end
+
+          completion_reason = :close
+          break
+        end
+      end
+
+      ws.close if completion_reason != :close
+      sleep 0.05
+
+      result
+    rescue Sdk::Error
+      # Re-raise SDK errors as-is
+      raise
+    rescue StandardError => e
+      # Wrap unexpected errors
+      raise Sdk::Error, "Failed to run code: #{e.message}"
+    end
+
+    # Create a new isolated interpreter context.
+    #
+    # Contexts provide isolated execution environments with their own global namespace.
+    # Variables, imports, and functions defined in one context don't affect others.
+    #
+    # @param cwd [String, nil] Working directory for the context
+    # @return [CogboxToolboxApiClient::InterpreterContext]
+    # @raise [Cogbox::Sdk::Error]
+    #
+    # @example
+    #   # Create isolated context
+    #   ctx = sandbox.code_interpreter.create_context
+    #
+    #   # Execute code in this context
+    #   sandbox.code_interpreter.run_code("x = 100", context: ctx)
+    #
+    #   # Variable only exists in this context
+    #   result = sandbox.code_interpreter.run_code("print(x)", context: ctx)  # OK
+    #
+    #   # Won't see the variable in default context
+    #   result = sandbox.code_interpreter.run_code("print(x)")  # NameError
+    #
+    #   # Clean up
+    #   sandbox.code_interpreter.delete_context(ctx)
+    def create_context(cwd: nil)
+      request = CogboxToolboxApiClient::CreateContextRequest.new(cwd:)
+      @toolbox_api.create_interpreter_context(request)
+    rescue StandardError => e
+      raise Sdk::Error, "Failed to create interpreter context: #{e.message}"
+    end
+
+    # List all user-created interpreter contexts.
+    #
+    # The default context is not included in this list. Only contexts created
+    # via `create_context` are returned.
+    #
+    # @return [Array<CogboxToolboxApiClient::InterpreterContext>]
+    # @raise [Cogbox::Sdk::Error]
+    #
+    # @example
+    #   contexts = sandbox.code_interpreter.list_contexts
+    #   contexts.each do |ctx|
+    #     puts "Context #{ctx.id}: #{ctx.language} at #{ctx.cwd}"
+    #   end
+    def list_contexts
+      response = @toolbox_api.list_interpreter_contexts
+      response.contexts || []
+    rescue StandardError => e
+      raise Sdk::Error, "Failed to list interpreter contexts: #{e.message}"
+    end
+
+    # Delete an interpreter context and shut down all associated processes.
+    #
+    # This permanently removes the context and all its state (variables, imports, etc.).
+    # The default context cannot be deleted.
+    #
+    # @param context [CogboxToolboxApiClient::InterpreterContext]
+    # @return [void]
+    # @raise [Cogbox::Sdk::Error]
+    #
+    # @example
+    #   ctx = sandbox.code_interpreter.create_context
+    #   # ... use context ...
+    #   sandbox.code_interpreter.delete_context(ctx)
+    def delete_context(context)
+      @toolbox_api.delete_interpreter_context(context.id)
+      nil
+    rescue StandardError => e
+      raise Sdk::Error, "Failed to delete interpreter context: #{e.message}"
+    end
+
+    instrument :run_code, :create_context, :list_contexts, :delete_context,
+               component: 'CodeInterpreter'
+
+    private
+
+    # @return [Cogbox::OtelState, nil]
+    attr_reader :otel_state
+
+    # @return [Hash<String, String>]
+    def build_headers
+      headers = {}
+      @toolbox_api.api_client.update_params_for_auth!(headers, nil, ['bearer'])
+      headers
+    end
+
+    # @param data [String]
+    # @param result [Cogbox::ExecutionResult]
+    # @param on_stdout [Proc, nil]
+    # @param on_stderr [Proc, nil]
+    # @param on_error [Proc, nil]
+    # @param completion_queue [Queue, nil] Queue to signal completion
+    # @return [void]
+    def handle_message(data, result, on_stdout, on_stderr, on_error, completion_queue = nil) # rubocop:disable Metrics/AbcSize, Metrics/ParameterLists
+      # Empty messages are just keepalives or noise, ignore them
+      if data.nil? || data.empty?
+        puts '[DEBUG] Received empty message, ignoring' if ENV['DEBUG']
+        return
+      end
+
+      chunk = JSON.parse(data)
+      chunk_type = chunk['type']
+
+      case chunk_type
+      when 'stdout'
+        stdout = chunk['text'] || ''
+        result.stdout += stdout
+        on_stdout&.call(OutputMessage.new(output: stdout))
+      when 'stderr'
+        stderr = chunk['text'] || ''
+        result.stderr += stderr
+        on_stderr&.call(OutputMessage.new(output: stderr))
+      when 'error'
+        error = ExecutionError.new(
+          name: chunk['name'] || '',
+          value: chunk['value'] || '',
+          traceback: chunk['traceback'] || ''
+        )
+        result.error = error
+        on_error&.call(error)
+      when 'control'
+        control_text = chunk['text'] || ''
+        if %w[completed interrupted].include?(control_text)
+          puts "[DEBUG] Received control message: #{control_text}" if ENV['DEBUG']
+          completion_queue&.push({ type: :completed })
+        end
+      end
+    rescue JSON::ParserError => e
+      # Skip malformed messages
+      warn "Warning: Failed to parse message: #{e.message}" if ENV['DEBUG']
+    end
+
+    # @param event [Object]
+    # @return [void]
+    def handle_close(event)
+      return nil unless event # Skip if event is nil (manual close)
+
+      code = event.respond_to?(:code) ? event.code : nil
+      reason = event.respond_to?(:reason) ? event.reason : nil
+
+      if code == WEBSOCKET_TIMEOUT_CODE
+        return 'Execution timed out: operation exceeded the configured `timeout`. Provide a larger value if needed.'
+      end
+
+      return nil if code == 1000 || code.nil? # Normal closure or no code
+
+      detail = reason.to_s.empty? ? 'WebSocket connection closed unexpectedly' : reason.to_s
+      detail = "#{detail} (close code #{code})" if code
+      detail
+    end
+  end
+end

data/lib/cogbox/cogbox.rb

@@ -0,0 +1,337 @@
+# Copyright Daytona Platforms Inc.
+# Copyright Cognifyi
+# SPDX-License-Identifier: Apache-2.0
+
+# frozen_string_literal: true
+
+require 'json'
+require 'uri'
+
+module Cogbox
+  class Cogbox
+    include Instrumentation
+
+    # @return [Cogbox::Config]
+    attr_reader :config
+
+    # @return [CogboxApiClient]
+    attr_reader :api_client
+
+    # @return [CogboxApiClient::SandboxApi]
+    attr_reader :sandbox_api
+
+    # @return [Cogbox::VolumeService]
+    attr_reader :volume
+
+    # @return [CogboxApiClient::ObjectStorageApi]
+    attr_reader :object_storage_api
+
+    # @return [CogboxApiClient::SnapshotsApi]
+    attr_reader :snapshots_api
+
+    # @return [Cogbox::SnapshotService]
+    attr_reader :snapshot
+
+    # @param config [Cogbox::Config] Configuration options. Defaults to Cogbox::Config.new
+    def initialize(config = Config.new)
+      @config = config
+      ensure_access_token_defined
+
+      otel_enabled = config.otel_enabled ||
+                     config._experimental&.dig('otel_enabled') ||
+                     config.read_env('COGBOX_OTEL_ENABLED') == 'true' ||
+                     config.read_env('COGBOX_EXPERIMENTAL_OTEL_ENABLED') == 'true'
+      @otel_state = (::Cogbox.init_otel(Sdk::VERSION) if otel_enabled)
+
+      @api_client = build_api_client
+      @sandbox_api = CogboxApiClient::SandboxApi.new(api_client)
+      @config_api = CogboxApiClient::ConfigApi.new(api_client)
+      @volume = VolumeService.new(CogboxApiClient::VolumesApi.new(api_client), otel_state:)
+      @object_storage_api = CogboxApiClient::ObjectStorageApi.new(api_client)
+      @snapshots_api = CogboxApiClient::SnapshotsApi.new(api_client)
+      @snapshot = SnapshotService.new(snapshots_api:, object_storage_api:, default_region_id: config.target,
+                                      otel_state:)
+    end
+
+    # Shuts down OTel providers, flushing any pending telemetry data.
+    #
+    # @return [void]
+    def close
+      ::Cogbox.shutdown_otel(@otel_state)
+      @otel_state = nil
+    end
+
+    # Creates a sandbox with the specified parameters
+    #
+    # @param params [Cogbox::CreateSandboxFromSnapshotParams, Cogbox::CreateSandboxFromImageParams, Nil] Sandbox creation parameters
+    # @return [Cogbox::Sandbox] The created sandbox
+    # @raise [Cogbox::Sdk::Error] If auto_stop_interval or auto_archive_interval is negative
+    def create(params = nil, on_snapshot_create_logs: nil)
+      if params.nil?
+        params = CreateSandboxFromSnapshotParams.new(language: CodeLanguage::PYTHON)
+      elsif params.language.nil?
+        params.language = CodeLanguage::PYTHON
+      end
+
+      unless CodeLanguage::ALL.include?(params.language.to_s.to_sym)
+        raise ArgumentError,
+              "Invalid #{CODE_TOOLBOX_LANGUAGE_LABEL}: #{params.language}. Supported languages: #{CodeLanguage::ALL.join(', ')}"
+      end
+
+      _create(params, on_snapshot_create_logs:)
+    end
+
+    # Deletes a Sandbox.
+    #
+    # @param sandbox [Cogbox::Sandbox]
+    # @return [void]
+    def delete(sandbox) = sandbox.delete
+
+    # Gets a Sandbox by its ID.
+    #
+    # @param id [String]
+    # @return [Cogbox::Sandbox]
+    def get(id)
+      sandbox_dto = sandbox_api.get_sandbox(id)
+      to_sandbox(sandbox_dto:)
+    end
+
+    # Iterates over Sandboxes matching the given query.
+    #
+    # @param query [Cogbox::ListSandboxesQuery, nil] Optional filters, sorting, and per-page size.
+    # @return [Enumerator<Cogbox::Sandbox>]
+    # @raise [Cogbox::Sdk::Error]
+    #
+    # @example
+    #   cogbox.list(Cogbox::ListSandboxesQuery.new(labels: { 'env' => 'dev' })).each do |sandbox|
+    #     puts sandbox.id
+    #   end
+    def list(query = nil)
+      q = query || ListSandboxesQuery.new
+
+      Enumerator.new do |yielder|
+        cursor = nil
+        first_page = true
+        while first_page || cursor
+          first_page = false
+          response = fetch_sandbox_page(q, cursor)
+          response.items.each do |sandbox_dto|
+            yielder << to_sandbox(sandbox_dto: sandbox_dto)
+          end
+          cursor = response.next_cursor
+          break if cursor.nil? || (cursor.respond_to?(:empty?) && cursor.empty?)
+        end
+      end
+    end
+
+    # Starts a Sandbox and waits for it to be ready.
+    #
+    # @param sandbox [Cogbox::Sandbox]
+    # @param timeout [Numeric] Maximum wait time in seconds (defaults to 60 s).
+    # @return [void]
+    def start(sandbox, timeout = Sandbox::DEFAULT_TIMEOUT) = sandbox.start(timeout)
+
+    # Stops a Sandbox and waits for it to be stopped.
+    #
+    # @param sandbox [Cogbox::Sandbox]
+    # @param timeout [Numeric] Maximum wait time in seconds (defaults to 60 s).
+    # @return [void]
+    def stop(sandbox, timeout = Sandbox::DEFAULT_TIMEOUT) = sandbox.stop(timeout)
+
+    instrument :create, :delete, :get, :start, :stop, component: 'Cogbox'
+
+    private
+
+    # @return [Cogbox::OtelState, nil]
+    attr_reader :otel_state
+
+    # Fetches a single page of sandboxes. Each call produces one OTel span
+    # ("Cogbox.list_fetch_page") so that paginated iteration emits N spans
+    # for N pages.
+    #
+    # @param q [Cogbox::ListSandboxesQuery]
+    # @param cursor [String, nil]
+    # @return [CogboxApiClient::ListSandboxesResponse]
+    def fetch_sandbox_page(q, cursor)
+      opts = {
+        cursor: cursor,
+        limit: q.limit,
+        id: q.id,
+        name: q.name,
+        labels: q.labels ? JSON.dump(q.labels) : nil,
+        states: q.states,
+        snapshots: q.snapshots,
+        region_ids: q.targets,
+        min_cpu: q.min_cpu,
+        max_cpu: q.max_cpu,
+        min_memory_gi_b: q.min_memory_gib,
+        max_memory_gi_b: q.max_memory_gib,
+        min_disk_gi_b: q.min_disk_gib,
+        max_disk_gi_b: q.max_disk_gib,
+        is_public: q.is_public,
+        is_recoverable: q.is_recoverable,
+        created_at_after: q.created_at_after,
+        created_at_before: q.created_at_before,
+        last_event_after: q.last_activity_after,
+        last_event_before: q.last_activity_before,
+        sort: q.sort,
+        order: q.order
+      }.compact
+
+      sandbox_api.list_sandboxes(opts)
+    end
+
+    instrument :fetch_sandbox_page, component: 'Cogbox.list'
+
+    # Creates a sandbox with the specified parameters
+    #
+    # @param params [Cogbox::CreateSandboxFromSnapshotParams, Cogbox::CreateSandboxFromImageParams] Sandbox creation parameters
+    # @param timeout [Numeric] Maximum wait time in seconds (defaults to 60 s).
+    # @param on_snapshot_create_logs [Proc]
+    # @return [Cogbox::Sandbox] The created sandbox
+    # @raise [Cogbox::Sdk::Error] If auto_stop_interval or auto_archive_interval is negative
+    def _create(params, timeout: 60, on_snapshot_create_logs: nil)
+      raise Sdk::Error, 'Timeout must be a non-negative number' if timeout.negative?
+
+      start_time = Time.now
+
+      raise Sdk::Error, 'auto_stop_interval must be a non-negative integer' if params.auto_stop_interval&.negative?
+
+      if params.auto_archive_interval&.negative?
+        raise Sdk::Error, 'auto_archive_interval must be a non-negative integer'
+      end
+
+      labels = params.labels&.dup || {}
+      labels[CODE_TOOLBOX_LANGUAGE_LABEL] = params.language.to_s if params.language
+
+      create_sandbox = CogboxApiClient::CreateSandbox.new(
+        user: params.os_user,
+        env: params.env_vars || {},
+        labels: labels,
+        public: params.public,
+        target: config.target,
+        auto_stop_interval: params.auto_stop_interval,
+        auto_archive_interval: params.auto_archive_interval,
+        auto_delete_interval: params.auto_delete_interval,
+        volumes: params.volumes,
+        network_block_all: params.network_block_all,
+        network_allow_list: params.network_allow_list,
+        domain_allow_list: params.domain_allow_list,
+        linked_sandbox: params.linked_sandbox
+      )
+
+      create_sandbox.snapshot = params.snapshot if params.respond_to?(:snapshot)
+
+      if params.respond_to?(:image) && params.image.is_a?(String)
+        create_sandbox.build_info = CogboxApiClient::CreateBuildInfo.new(
+          dockerfile_content: Image.base(params.image).dockerfile
+        )
+      elsif params.respond_to?(:image) && params.image.is_a?(Image)
+        create_sandbox.build_info = CogboxApiClient::CreateBuildInfo.new(
+          context_hashes: SnapshotService.process_image_context(object_storage_api, params.image),
+          dockerfile_content: params.image.dockerfile
+        )
+      end
+
+      if params.respond_to?(:resources)
+        create_sandbox.cpu = params.resources&.cpu
+        create_sandbox.memory = params.resources&.memory
+        create_sandbox.disk = params.resources&.disk
+        create_sandbox.gpu = params.resources&.gpu
+        if params.resources&.gpu_type
+          create_sandbox.gpu_type =
+            params.resources.gpu_type.is_a?(Array) ? params.resources.gpu_type : [params.resources.gpu_type]
+        end
+      end
+
+      response = sandbox_api.create_sandbox(create_sandbox)
+
+      if response.state == CogboxApiClient::SandboxState::PENDING_BUILD && on_snapshot_create_logs
+        # Wait for state to change from PENDING_BUILD before fetching logs
+        while response.state == CogboxApiClient::SandboxState::PENDING_BUILD
+          sleep(1)
+          response = sandbox_api.get_sandbox(response.id)
+        end
+
+        # Get build logs URL from API
+        build_logs_response = sandbox_api.get_build_logs_url(response.id)
+        uri = URI.parse("#{build_logs_response.url}?follow=true")
+
+        headers = {}
+        sandbox_api.api_client.update_params_for_auth!(headers, nil, ['bearer'])
+        Util.stream_async(uri:, headers:, on_chunk: on_snapshot_create_logs)
+      end
+
+      sandbox = to_sandbox(sandbox_dto: response)
+
+      if sandbox.state != CogboxApiClient::SandboxState::STARTED
+        sandbox.wait_for_sandbox_start([0.001, timeout - (Time.now - start_time)].max)
+      end
+
+      sandbox
+    end
+
+    # @return [void]
+    # @raise [Cogbox::Sdk::Error]
+    def ensure_access_token_defined
+      return if config.api_key
+
+      unless config.jwt_token
+        raise Sdk::Error,
+              'Authentication credentials not found. Set COGBOX_API_KEY, or both COGBOX_JWT_TOKEN and ' \
+              'COGBOX_ORGANIZATION_ID. These can also be provided via Cogbox::Config.'
+      end
+      return if config.organization_id
+
+      raise Sdk::Error,
+            'COGBOX_ORGANIZATION_ID is required when authenticating with COGBOX_JWT_TOKEN. ' \
+            'It can also be provided via Cogbox::Config.'
+    end
+
+    # @return [CogboxApiClient::ApiClient]
+    def build_api_client
+      CogboxApiClient::ApiClient.new(api_client_config).tap do |client|
+        client.default_headers[HEADER_SOURCE] = SOURCE_RUBY
+        client.default_headers[HEADER_SDK_VERSION] = Sdk::VERSION
+        client.default_headers[HEADER_ORGANIZATION_ID] = config.organization_id if config.jwt_token
+        client.user_agent = "sdk-ruby/#{Sdk::VERSION}"
+      end
+    end
+
+    # @return [CogboxApiClient::Configuration]
+    def api_client_config
+      CogboxApiClient::Configuration.new.configure do |api_config|
+        uri = URI(config.api_url)
+        api_config.scheme = uri.scheme
+        api_config.host = uri.authority # Includes hostname:port
+        api_config.base_path = uri.path
+
+        api_config.access_token_getter = proc { config.api_key || config.jwt_token }
+        api_config
+      end
+    end
+
+    # @param sandbox_dto [CogboxApiClient::Sandbox, CogboxApiClient::SandboxListItem]
+    # @return [Cogbox::Sandbox]
+    def to_sandbox(sandbox_dto:)
+      Sandbox.new(
+        sandbox_dto:,
+        config:,
+        sandbox_api:,
+        otel_state: @otel_state
+      )
+    end
+
+    SOURCE_RUBY = 'sdk-ruby'
+    private_constant :SOURCE_RUBY
+
+    HEADER_SOURCE = 'X-Cogbox-Source'
+    private_constant :HEADER_SOURCE
+
+    HEADER_SDK_VERSION = 'X-Cogbox-SDK-Version'
+    private_constant :HEADER_SDK_VERSION
+
+    HEADER_ORGANIZATION_ID = 'X-Cogbox-Organization-ID'
+    private_constant :HEADER_ORGANIZATION_ID
+  end
+end