cerca 0.1.0

data/lib/cerca.rb

@@ -0,0 +1,231 @@
+# frozen_string_literal: true
+
+# Standard libraries.
+# rubocop:disable Lint/RedundantRequireStatement
+require "English"
+require "base64"
+require "cgi"
+require "date"
+require "erb"
+require "etc"
+require "json"
+require "net/http"
+require "openssl"
+require "pathname"
+require "rbconfig"
+require "securerandom"
+require "set"
+require "stringio"
+require "time"
+require "uri"
+# rubocop:enable Lint/RedundantRequireStatement
+
+# We already ship the preferred sorbet manifests in the package itself.
+# `tapioca` currently does not offer us a way to opt out of unnecessary compilation.
+if Object.const_defined?(:Tapioca) &&
+   caller.chain([$PROGRAM_NAME]).chain(ARGV).any?(/tapioca/) &&
+   ARGV.none?(/dsl/)
+  return
+end
+
+# Gems.
+require "connection_pool"
+
+# Package files.
+require_relative "cerca/version"
+require_relative "cerca/internal/util"
+require_relative "cerca/internal/type/converter"
+require_relative "cerca/internal/type/unknown"
+require_relative "cerca/internal/type/boolean"
+require_relative "cerca/internal/type/file_input"
+require_relative "cerca/internal/type/enum"
+require_relative "cerca/internal/type/union"
+require_relative "cerca/internal/type/array_of"
+require_relative "cerca/internal/type/hash_of"
+require_relative "cerca/internal/type/base_model"
+require_relative "cerca/internal/type/base_page"
+require_relative "cerca/internal/type/base_stream"
+require_relative "cerca/internal/type/request_parameters"
+require_relative "cerca/internal"
+require_relative "cerca/request_options"
+require_relative "cerca/file_part"
+require_relative "cerca/errors"
+require_relative "cerca/internal/transport/base_client"
+require_relative "cerca/internal/transport/pooled_net_requester"
+require_relative "cerca/client"
+require_relative "cerca/internal/stream"
+require_relative "cerca/internal/agents_cursor_page"
+require_relative "cerca/internal/approval_requests_cursor_page"
+require_relative "cerca/internal/connections_cursor_page"
+require_relative "cerca/internal/entries_cursor_page"
+require_relative "cerca/internal/events_cursor_page"
+require_relative "cerca/internal/fleets_cursor_page"
+require_relative "cerca/internal/grants_cursor_page"
+require_relative "cerca/internal/results_cursor_page"
+require_relative "cerca/internal/sources_cursor_page"
+require_relative "cerca/internal/subscriptions_cursor_page"
+require_relative "cerca/internal/threads_cursor_page"
+require_relative "cerca/models/connection"
+require_relative "cerca/models/agent"
+require_relative "cerca/models/agent_create_params"
+require_relative "cerca/models/agent_delete_params"
+require_relative "cerca/models/agent_delete_response"
+require_relative "cerca/models/agent_list_params"
+require_relative "cerca/models/agent_list_tools_params"
+require_relative "cerca/models/agent_list_tools_response"
+require_relative "cerca/models/agent_retrieve_config_params"
+require_relative "cerca/models/agent_retrieve_params"
+require_relative "cerca/models/agent_summary"
+require_relative "cerca/models/agent_update_metadata_params"
+require_relative "cerca/models/agent_update_params"
+require_relative "cerca/models/api_key_tool_source_auth"
+require_relative "cerca/models/approval_grant"
+require_relative "cerca/models/approval_grant_delete_for_thread_params"
+require_relative "cerca/models/approval_grant_delete_for_thread_response"
+require_relative "cerca/models/approval_grant_delete_params"
+require_relative "cerca/models/approval_grant_delete_response"
+require_relative "cerca/models/approval_grant_list_for_thread_params"
+require_relative "cerca/models/approval_grant_list_for_thread_response"
+require_relative "cerca/models/approval_grant_list_params"
+require_relative "cerca/models/approval_mode"
+require_relative "cerca/models/approval_policy"
+require_relative "cerca/models/approval_request"
+require_relative "cerca/models/approval_request_list_params"
+require_relative "cerca/models/approval_request_resolve_params"
+require_relative "cerca/models/attached_connection"
+require_relative "cerca/models/auth_context_params"
+require_relative "cerca/models/auth_context_response"
+require_relative "cerca/models/auth_fleets_response"
+require_relative "cerca/models/auth_injection"
+require_relative "cerca/models/auth_list_fleets_params"
+require_relative "cerca/models/compiled_context"
+require_relative "cerca/models/configuration"
+require_relative "cerca/models/configuration_field_name"
+require_relative "cerca/models/connection_attach_params"
+require_relative "cerca/models/connection_create_params"
+require_relative "cerca/models/connection_delete_params"
+require_relative "cerca/models/connection_delete_response"
+require_relative "cerca/models/connection_detach_params"
+require_relative "cerca/models/connection_detach_response"
+require_relative "cerca/models/connection_list_for_agent_params"
+require_relative "cerca/models/connection_list_for_agent_response"
+require_relative "cerca/models/connection_list_params"
+require_relative "cerca/models/connection_owner"
+require_relative "cerca/models/content_block"
+require_relative "cerca/models/context_delete_params"
+require_relative "cerca/models/context_delete_response"
+require_relative "cerca/models/context_list_params"
+require_relative "cerca/models/context_retrieve_params"
+require_relative "cerca/models/context_search_params"
+require_relative "cerca/models/context_write_params"
+require_relative "cerca/models/credential_provider"
+require_relative "cerca/models/credential_type"
+require_relative "cerca/models/discovered_tool"
+require_relative "cerca/models/effective_configuration"
+require_relative "cerca/models/entry"
+require_relative "cerca/models/entry_summary"
+require_relative "cerca/models/error_response"
+require_relative "cerca/models/event_list_for_agent_params"
+require_relative "cerca/models/event_list_for_fleet_params"
+require_relative "cerca/models/event_list_for_thread_params"
+require_relative "cerca/models/event_stream_for_agent_params"
+require_relative "cerca/models/event_stream_for_fleet_params"
+require_relative "cerca/models/event_stream_for_thread_events_params"
+require_relative "cerca/models/event_stream_for_thread_params"
+require_relative "cerca/models/exec_result"
+require_relative "cerca/models/execution_principal"
+require_relative "cerca/models/fleet"
+require_relative "cerca/models/http_endpoint"
+require_relative "cerca/models/http_tool_definition"
+require_relative "cerca/models/http_tool_execution_policy"
+require_relative "cerca/models/http_tool_source"
+require_relative "cerca/models/json_object"
+require_relative "cerca/models/mcp_tool_execution_policy"
+require_relative "cerca/models/mcp_tool_source"
+require_relative "cerca/models/message"
+require_relative "cerca/models/metadata"
+require_relative "cerca/models/model_descriptor"
+require_relative "cerca/models/model_list_params"
+require_relative "cerca/models/model_list_response"
+require_relative "cerca/models/no_tool_source_auth"
+require_relative "cerca/models/oauth_connection_tool_source_auth"
+require_relative "cerca/models/oauth_connect_params"
+require_relative "cerca/models/oauth_connect_response"
+require_relative "cerca/models/oauth_exchange_config"
+require_relative "cerca/models/oauth_exchange_tool_source_auth"
+require_relative "cerca/models/read_response"
+require_relative "cerca/models/response_normalization_hint"
+require_relative "cerca/models/runtime_webhook_event"
+require_relative "cerca/models/sandbox_exec_params"
+require_relative "cerca/models/sandbox_read_params"
+require_relative "cerca/models/sandbox_write_params"
+require_relative "cerca/models/sandbox_write_response"
+require_relative "cerca/models/schedule"
+require_relative "cerca/models/schedule_create_params"
+require_relative "cerca/models/schedule_delete_params"
+require_relative "cerca/models/schedule_delete_response"
+require_relative "cerca/models/schedule_list_params"
+require_relative "cerca/models/schedule_list_response"
+require_relative "cerca/models/schedule_trigger_params"
+require_relative "cerca/models/schedule_trigger_response"
+require_relative "cerca/models/schedule_update_params"
+require_relative "cerca/models/search_result"
+require_relative "cerca/models/source_warning"
+require_relative "cerca/models/status"
+require_relative "cerca/models/steer_result"
+require_relative "cerca/models/subscription_event"
+require_relative "cerca/models/sub_thread_summary"
+require_relative "cerca/models/thread"
+require_relative "cerca/models/thread_cancel_params"
+require_relative "cerca/models/thread_close_params"
+require_relative "cerca/models/thread_compact_params"
+require_relative "cerca/models/thread_create_params"
+require_relative "cerca/models/thread_list_params"
+require_relative "cerca/models/thread_retrieve_params"
+require_relative "cerca/models/thread_start_turn_params"
+require_relative "cerca/models/thread_steer_params"
+require_relative "cerca/models/thread_stream_event"
+require_relative "cerca/models/thread_summary"
+require_relative "cerca/models/token_usage"
+require_relative "cerca/models/tool"
+require_relative "cerca/models/tool_approval_mode"
+require_relative "cerca/models/tool_connection_metadata"
+require_relative "cerca/models/tool_create_params"
+require_relative "cerca/models/tool_delete_params"
+require_relative "cerca/models/tool_descriptor"
+require_relative "cerca/models/tool_list_params"
+require_relative "cerca/models/tool_name"
+require_relative "cerca/models/tool_retrieve_params"
+require_relative "cerca/models/tool_source"
+require_relative "cerca/models/tool_source_auth"
+require_relative "cerca/models/tool_spec"
+require_relative "cerca/models/tool_update_params"
+require_relative "cerca/models/turn"
+require_relative "cerca/models/webhook_create_params"
+require_relative "cerca/models/webhook_delete_params"
+require_relative "cerca/models/webhook_event_type"
+require_relative "cerca/models/webhook_list_params"
+require_relative "cerca/models/webhook_retrieve_params"
+require_relative "cerca/models/webhook_rotate_params"
+require_relative "cerca/models/webhook_subscription"
+require_relative "cerca/models/webhook_subscription_created"
+require_relative "cerca/models/webhook_subscription_event_type"
+require_relative "cerca/models/webhook_test_params"
+require_relative "cerca/models/webhook_test_response"
+require_relative "cerca/models/webhook_update_params"
+require_relative "cerca/models"
+require_relative "cerca/resources/agents"
+require_relative "cerca/resources/approval_grants"
+require_relative "cerca/resources/approval_requests"
+require_relative "cerca/resources/auth"
+require_relative "cerca/resources/connections"
+require_relative "cerca/resources/context"
+require_relative "cerca/resources/events"
+require_relative "cerca/resources/fleets"
+require_relative "cerca/resources/models"
+require_relative "cerca/resources/oauth"
+require_relative "cerca/resources/sandbox"
+require_relative "cerca/resources/schedules"
+require_relative "cerca/resources/threads"
+require_relative "cerca/resources/tools"
+require_relative "cerca/resources/webhooks"

data/manifest.yaml

@@ -0,0 +1,17 @@
+dependencies:
+  - English
+  - base64
+  - cgi
+  - date
+  - erb
+  - etc
+  - json
+  - net/http
+  - openssl
+  - pathname
+  - rbconfig
+  - securerandom
+  - set
+  - stringio
+  - time
+  - uri

data/rbi/cerca/client.rbi

@@ -0,0 +1,91 @@
+# typed: strong
+
+module Cerca
+  class Client < Cerca::Internal::Transport::BaseClient
+    DEFAULT_MAX_RETRIES = 2
+
+    DEFAULT_TIMEOUT_IN_SECONDS = T.let(60.0, Float)
+
+    DEFAULT_INITIAL_RETRY_DELAY = T.let(0.5, Float)
+
+    DEFAULT_MAX_RETRY_DELAY = T.let(8.0, Float)
+
+    sig { returns(String) }
+    attr_reader :api_key
+
+    sig { returns(Cerca::Resources::Auth) }
+    attr_reader :auth
+
+    sig { returns(Cerca::Resources::OAuth) }
+    attr_reader :oauth
+
+    sig { returns(Cerca::Resources::Connections) }
+    attr_reader :connections
+
+    sig { returns(Cerca::Resources::Fleets) }
+    attr_reader :fleets
+
+    sig { returns(Cerca::Resources::Tools) }
+    attr_reader :tools
+
+    sig { returns(Cerca::Resources::Webhooks) }
+    attr_reader :webhooks
+
+    sig { returns(Cerca::Resources::Events) }
+    attr_reader :events
+
+    sig { returns(Cerca::Resources::Agents) }
+    attr_reader :agents
+
+    sig { returns(Cerca::Resources::Threads) }
+    attr_reader :threads
+
+    sig { returns(Cerca::Resources::Context) }
+    attr_reader :context
+
+    sig { returns(Cerca::Resources::Schedules) }
+    attr_reader :schedules
+
+    sig { returns(Cerca::Resources::ApprovalRequests) }
+    attr_reader :approval_requests
+
+    sig { returns(Cerca::Resources::ApprovalGrants) }
+    attr_reader :approval_grants
+
+    sig { returns(Cerca::Resources::Sandbox) }
+    attr_reader :sandbox
+
+    sig { returns(Cerca::Resources::Models) }
+    attr_reader :models
+
+    # @api private
+    sig { override.returns(T::Hash[String, String]) }
+    private def auth_headers
+    end
+
+    # Creates and returns a new client for interacting with the API.
+    sig do
+      params(
+        api_key: T.nilable(String),
+        base_url: T.nilable(String),
+        max_retries: Integer,
+        timeout: Float,
+        initial_retry_delay: Float,
+        max_retry_delay: Float
+      ).returns(T.attached_class)
+    end
+    def self.new(
+      # Defaults to `ENV["CERCA_API_KEY"]`
+      api_key: ENV["CERCA_API_KEY"],
+      # Override the default base URL for the API, e.g.,
+      # `"https://api.example.com/v2/"`. Defaults to `ENV["CERCA_BASE_URL"]`
+      base_url: ENV["CERCA_BASE_URL"],
+      # Max number of retries to attempt after a failed retryable request.
+      max_retries: Cerca::Client::DEFAULT_MAX_RETRIES,
+      timeout: Cerca::Client::DEFAULT_TIMEOUT_IN_SECONDS,
+      initial_retry_delay: Cerca::Client::DEFAULT_INITIAL_RETRY_DELAY,
+      max_retry_delay: Cerca::Client::DEFAULT_MAX_RETRY_DELAY
+    )
+    end
+  end
+end

data/rbi/cerca/errors.rbi

@@ -0,0 +1,205 @@
+# typed: strong
+
+module Cerca
+  module Errors
+    class Error < StandardError
+      sig { returns(T.nilable(StandardError)) }
+      attr_accessor :cause
+    end
+
+    class ConversionError < Cerca::Errors::Error
+      sig { returns(T.nilable(StandardError)) }
+      def cause
+      end
+
+      # @api private
+      sig do
+        params(
+          on: T::Class[StandardError],
+          method: Symbol,
+          target: T.anything,
+          value: T.anything,
+          cause: T.nilable(StandardError)
+        ).returns(T.attached_class)
+      end
+      def self.new(on:, method:, target:, value:, cause: nil)
+      end
+    end
+
+    class APIError < Cerca::Errors::Error
+      sig { returns(URI::Generic) }
+      attr_accessor :url
+
+      sig { returns(T.nilable(Integer)) }
+      attr_accessor :status
+
+      sig { returns(T.nilable(T::Hash[String, String])) }
+      attr_accessor :headers
+
+      sig { returns(T.nilable(T.anything)) }
+      attr_accessor :body
+
+      # @api private
+      sig do
+        params(
+          url: URI::Generic,
+          status: T.nilable(Integer),
+          headers: T.nilable(T::Hash[String, String]),
+          body: T.nilable(Object),
+          request: NilClass,
+          response: NilClass,
+          message: T.nilable(String)
+        ).returns(T.attached_class)
+      end
+      def self.new(
+        url:,
+        status: nil,
+        headers: nil,
+        body: nil,
+        request: nil,
+        response: nil,
+        message: nil
+      )
+      end
+    end
+
+    class APIConnectionError < Cerca::Errors::APIError
+      sig { returns(NilClass) }
+      attr_accessor :status
+
+      sig { returns(NilClass) }
+      attr_accessor :body
+
+      # @api private
+      sig do
+        params(
+          url: URI::Generic,
+          status: NilClass,
+          headers: T.nilable(T::Hash[String, String]),
+          body: NilClass,
+          request: NilClass,
+          response: NilClass,
+          message: T.nilable(String)
+        ).returns(T.attached_class)
+      end
+      def self.new(
+        url:,
+        status: nil,
+        headers: nil,
+        body: nil,
+        request: nil,
+        response: nil,
+        message: "Connection error."
+      )
+      end
+    end
+
+    class APITimeoutError < Cerca::Errors::APIConnectionError
+      # @api private
+      sig do
+        params(
+          url: URI::Generic,
+          status: NilClass,
+          headers: T.nilable(T::Hash[String, String]),
+          body: NilClass,
+          request: NilClass,
+          response: NilClass,
+          message: T.nilable(String)
+        ).returns(T.attached_class)
+      end
+      def self.new(
+        url:,
+        status: nil,
+        headers: nil,
+        body: nil,
+        request: nil,
+        response: nil,
+        message: "Request timed out."
+      )
+      end
+    end
+
+    class APIStatusError < Cerca::Errors::APIError
+      # @api private
+      sig do
+        params(
+          url: URI::Generic,
+          status: Integer,
+          headers: T.nilable(T::Hash[String, String]),
+          body: T.nilable(Object),
+          request: NilClass,
+          response: NilClass,
+          message: T.nilable(String)
+        ).returns(T.attached_class)
+      end
+      def self.for(
+        url:,
+        status:,
+        headers:,
+        body:,
+        request:,
+        response:,
+        message: nil
+      )
+      end
+
+      sig { returns(Integer) }
+      attr_accessor :status
+
+      # @api private
+      sig do
+        params(
+          url: URI::Generic,
+          status: Integer,
+          headers: T.nilable(T::Hash[String, String]),
+          body: T.nilable(Object),
+          request: NilClass,
+          response: NilClass,
+          message: T.nilable(String)
+        ).returns(T.attached_class)
+      end
+      def self.new(
+        url:,
+        status:,
+        headers:,
+        body:,
+        request:,
+        response:,
+        message: nil
+      )
+      end
+    end
+
+    class BadRequestError < Cerca::Errors::APIStatusError
+      HTTP_STATUS = 400
+    end
+
+    class AuthenticationError < Cerca::Errors::APIStatusError
+      HTTP_STATUS = 401
+    end
+
+    class PermissionDeniedError < Cerca::Errors::APIStatusError
+      HTTP_STATUS = 403
+    end
+
+    class NotFoundError < Cerca::Errors::APIStatusError
+      HTTP_STATUS = 404
+    end
+
+    class ConflictError < Cerca::Errors::APIStatusError
+      HTTP_STATUS = 409
+    end
+
+    class UnprocessableEntityError < Cerca::Errors::APIStatusError
+      HTTP_STATUS = 422
+    end
+
+    class RateLimitError < Cerca::Errors::APIStatusError
+      HTTP_STATUS = 429
+    end
+
+    class InternalServerError < Cerca::Errors::APIStatusError
+      HTTP_STATUS = T.let((500..), T::Range[Integer])
+    end
+  end
+end

data/rbi/cerca/file_part.rbi

@@ -0,0 +1,37 @@
+# typed: strong
+
+module Cerca
+  class FilePart
+    sig { returns(T.any(Pathname, StringIO, IO, String)) }
+    attr_reader :content
+
+    sig { returns(T.nilable(String)) }
+    attr_reader :content_type
+
+    sig { returns(T.nilable(String)) }
+    attr_reader :filename
+
+    # @api private
+    sig { returns(String) }
+    private def read
+    end
+
+    sig { params(a: T.anything).returns(String) }
+    def to_json(*a)
+    end
+
+    sig { params(a: T.anything).returns(String) }
+    def to_yaml(*a)
+    end
+
+    sig do
+      params(
+        content: T.any(Pathname, StringIO, IO, String),
+        filename: T.nilable(T.any(Pathname, String)),
+        content_type: T.nilable(String)
+      ).returns(T.attached_class)
+    end
+    def self.new(content, filename: nil, content_type: nil)
+    end
+  end
+end

data/rbi/cerca/internal/agents_cursor_page.rbi

@@ -0,0 +1,25 @@
+# typed: strong
+
+module Cerca
+  module Internal
+    class AgentsCursorPage
+      include Cerca::Internal::Type::BasePage
+
+      Elem = type_member
+
+      sig { returns(T.nilable(T::Array[Elem])) }
+      attr_accessor :agents
+
+      sig { returns(T.nilable(String)) }
+      attr_accessor :cursor
+
+      sig { returns(T::Boolean) }
+      attr_accessor :has_more
+
+      # @api private
+      sig { returns(String) }
+      def inspect
+      end
+    end
+  end
+end

data/rbi/cerca/internal/approval_requests_cursor_page.rbi

@@ -0,0 +1,25 @@
+# typed: strong
+
+module Cerca
+  module Internal
+    class ApprovalRequestsCursorPage
+      include Cerca::Internal::Type::BasePage
+
+      Elem = type_member
+
+      sig { returns(T.nilable(T::Array[Elem])) }
+      attr_accessor :approvals
+
+      sig { returns(T.nilable(String)) }
+      attr_accessor :cursor
+
+      sig { returns(T::Boolean) }
+      attr_accessor :has_more
+
+      # @api private
+      sig { returns(String) }
+      def inspect
+      end
+    end
+  end
+end

data/rbi/cerca/internal/connections_cursor_page.rbi

@@ -0,0 +1,25 @@
+# typed: strong
+
+module Cerca
+  module Internal
+    class ConnectionsCursorPage
+      include Cerca::Internal::Type::BasePage
+
+      Elem = type_member
+
+      sig { returns(T.nilable(T::Array[Elem])) }
+      attr_accessor :connections
+
+      sig { returns(T.nilable(String)) }
+      attr_accessor :cursor
+
+      sig { returns(T::Boolean) }
+      attr_accessor :has_more
+
+      # @api private
+      sig { returns(String) }
+      def inspect
+      end
+    end
+  end
+end

data/rbi/cerca/internal/entries_cursor_page.rbi

@@ -0,0 +1,25 @@
+# typed: strong
+
+module Cerca
+  module Internal
+    class EntriesCursorPage
+      include Cerca::Internal::Type::BasePage
+
+      Elem = type_member
+
+      sig { returns(T.nilable(T::Array[Elem])) }
+      attr_accessor :entries
+
+      sig { returns(T.nilable(String)) }
+      attr_accessor :cursor
+
+      sig { returns(T::Boolean) }
+      attr_accessor :has_more
+
+      # @api private
+      sig { returns(String) }
+      def inspect
+      end
+    end
+  end
+end