handinger 0.5.0 → 0.7.0

data/lib/handinger/resources/workers/webhooks.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+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.
+        #
+        # @overload retrieve(worker_id, request_options: {})
+        #
+        # @param worker_id [String] Worker id returned by the create worker endpoint.
+        #
+        # @param request_options [Handinger::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [Handinger::Models::Workers::Webhook]
+        #
+        # @see Handinger::Models::Workers::WebhookRetrieveParams
+        def retrieve(worker_id, params = {})
+          @client.request(
+            method: :get,
+            path: ["api/workers/%1$s/webhook", worker_id],
+            model: Handinger::Workers::Webhook,
+            options: params[:request_options]
+          )
+        end
+
+        # Some parameter documentations has been truncated, see
+        # {Handinger::Models::Workers::WebhookUpdateParams} for more details.
+        #
+        # 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.
+        #
+        # @overload update(worker_id, url:, request_options: {})
+        #
+        # @param worker_id [String] Worker id returned by the create worker endpoint.
+        #
+        # @param url [String, nil] HTTPS endpoint Handinger should POST to when a task finishes. Pass `null` to rem
+        #
+        # @param request_options [Handinger::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [Handinger::Models::Workers::Webhook]
+        #
+        # @see Handinger::Models::Workers::WebhookUpdateParams
+        def update(worker_id, params)
+          parsed, options = Handinger::Workers::WebhookUpdateParams.dump_request(params)
+          @client.request(
+            method: :put,
+            path: ["api/workers/%1$s/webhook", worker_id],
+            body: parsed,
+            model: Handinger::Workers::Webhook,
+            options: 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.
+        #
+        # @overload delete(worker_id, request_options: {})
+        #
+        # @param worker_id [String] Worker id returned by the create worker endpoint.
+        #
+        # @param request_options [Handinger::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [Handinger::Models::Workers::Webhook]
+        #
+        # @see Handinger::Models::Workers::WebhookDeleteParams
+        def delete(worker_id, params = {})
+          @client.request(
+            method: :delete,
+            path: ["api/workers/%1$s/webhook", worker_id],
+            model: Handinger::Workers::Webhook,
+            options: params[: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.
+        #
+        # @overload list_executions(worker_id, page: nil, request_options: {})
+        #
+        # @param worker_id [String] Worker id returned by the create worker endpoint.
+        #
+        # @param page [Integer] Page number (1-indexed). Defaults to 1.
+        #
+        # @param request_options [Handinger::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [Handinger::Models::Workers::WebhookExecutionList]
+        #
+        # @see Handinger::Models::Workers::WebhookListExecutionsParams
+        def list_executions(worker_id, params = {})
+          parsed, options = Handinger::Workers::WebhookListExecutionsParams.dump_request(params)
+          query = Handinger::Internal::Util.encode_query_params(parsed)
+          @client.request(
+            method: :get,
+            path: ["api/workers/%1$s/webhook/executions", worker_id],
+            query: query,
+            model: Handinger::Workers::WebhookExecutionList,
+            options: 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.
+        #
+        # @overload regenerate_token(worker_id, request_options: {})
+        #
+        # @param worker_id [String] Worker id returned by the create worker endpoint.
+        #
+        # @param request_options [Handinger::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [Handinger::Models::Workers::Webhook]
+        #
+        # @see Handinger::Models::Workers::WebhookRegenerateTokenParams
+        def regenerate_token(worker_id, params = {})
+          @client.request(
+            method: :post,
+            path: ["api/workers/%1$s/webhook/regenerate-token", worker_id],
+            model: Handinger::Workers::Webhook,
+            options: params[:request_options]
+          )
+        end
+
+        # @api private
+        #
+        # @param client [Handinger::Client]
+        def initialize(client:)
+          @client = client
+        end
+      end
+    end
+  end
+end

data/lib/handinger/resources/workers.rb

@@ -8,6 +8,10 @@ module Handinger
       # @return [Handinger::Resources::Workers::Schedules]
       attr_reader :schedules
 
+      # Configure outbound webhooks delivered when a worker's tasks complete.
+      # @return [Handinger::Resources::Workers::Webhooks]
+      attr_reader :webhooks
+
       # Some parameter documentations has been truncated, see
       # {Handinger::Models::WorkerCreateParams} for more details.
       #
@@ -159,6 +163,7 @@ module Handinger
       def initialize(client:)
         @client = client
         @schedules = Handinger::Resources::Workers::Schedules.new(client: client)
+        @webhooks = Handinger::Resources::Workers::Webhooks.new(client: client)
       end
     end
   end

data/lib/handinger/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Handinger
-  VERSION = "0.5.0"
+  VERSION = "0.7.0"
 end

data/lib/handinger.rb

@@ -54,6 +54,7 @@ require_relative "handinger/internal/transport/pooled_net_requester"
 require_relative "handinger/client"
 require_relative "handinger/models/create_task"
 require_relative "handinger/models/create_worker"
+require_relative "handinger/models/workers/update_webhook"
 require_relative "handinger/models/update_worker"
 require_relative "handinger/models/delete_task_response"
 require_relative "handinger/models/delete_worker_response"
@@ -73,6 +74,14 @@ require_relative "handinger/models/workers/schedule_cancel_response"
 require_relative "handinger/models/workers/schedule_create_params"
 require_relative "handinger/models/workers/schedule_list_params"
 require_relative "handinger/models/workers/schedule_list_response"
+require_relative "handinger/models/workers/webhook"
+require_relative "handinger/models/workers/webhook_delete_params"
+require_relative "handinger/models/workers/webhook_execution"
+require_relative "handinger/models/workers/webhook_execution_list"
+require_relative "handinger/models/workers/webhook_list_executions_params"
+require_relative "handinger/models/workers/webhook_regenerate_token_params"
+require_relative "handinger/models/workers/webhook_retrieve_params"
+require_relative "handinger/models/workers/webhook_update_params"
 require_relative "handinger/models/workers/worker_schedule"
 require_relative "handinger/models/worker_template"
 require_relative "handinger/models/worker_update_params"
@@ -80,3 +89,4 @@ require_relative "handinger/models"
 require_relative "handinger/resources/tasks"
 require_relative "handinger/resources/workers"
 require_relative "handinger/resources/workers/schedules"
+require_relative "handinger/resources/workers/webhooks"

data/rbi/handinger/models/worker.rbi

@@ -27,7 +27,7 @@ module Handinger
       sig { returns(T::Hash[Symbol, T.anything]) }
       attr_accessor :metadata
 
-      sig { returns(Handinger::Worker::Object::TaggedSymbol) }
+      sig { returns(Symbol) }
       attr_accessor :object
 
       sig { returns(T::Array[Handinger::Worker::Output]) }
@@ -67,7 +67,6 @@ module Handinger
           incomplete_details: NilClass,
           messages: T::Array[T.anything],
           metadata: T::Hash[Symbol, T.anything],
-          object: Handinger::Worker::Object::OrSymbol,
           output: T::Array[Handinger::Worker::Output::OrHash],
           output_text: String,
           running: T::Boolean,
@@ -75,7 +74,8 @@ module Handinger
           status: Handinger::Worker::Status::OrSymbol,
           structured_output: T.nilable(T::Hash[Symbol, T.anything]),
           url: String,
-          usage: Handinger::Worker::Usage::OrHash
+          usage: Handinger::Worker::Usage::OrHash,
+          object: Symbol
         ).returns(T.attached_class)
       end
       def self.new(
@@ -86,7 +86,6 @@ module Handinger
         incomplete_details:,
         messages:,
         metadata:,
-        object:,
         output:,
         output_text:,
         running:,
@@ -95,7 +94,8 @@ module Handinger
         structured_output:,
         # Web URL of the worker in the Handinger dashboard.
         url:,
-        usage: nil
+        usage: nil,
+        object: :worker
       )
       end
 
@@ -109,7 +109,7 @@ module Handinger
             incomplete_details: NilClass,
             messages: T::Array[T.anything],
             metadata: T::Hash[Symbol, T.anything],
-            object: Handinger::Worker::Object::TaggedSymbol,
+            object: Symbol,
             output: T::Array[Handinger::Worker::Output],
             output_text: String,
             running: T::Boolean,
@@ -158,21 +158,6 @@ module Handinger
         end
       end
 
-      module Object
-        extend Handinger::Internal::Type::Enum
-
-        TaggedSymbol = T.type_alias { T.all(Symbol, Handinger::Worker::Object) }
-        OrSymbol = T.type_alias { T.any(Symbol, String) }
-
-        WORKER = T.let(:worker, Handinger::Worker::Object::TaggedSymbol)
-
-        sig do
-          override.returns(T::Array[Handinger::Worker::Object::TaggedSymbol])
-        end
-        def self.values
-        end
-      end
-
       class Output < Handinger::Internal::Type::BaseModel
         OrHash =
           T.type_alias do
@@ -185,25 +170,31 @@ module Handinger
         sig { returns(T::Array[Handinger::Worker::Output::Content]) }
         attr_accessor :content
 
-        sig { returns(Handinger::Worker::Output::Role::TaggedSymbol) }
+        sig { returns(Symbol) }
         attr_accessor :role
 
-        sig { returns(Handinger::Worker::Output::Status::TaggedSymbol) }
+        sig { returns(Symbol) }
         attr_accessor :status
 
-        sig { returns(Handinger::Worker::Output::Type::TaggedSymbol) }
+        sig { returns(Symbol) }
         attr_accessor :type
 
         sig do
           params(
             id: String,
             content: T::Array[Handinger::Worker::Output::Content::OrHash],
-            role: Handinger::Worker::Output::Role::OrSymbol,
-            status: Handinger::Worker::Output::Status::OrSymbol,
-            type: Handinger::Worker::Output::Type::OrSymbol
+            role: Symbol,
+            status: Symbol,
+            type: Symbol
           ).returns(T.attached_class)
         end
-        def self.new(id:, content:, role:, status:, type:)
+        def self.new(
+          id:,
+          content:,
+          role: :assistant,
+          status: :completed,
+          type: :message
+        )
         end
 
         sig do
@@ -211,9 +202,9 @@ module Handinger
             {
               id: String,
               content: T::Array[Handinger::Worker::Output::Content],
-              role: Handinger::Worker::Output::Role::TaggedSymbol,
-              status: Handinger::Worker::Output::Status::TaggedSymbol,
-              type: Handinger::Worker::Output::Type::TaggedSymbol
+              role: Symbol,
+              status: Symbol,
+              type: Symbol
             }
           )
         end
@@ -232,111 +223,16 @@ module Handinger
           sig { returns(String) }
           attr_accessor :text
 
-          sig do
-            returns(Handinger::Worker::Output::Content::Type::TaggedSymbol)
-          end
+          sig { returns(Symbol) }
           attr_accessor :type
 
-          sig do
-            params(
-              text: String,
-              type: Handinger::Worker::Output::Content::Type::OrSymbol
-            ).returns(T.attached_class)
-          end
-          def self.new(text:, type:)
+          sig { params(text: String, type: Symbol).returns(T.attached_class) }
+          def self.new(text:, type: :output_text)
           end
 
-          sig do
-            override.returns(
-              {
-                text: String,
-                type: Handinger::Worker::Output::Content::Type::TaggedSymbol
-              }
-            )
-          end
+          sig { override.returns({ text: String, type: Symbol }) }
           def to_hash
           end
-
-          module Type
-            extend Handinger::Internal::Type::Enum
-
-            TaggedSymbol =
-              T.type_alias do
-                T.all(Symbol, Handinger::Worker::Output::Content::Type)
-              end
-            OrSymbol = T.type_alias { T.any(Symbol, String) }
-
-            OUTPUT_TEXT =
-              T.let(
-                :output_text,
-                Handinger::Worker::Output::Content::Type::TaggedSymbol
-              )
-
-            sig do
-              override.returns(
-                T::Array[Handinger::Worker::Output::Content::Type::TaggedSymbol]
-              )
-            end
-            def self.values
-            end
-          end
-        end
-
-        module Role
-          extend Handinger::Internal::Type::Enum
-
-          TaggedSymbol =
-            T.type_alias { T.all(Symbol, Handinger::Worker::Output::Role) }
-          OrSymbol = T.type_alias { T.any(Symbol, String) }
-
-          ASSISTANT =
-            T.let(:assistant, Handinger::Worker::Output::Role::TaggedSymbol)
-
-          sig do
-            override.returns(
-              T::Array[Handinger::Worker::Output::Role::TaggedSymbol]
-            )
-          end
-          def self.values
-          end
-        end
-
-        module Status
-          extend Handinger::Internal::Type::Enum
-
-          TaggedSymbol =
-            T.type_alias { T.all(Symbol, Handinger::Worker::Output::Status) }
-          OrSymbol = T.type_alias { T.any(Symbol, String) }
-
-          COMPLETED =
-            T.let(:completed, Handinger::Worker::Output::Status::TaggedSymbol)
-
-          sig do
-            override.returns(
-              T::Array[Handinger::Worker::Output::Status::TaggedSymbol]
-            )
-          end
-          def self.values
-          end
-        end
-
-        module Type
-          extend Handinger::Internal::Type::Enum
-
-          TaggedSymbol =
-            T.type_alias { T.all(Symbol, Handinger::Worker::Output::Type) }
-          OrSymbol = T.type_alias { T.any(Symbol, String) }
-
-          MESSAGE =
-            T.let(:message, Handinger::Worker::Output::Type::TaggedSymbol)
-
-          sig do
-            override.returns(
-              T::Array[Handinger::Worker::Output::Type::TaggedSymbol]
-            )
-          end
-          def self.values
-          end
         end
       end
 
@@ -352,7 +248,7 @@ module Handinger
         sig { returns(T.nilable(String)) }
         attr_accessor :title
 
-        sig { returns(Handinger::Worker::Source::Type::TaggedSymbol) }
+        sig { returns(Symbol) }
         attr_accessor :type
 
         sig { returns(String) }
@@ -362,43 +258,20 @@ module Handinger
           params(
             id: String,
             title: T.nilable(String),
-            type: Handinger::Worker::Source::Type::OrSymbol,
-            url: String
+            url: String,
+            type: Symbol
           ).returns(T.attached_class)
         end
-        def self.new(id:, title:, type:, url:)
+        def self.new(id:, title:, url:, type: :url)
         end
 
         sig do
           override.returns(
-            {
-              id: String,
-              title: T.nilable(String),
-              type: Handinger::Worker::Source::Type::TaggedSymbol,
-              url: String
-            }
+            { id: String, title: T.nilable(String), type: Symbol, url: String }
           )
         end
         def to_hash
         end
-
-        module Type
-          extend Handinger::Internal::Type::Enum
-
-          TaggedSymbol =
-            T.type_alias { T.all(Symbol, Handinger::Worker::Source::Type) }
-          OrSymbol = T.type_alias { T.any(Symbol, String) }
-
-          URL = T.let(:url, Handinger::Worker::Source::Type::TaggedSymbol)
-
-          sig do
-            override.returns(
-              T::Array[Handinger::Worker::Source::Type::TaggedSymbol]
-            )
-          end
-          def self.values
-          end
-        end
       end
 
       module Status

data/rbi/handinger/models/workers/update_webhook.rbi

@@ -0,0 +1,34 @@
+# typed: strong
+
+module Handinger
+  module Models
+    module Workers
+      class UpdateWebhook < Handinger::Internal::Type::BaseModel
+        OrHash =
+          T.type_alias do
+            T.any(
+              Handinger::Workers::UpdateWebhook,
+              Handinger::Internal::AnyHash
+            )
+          end
+
+        # HTTPS endpoint Handinger should POST to when a task finishes. Pass `null` to
+        # remove the webhook and clear its token.
+        sig { returns(T.nilable(String)) }
+        attr_accessor :url
+
+        sig { params(url: T.nilable(String)).returns(T.attached_class) }
+        def self.new(
+          # HTTPS endpoint Handinger should POST to when a task finishes. Pass `null` to
+          # remove the webhook and clear its token.
+          url:
+        )
+        end
+
+        sig { override.returns({ url: T.nilable(String) }) }
+        def to_hash
+        end
+      end
+    end
+  end
+end

data/rbi/handinger/models/workers/webhook.rbi

@@ -0,0 +1,45 @@
+# typed: strong
+
+module Handinger
+  module Models
+    module Workers
+      class Webhook < Handinger::Internal::Type::BaseModel
+        OrHash =
+          T.type_alias do
+            T.any(Handinger::Workers::Webhook, Handinger::Internal::AnyHash)
+          end
+
+        # Shared secret sent in the `X-Handinger-Token` header on each delivery. `null`
+        # when no webhook is configured.
+        sig { returns(T.nilable(String)) }
+        attr_accessor :token
+
+        # HTTPS endpoint that receives webhook deliveries when a task completes. `null`
+        # when no webhook is configured.
+        sig { returns(T.nilable(String)) }
+        attr_accessor :url
+
+        sig do
+          params(token: T.nilable(String), url: T.nilable(String)).returns(
+            T.attached_class
+          )
+        end
+        def self.new(
+          # Shared secret sent in the `X-Handinger-Token` header on each delivery. `null`
+          # when no webhook is configured.
+          token:,
+          # HTTPS endpoint that receives webhook deliveries when a task completes. `null`
+          # when no webhook is configured.
+          url:
+        )
+        end
+
+        sig do
+          override.returns({ token: T.nilable(String), url: T.nilable(String) })
+        end
+        def to_hash
+        end
+      end
+    end
+  end
+end

data/rbi/handinger/models/workers/webhook_delete_params.rbi

@@ -0,0 +1,40 @@
+# typed: strong
+
+module Handinger
+  module Models
+    module Workers
+      class WebhookDeleteParams < Handinger::Internal::Type::BaseModel
+        extend Handinger::Internal::Type::RequestParameters::Converter
+        include Handinger::Internal::Type::RequestParameters
+
+        OrHash =
+          T.type_alias do
+            T.any(
+              Handinger::Workers::WebhookDeleteParams,
+              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