handinger 0.6.0 → 0.7.0

data/rbi/handinger/models/workers/webhook_execution.rbi

@@ -0,0 +1,146 @@
+# typed: strong
+
+module Handinger
+  module Models
+    module Workers
+      class WebhookExecution < Handinger::Internal::Type::BaseModel
+        OrHash =
+          T.type_alias do
+            T.any(
+              Handinger::Workers::WebhookExecution,
+              Handinger::Internal::AnyHash
+            )
+          end
+
+        sig { returns(String) }
+        attr_accessor :id
+
+        sig { returns(Time) }
+        attr_accessor :created_at
+
+        # Wall-clock time spent on the delivery attempt.
+        sig { returns(Integer) }
+        attr_accessor :duration_ms
+
+        # Failure reason when `requestStatus` is `error`.
+        sig { returns(T.nilable(String)) }
+        attr_accessor :error_message
+
+        # `success` when the endpoint returned a 2xx response, `error` otherwise.
+        sig do
+          returns(
+            Handinger::Workers::WebhookExecution::RequestStatus::TaggedSymbol
+          )
+        end
+        attr_accessor :request_status
+
+        # HTTP status returned by the endpoint, when reachable.
+        sig { returns(T.nilable(Integer)) }
+        attr_accessor :response_status
+
+        # Task that triggered the delivery, when available.
+        sig { returns(T.nilable(String)) }
+        attr_accessor :task_id
+
+        # Title of the originating task, when available.
+        sig { returns(T.nilable(String)) }
+        attr_accessor :task_title
+
+        # Endpoint Handinger attempted to deliver to.
+        sig { returns(String) }
+        attr_accessor :url
+
+        sig { returns(String) }
+        attr_accessor :worker_id
+
+        sig do
+          params(
+            id: String,
+            created_at: Time,
+            duration_ms: Integer,
+            error_message: T.nilable(String),
+            request_status:
+              Handinger::Workers::WebhookExecution::RequestStatus::OrSymbol,
+            response_status: T.nilable(Integer),
+            task_id: T.nilable(String),
+            task_title: T.nilable(String),
+            url: String,
+            worker_id: String
+          ).returns(T.attached_class)
+        end
+        def self.new(
+          id:,
+          created_at:,
+          # Wall-clock time spent on the delivery attempt.
+          duration_ms:,
+          # Failure reason when `requestStatus` is `error`.
+          error_message:,
+          # `success` when the endpoint returned a 2xx response, `error` otherwise.
+          request_status:,
+          # HTTP status returned by the endpoint, when reachable.
+          response_status:,
+          # Task that triggered the delivery, when available.
+          task_id:,
+          # Title of the originating task, when available.
+          task_title:,
+          # Endpoint Handinger attempted to deliver to.
+          url:,
+          worker_id:
+        )
+        end
+
+        sig do
+          override.returns(
+            {
+              id: String,
+              created_at: Time,
+              duration_ms: Integer,
+              error_message: T.nilable(String),
+              request_status:
+                Handinger::Workers::WebhookExecution::RequestStatus::TaggedSymbol,
+              response_status: T.nilable(Integer),
+              task_id: T.nilable(String),
+              task_title: T.nilable(String),
+              url: String,
+              worker_id: String
+            }
+          )
+        end
+        def to_hash
+        end
+
+        # `success` when the endpoint returned a 2xx response, `error` otherwise.
+        module RequestStatus
+          extend Handinger::Internal::Type::Enum
+
+          TaggedSymbol =
+            T.type_alias do
+              T.all(Symbol, Handinger::Workers::WebhookExecution::RequestStatus)
+            end
+          OrSymbol = T.type_alias { T.any(Symbol, String) }
+
+          SUCCESS =
+            T.let(
+              :success,
+              Handinger::Workers::WebhookExecution::RequestStatus::TaggedSymbol
+            )
+          ERROR =
+            T.let(
+              :error,
+              Handinger::Workers::WebhookExecution::RequestStatus::TaggedSymbol
+            )
+
+          sig do
+            override.returns(
+              T::Array[
+                Handinger::Workers::WebhookExecution::RequestStatus::TaggedSymbol
+              ]
+            )
+          end
+          def self.values
+          end
+        end
+      end
+    end
+  end
+end

data/rbi/handinger/models/workers/webhook_execution_list.rbi

@@ -0,0 +1,64 @@
+# typed: strong
+
+module Handinger
+  module Models
+    module Workers
+      class WebhookExecutionList < Handinger::Internal::Type::BaseModel
+        OrHash =
+          T.type_alias do
+            T.any(
+              Handinger::Workers::WebhookExecutionList,
+              Handinger::Internal::AnyHash
+            )
+          end
+
+        sig { returns(T::Array[Handinger::Workers::WebhookExecution]) }
+        attr_accessor :logs
+
+        # Current page number.
+        sig { returns(Integer) }
+        attr_accessor :page
+
+        # Total number of pages available.
+        sig { returns(Integer) }
+        attr_accessor :page_count
+
+        # Total number of executions recorded.
+        sig { returns(Integer) }
+        attr_accessor :total_count
+
+        sig do
+          params(
+            logs: T::Array[Handinger::Workers::WebhookExecution::OrHash],
+            page: Integer,
+            page_count: Integer,
+            total_count: Integer
+          ).returns(T.attached_class)
+        end
+        def self.new(
+          logs:,
+          # Current page number.
+          page:,
+          # Total number of pages available.
+          page_count:,
+          # Total number of executions recorded.
+          total_count:
+        )
+        end
+
+        sig do
+          override.returns(
+            {
+              logs: T::Array[Handinger::Workers::WebhookExecution],
+              page: Integer,
+              page_count: Integer,
+              total_count: Integer
+            }
+          )
+        end
+        def to_hash
+        end
+      end
+    end
+  end
+end

data/rbi/handinger/models/workers/webhook_list_executions_params.rbi

@@ -0,0 +1,57 @@
+# typed: strong
+
+module Handinger
+  module Models
+    module Workers
+      class WebhookListExecutionsParams < Handinger::Internal::Type::BaseModel
+        extend Handinger::Internal::Type::RequestParameters::Converter
+        include Handinger::Internal::Type::RequestParameters
+
+        OrHash =
+          T.type_alias do
+            T.any(
+              Handinger::Workers::WebhookListExecutionsParams,
+              Handinger::Internal::AnyHash
+            )
+          end
+
+        sig { returns(String) }
+        attr_accessor :worker_id
+
+        # Page number (1-indexed). Defaults to 1.
+        sig { returns(T.nilable(Integer)) }
+        attr_reader :page
+
+        sig { params(page: Integer).void }
+        attr_writer :page
+
+        sig do
+          params(
+            worker_id: String,
+            page: Integer,
+            request_options: Handinger::RequestOptions::OrHash
+          ).returns(T.attached_class)
+        end
+        def self.new(
+          worker_id:,
+          # Page number (1-indexed). Defaults to 1.
+          page: nil,
+          request_options: {}
+        )
+        end
+
+        sig do
+          override.returns(
+            {
+              worker_id: String,
+              page: Integer,
+              request_options: Handinger::RequestOptions
+            }
+          )
+        end
+        def to_hash
+        end
+      end
+    end
+  end
+end

data/rbi/handinger/models/workers/webhook_regenerate_token_params.rbi

@@ -0,0 +1,40 @@
+# typed: strong
+
+module Handinger
+  module Models
+    module Workers
+      class WebhookRegenerateTokenParams < Handinger::Internal::Type::BaseModel
+        extend Handinger::Internal::Type::RequestParameters::Converter
+        include Handinger::Internal::Type::RequestParameters
+
+        OrHash =
+          T.type_alias do
+            T.any(
+              Handinger::Workers::WebhookRegenerateTokenParams,
+              Handinger::Internal::AnyHash
+            )
+          end
+
+        sig { returns(String) }
+        attr_accessor :worker_id
+
+        sig do
+          params(
+            worker_id: String,
+            request_options: Handinger::RequestOptions::OrHash
+          ).returns(T.attached_class)
+        end
+        def self.new(worker_id:, request_options: {})
+        end
+
+        sig do
+          override.returns(
+            { worker_id: String, request_options: Handinger::RequestOptions }
+          )
+        end
+        def to_hash
+        end
+      end
+    end
+  end
+end

data/rbi/handinger/models/workers/webhook_retrieve_params.rbi

@@ -0,0 +1,40 @@
+# typed: strong
+
+module Handinger
+  module Models
+    module Workers
+      class WebhookRetrieveParams < Handinger::Internal::Type::BaseModel
+        extend Handinger::Internal::Type::RequestParameters::Converter
+        include Handinger::Internal::Type::RequestParameters
+
+        OrHash =
+          T.type_alias do
+            T.any(
+              Handinger::Workers::WebhookRetrieveParams,
+              Handinger::Internal::AnyHash
+            )
+          end
+
+        sig { returns(String) }
+        attr_accessor :worker_id
+
+        sig do
+          params(
+            worker_id: String,
+            request_options: Handinger::RequestOptions::OrHash
+          ).returns(T.attached_class)
+        end
+        def self.new(worker_id:, request_options: {})
+        end
+
+        sig do
+          override.returns(
+            { worker_id: String, request_options: Handinger::RequestOptions }
+          )
+        end
+        def to_hash
+        end
+      end
+    end
+  end
+end

data/rbi/handinger/models/workers/webhook_update_params.rbi

@@ -0,0 +1,40 @@
+# typed: strong
+
+module Handinger
+  module Models
+    module Workers
+      class WebhookUpdateParams < Handinger::Models::Workers::UpdateWebhook
+        extend Handinger::Internal::Type::RequestParameters::Converter
+        include Handinger::Internal::Type::RequestParameters
+
+        OrHash =
+          T.type_alias do
+            T.any(
+              Handinger::Workers::WebhookUpdateParams,
+              Handinger::Internal::AnyHash
+            )
+          end
+
+        sig { returns(String) }
+        attr_accessor :worker_id
+
+        sig do
+          params(
+            worker_id: String,
+            request_options: Handinger::RequestOptions::OrHash
+          ).returns(T.attached_class)
+        end
+        def self.new(worker_id:, request_options: {})
+        end
+
+        sig do
+          override.returns(
+            { worker_id: String, request_options: Handinger::RequestOptions }
+          )
+        end
+        def to_hash
+        end
+      end
+    end
+  end
+end

data/rbi/handinger/resources/workers/webhooks.rbi

@@ -0,0 +1,101 @@
+# typed: strong
+
+module Handinger
+  module Resources
+    class Workers
+      # Configure outbound webhooks delivered when a worker's tasks complete.
+      class Webhooks
+        # Retrieve the webhook URL and shared token configured for a worker. Both fields
+        # are `null` when no webhook is configured. Only the worker creator can read the
+        # webhook configuration.
+        sig do
+          params(
+            worker_id: String,
+            request_options: Handinger::RequestOptions::OrHash
+          ).returns(Handinger::Workers::Webhook)
+        end
+        def retrieve(
+          # Worker id returned by the create worker endpoint.
+          worker_id,
+          request_options: {}
+        )
+        end
+
+        # Set or replace the webhook URL for a worker. A fresh token is generated the
+        # first time a URL is set; subsequent updates keep the existing token. Pass
+        # `url: null` to clear the webhook (use the dedicated DELETE for the same effect).
+        # Only the worker creator can update the webhook.
+        sig do
+          params(
+            worker_id: String,
+            url: T.nilable(String),
+            request_options: Handinger::RequestOptions::OrHash
+          ).returns(Handinger::Workers::Webhook)
+        end
+        def update(
+          # Worker id returned by the create worker endpoint.
+          worker_id,
+          # HTTPS endpoint Handinger should POST to when a task finishes. Pass `null` to
+          # remove the webhook and clear its token.
+          url:,
+          request_options: {}
+        )
+        end
+
+        # Remove the webhook from a worker. Both `url` and `token` are cleared and no
+        # further deliveries are attempted. Only the worker creator can delete the
+        # webhook.
+        sig do
+          params(
+            worker_id: String,
+            request_options: Handinger::RequestOptions::OrHash
+          ).returns(Handinger::Workers::Webhook)
+        end
+        def delete(
+          # Worker id returned by the create worker endpoint.
+          worker_id,
+          request_options: {}
+        )
+        end
+
+        # List recent webhook delivery attempts for a worker, newest first, paginated 50
+        # per page. Only the worker creator can read execution history.
+        sig do
+          params(
+            worker_id: String,
+            page: Integer,
+            request_options: Handinger::RequestOptions::OrHash
+          ).returns(Handinger::Workers::WebhookExecutionList)
+        end
+        def list_executions(
+          # Worker id returned by the create worker endpoint.
+          worker_id,
+          # Page number (1-indexed). Defaults to 1.
+          page: nil,
+          request_options: {}
+        )
+        end
+
+        # Issue a new shared token for the webhook, invalidating the previous one. The
+        # webhook URL is preserved. Only the worker creator can regenerate the token.
+        sig do
+          params(
+            worker_id: String,
+            request_options: Handinger::RequestOptions::OrHash
+          ).returns(Handinger::Workers::Webhook)
+        end
+        def regenerate_token(
+          # Worker id returned by the create worker endpoint.
+          worker_id,
+          request_options: {}
+        )
+        end
+
+        # @api private
+        sig { params(client: Handinger::Client).returns(T.attached_class) }
+        def self.new(client:)
+        end
+      end
+    end
+  end
+end

data/rbi/handinger/resources/workers.rbi

@@ -8,6 +8,10 @@ module Handinger
       sig { returns(Handinger::Resources::Workers::Schedules) }
       attr_reader :schedules
 
+      # Configure outbound webhooks delivered when a worker's tasks complete.
+      sig { returns(Handinger::Resources::Workers::Webhooks) }
+      attr_reader :webhooks
+
       # Create a new worker. The worker is a reusable agent template; tasks are runs
       # against this template. Use `POST /tasks` to actually run the agent.
       sig do

data/sig/handinger/models/workers/update_webhook.rbs

@@ -0,0 +1,15 @@
+module Handinger
+  module Models
+    module Workers
+      type update_webhook = { url: String? }
+
+      class UpdateWebhook < Handinger::Internal::Type::BaseModel
+        attr_accessor url: String?
+
+        def initialize: (url: String?) -> void
+
+        def to_hash: -> { url: String? }
+      end
+    end
+  end
+end

data/sig/handinger/models/workers/webhook.rbs

@@ -0,0 +1,17 @@
+module Handinger
+  module Models
+    module Workers
+      type webhook = { token: String?, url: String? }
+
+      class Webhook < Handinger::Internal::Type::BaseModel
+        attr_accessor token: String?
+
+        attr_accessor url: String?
+
+        def initialize: (token: String?, url: String?) -> void
+
+        def to_hash: -> { token: String?, url: String? }
+      end
+    end
+  end
+end

data/sig/handinger/models/workers/webhook_delete_params.rbs

@@ -0,0 +1,25 @@
+module Handinger
+  module Models
+    module Workers
+      type webhook_delete_params =
+        { worker_id: String } & Handinger::Internal::Type::request_parameters
+
+      class WebhookDeleteParams < Handinger::Internal::Type::BaseModel
+        extend Handinger::Internal::Type::RequestParameters::Converter
+        include Handinger::Internal::Type::RequestParameters
+
+        attr_accessor worker_id: String
+
+        def initialize: (
+          worker_id: String,
+          ?request_options: Handinger::request_opts
+        ) -> void
+
+        def to_hash: -> {
+          worker_id: String,
+          request_options: Handinger::RequestOptions
+        }
+      end
+    end
+  end
+end

data/sig/handinger/models/workers/webhook_execution.rbs

@@ -0,0 +1,78 @@
+module Handinger
+  module Models
+    module Workers
+      type webhook_execution =
+        {
+          id: String,
+          created_at: Time,
+          duration_ms: Integer,
+          error_message: String?,
+          request_status: Handinger::Models::Workers::WebhookExecution::request_status,
+          response_status: Integer?,
+          task_id: String?,
+          task_title: String?,
+          url: String,
+          worker_id: String
+        }
+
+      class WebhookExecution < Handinger::Internal::Type::BaseModel
+        attr_accessor id: String
+
+        attr_accessor created_at: Time
+
+        attr_accessor duration_ms: Integer
+
+        attr_accessor error_message: String?
+
+        attr_accessor request_status: Handinger::Models::Workers::WebhookExecution::request_status
+
+        attr_accessor response_status: Integer?
+
+        attr_accessor task_id: String?
+
+        attr_accessor task_title: String?
+
+        attr_accessor url: String
+
+        attr_accessor worker_id: String
+
+        def initialize: (
+          id: String,
+          created_at: Time,
+          duration_ms: Integer,
+          error_message: String?,
+          request_status: Handinger::Models::Workers::WebhookExecution::request_status,
+          response_status: Integer?,
+          task_id: String?,
+          task_title: String?,
+          url: String,
+          worker_id: String
+        ) -> void
+
+        def to_hash: -> {
+          id: String,
+          created_at: Time,
+          duration_ms: Integer,
+          error_message: String?,
+          request_status: Handinger::Models::Workers::WebhookExecution::request_status,
+          response_status: Integer?,
+          task_id: String?,
+          task_title: String?,
+          url: String,
+          worker_id: String
+        }
+
+        type request_status = :success | :error
+
+        module RequestStatus
+          extend Handinger::Internal::Type::Enum
+
+          SUCCESS: :success
+          ERROR: :error
+
+          def self?.values: -> ::Array[Handinger::Models::Workers::WebhookExecution::request_status]
+        end
+      end
+    end
+  end
+end

data/sig/handinger/models/workers/webhook_execution_list.rbs

@@ -0,0 +1,37 @@
+module Handinger
+  module Models
+    module Workers
+      type webhook_execution_list =
+        {
+          logs: ::Array[Handinger::Workers::WebhookExecution],
+          page: Integer,
+          page_count: Integer,
+          total_count: Integer
+        }
+
+      class WebhookExecutionList < Handinger::Internal::Type::BaseModel
+        attr_accessor logs: ::Array[Handinger::Workers::WebhookExecution]
+
+        attr_accessor page: Integer
+
+        attr_accessor page_count: Integer
+
+        attr_accessor total_count: Integer
+
+        def initialize: (
+          logs: ::Array[Handinger::Workers::WebhookExecution],
+          page: Integer,
+          page_count: Integer,
+          total_count: Integer
+        ) -> void
+
+        def to_hash: -> {
+          logs: ::Array[Handinger::Workers::WebhookExecution],
+          page: Integer,
+          page_count: Integer,
+          total_count: Integer
+        }
+      end
+    end
+  end
+end