operto 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 53adc7fd65b6257d17d1e93c2c2123134ac92189bf176d98fb89fb50e364a1ee
-  data.tar.gz: 979c8c81475d4a39ff1a12c695b7a5da98de80d5e9260a9f534b9c9faf940481
+  metadata.gz: 31bc34a291dadd87aded5937654fc9824be5cc365e94010724ef763b75169b49
+  data.tar.gz: 46b42729bb8e8590b02452b56c83fe4387638e5db2bee5b290f6f98040196d63
 SHA512:
-  metadata.gz: c61aa111e25800de6e098490e30a181c202be74cc8b0758c1099f147ea306575f4d7e5b5c7d30529404f3271322fe00dad1768e2b2762d2916de733a15959ab6
-  data.tar.gz: 0b09cc302afb111a5dad1120eb55ba19cd9ce7220e3ace9432b6641b1a04293559a7dabddb6a3adc5e54c999b024e07cc27757229b8945a959a2206d50d98421
+  metadata.gz: 0cc0aa3b12cb92f0d521dfa5f46e6a834a69ddb047a881f9eb125a12a829bc5ff4ca2b9210a8c18b48f9df761abc81ad7374133fd2bac236dac55d6199cae374
+  data.tar.gz: 8579d576182fc7598faf1bc8a4fa5e7e166a995def47059412a00a74ab23f5854225ea702468611f4116a76a29db45ab6469a73182437b1e02b5222c449a27fb

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.3.0 - 2026-09-27
+
+- `Tasks::Index` returns the whole task: rule, booking, name, description, start and due times, and the active and completion flags.
+- Add `Tasks::Show` for one task. A missing task fails with `Operto::NotFoundError`.
+- `Tasks::Update` sends only the attributes it gets, so a description-only update keeps the name, schedule and rule.
+
 ## 0.2.0 - 2026-08-17
 
 - Add RBS type signatures for the public API.

data/README.md

@@ -9,7 +9,7 @@ framework dependency.
 
 ```ruby
 # Gemfile
-gem 'operto', '~> 0.2.0'
+gem 'operto', '~> 0.3.0'
 ```
 
 ```sh
@@ -66,7 +66,7 @@ Operto::Tasks::Create.new.call(
 `#call` returns a `Result`; `#call!` unwraps it and raises the underlying
 failure. Operations are grouped by resource:
 
-- `Operto::Tasks::{Create,Update,Index}`
+- `Operto::Tasks::{Create,Update,Index,Show}`
 - `Operto::StaffTasks::{Create,Destroy}` · `Operto::StaffTaskTimes::Index`
 - `Operto::Issues::{Index,Close}` · `Operto::Homes::Index` · `Operto::Staff::Index`
 

data/lib/operto/error.rb

@@ -3,4 +3,7 @@ module Operto
 
   # Raised by operations for malformed arguments before any network call.
   class ArgumentError < Error; end
+
+  # Raised when Operto answers a single-record read with nothing.
+  class NotFoundError < Error; end
 end

data/lib/operto/homes/index.rb

@@ -46,7 +46,7 @@ module Operto
         return if value.blank?
 
         Date.strptime(value.to_s, '%Y%m%d')
-      rescue ArgumentError
+      rescue Date::Error
         value
       end
     end

data/lib/operto/operation.rb

@@ -19,13 +19,5 @@ module Operto
       key, reason = attrs.first
       raise Operto::ArgumentError, "#{key}: #{reason}"
     end
-
-    def required_attribute!(key)
-      raise Operto::ArgumentError, "#{key}: required"
-    end
-
-    def invalid_attribute!(key, type:)
-      raise Operto::ArgumentError, "#{key}: expected #{type}"
-    end
   end
 end

data/lib/operto/staff/index.rb

@@ -51,7 +51,7 @@ module Operto
         return if value.blank?
 
         Date.parse(value.to_s)
-      rescue ArgumentError
+      rescue Date::Error
         value
       end
     end

data/lib/operto/tasks/create.rb

@@ -8,8 +8,8 @@ module Operto
       def call(attributes:)
         validate_arguments!(attributes)
 
-        request_attributes = prepare_attributes(attributes)
-        response = Operto::Client.connection.post('tasks', request_attributes)
+        # A create always sends a description, '-' when there is none.
+        response = Operto::Client.connection.post('tasks', request_attributes(attributes.reverse_merge(description: nil)))
 
         handle_task_response(response)
       rescue StandardError => e
@@ -22,7 +22,7 @@ module Operto
         argument! attributes: :invalid unless attributes.is_a?(Hash) && attributes.present?
 
         required_keys.each do |key|
-          required_attribute!(key) if attributes[key].blank?
+          argument!(key => :required) if attributes[key].blank?
         end
       end
 

data/lib/operto/tasks/index.rb

@@ -3,6 +3,7 @@ module Operto
     class Index
       include Operto::Operation
       include FilteredPagination
+      include Shared
 
       FILTER_MAPPINGS = {
         property_id: 'PropertyID',
@@ -37,34 +38,13 @@ module Operto
       private
 
       def format_results(body)
-        results = body[:data].map do |task|
-          {
-            task_id: task[:TaskID],
-            property_id: task[:PropertyID],
-            approved_at: task[:ApprovedDate]&.to_datetime,
-            completed_at: task[:CompleteConfirmedDate]&.to_datetime,
-            staff: extract_staff(task[:Staff])
-          }
-        end
+        results = body[:data].map { |task| normalize_task(task) }
 
         {
           results:,
           count: body[:total_items] || results.size
         }
       end
-
-      def extract_staff(staff_array)
-        return [] if staff_array.blank?
-
-        staff_array.map do |staff|
-          {
-            staff_id: staff[:StaffID],
-            name: staff[:Name],
-            email: staff[:Email]&.downcase,
-            active: staff[:Active]
-          }
-        end
-      end
     end
   end
 end

data/lib/operto/tasks/shared.rb

@@ -1,31 +1,30 @@
 module Operto
   module Tasks
     module Shared
-      private
+      COMPLETED_VALUES = [true, '1', 1].freeze
 
-      def prepare_attributes(attrs)
-        base_attrs = {
-          PropertyID: attrs[:house_id],
-          TaskRuleID: attrs[:rule_id],
-          TaskName: attrs[:name],
-          TaskDescription: attrs[:description].presence || '-'
-        }.compact_blank
+      private
 
-        base_attrs.merge(datetime_attributes(attrs))
+      # Only the given keys travel, so an update never resets what the caller left out.
+      def request_attributes(attrs)
+        request = { PropertyID: attrs[:house_id], TaskRuleID: attrs[:rule_id], TaskName: attrs[:name] }.compact_blank
+        request[:TaskDescription] = attrs[:description].presence || '-' if attrs.key?(:description)
+        request.merge!(start_attributes(attrs[:start_date])) if attrs[:start_date]
+        request.merge!(complete_by_attributes(attrs[:end_date])) if attrs[:end_date]
+        request
       end
 
-      def datetime_attributes(attrs)
-        h = {}
+      def start_attributes(value)
+        start_date = parse_datetime(value)
+        date = as_date(start_date)
 
-        start_date = parse_datetime(attrs[:start_date])
-        h[:TaskDate] = h[:TaskStartDate] = as_date(start_date)
-        h[:TaskTime] = h[:TaskStartTime] = start_date.hour
+        { TaskStartDate: date, TaskDate: date, TaskStartTime: start_date.hour, TaskTime: start_date.hour }
+      end
 
-        complete_by = parse_datetime(attrs[:end_date])
-        h[:TaskCompleteByDate] = as_date(complete_by)
-        h[:TaskCompleteByTime] = complete_by.hour
+      def complete_by_attributes(value)
+        complete_by = parse_datetime(value)
 
-        h
+        { TaskCompleteByDate: as_date(complete_by), TaskCompleteByTime: complete_by.hour }
       end
 
       def parse_datetime(value)
@@ -39,6 +38,50 @@ module Operto
       def handle_task_response(response)
         Operto::Client.handle_response(response) { |body| { task_id: body[:TaskID] } }
       end
+
+      # The list and the single-task read send "10:00" and "0"/"1"; a write echoes 10 and false.
+      def normalize_task(task)
+        {
+          task_id: task[:TaskID],
+          property_id: task[:PropertyID],
+          property_booking_id: task[:PropertyBookingID],
+          rule_id: task[:TaskRuleID],
+          name: task[:TaskName]&.strip,
+          description: task[:TaskDescription],
+          **task_schedule(task),
+          **task_progress(task)
+        }
+      end
+
+      def task_schedule(task)
+        {
+          starts_at: task_time(task[:TaskStartDate] || task[:TaskDate], task[:TaskStartTime] || task[:TaskTime]),
+          due_at: task_time(task[:TaskCompleteByDate], task[:TaskCompleteByTime])
+        }
+      end
+
+      def task_progress(task)
+        {
+          active: task[:TaskActive] != false,
+          completed: COMPLETED_VALUES.include?(task[:Completed]),
+          approved_at: task[:ApprovedDate]&.to_datetime,
+          completed_at: task[:CompleteConfirmedDate]&.to_datetime,
+          staff: extract_staff(task[:Staff])
+        }
+      end
+
+      def task_time(date, time)
+        return if date.blank?
+
+        hour, minute = time.to_s.split(':')
+        Time.zone.parse(date.to_s).change(hour: hour.to_i, min: minute.to_i)
+      end
+
+      def extract_staff(staff)
+        Array(staff).map do |member|
+          { staff_id: member[:StaffID], name: member[:Name], email: member[:Email]&.downcase, active: member[:Active] }
+        end
+      end
     end
   end
 end

data/lib/operto/tasks/show.rb

@@ -0,0 +1,25 @@
+module Operto
+  module Tasks
+    class Show
+      include Operto::Operation
+      include Shared
+
+      # @rbs (task_id: ::String | ::Integer) -> Dry::Monads::Result[::Hash[::Symbol, untyped]]
+      def call(task_id:)
+        argument! task_id: :required if task_id.blank?
+
+        response = Operto::Client.connection.get("tasks/#{task_id}")
+
+        Operto::Client.handle_response(response) do |body|
+          # A missing task comes back as an empty list, not a 404.
+          task = body[:data]&.first
+          raise Operto::NotFoundError, "Task #{task_id} not found" unless task
+
+          normalize_task(task)
+        end
+      rescue StandardError => e
+        Failure(e)
+      end
+    end
+  end
+end

data/lib/operto/tasks/update.rb

@@ -4,12 +4,11 @@ module Operto
       include Operto::Operation
       include Shared
 
-      # @rbs (task_id: ::String, attributes: ::Hash[::Symbol, untyped]) -> Dry::Monads::Result[::Hash[::Symbol, untyped]]
+      # @rbs (task_id: ::String | ::Integer, attributes: ::Hash[::Symbol, untyped]) -> Dry::Monads::Result[::Hash[::Symbol, untyped]]
       def call(task_id:, attributes:)
         validate_arguments!(task_id, attributes)
 
-        request_attributes = prepare_attributes(attributes).compact_blank
-        response = Operto::Client.connection.put("tasks/#{task_id}", request_attributes)
+        response = Operto::Client.connection.put("tasks/#{task_id}", request_attributes(attributes))
 
         handle_task_response(response)
       rescue StandardError => e

data/lib/operto/version.rb

@@ -1,3 +1,3 @@
 module Operto
-  VERSION = '0.2.0'.freeze
+  VERSION = '0.3.0'.freeze
 end

data/lib/operto.rb

@@ -18,6 +18,7 @@ require_relative 'operto/tasks/shared'
 require_relative 'operto/tasks/create'
 require_relative 'operto/tasks/update'
 require_relative 'operto/tasks/index'
+require_relative 'operto/tasks/show'
 require_relative 'operto/staff_tasks/create'
 require_relative 'operto/staff_tasks/destroy'
 require_relative 'operto/staff_task_times/index'

data/sig/operto.rbs

@@ -13,6 +13,10 @@ module Operto
   class ArgumentError < Error
   end
 
+  # Raised when Operto answers a single-record read with nothing.
+  class NotFoundError < Error
+  end
+
   class Config
     attr_accessor client_id: ::String?
     attr_accessor secret: ::String?
@@ -55,7 +59,12 @@ module Operto
     end
 
     class Update
-      def call: (task_id: ::String, attributes: ::Hash[::Symbol, untyped]) -> ::Dry::Monads::Result[::Hash[::Symbol, untyped]]
+      def call: (task_id: ::String | ::Integer, attributes: ::Hash[::Symbol, untyped]) -> ::Dry::Monads::Result[::Hash[::Symbol, untyped]]
+      alias call! call
+    end
+
+    class Show
+      def call: (task_id: ::String | ::Integer) -> ::Dry::Monads::Result[::Hash[::Symbol, untyped]]
       alias call! call
     end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: operto
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Guestit
@@ -107,6 +107,7 @@ files:
 - lib/operto/tasks/create.rb
 - lib/operto/tasks/index.rb
 - lib/operto/tasks/shared.rb
+- lib/operto/tasks/show.rb
 - lib/operto/tasks/update.rb
 - lib/operto/version.rb
 - sig/operto.rbs
@@ -132,7 +133,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.17
+rubygems_version: 4.0.20
 specification_version: 4
 summary: Client for the Operto Teams API
 test_files: []