handinger 0.1.0 → 0.3.0

data/lib/handinger/models/task_with_turns.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module Handinger
+  module Models
+    # @see Handinger::Resources::Tasks#retrieve
+    class TaskWithTurns < Handinger::Internal::Type::BaseModel
+      # @!attribute task
+      #
+      #   @return [Handinger::Models::Task]
+      required :task, -> { Handinger::Task }
+
+      # @!attribute turns
+      #
+      #   @return [Array<Handinger::Models::TaskWithTurns::Turn>]
+      required :turns, -> { Handinger::Internal::Type::ArrayOf[Handinger::TaskWithTurns::Turn] }
+
+      # @!method initialize(task:, turns:)
+      #   @param task [Handinger::Models::Task]
+      #   @param turns [Array<Handinger::Models::TaskWithTurns::Turn>]
+
+      class Turn < Handinger::Internal::Type::BaseModel
+        # @!attribute id
+        #
+        #   @return [String]
+        required :id, String
+
+        # @!attribute completed_at
+        #
+        #   @return [String, nil]
+        required :completed_at, String, api_name: :completedAt, nil?: true
+
+        # @!attribute credits
+        #
+        #   @return [Float]
+        required :credits, Float
+
+        # @!attribute duration_ms
+        #
+        #   @return [Integer]
+        required :duration_ms, Integer, api_name: :durationMs
+
+        # @!attribute input
+        #
+        #   @return [String]
+        required :input, String
+
+        # @!attribute input_tokens
+        #
+        #   @return [Integer]
+        required :input_tokens, Integer, api_name: :inputTokens
+
+        # @!attribute output_text
+        #
+        #   @return [String]
+        required :output_text, String, api_name: :outputText
+
+        # @!attribute output_tokens
+        #
+        #   @return [Integer]
+        required :output_tokens, Integer, api_name: :outputTokens
+
+        # @!attribute role
+        #
+        #   @return [String]
+        required :role, String
+
+        # @!attribute seq
+        #
+        #   @return [Integer]
+        required :seq, Integer
+
+        # @!attribute started_at
+        #
+        #   @return [String]
+        required :started_at, String, api_name: :startedAt
+
+        # @!attribute status
+        #
+        #   @return [String]
+        required :status, String
+
+        # @!attribute structured_output
+        #
+        #   @return [Hash{Symbol=>Object}, nil]
+        required :structured_output,
+                 Handinger::Internal::Type::HashOf[Handinger::Internal::Type::Unknown],
+                 api_name: :structuredOutput,
+                 nil?: true
+
+        # @!attribute task_id
+        #
+        #   @return [String]
+        required :task_id, String, api_name: :taskId
+
+        # @!method initialize(id:, completed_at:, credits:, duration_ms:, input:, input_tokens:, output_text:, output_tokens:, role:, seq:, started_at:, status:, structured_output:, task_id:)
+        #   @param id [String]
+        #   @param completed_at [String, nil]
+        #   @param credits [Float]
+        #   @param duration_ms [Integer]
+        #   @param input [String]
+        #   @param input_tokens [Integer]
+        #   @param output_text [String]
+        #   @param output_tokens [Integer]
+        #   @param role [String]
+        #   @param seq [Integer]
+        #   @param started_at [String]
+        #   @param status [String]
+        #   @param structured_output [Hash{Symbol=>Object}, nil]
+        #   @param task_id [String]
+      end
+    end
+  end
+end

data/lib/handinger/models/update_worker.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Handinger
+  module Models
+    class UpdateWorker < Handinger::Internal::Type::BaseModel
+      # @!attribute instructions
+      #   Replaces the persistent system prompt. Subsequent tasks pick up the new
+      #   instructions immediately; in-flight tasks keep using the previous version.
+      #
+      #   @return [String, nil]
+      optional :instructions, String
+
+      # @!attribute output_schema
+      #   Replace the worker's structured output schema. Pass `null` to clear it and
+      #   return to free-form text responses.
+      #
+      #   @return [Hash{Symbol=>Object}, nil]
+      optional :output_schema,
+               Handinger::Internal::Type::HashOf[Handinger::Internal::Type::Unknown],
+               api_name: :outputSchema,
+               nil?: true
+
+      # @!attribute summary
+      #   Replaces the worker's short one-line summary.
+      #
+      #   @return [String, nil]
+      optional :summary, String
+
+      # @!attribute title
+      #   New display name for the worker.
+      #
+      #   @return [String, nil]
+      optional :title, String
+
+      # @!attribute visibility
+      #   Change visibility between `public` (any org member can run tasks) and `private`
+      #   (only invited members).
+      #
+      #   @return [Symbol, Handinger::Models::UpdateWorker::Visibility, nil]
+      optional :visibility, enum: -> { Handinger::UpdateWorker::Visibility }
+
+      # @!method initialize(instructions: nil, output_schema: nil, summary: nil, title: nil, visibility: nil)
+      #   Some parameter documentations has been truncated, see
+      #   {Handinger::Models::UpdateWorker} for more details.
+      #
+      #   @param instructions [String] Replaces the persistent system prompt. Subsequent tasks pick up the new instruct
+      #
+      #   @param output_schema [Hash{Symbol=>Object}, nil] Replace the worker's structured output schema. Pass `null` to clear it and retur
+      #
+      #   @param summary [String] Replaces the worker's short one-line summary.
+      #
+      #   @param title [String] New display name for the worker.
+      #
+      #   @param visibility [Symbol, Handinger::Models::UpdateWorker::Visibility] Change visibility between `public` (any org member can run tasks) and `private`
+
+      # Change visibility between `public` (any org member can run tasks) and `private`
+      # (only invited members).
+      #
+      # @see Handinger::Models::UpdateWorker#visibility
+      module Visibility
+        extend Handinger::Internal::Type::Enum
+
+        PUBLIC = :public
+        PRIVATE = :private
+
+        # @!method self.values
+        #   @return [Array<Symbol>]
+      end
+    end
+  end
+end

data/lib/handinger/models/worker.rb

@@ -2,7 +2,7 @@
 
 module Handinger
   module Models
-    # @see Handinger::Resources::Workers#create
+    # @see Handinger::Resources::Workers#retrieve
     class Worker < Handinger::Internal::Type::BaseModel
       # @!attribute id
       #
@@ -69,17 +69,19 @@ module Handinger
       #   @return [Symbol, Handinger::Models::Worker::Status]
       required :status, enum: -> { Handinger::Worker::Status }
 
-      # @!attribute costs
+      # @!attribute structured_output
       #
-      #   @return [Handinger::Models::Worker::Costs, nil]
-      optional :costs, -> { Handinger::Worker::Costs }, nil?: true
+      #   @return [Hash{Symbol=>Object}, nil]
+      required :structured_output,
+               Handinger::Internal::Type::HashOf[Handinger::Internal::Type::Unknown],
+               nil?: true
 
       # @!attribute usage
       #
       #   @return [Handinger::Models::Worker::Usage, nil]
       optional :usage, -> { Handinger::Worker::Usage }
 
-      # @!method initialize(id:, created_at:, error:, files:, incomplete_details:, messages:, metadata:, object:, output:, output_text:, running:, sources:, status:, costs: nil, usage: nil)
+      # @!method initialize(id:, created_at:, error:, files:, incomplete_details:, messages:, metadata:, object:, output:, output_text:, running:, sources:, status:, structured_output:, usage: nil)
       #   @param id [String]
       #   @param created_at [Integer, nil]
       #   @param error [nil]
@@ -93,7 +95,7 @@ module Handinger
       #   @param running [Boolean]
       #   @param sources [Array<Handinger::Models::Worker::Source>]
       #   @param status [Symbol, Handinger::Models::Worker::Status]
-      #   @param costs [Handinger::Models::Worker::Costs, nil]
+      #   @param structured_output [Hash{Symbol=>Object}, nil]
       #   @param usage [Handinger::Models::Worker::Usage]
 
       class File < Handinger::Internal::Type::BaseModel
@@ -268,77 +270,8 @@ module Handinger
         #   @return [Array<Symbol>]
       end
 
-      # @see Handinger::Models::Worker#costs
-      class Costs < Handinger::Internal::Type::BaseModel
-        # @!attribute internal_cost_usd
-        #
-        #   @return [Float]
-        required :internal_cost_usd, Float, api_name: :internalCostUsd
-
-        # @!attribute model_cost_usd
-        #
-        #   @return [Float]
-        required :model_cost_usd, Float, api_name: :modelCostUsd
-
-        # @!attribute sandbox_cost_usd
-        #
-        #   @return [Float]
-        required :sandbox_cost_usd, Float, api_name: :sandboxCostUsd
-
-        # @!attribute tool_cost_usd
-        #
-        #   @return [Float]
-        required :tool_cost_usd, Float, api_name: :toolCostUsd
-
-        # @!method initialize(internal_cost_usd:, model_cost_usd:, sandbox_cost_usd:, tool_cost_usd:)
-        #   @param internal_cost_usd [Float]
-        #   @param model_cost_usd [Float]
-        #   @param sandbox_cost_usd [Float]
-        #   @param tool_cost_usd [Float]
-      end
-
       # @see Handinger::Models::Worker#usage
       class Usage < Handinger::Internal::Type::BaseModel
-        # @!attribute cache_read_tokens
-        #
-        #   @return [Integer]
-        required :cache_read_tokens, Integer, api_name: :cacheReadTokens
-
-        # @!attribute cache_write_tokens
-        #
-        #   @return [Integer]
-        required :cache_write_tokens, Integer, api_name: :cacheWriteTokens
-
-        # @!attribute cost_usd
-        #
-        #   @return [Float]
-        required :cost_usd, Float, api_name: :costUsd
-
-        # @!attribute input_tokens
-        #
-        #   @return [Integer]
-        required :input_tokens, Integer, api_name: :inputTokens
-
-        # @!attribute output_tokens
-        #
-        #   @return [Integer]
-        required :output_tokens, Integer, api_name: :outputTokens
-
-        # @!attribute reasoning_tokens
-        #
-        #   @return [Integer]
-        required :reasoning_tokens, Integer, api_name: :reasoningTokens
-
-        # @!attribute steps
-        #
-        #   @return [Integer]
-        required :steps, Integer
-
-        # @!attribute total_tokens
-        #
-        #   @return [Integer]
-        required :total_tokens, Integer, api_name: :totalTokens
-
         # @!attribute credits
         #
         #   @return [Integer, nil]
@@ -349,15 +282,7 @@ module Handinger
         #   @return [Integer, nil]
         optional :duration_ms, Integer, api_name: :durationMs
 
-        # @!method initialize(cache_read_tokens:, cache_write_tokens:, cost_usd:, input_tokens:, output_tokens:, reasoning_tokens:, steps:, total_tokens:, credits: nil, duration_ms: nil)
-        #   @param cache_read_tokens [Integer]
-        #   @param cache_write_tokens [Integer]
-        #   @param cost_usd [Float]
-        #   @param input_tokens [Integer]
-        #   @param output_tokens [Integer]
-        #   @param reasoning_tokens [Integer]
-        #   @param steps [Integer]
-        #   @param total_tokens [Integer]
+        # @!method initialize(credits: nil, duration_ms: nil)
         #   @param credits [Integer]
         #   @param duration_ms [Integer]
       end

data/lib/handinger/models/{worker_stream_updates_params.rb → worker_delete_params.rb}

@@ -2,8 +2,8 @@
 
 module Handinger
   module Models
-    # @see Handinger::Resources::Workers#stream_updates_streaming
-    class WorkerStreamUpdatesParams < Handinger::Internal::Type::BaseModel
+    # @see Handinger::Resources::Workers#delete
+    class WorkerDeleteParams < Handinger::Internal::Type::BaseModel
       extend Handinger::Internal::Type::RequestParameters::Converter
       include Handinger::Internal::Type::RequestParameters
 

data/lib/handinger/models/worker_retrieve_email_response.rb

@@ -2,6 +2,15 @@
 
 module Handinger
   module Models
-    WorkerRetrieveEmailResponse = String
+    # @see Handinger::Resources::Workers#retrieve_email
+    class WorkerRetrieveEmailResponse < Handinger::Internal::Type::BaseModel
+      # @!attribute email
+      #
+      #   @return [String]
+      required :email, String
+
+      # @!method initialize(email:)
+      #   @param email [String]
+    end
   end
 end

data/lib/handinger/models/worker_retrieve_params.rb

@@ -13,17 +13,35 @@ module Handinger
       required :worker_id, String
 
       # @!attribute stream
-      #   Return a server-sent event stream instead of JSON.
+      #   Set to "true" to receive a server-sent event stream that replays all stored
+      #   messages and then continues with live chunks from the active task (if any)
+      #   before closing.
       #
-      #   @return [Boolean, nil]
-      optional :stream, Handinger::Internal::Type::Boolean
+      #   @return [Symbol, Handinger::Models::WorkerRetrieveParams::Stream, nil]
+      optional :stream, enum: -> { Handinger::WorkerRetrieveParams::Stream }
 
       # @!method initialize(worker_id:, stream: nil, request_options: {})
+      #   Some parameter documentations has been truncated, see
+      #   {Handinger::Models::WorkerRetrieveParams} for more details.
+      #
       #   @param worker_id [String]
       #
-      #   @param stream [Boolean] Return a server-sent event stream instead of JSON.
+      #   @param stream [Symbol, Handinger::Models::WorkerRetrieveParams::Stream] Set to "true" to receive a server-sent event stream that replays all stored mess
       #
       #   @param request_options [Handinger::RequestOptions, Hash{Symbol=>Object}]
+
+      # Set to "true" to receive a server-sent event stream that replays all stored
+      # messages and then continues with live chunks from the active task (if any)
+      # before closing.
+      module Stream
+        extend Handinger::Internal::Type::Enum
+
+        TRUE = :true
+        FALSE = :false
+
+        # @!method self.values
+        #   @return [Array<Symbol>]
+      end
     end
   end
 end

data/lib/handinger/models/worker_template.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Handinger
+  module Models
+    # @see Handinger::Resources::Workers#create
+    class WorkerTemplate < Handinger::Internal::Type::BaseModel
+      # @!attribute id
+      #
+      #   @return [String]
+      required :id, String
+
+      # @!attribute created_at
+      #
+      #   @return [String, nil]
+      required :created_at, String, api_name: :createdAt, nil?: true
+
+      # @!attribute instructions
+      #
+      #   @return [String]
+      required :instructions, String
+
+      # @!attribute organization_id
+      #
+      #   @return [String]
+      required :organization_id, String, api_name: :organizationId
+
+      # @!attribute output_schema
+      #
+      #   @return [Hash{Symbol=>Object}, nil]
+      required :output_schema,
+               Handinger::Internal::Type::HashOf[Handinger::Internal::Type::Unknown],
+               api_name: :outputSchema,
+               nil?: true
+
+      # @!attribute summary
+      #
+      #   @return [String]
+      required :summary, String
+
+      # @!attribute title
+      #
+      #   @return [String]
+      required :title, String
+
+      # @!attribute updated_at
+      #
+      #   @return [String, nil]
+      required :updated_at, String, api_name: :updatedAt, nil?: true
+
+      # @!attribute user_id
+      #
+      #   @return [String]
+      required :user_id, String, api_name: :userId
+
+      # @!attribute visibility
+      #
+      #   @return [Symbol, Handinger::Models::WorkerTemplate::Visibility]
+      required :visibility, enum: -> { Handinger::WorkerTemplate::Visibility }
+
+      # @!method initialize(id:, created_at:, instructions:, organization_id:, output_schema:, summary:, title:, updated_at:, user_id:, visibility:)
+      #   @param id [String]
+      #   @param created_at [String, nil]
+      #   @param instructions [String]
+      #   @param organization_id [String]
+      #   @param output_schema [Hash{Symbol=>Object}, nil]
+      #   @param summary [String]
+      #   @param title [String]
+      #   @param updated_at [String, nil]
+      #   @param user_id [String]
+      #   @param visibility [Symbol, Handinger::Models::WorkerTemplate::Visibility]
+
+      # @see Handinger::Models::WorkerTemplate#visibility
+      module Visibility
+        extend Handinger::Internal::Type::Enum
+
+        PUBLIC = :public
+        PRIVATE = :private
+
+        # @!method self.values
+        #   @return [Array<Symbol>]
+      end
+    end
+  end
+end

data/lib/handinger/models/{worker_continue_params.rb → worker_update_params.rb}

@@ -2,8 +2,8 @@
 
 module Handinger
   module Models
-    # @see Handinger::Resources::Workers#continue
-    class WorkerContinueParams < Handinger::Models::CreateWorker
+    # @see Handinger::Resources::Workers#update
+    class WorkerUpdateParams < Handinger::Models::UpdateWorker
       extend Handinger::Internal::Type::RequestParameters::Converter
       include Handinger::Internal::Type::RequestParameters
 

data/lib/handinger/models.rb

@@ -39,21 +39,39 @@ module Handinger
     mod.define_sorbet_constant!(const) { T.type_alias { mod.to_sorbet_type } }
   end
 
+  CreateTask = Handinger::Models::CreateTask
+
   CreateWorker = Handinger::Models::CreateWorker
 
-  Worker = Handinger::Models::Worker
+  DeleteTaskResponse = Handinger::Models::DeleteTaskResponse
+
+  DeleteWorkerResponse = Handinger::Models::DeleteWorkerResponse
+
+  Task = Handinger::Models::Task
+
+  TaskCreateParams = Handinger::Models::TaskCreateParams
+
+  TaskDeleteParams = Handinger::Models::TaskDeleteParams
+
+  TaskRetrieveParams = Handinger::Models::TaskRetrieveParams
 
-  WorkerContinueParams = Handinger::Models::WorkerContinueParams
+  TaskWithTurns = Handinger::Models::TaskWithTurns
+
+  UpdateWorker = Handinger::Models::UpdateWorker
+
+  Worker = Handinger::Models::Worker
 
   WorkerCreateParams = Handinger::Models::WorkerCreateParams
 
-  WorkerRetrieveEmailParams = Handinger::Models::WorkerRetrieveEmailParams
+  WorkerDeleteParams = Handinger::Models::WorkerDeleteParams
 
-  WorkerRetrieveFileParams = Handinger::Models::WorkerRetrieveFileParams
+  WorkerRetrieveEmailParams = Handinger::Models::WorkerRetrieveEmailParams
 
   WorkerRetrieveParams = Handinger::Models::WorkerRetrieveParams
 
   Workers = Handinger::Models::Workers
 
-  WorkerStreamUpdatesParams = Handinger::Models::WorkerStreamUpdatesParams
+  WorkerTemplate = Handinger::Models::WorkerTemplate
+
+  WorkerUpdateParams = Handinger::Models::WorkerUpdateParams
 end

data/lib/handinger/resources/tasks.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Handinger
+  module Resources
+    # Run and inspect tasks against a worker.
+    class Tasks
+      # Some parameter documentations has been truncated, see
+      # {Handinger::Models::TaskCreateParams} for more details.
+      #
+      # Run a new task against an existing worker. Send a `taskId` of a prior task to
+      # add a follow-up turn instead of starting a fresh task. Send
+      # `multipart/form-data` to attach files; the bytes are bootstrapped into the
+      # worker's workspace before the task starts.
+      #
+      # @overload create(worker_id:, instructions: nil, output_schema: nil, prompt: nil, summary: nil, task_id: nil, title: nil, visibility: nil, request_options: {})
+      #
+      # @param worker_id [String] Worker id the task belongs to.
+      #
+      # @param instructions [String] Persistent system prompt the worker uses for every task it runs.
+      #
+      # @param output_schema [Hash{Symbol=>Object}] Optional JSON Schema (Draft-07) describing the structured object the worker must
+      #
+      # @param prompt [String] Natural-language description of the worker to use for AI-generated instructions
+      #
+      # @param summary [String] Short one-line description of the worker's purpose. Auto-generated when omitted
+      #
+      # @param task_id [String] Optional client-provided task id. Reuse this id to add turns to an existing task
+      #
+      # @param title [String] Optional display name. When omitted, Handinger assigns a random dog-themed name.
+      #
+      # @param visibility [Symbol, Handinger::Models::CreateTask::Visibility] `public` (default) is visible to all org members. `private` is only visible to i
+      #
+      # @param request_options [Handinger::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [Handinger::Models::Worker]
+      #
+      # @see Handinger::Models::TaskCreateParams
+      def create(params)
+        parsed, options = Handinger::TaskCreateParams.dump_request(params)
+        @client.request(
+          method: :post,
+          path: "api/tasks",
+          body: parsed,
+          model: Handinger::Worker,
+          options: options
+        )
+      end
+
+      # Retrieve a single task and its individual turns.
+      #
+      # @overload retrieve(task_id, request_options: {})
+      #
+      # @param task_id [String] Task id returned by the create task endpoint.
+      #
+      # @param request_options [Handinger::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [Handinger::Models::TaskWithTurns]
+      #
+      # @see Handinger::Models::TaskRetrieveParams
+      def retrieve(task_id, params = {})
+        @client.request(
+          method: :get,
+          path: ["api/tasks/%1$s", task_id],
+          model: Handinger::TaskWithTurns,
+          options: params[:request_options]
+        )
+      end
+
+      # Archive a task so it stops appearing in `GET /tasks` results. Turns and files
+      # are retained for audit purposes. Only the worker creator can archive a task.
+      #
+      # @overload delete(task_id, request_options: {})
+      #
+      # @param task_id [String] Task id returned by the create task endpoint.
+      #
+      # @param request_options [Handinger::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [Handinger::Models::DeleteTaskResponse]
+      #
+      # @see Handinger::Models::TaskDeleteParams
+      def delete(task_id, params = {})
+        @client.request(
+          method: :delete,
+          path: ["api/tasks/%1$s", task_id],
+          model: Handinger::DeleteTaskResponse,
+          options: params[:request_options]
+        )
+      end
+
+      # @api private
+      #
+      # @param client [Handinger::Client]
+      def initialize(client:)
+        @client = client
+      end
+    end
+  end
+end