operto 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 53adc7fd65b6257d17d1e93c2c2123134ac92189bf176d98fb89fb50e364a1ee
-  data.tar.gz: 979c8c81475d4a39ff1a12c695b7a5da98de80d5e9260a9f534b9c9faf940481
+  metadata.gz: 560a7613ec23670aa8c3e8f14eae1047aa3aa56b11e918b436aea5a0650fea19
+  data.tar.gz: ade003d02974835e84663c7d9bdb745bb420d6d076daed0452cab20f8a55f35d
 SHA512:
-  metadata.gz: c61aa111e25800de6e098490e30a181c202be74cc8b0758c1099f147ea306575f4d7e5b5c7d30529404f3271322fe00dad1768e2b2762d2916de733a15959ab6
-  data.tar.gz: 0b09cc302afb111a5dad1120eb55ba19cd9ce7220e3ace9432b6641b1a04293559a7dabddb6a3adc5e54c999b024e07cc27757229b8945a959a2206d50d98421
+  metadata.gz: 898ef137d8c04c1aa72ee37783c1b731cd4789bbe297355c5605fad46551f1bdd9f5af45140778e3c02d561801590e23263d7ad90f6ae2769c18b8039059d06d
+  data.tar.gz: 98691df6518db77646c2e26d9310746bf0c71c686714b615cc6d224f780ba8fa50ea61491d97daae8dbe463d6e4f6744110cc3e81046e43abb4681baa82c8a94

data/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.4.0 - 2026-10-12
+
+- When Operto rejects the access token (a `401` or an `auth_token_expired` response), the client clears the token store, renews the token and replays the request once.
+- A host token store's `clear` must retire the token so the next `active` returns `nil`.
+- Retry only idempotent requests, and only on `502`, `503` and `504`. `POST` and `PATCH` requests and `429` responses are no longer retried.
+- `Homes::Index` and `Staff::Index` keep an unparseable create date as the raw value instead of failing with `Date::Error`.
+
+## 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.4.0'
 ```
 
 ```sh
@@ -43,7 +43,7 @@ login/refresh and delegates persistence to it via four methods:
 | `active` | the current non-expired token, or `nil` |
 | `refreshable` | a token whose refresh token is still valid, or `nil` |
 | `save(access_token:, expires_at:, refresh_token: nil, refresh_expires_at: nil)` | persist and return the token |
-| `clear` | drop the cached token (called after a `401`) |
+| `clear` | retire the token so the next `active` returns `nil` (called when Operto rejects it, before the renewal) |
 
 A token responds to `access_token`, `refresh_token`, `refresh_expires_at`, and
 `expired?`.
@@ -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/authorization.rb

@@ -0,0 +1,30 @@
+module Operto
+  # Faraday middleware that signs each request with the stored access token.
+  # When Operto rejects the token (a 401 or an auth_token_expired envelope), it
+  # clears the store, renews the token and replays the request once.
+  class Authorization < Faraday::Middleware
+    HEADER = 'Authorization'.freeze
+    EXPIRED_REASON = 'auth_token_expired'.freeze
+
+    def call(env)
+      request_body = env.body
+      response = @app.call(sign(env))
+      return response unless rejected?(response)
+
+      Operto.config.token_store.clear
+      env.body = request_body
+      @app.call(sign(env))
+    end
+
+    private
+
+    def sign(env)
+      env.request_headers[HEADER] = "VRS #{Operto::Client.auth_token}"
+      env
+    end
+
+    def rejected?(response)
+      response.status == 401 || Operto::Client.response_body(response)[:ReasonText].to_s.include?(EXPIRED_REASON)
+    end
+  end
+end

data/lib/operto/client.rb

@@ -10,15 +10,14 @@ module Operto
       interval: 1.0,
       interval_randomness: 0.5,
       backoff_factor: 2,
-      retry_statuses: [401, 429, 502, 503, 504],
+      retry_statuses: [502, 503, 504],
       exceptions: [*Faraday::Retry::Middleware::DEFAULT_EXCEPTIONS, Faraday::ConnectionFailed],
-      methods: [*Faraday::Retry::Middleware::IDEMPOTENT_METHODS, :patch, :post],
-      retry_block: ->(env:, **) { Operto.config.token_store.clear if env.status == 401 }
+      methods: Faraday::Retry::Middleware::IDEMPOTENT_METHODS
     }.freeze
 
     def connection(url: Operto.config.base_url, skip_auth: false)
       Faraday.new(url:) do |builder|
-        builder.request :authorization, 'VRS', -> { auth_token } unless skip_auth
+        builder.use Operto::Authorization unless skip_auth
 
         builder.request :json
         builder.request :retry, RETRY_OPTIONS

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.4.0'.freeze
 end

data/lib/operto.rb

@@ -10,6 +10,7 @@ require_relative 'operto/error'
 require_relative 'operto/memory_token_store'
 require_relative 'operto/config'
 require_relative 'operto/operation'
+require_relative 'operto/authorization'
 require_relative 'operto/client'
 require_relative 'operto/issue_types'
 require_relative 'operto/filtered_pagination'
@@ -18,6 +19,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.4.0
 platform: ruby
 authors:
 - Guestit
@@ -90,6 +90,7 @@ files:
 - README.md
 - lib/operto.rb
 - lib/operto/access_tokens/upsert.rb
+- lib/operto/authorization.rb
 - lib/operto/client.rb
 - lib/operto/config.rb
 - lib/operto/error.rb
@@ -107,6 +108,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 +134,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.17
+rubygems_version: 4.0.21
 specification_version: 4
 summary: Client for the Operto Teams API
 test_files: []