cerca 0.1.0

data/rbi/cerca/resources/threads.rbi

@@ -0,0 +1,160 @@
+# typed: strong
+
+module Cerca
+  module Resources
+    class Threads
+      # Create thread
+      sig do
+        params(
+          agent_id: String,
+          instructions: String,
+          message: String,
+          model: String,
+          system_prompt: String,
+          tools: T::Array[String],
+          request_options: Cerca::RequestOptions::OrHash
+        ).returns(Cerca::Thread)
+      end
+      def create(
+        agent_id,
+        instructions: nil,
+        message: nil,
+        model: nil,
+        # Deprecated alias for `instructions`; accepted for backwards compatibility.
+        system_prompt: nil,
+        # Per-thread tool subset. Omit to inherit the agent's full effective tools; pass
+        # [] to run with no configurable tools. Provided entries can only narrow the
+        # agent's effective tools.
+        tools: nil,
+        request_options: {}
+      )
+      end
+
+      # Retrieve thread
+      sig do
+        params(
+          agent_id: String,
+          thread_id: String,
+          debug: Cerca::ThreadRetrieveParams::Debug::OrSymbol,
+          include_messages:
+            Cerca::ThreadRetrieveParams::IncludeMessages::OrSymbol,
+          request_options: Cerca::RequestOptions::OrHash
+        ).returns(Cerca::Thread)
+      end
+      def retrieve(
+        agent_id,
+        thread_id,
+        # When true, includes debug-only compiled context fields.
+        debug: nil,
+        # When true, includes message content in the thread detail.
+        include_messages: nil,
+        request_options: {}
+      )
+      end
+
+      # List threads
+      sig do
+        params(
+          agent_id: String,
+          cursor: String,
+          limit: String,
+          schedule_id: String,
+          status: Cerca::Status::OrSymbol,
+          request_options: Cerca::RequestOptions::OrHash
+        ).returns(Cerca::Internal::ThreadsCursorPage[Cerca::ThreadSummary])
+      end
+      def list(
+        agent_id,
+        # Opaque pagination cursor returned by a previous request.
+        cursor: nil,
+        # Maximum number of items to return. Defaults to 20 and preserves parseInt
+        # semantics.
+        limit: nil,
+        # Optional schedule id filter.
+        schedule_id: nil,
+        # Optional thread status filter.
+        status: nil,
+        request_options: {}
+      )
+      end
+
+      # Cancel a running or awaiting thread. The underlying runtime treats repeat
+      # cancellation as an idempotent lifecycle operation when possible.
+      sig do
+        params(
+          agent_id: String,
+          thread_id: String,
+          request_options: Cerca::RequestOptions::OrHash
+        ).returns(Cerca::Thread)
+      end
+      def cancel(agent_id, thread_id, request_options: {})
+      end
+
+      # Close an idle thread. Closing a running, awaiting, or already-closed thread
+      # returns a lifecycle conflict.
+      sig do
+        params(
+          agent_id: String,
+          thread_id: String,
+          request_options: Cerca::RequestOptions::OrHash
+        ).returns(Cerca::Thread)
+      end
+      def close(agent_id, thread_id, request_options: {})
+      end
+
+      # Force context compaction for an idle thread. Compacting a running thread returns
+      # a lifecycle conflict.
+      sig do
+        params(
+          agent_id: String,
+          thread_id: String,
+          request_options: Cerca::RequestOptions::OrHash
+        ).returns(Cerca::Thread)
+      end
+      def compact(agent_id, thread_id, request_options: {})
+      end
+
+      # Create turn
+      sig do
+        params(
+          agent_id: String,
+          thread_id: String,
+          message: String,
+          model: String,
+          tools: T::Array[String],
+          request_options: Cerca::RequestOptions::OrHash
+        ).returns(Cerca::Turn)
+      end
+      def start_turn(
+        agent_id,
+        thread_id,
+        message:,
+        model: nil,
+        # Per-turn tool subset. Omit to inherit the thread's current tools; pass [] to run
+        # this turn with no configurable tools. Provided entries can only narrow the
+        # agent/thread effective tools.
+        tools: nil,
+        request_options: {}
+      )
+      end
+
+      # Steer a thread with another user message. Steering a closed thread returns a
+      # conflict; steering a running or awaiting thread queues the message.
+      sig do
+        params(
+          agent_id: String,
+          thread_id: String,
+          message: String,
+          request_options: Cerca::RequestOptions::OrHash
+        ).returns(Cerca::SteerResult)
+      end
+      def steer(agent_id, thread_id, message:, request_options: {})
+      end
+
+      # @api private
+      sig { params(client: Cerca::Client).returns(T.attached_class) }
+      def self.new(client:)
+      end
+    end
+  end
+end

data/rbi/cerca/resources/tools.rbi

@@ -0,0 +1,87 @@
+# typed: strong
+
+module Cerca
+  module Resources
+    class Tools
+      # Create tool
+      sig do
+        params(
+          fleet_id: String,
+          body:
+            T.any(
+              Cerca::ToolCreateParams::Body::CreateHTTPToolSourceRequest::OrHash,
+              Cerca::ToolCreateParams::Body::CreateMcpToolSourceRequest::OrHash
+            ),
+          request_options: Cerca::RequestOptions::OrHash
+        ).returns(Cerca::ToolSource::Variants)
+      end
+      def create(fleet_id, body:, request_options: {})
+      end
+
+      # Retrieve tool source
+      sig do
+        params(
+          fleet_id: String,
+          source_id: String,
+          request_options: Cerca::RequestOptions::OrHash
+        ).returns(Cerca::ToolSource::Variants)
+      end
+      def retrieve(fleet_id, source_id, request_options: {})
+      end
+
+      # Update tool source
+      sig do
+        params(
+          fleet_id: String,
+          source_id: String,
+          body:
+            T.any(
+              Cerca::ToolUpdateParams::Body::UpdateHTTPToolSourceRequest::OrHash,
+              Cerca::ToolUpdateParams::Body::UpdateMcpToolSourceRequest::OrHash
+            ),
+          request_options: Cerca::RequestOptions::OrHash
+        ).returns(Cerca::ToolSource::Variants)
+      end
+      def update(fleet_id, source_id, body:, request_options: {})
+      end
+
+      # List tools
+      sig do
+        params(
+          fleet_id: String,
+          cursor: String,
+          limit: String,
+          request_options: Cerca::RequestOptions::OrHash
+        ).returns(
+          Cerca::Internal::SourcesCursorPage[Cerca::ToolSource::Variants]
+        )
+      end
+      def list(
+        fleet_id,
+        # Opaque pagination cursor returned by a previous request.
+        cursor: nil,
+        # Maximum number of items to return. Defaults to 20 and preserves parseInt
+        # semantics.
+        limit: nil,
+        request_options: {}
+      )
+      end
+
+      # Delete tool source
+      sig do
+        params(
+          fleet_id: String,
+          source_id: String,
+          request_options: Cerca::RequestOptions::OrHash
+        ).void
+      end
+      def delete(fleet_id, source_id, request_options: {})
+      end
+
+      # @api private
+      sig { params(client: Cerca::Client).returns(T.attached_class) }
+      def self.new(client:)
+      end
+    end
+  end
+end

data/rbi/cerca/resources/webhooks.rbi

@@ -0,0 +1,121 @@
+# typed: strong
+
+module Cerca
+  module Resources
+    class Webhooks
+      # Create webhook
+      sig do
+        params(
+          fleet_id: String,
+          url: String,
+          events: T::Array[Cerca::WebhookSubscriptionEventType::OrSymbol],
+          request_options: Cerca::RequestOptions::OrHash
+        ).returns(Cerca::WebhookSubscriptionCreated)
+      end
+      def create(
+        fleet_id,
+        # HTTPS endpoint that will receive webhook deliveries.
+        url:,
+        # Event names to deliver. Omit to subscribe to all non-test events.
+        events: nil,
+        request_options: {}
+      )
+      end
+
+      # Retrieve webhook
+      sig do
+        params(
+          fleet_id: String,
+          webhook_id: String,
+          request_options: Cerca::RequestOptions::OrHash
+        ).returns(Cerca::WebhookSubscription)
+      end
+      def retrieve(fleet_id, webhook_id, request_options: {})
+      end
+
+      # Update webhook
+      sig do
+        params(
+          fleet_id: String,
+          webhook_id: String,
+          enabled: T::Boolean,
+          events: T::Array[Cerca::WebhookSubscriptionEventType::OrSymbol],
+          url: String,
+          request_options: Cerca::RequestOptions::OrHash
+        ).returns(Cerca::WebhookSubscription)
+      end
+      def update(
+        fleet_id,
+        webhook_id,
+        # Whether deliveries are enabled for this subscription.
+        enabled: nil,
+        # Event names to deliver. Omit to subscribe to all non-test events.
+        events: nil,
+        # HTTPS endpoint that will receive webhook deliveries.
+        url: nil,
+        request_options: {}
+      )
+      end
+
+      # List webhooks
+      sig do
+        params(
+          fleet_id: String,
+          cursor: String,
+          limit: String,
+          request_options: Cerca::RequestOptions::OrHash
+        ).returns(
+          Cerca::Internal::SubscriptionsCursorPage[Cerca::WebhookSubscription]
+        )
+      end
+      def list(
+        fleet_id,
+        # Opaque pagination cursor returned by a previous request.
+        cursor: nil,
+        # Maximum number of items to return. Defaults to 20 and preserves parseInt
+        # semantics.
+        limit: nil,
+        request_options: {}
+      )
+      end
+
+      # Delete webhook
+      sig do
+        params(
+          fleet_id: String,
+          webhook_id: String,
+          request_options: Cerca::RequestOptions::OrHash
+        ).void
+      end
+      def delete(fleet_id, webhook_id, request_options: {})
+      end
+
+      # Rotate webhook secret
+      sig do
+        params(
+          fleet_id: String,
+          webhook_id: String,
+          request_options: Cerca::RequestOptions::OrHash
+        ).returns(Cerca::WebhookSubscriptionCreated)
+      end
+      def rotate(fleet_id, webhook_id, request_options: {})
+      end
+
+      # Send test webhook
+      sig do
+        params(
+          fleet_id: String,
+          webhook_id: String,
+          request_options: Cerca::RequestOptions::OrHash
+        ).returns(Cerca::Models::WebhookTestResponse)
+      end
+      def test_(fleet_id, webhook_id, request_options: {})
+      end
+
+      # @api private
+      sig { params(client: Cerca::Client).returns(T.attached_class) }
+      def self.new(client:)
+      end
+    end
+  end
+end

data/rbi/cerca/version.rbi

@@ -0,0 +1,5 @@
+# typed: strong
+
+module Cerca
+  VERSION = T.let(T.unsafe(nil), String)
+end

data/sig/cerca/client.rbs

@@ -0,0 +1,54 @@
+module Cerca
+  class Client < Cerca::Internal::Transport::BaseClient
+    DEFAULT_MAX_RETRIES: 2
+
+    DEFAULT_TIMEOUT_IN_SECONDS: Float
+
+    DEFAULT_INITIAL_RETRY_DELAY: Float
+
+    DEFAULT_MAX_RETRY_DELAY: Float
+
+    attr_reader api_key: String
+
+    attr_reader auth: Cerca::Resources::Auth
+
+    attr_reader oauth: Cerca::Resources::OAuth
+
+    attr_reader connections: Cerca::Resources::Connections
+
+    attr_reader fleets: Cerca::Resources::Fleets
+
+    attr_reader tools: Cerca::Resources::Tools
+
+    attr_reader webhooks: Cerca::Resources::Webhooks
+
+    attr_reader events: Cerca::Resources::Events
+
+    attr_reader agents: Cerca::Resources::Agents
+
+    attr_reader threads: Cerca::Resources::Threads
+
+    attr_reader context: Cerca::Resources::Context
+
+    attr_reader schedules: Cerca::Resources::Schedules
+
+    attr_reader approval_requests: Cerca::Resources::ApprovalRequests
+
+    attr_reader approval_grants: Cerca::Resources::ApprovalGrants
+
+    attr_reader sandbox: Cerca::Resources::Sandbox
+
+    attr_reader models: Cerca::Resources::Models
+
+    private def auth_headers: -> ::Hash[String, String]
+
+    def initialize: (
+      ?api_key: String?,
+      ?base_url: String?,
+      ?max_retries: Integer,
+      ?timeout: Float,
+      ?initial_retry_delay: Float,
+      ?max_retry_delay: Float
+    ) -> void
+  end
+end

data/sig/cerca/errors.rbs

@@ -0,0 +1,117 @@
+module Cerca
+  module Errors
+    class Error < StandardError
+      attr_accessor cause: StandardError?
+    end
+
+    class ConversionError < Cerca::Errors::Error
+      def cause: -> StandardError?
+
+      def initialize: (
+        on: Class,
+        method: Symbol,
+        target: top,
+        value: top,
+        ?cause: StandardError?
+      ) -> void
+    end
+
+    class APIError < Cerca::Errors::Error
+      attr_accessor url: URI::Generic
+
+      attr_accessor status: Integer?
+
+      attr_accessor headers: ::Hash[String, String]?
+
+      attr_accessor body: top?
+
+      def initialize: (
+        url: URI::Generic,
+        ?status: Integer?,
+        ?headers: ::Hash[String, String]?,
+        ?body: Object?,
+        ?request: nil,
+        ?response: nil,
+        ?message: String?
+      ) -> void
+    end
+
+    class APIConnectionError < Cerca::Errors::APIError
+      def initialize: (
+        url: URI::Generic,
+        ?status: nil,
+        ?headers: ::Hash[String, String]?,
+        ?body: nil,
+        ?request: nil,
+        ?response: nil,
+        ?message: String?
+      ) -> void
+    end
+
+    class APITimeoutError < Cerca::Errors::APIConnectionError
+      def initialize: (
+        url: URI::Generic,
+        ?status: nil,
+        ?headers: ::Hash[String, String]?,
+        ?body: nil,
+        ?request: nil,
+        ?response: nil,
+        ?message: String?
+      ) -> void
+    end
+
+    class APIStatusError < Cerca::Errors::APIError
+      def self.for: (
+        url: URI::Generic,
+        status: Integer,
+        headers: ::Hash[String, String]?,
+        body: Object?,
+        request: nil,
+        response: nil,
+        ?message: String?
+      ) -> instance
+
+      def initialize: (
+        url: URI::Generic,
+        status: Integer,
+        headers: ::Hash[String, String]?,
+        body: Object?,
+        request: nil,
+        response: nil,
+        ?message: String?
+      ) -> void
+    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: Range[Integer]
+    end
+  end
+end

data/sig/cerca/file_part.rbs

@@ -0,0 +1,21 @@
+module Cerca
+  class FilePart
+    attr_reader content: Pathname | StringIO | IO | String
+
+    attr_reader content_type: String?
+
+    attr_reader filename: String?
+
+    private def read: -> String
+
+    def to_json: (*top a) -> String
+
+    def to_yaml: (*top a) -> String
+
+    def initialize: (
+      Pathname | StringIO | IO | String content,
+      ?filename: (Pathname | String)?,
+      ?content_type: String?
+    ) -> void
+  end
+end

data/sig/cerca/internal/agents_cursor_page.rbs

@@ -0,0 +1,15 @@
+module Cerca
+  module Internal
+    class AgentsCursorPage[Elem]
+      include Cerca::Internal::Type::BasePage[Elem]
+
+      attr_accessor agents: ::Array[Elem]?
+
+      attr_accessor cursor: String?
+
+      attr_accessor has_more: bool
+
+      def inspect: -> String
+    end
+  end
+end

data/sig/cerca/internal/approval_requests_cursor_page.rbs

@@ -0,0 +1,15 @@
+module Cerca
+  module Internal
+    class ApprovalRequestsCursorPage[Elem]
+      include Cerca::Internal::Type::BasePage[Elem]
+
+      attr_accessor approvals: ::Array[Elem]?
+
+      attr_accessor cursor: String?
+
+      attr_accessor has_more: bool
+
+      def inspect: -> String
+    end
+  end
+end

data/sig/cerca/internal/connections_cursor_page.rbs

@@ -0,0 +1,15 @@
+module Cerca
+  module Internal
+    class ConnectionsCursorPage[Elem]
+      include Cerca::Internal::Type::BasePage[Elem]
+
+      attr_accessor connections: ::Array[Elem]?
+
+      attr_accessor cursor: String?
+
+      attr_accessor has_more: bool
+
+      def inspect: -> String
+    end
+  end
+end

data/sig/cerca/internal/entries_cursor_page.rbs

@@ -0,0 +1,15 @@
+module Cerca
+  module Internal
+    class EntriesCursorPage[Elem]
+      include Cerca::Internal::Type::BasePage[Elem]
+
+      attr_accessor entries: ::Array[Elem]?
+
+      attr_accessor cursor: String?
+
+      attr_accessor has_more: bool
+
+      def inspect: -> String
+    end
+  end
+end

data/sig/cerca/internal/events_cursor_page.rbs

@@ -0,0 +1,15 @@
+module Cerca
+  module Internal
+    class EventsCursorPage[Elem]
+      include Cerca::Internal::Type::BasePage[Elem]
+
+      attr_accessor events: ::Array[Elem]?
+
+      attr_accessor cursor: String?
+
+      attr_accessor has_more: bool
+
+      def inspect: -> String
+    end
+  end
+end

data/sig/cerca/internal/fleets_cursor_page.rbs

@@ -0,0 +1,15 @@
+module Cerca
+  module Internal
+    class FleetsCursorPage[Elem]
+      include Cerca::Internal::Type::BasePage[Elem]
+
+      attr_accessor fleets: ::Array[Elem]?
+
+      attr_accessor cursor: String?
+
+      attr_accessor has_more: bool
+
+      def inspect: -> String
+    end
+  end
+end

data/sig/cerca/internal/grants_cursor_page.rbs

@@ -0,0 +1,15 @@
+module Cerca
+  module Internal
+    class GrantsCursorPage[Elem]
+      include Cerca::Internal::Type::BasePage[Elem]
+
+      attr_accessor grants: ::Array[Elem]?
+
+      attr_accessor cursor: String?
+
+      attr_accessor has_more: bool
+
+      def inspect: -> String
+    end
+  end
+end

data/sig/cerca/internal/results_cursor_page.rbs

@@ -0,0 +1,15 @@
+module Cerca
+  module Internal
+    class ResultsCursorPage[Elem]
+      include Cerca::Internal::Type::BasePage[Elem]
+
+      attr_accessor results: ::Array[Elem]?
+
+      attr_accessor cursor: String?
+
+      attr_accessor has_more: bool
+
+      def inspect: -> String
+    end
+  end
+end