handinger 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7dae0342381fa57c73c63b01538c6e47a68de902e4a10b8f4bdb593ef1d9a468
-  data.tar.gz: de8803ae634451f609533050e1d0bc66d750286c1abc3c09cc34fd679926fdac
+  metadata.gz: a53acab611d6eb55ba8f32f3b21854f6d936ff7fc2bdc0bda9da0394040bd3af
+  data.tar.gz: 3f7daaeb057baa8ebf48a03e2db9a5d83706c3bdf3d46377337103be73bb569f
 SHA512:
-  metadata.gz: '091f26caa999562c9080eb8a223fc685588a7435943d2085d4c94a9ed8c89e94f2d0f4b7be1e853fefbbd52d336ee791988d2a0c7e9f60115b3e1a4520af2817'
-  data.tar.gz: 2c7991d7e71d0d129e2fa4b1656b058630e653d12411b91cc6268d8694f91d53f4e20c1297b8b72e554b95f6858167322d10eaaef06bc3b18395d0d56e7db2c7
+  metadata.gz: 22c03ed4a0641b1b16427f0928804b695cb23923534a9abb233a47a247ecd94a77f0a34553c3658de15a556979abd85e10af7ae6a7e25fe07e48234db1d63c40
+  data.tar.gz: 5e0bc25dc0a11ed63751c99f7d06ae807b778865bf5c96e6f141f9f5e40d512c95d9b740d4a99bd4ba50435f6889351659defb4340ad8fe8901c75f76bf452eb

data/CHANGELOG.md

@@ -1,5 +1,40 @@
 # Changelog
 
+## 0.3.0 (2026-05-11)
+
+Full Changelog: [v0.2.0...v0.3.0](https://github.com/Ramensoft/handinger-ruby/compare/v0.2.0...v0.3.0)
+
+### Features
+
+* Add update and delete endpoints for workers and tasks ([caa25aa](https://github.com/Ramensoft/handinger-ruby/commit/caa25aa9ff32f9ea62143cf674ca13efc6e72729))
+
+## 0.2.0 (2026-05-09)
+
+Full Changelog: [v0.1.0...v0.2.0](https://github.com/Ramensoft/handinger-ruby/compare/v0.1.0...v0.2.0)
+
+### Features
+
+* Add JSON Schema output validation and structured display ([d2d009f](https://github.com/Ramensoft/handinger-ruby/commit/d2d009fef801e296238abb13f66980523f6fe635))
+* Add worker avatars and summaries with edit UI ([9363cd1](https://github.com/Ramensoft/handinger-ruby/commit/9363cd185a2973a889324097215bff9c3f4fe59d))
+* **api:** api update ([24ba9a1](https://github.com/Ramensoft/handinger-ruby/commit/24ba9a1bacb86f4f72dc6599223678c34fb40eb8))
+* **api:** api update ([05d22fc](https://github.com/Ramensoft/handinger-ruby/commit/05d22fc5b3de4a8c4115ef234b362f667fc08eb7))
+* **api:** api update ([edee7a7](https://github.com/Ramensoft/handinger-ruby/commit/edee7a788bda863304a5b3216abdf6d9273dc95e))
+* **api:** api update ([a335064](https://github.com/Ramensoft/handinger-ruby/commit/a335064d021768f799f38c2a5d8766d42b36816c))
+* File uploads ([d7fd499](https://github.com/Ramensoft/handinger-ruby/commit/d7fd499cfc7a9d0d15875b3f4e0ebc0571177f15))
+* Le big refactor ([9631a55](https://github.com/Ramensoft/handinger-ruby/commit/9631a55979db401c85faf3d90ac827aea41dd19d))
+* Overhaul email/permissions and ids ([e686bb8](https://github.com/Ramensoft/handinger-ruby/commit/e686bb8e9de4e492083c7ca3bf47d89662bb141b))
+* support setting headers via env ([cf53d6e](https://github.com/Ramensoft/handinger-ruby/commit/cf53d6ed1323a7253e9c5ffc03047ac2b9f1aeb7))
+
+
+### Bug Fixes
+
+* avoid gzip buffering during streaming ([7d1e1bc](https://github.com/Ramensoft/handinger-ruby/commit/7d1e1bcd465f422cc6e1b5fce68c308f25030cd5))
+
+
+### Chores
+
+* **internal:** more robust bootstrap script ([61ba919](https://github.com/Ramensoft/handinger-ruby/commit/61ba919436fe1ccdf663b8822904623421ee773c))
+
 ## 0.1.0 (2026-04-23)
 
 Full Changelog: [v0.0.2...v0.1.0](https://github.com/Ramensoft/handinger-ruby/compare/v0.0.2...v0.1.0)

data/README.md

@@ -8,6 +8,8 @@ It is generated with [Stainless](https://www.stainless.com/).
 
 Documentation for releases of this gem can be found [on RubyDoc](https://gemdocs.org/gems/handinger).
 
+The REST API documentation can be found on [docs.handinger.com](https://docs.handinger.com).
+
 ## Installation
 
 To use this gem, install via Bundler by adding the following to your application's `Gemfile`:
@@ -15,7 +17,7 @@ To use this gem, install via Bundler by adding the following to your application
 <!-- x-release-please-start-version -->
 
 ```ruby
-gem "handinger", "~> 0.1.0"
+gem "handinger", "~> 0.3.0"
 ```
 
 <!-- x-release-please-end -->
@@ -30,7 +32,7 @@ handinger = Handinger::Client.new(
   api_key: ENV["HANDINGER_API_KEY"] # This is the default and can be omitted
 )
 
-worker = handinger.workers.create(input: "What's the weather today in Barcelona?")
+worker = handinger.tasks.create(worker_id: "wrk_vk81XUHKHG-qr4")
 
 puts(worker.id)
 ```
@@ -41,7 +43,7 @@ When the library is unable to connect to the API, or if the API returns a non-su
 
 ```ruby
 begin
-  worker = handinger.workers.create(input: "What's the weather today in Barcelona?")
+  task = handinger.tasks.create(worker_id: "wrk_vk81XUHKHG-qr4")
 rescue Handinger::Errors::APIConnectionError => e
   puts("The server could not be reached")
   puts(e.cause)  # an underlying Exception, likely raised within `net/http`
@@ -84,10 +86,7 @@ handinger = Handinger::Client.new(
 )
 
 # Or, configure per-request:
-handinger.workers.create(
-  input: "What's the weather today in Barcelona?",
-  request_options: {max_retries: 5}
-)
+handinger.tasks.create(worker_id: "wrk_vk81XUHKHG-qr4", request_options: {max_retries: 5})
 ```
 
 ### Timeouts
@@ -101,7 +100,7 @@ handinger = Handinger::Client.new(
 )
 
 # Or, configure per-request:
-handinger.workers.create(input: "What's the weather today in Barcelona?", request_options: {timeout: 5})
+handinger.tasks.create(worker_id: "wrk_vk81XUHKHG-qr4", request_options: {timeout: 5})
 ```
 
 On timeout, `Handinger::Errors::APITimeoutError` is raised.
@@ -132,8 +131,8 @@ Note: the `extra_` parameters of the same name overrides the documented paramete
 
 ```ruby
 worker =
-  handinger.workers.create(
-    input: "What's the weather today in Barcelona?",
+  handinger.tasks.create(
+    worker_id: "wrk_vk81XUHKHG-qr4",
     request_options: {
       extra_query: {my_query_parameter: value},
       extra_body: {my_body_parameter: value},
@@ -179,18 +178,18 @@ This library provides comprehensive [RBI](https://sorbet.org/docs/rbi) definitio
 You can provide typesafe request parameters like so:
 
 ```ruby
-handinger.workers.create(input: "What's the weather today in Barcelona?")
+handinger.tasks.create(worker_id: "wrk_vk81XUHKHG-qr4")
 ```
 
 Or, equivalently:
 
 ```ruby
 # Hashes work, but are not typesafe:
-handinger.workers.create(input: "What's the weather today in Barcelona?")
+handinger.tasks.create(worker_id: "wrk_vk81XUHKHG-qr4")
 
 # You can also splat a full Params class:
-params = Handinger::WorkerCreateParams.new(input: "What's the weather today in Barcelona?")
-handinger.workers.create(**params)
+params = Handinger::TaskCreateParams.new(worker_id: "wrk_vk81XUHKHG-qr4")
+handinger.tasks.create(**params)
 ```
 
 ### Enums
@@ -198,11 +197,11 @@ handinger.workers.create(**params)
 Since this library does not depend on `sorbet-runtime`, it cannot provide [`T::Enum`](https://sorbet.org/docs/tenum) instances. Instead, we provide "tagged symbols" instead, which is always a primitive at runtime:
 
 ```ruby
-# :low
-puts(Handinger::CreateWorker::Budget::LOW)
+# :public
+puts(Handinger::CreateWorker::Visibility::PUBLIC)
 
-# Revealed type: `T.all(Handinger::CreateWorker::Budget, Symbol)`
-T.reveal_type(Handinger::CreateWorker::Budget::LOW)
+# Revealed type: `T.all(Handinger::CreateWorker::Visibility, Symbol)`
+T.reveal_type(Handinger::CreateWorker::Visibility::PUBLIC)
 ```
 
 Enum parameters have a "relaxed" type, so you can either pass in enum constants or their literal value:
@@ -210,13 +209,13 @@ Enum parameters have a "relaxed" type, so you can either pass in enum constants
 ```ruby
 # Using the enum constants preserves the tagged type information:
 handinger.workers.create(
-  budget: Handinger::CreateWorker::Budget::LOW,
+  visibility: Handinger::CreateWorker::Visibility::PUBLIC,
   # …
 )
 
 # Literal values are also permissible:
 handinger.workers.create(
-  budget: :low,
+  visibility: :public,
   # …
 )
 ```

data/SECURITY.md

@@ -18,6 +18,10 @@ before making any information public.
 If you encounter security issues that are not directly related to SDKs but pertain to the services
 or products provided by Handinger, please follow the respective company's security reporting guidelines.
 
+### Handinger Terms and Policies
+
+Please contact support@handinger.com for any questions or concerns regarding the security of our services.
+
 ---
 
 Thank you for helping us keep the SDKs and systems they interact with secure.

data/lib/handinger/client.rb

@@ -18,9 +18,14 @@ module Handinger
     # @return [String]
     attr_reader :api_key
 
+    # Create, retrieve, and manage agent worker templates.
     # @return [Handinger::Resources::Workers]
     attr_reader :workers
 
+    # Run and inspect tasks against a worker.
+    # @return [Handinger::Resources::Tasks]
+    attr_reader :tasks
+
     # @api private
     #
     # @return [Hash{String=>String}]
@@ -58,6 +63,19 @@ module Handinger
         raise ArgumentError.new("api_key is required, and can be set via environ: \"HANDINGER_API_KEY\"")
       end
 
+      headers = {}
+      custom_headers_env = ENV["HANDINGER_CUSTOM_HEADERS"]
+      unless custom_headers_env.nil?
+        parsed = {}
+        custom_headers_env.split("\n").each do |line|
+          colon = line.index(":")
+          unless colon.nil?
+            parsed[line[0...colon].strip] = line[(colon + 1)..].strip
+          end
+        end
+        headers = parsed.merge(headers)
+      end
+
       @api_key = api_key.to_s
 
       super(
@@ -65,10 +83,12 @@ module Handinger
         timeout: timeout,
         max_retries: max_retries,
         initial_retry_delay: initial_retry_delay,
-        max_retry_delay: max_retry_delay
+        max_retry_delay: max_retry_delay,
+        headers: headers
       )
 
       @workers = Handinger::Resources::Workers.new(client: self)
+      @tasks = Handinger::Resources::Tasks.new(client: self)
     end
   end
 end

data/lib/handinger/internal/transport/base_client.rb

@@ -549,9 +549,7 @@ module Handinger
                 )
               ),
               page: T.nilable(T::Class[Handinger::Internal::Type::BasePage[Handinger::Internal::Type::BaseModel]]),
-              stream: T.nilable(
-                T::Class[Handinger::Internal::Type::BaseStream[T.anything, Handinger::Internal::Type::BaseModel]]
-              ),
+              stream: T.nilable(T::Class[T.anything]),
               model: T.nilable(Handinger::Internal::Type::Converter::Input),
               options: T.nilable(Handinger::RequestOptions::OrHash)
             }

data/lib/handinger/internal/type/base_model.rb

@@ -440,9 +440,9 @@ module Handinger
         # @example
         #   # `create_worker` is a `Handinger::CreateWorker`
         #   create_worker => {
-        #     input: input,
-        #     budget: budget,
-        #     stream: stream
+        #     instructions: instructions,
+        #     output_schema: output_schema,
+        #     prompt: prompt
         #   }
         def deconstruct_keys(keys)
           (keys || self.class.known_fields.keys)

data/lib/handinger/models/create_task.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Handinger
+  module Models
+    class CreateTask < Handinger::Models::CreateWorker
+      # @!attribute worker_id
+      #   Worker id the task belongs to.
+      #
+      #   @return [String]
+      required :worker_id, String, api_name: :workerId
+
+      # @!attribute task_id
+      #   Optional client-provided task id. Reuse this id to add turns to an existing
+      #   task.
+      #
+      #   @return [String, nil]
+      optional :task_id, String, api_name: :taskId
+
+      # @!method initialize(worker_id:, task_id: nil)
+      #   Some parameter documentations has been truncated, see
+      #   {Handinger::Models::CreateTask} for more details.
+      #
+      #   @param worker_id [String] Worker id the task belongs to.
+      #
+      #   @param task_id [String] Optional client-provided task id. Reuse this id to add turns to an existing task
+    end
+  end
+end

data/lib/handinger/models/create_worker.rb

@@ -3,34 +3,74 @@
 module Handinger
   module Models
     class CreateWorker < Handinger::Internal::Type::BaseModel
-      # @!attribute input
+      # @!attribute instructions
+      #   Persistent system prompt the worker uses for every task it runs.
       #
-      #   @return [String]
-      required :input, String
+      #   @return [String, nil]
+      optional :instructions, String
 
-      # @!attribute budget
+      # @!attribute output_schema
+      #   Optional JSON Schema (Draft-07) describing the structured object the worker must
+      #   produce. When set, every task response is validated against the schema and
+      #   exposed as `structuredOutput`.
       #
-      #   @return [Symbol, Handinger::Models::CreateWorker::Budget, nil]
-      optional :budget, enum: -> { Handinger::CreateWorker::Budget }
+      #   @return [Hash{Symbol=>Object}, nil]
+      optional :output_schema,
+               Handinger::Internal::Type::HashOf[Handinger::Internal::Type::Unknown],
+               api_name: :outputSchema
 
-      # @!attribute stream
+      # @!attribute prompt
+      #   Natural-language description of the worker to use for AI-generated instructions
+      #   when `instructions` is omitted.
       #
-      #   @return [Boolean, nil]
-      optional :stream, Handinger::Internal::Type::Boolean
+      #   @return [String, nil]
+      optional :prompt, String
 
-      # @!method initialize(input:, budget: nil, stream: nil)
-      #   @param input [String]
-      #   @param budget [Symbol, Handinger::Models::CreateWorker::Budget]
-      #   @param stream [Boolean]
+      # @!attribute summary
+      #   Short one-line description of the worker's purpose. Auto-generated when omitted
+      #   and a `prompt` is provided.
+      #
+      #   @return [String, nil]
+      optional :summary, String
+
+      # @!attribute title
+      #   Optional display name. When omitted, Handinger assigns a random dog-themed name.
+      #
+      #   @return [String, nil]
+      optional :title, String
 
-      # @see Handinger::Models::CreateWorker#budget
-      module Budget
+      # @!attribute visibility
+      #   `public` (default) is visible to all org members. `private` is only visible to
+      #   invited members.
+      #
+      #   @return [Symbol, Handinger::Models::CreateWorker::Visibility, nil]
+      optional :visibility, enum: -> { Handinger::CreateWorker::Visibility }
+
+      # @!method initialize(instructions: nil, output_schema: nil, prompt: nil, summary: nil, title: nil, visibility: nil)
+      #   Some parameter documentations has been truncated, see
+      #   {Handinger::Models::CreateWorker} for more details.
+      #
+      #   @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 title [String] Optional display name. When omitted, Handinger assigns a random dog-themed name.
+      #
+      #   @param visibility [Symbol, Handinger::Models::CreateWorker::Visibility] `public` (default) is visible to all org members. `private` is only visible to i
+
+      # `public` (default) is visible to all org members. `private` is only visible to
+      # invited members.
+      #
+      # @see Handinger::Models::CreateWorker#visibility
+      module Visibility
         extend Handinger::Internal::Type::Enum
 
-        LOW = :low
-        STANDARD = :standard
-        HIGH = :high
-        UNLIMITED = :unlimited
+        PUBLIC = :public
+        PRIVATE = :private
 
         # @!method self.values
         #   @return [Array<Symbol>]

data/lib/handinger/models/delete_task_response.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Handinger
+  module Models
+    # @see Handinger::Resources::Tasks#delete
+    class DeleteTaskResponse < Handinger::Internal::Type::BaseModel
+      # @!attribute archived
+      #
+      #   @return [Boolean]
+      required :archived, Handinger::Internal::Type::Boolean
+
+      # @!method initialize(archived:)
+      #   @param archived [Boolean]
+    end
+  end
+end

data/lib/handinger/models/delete_worker_response.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Handinger
+  module Models
+    # @see Handinger::Resources::Workers#delete
+    class DeleteWorkerResponse < Handinger::Internal::Type::BaseModel
+      # @!attribute deleted
+      #
+      #   @return [Boolean]
+      required :deleted, Handinger::Internal::Type::Boolean
+
+      # @!method initialize(deleted:)
+      #   @param deleted [Boolean]
+    end
+  end
+end

data/lib/handinger/models/task.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module Handinger
+  module Models
+    class Task < 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 created_at
+      #
+      #   @return [String]
+      required :created_at, String, api_name: :createdAt
+
+      # @!attribute created_by_user_id
+      #
+      #   @return [String, nil]
+      required :created_by_user_id, String, api_name: :createdByUserId, nil?: true
+
+      # @!attribute organization_id
+      #
+      #   @return [String]
+      required :organization_id, String, api_name: :organizationId
+
+      # @!attribute status
+      #
+      #   @return [Symbol, Handinger::Models::Task::Status]
+      required :status, enum: -> { Handinger::Task::Status }
+
+      # @!attribute title
+      #
+      #   @return [String]
+      required :title, String
+
+      # @!attribute totals
+      #
+      #   @return [Handinger::Models::Task::Totals]
+      required :totals, -> { Handinger::Task::Totals }
+
+      # @!attribute triggered_by
+      #
+      #   @return [Symbol, Handinger::Models::Task::TriggeredBy]
+      required :triggered_by, enum: -> { Handinger::Task::TriggeredBy }, api_name: :triggeredBy
+
+      # @!attribute worker_id
+      #
+      #   @return [String]
+      required :worker_id, String, api_name: :workerId
+
+      # @!method initialize(id:, completed_at:, created_at:, created_by_user_id:, organization_id:, status:, title:, totals:, triggered_by:, worker_id:)
+      #   @param id [String]
+      #   @param completed_at [String, nil]
+      #   @param created_at [String]
+      #   @param created_by_user_id [String, nil]
+      #   @param organization_id [String]
+      #   @param status [Symbol, Handinger::Models::Task::Status]
+      #   @param title [String]
+      #   @param totals [Handinger::Models::Task::Totals]
+      #   @param triggered_by [Symbol, Handinger::Models::Task::TriggeredBy]
+      #   @param worker_id [String]
+
+      # @see Handinger::Models::Task#status
+      module Status
+        extend Handinger::Internal::Type::Enum
+
+        PENDING = :pending
+        RUNNING = :running
+        COMPLETED = :completed
+        ERROR = :error
+        ABORTED = :aborted
+
+        # @!method self.values
+        #   @return [Array<Symbol>]
+      end
+
+      # @see Handinger::Models::Task#totals
+      class Totals < Handinger::Internal::Type::BaseModel
+        # @!attribute credits
+        #
+        #   @return [Float]
+        required :credits, Float
+
+        # @!attribute duration_ms
+        #
+        #   @return [Float]
+        required :duration_ms, Float, api_name: :durationMs
+
+        # @!attribute turn_count
+        #
+        #   @return [Float]
+        required :turn_count, Float, api_name: :turnCount
+
+        # @!method initialize(credits:, duration_ms:, turn_count:)
+        #   @param credits [Float]
+        #   @param duration_ms [Float]
+        #   @param turn_count [Float]
+      end
+
+      # @see Handinger::Models::Task#triggered_by
+      module TriggeredBy
+        extend Handinger::Internal::Type::Enum
+
+        API = :api
+        EMAIL = :email
+        SCHEDULE = :schedule
+        UI = :ui
+
+        # @!method self.values
+        #   @return [Array<Symbol>]
+      end
+    end
+  end
+end

data/lib/handinger/models/task_create_params.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Handinger
+  module Models
+    # @see Handinger::Resources::Tasks#create
+    class TaskCreateParams < Handinger::Models::CreateTask
+      extend Handinger::Internal::Type::RequestParameters::Converter
+      include Handinger::Internal::Type::RequestParameters
+
+      # @!method initialize(request_options: {})
+      #   @param request_options [Handinger::RequestOptions, Hash{Symbol=>Object}]
+    end
+  end
+end

data/lib/handinger/models/task_delete_params.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Handinger
+  module Models
+    # @see Handinger::Resources::Tasks#delete
+    class TaskDeleteParams < Handinger::Internal::Type::BaseModel
+      extend Handinger::Internal::Type::RequestParameters::Converter
+      include Handinger::Internal::Type::RequestParameters
+
+      # @!attribute task_id
+      #
+      #   @return [String]
+      required :task_id, String
+
+      # @!method initialize(task_id:, request_options: {})
+      #   @param task_id [String]
+      #   @param request_options [Handinger::RequestOptions, Hash{Symbol=>Object}]
+    end
+  end
+end

data/lib/handinger/models/task_retrieve_params.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Handinger
+  module Models
+    # @see Handinger::Resources::Tasks#retrieve
+    class TaskRetrieveParams < Handinger::Internal::Type::BaseModel
+      extend Handinger::Internal::Type::RequestParameters::Converter
+      include Handinger::Internal::Type::RequestParameters
+
+      # @!attribute task_id
+      #
+      #   @return [String]
+      required :task_id, String
+
+      # @!method initialize(task_id:, request_options: {})
+      #   @param task_id [String]
+      #   @param request_options [Handinger::RequestOptions, Hash{Symbol=>Object}]
+    end
+  end
+end