operto 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0cf8a26aabacf6a653ef155a836d95ef727b29794a0f1fbdf1365d2306ba0a4b
-  data.tar.gz: 300fc9d056683aa3d1cedc322b887b263b454c4449a84592875484624dafd320
+  metadata.gz: 31bc34a291dadd87aded5937654fc9824be5cc365e94010724ef763b75169b49
+  data.tar.gz: 46b42729bb8e8590b02452b56c83fe4387638e5db2bee5b290f6f98040196d63
 SHA512:
-  metadata.gz: 12713010ba3c3b7b909e1c54e959bf00411647352f959862446f54c40ad443461af683c141057f0cf59e192191cb8866ee04c82bba929ddad6b7857fa3c2ae4f
-  data.tar.gz: e609b53f901d429bc8957decbf04029e26b815e7ae266f1929d3d3000810026a10025111c9b2ab3854987d12aded73cdc23d1175a2253d15a10e4a9c12a7beaa
+  metadata.gz: 0cc0aa3b12cb92f0d521dfa5f46e6a834a69ddb047a881f9eb125a12a829bc5ff4ca2b9210a8c18b48f9df761abc81ad7374133fd2bac236dac55d6199cae374
+  data.tar.gz: 8579d576182fc7598faf1bc8a4fa5e7e166a995def47059412a00a74ab23f5854225ea702468611f4116a76a29db45ab6469a73182437b1e02b5222c449a27fb

data/CHANGELOG.md

@@ -0,0 +1,18 @@
+# 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.
+- Add RubyGems project, changelog, and license metadata.
+- Package the README, changelog, and license with the gem.
+- Bound runtime dependencies to the supported major versions.
+
+## 0.1.0 - 2026-07-23
+
+- Initial release of the Operto Teams API client, including the default in-memory token store.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Guestit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,85 @@
+# Operto
+
+A Ruby client for the [Operto Teams](https://teams.operto.com) API. Every call
+is an operation returning a [`Dry::Monads::Result`](https://dry-rb.org/gems/dry-monads/);
+credentials and token storage are injected by the host, so the gem carries no
+framework dependency.
+
+## Installation
+
+```ruby
+# Gemfile
+gem 'operto', '~> 0.3.0'
+```
+
+```sh
+bundle install
+```
+
+## Configuration
+
+Configure once at boot with your API credentials and a token store. In Rails,
+put this in `config/initializers/operto.rb`:
+
+```ruby
+Rails.application.config.to_prepare do
+  Operto.configure do |config|
+    config.client_id    = Rails.application.credentials.dig(:operto, :client_id)
+    config.secret       = Rails.application.credentials.dig(:operto, :secret)
+    config.token_store  = MyTokenStore.new
+  end
+end
+```
+
+### Token store
+
+The gem defaults to an in-memory `Operto::MemoryTokenStore` (fine for a single
+long-running process — the token re-issues after a restart). For shared or
+persistent storage, provide your own store: the gem performs the OAuth
+login/refresh and delegates persistence to it via four methods:
+
+| Method | Returns / does |
+| --- | --- |
+| `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`) |
+
+A token responds to `access_token`, `refresh_token`, `refresh_expires_at`, and
+`expired?`.
+
+## Usage
+
+```ruby
+Operto::Tasks::Create.new.call(
+  attributes: {
+    house_id:   '110784',
+    rule_id:    '27986',
+    name:       'Deep clean',
+    start_date: Time.zone.parse('2026-01-01 09:00'),
+    end_date:   Time.zone.parse('2026-01-02 09:00')
+  }
+)
+# => Success({ task_id: 44683131 })
+```
+
+`#call` returns a `Result`; `#call!` unwraps it and raises the underlying
+failure. Operations are grouped by resource:
+
+- `Operto::Tasks::{Create,Update,Index,Show}`
+- `Operto::StaffTasks::{Create,Destroy}` · `Operto::StaffTaskTimes::Index`
+- `Operto::Issues::{Index,Close}` · `Operto::Homes::Index` · `Operto::Staff::Index`
+
+## Development
+
+```sh
+bundle install
+bundle exec rake        # spec + rubocop
+```
+
+HTTP interactions are recorded with [VCR](https://github.com/vcr/vcr); specs run
+offline against `spec/fixtures/cassettes`.
+
+## License
+
+Released under the [MIT License](LICENSE).

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.1.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

@@ -0,0 +1,121 @@
+# Public API of the gem, mirroring the inline `# @rbs` annotations in lib/.
+# Shipped with the gem so host apps pick it up through `rbs collection`.
+module Operto
+  VERSION: ::String
+
+  def self.configure: () { (Config) -> void } -> void
+  def self.config: () -> Config
+
+  class Error < ::StandardError
+  end
+
+  # 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
+
+  class Config
+    attr_accessor client_id: ::String?
+    attr_accessor secret: ::String?
+    attr_accessor base_url: ::String
+
+    # Duck-typed: the host may inject its own store (see MemoryTokenStore).
+    attr_accessor token_store: untyped
+  end
+
+  class MemoryTokenStore
+    REFRESH_BUFFER: ::Integer
+
+    def active: () -> untyped
+    def refreshable: () -> untyped
+    def save: (access_token: ::String, expires_at: ::Time, ?refresh_token: ::String?, ?refresh_expires_at: ::Time?) -> untyped
+    def clear: () -> nil
+  end
+
+  module IssueTypes
+    ISSUE_TYPES: ::Hash[::Integer, ::String]
+  end
+
+  # #call! returns the same Result as #call, raising the failure instead of
+  # wrapping it — hence the `alias call! call` on every operation below.
+  module Operation
+    def call!: (*untyped, **untyped) -> untyped
+  end
+
+  module AccessTokens
+    class Upsert
+      def call: () -> ::Dry::Monads::Result[untyped]
+      alias call! call
+    end
+  end
+
+  module Tasks
+    class Create
+      def call: (attributes: ::Hash[::Symbol, untyped]) -> ::Dry::Monads::Result[::Hash[::Symbol, untyped]]
+      alias call! call
+    end
+
+    class Update
+      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
+
+    class Index
+      def call: (?attributes: ::Hash[::Symbol, untyped], ?skip: ::Integer, ?take: ::Integer) -> ::Dry::Monads::Result[::Hash[::Symbol, untyped]]
+      alias call! call
+    end
+  end
+
+  module StaffTasks
+    class Create
+      def call: (task_id: ::String, staff_id: ::String, property_id: ::String) -> ::Dry::Monads::Result[::Hash[::Symbol, untyped]]
+      alias call! call
+    end
+
+    class Destroy
+      def call: (staff_task_id: ::String) -> ::Dry::Monads::Result[bool]
+      alias call! call
+    end
+  end
+
+  module StaffTaskTimes
+    class Index
+      def call: (?attributes: ::Hash[::Symbol, untyped], ?skip: ::Integer, ?take: ::Integer) -> ::Dry::Monads::Result[::Hash[::Symbol, untyped]]
+      alias call! call
+    end
+  end
+
+  module Issues
+    class Index
+      def call: (start_date: ::Date, ?skip: ::Integer, ?take: ::Integer) -> ::Dry::Monads::Result[::Hash[::Symbol, untyped]]
+      alias call! call
+    end
+
+    class Close
+      def call: (issue_id: ::Integer | ::String) -> ::Dry::Monads::Result[::Hash[::Symbol, untyped]]
+      alias call! call
+    end
+  end
+
+  module Homes
+    class Index
+      def call: (?skip: ::Integer, ?take: ::Integer) -> ::Dry::Monads::Result[::Hash[::Symbol, untyped]]
+      alias call! call
+    end
+  end
+
+  module Staff
+    class Index
+      def call: (?skip: ::Integer, ?take: ::Integer) -> ::Dry::Monads::Result[::Hash[::Symbol, untyped]]
+      alias call! call
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: operto
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Guestit
@@ -13,78 +13,81 @@ dependencies:
   name: activesupport
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '8.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '8.1'
 - !ruby/object:Gem::Dependency
   name: dry-monads
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '1.10'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '1.10'
 - !ruby/object:Gem::Dependency
   name: faraday
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '2.14'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '2.14'
 - !ruby/object:Gem::Dependency
   name: faraday-retry
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '2.4'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '2.4'
 - !ruby/object:Gem::Dependency
   name: oj
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '3.17'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '3.17'
 description: HTTP client and operations for the Operto Teams API, decoupled from the
   host application.
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
+- LICENSE
+- README.md
 - lib/operto.rb
 - lib/operto/access_tokens/upsert.rb
 - lib/operto/client.rb
@@ -104,10 +107,17 @@ 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
-licenses: []
+- sig/operto.rbs
+homepage: https://github.com/guestitab/operto-client
+licenses:
+- MIT
 metadata:
+  allowed_push_host: https://rubygems.org
+  source_code_uri: https://github.com/guestitab/operto-client
+  changelog_uri: https://github.com/guestitab/operto-client/blob/main/CHANGELOG.md
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
@@ -123,7 +133,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.15
+rubygems_version: 4.0.20
 specification_version: 4
 summary: Client for the Operto Teams API
 test_files: []