operto 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0cf8a26aabacf6a653ef155a836d95ef727b29794a0f1fbdf1365d2306ba0a4b
-  data.tar.gz: 300fc9d056683aa3d1cedc322b887b263b454c4449a84592875484624dafd320
+  metadata.gz: 53adc7fd65b6257d17d1e93c2c2123134ac92189bf176d98fb89fb50e364a1ee
+  data.tar.gz: 979c8c81475d4a39ff1a12c695b7a5da98de80d5e9260a9f534b9c9faf940481
 SHA512:
-  metadata.gz: 12713010ba3c3b7b909e1c54e959bf00411647352f959862446f54c40ad443461af683c141057f0cf59e192191cb8866ee04c82bba929ddad6b7857fa3c2ae4f
-  data.tar.gz: e609b53f901d429bc8957decbf04029e26b815e7ae266f1929d3d3000810026a10025111c9b2ab3854987d12aded73cdc23d1175a2253d15a10e4a9c12a7beaa
+  metadata.gz: c61aa111e25800de6e098490e30a181c202be74cc8b0758c1099f147ea306575f4d7e5b5c7d30529404f3271322fe00dad1768e2b2762d2916de733a15959ab6
+  data.tar.gz: 0b09cc302afb111a5dad1120eb55ba19cd9ce7220e3ace9432b6641b1a04293559a7dabddb6a3adc5e54c999b024e07cc27757229b8945a959a2206d50d98421

data/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## 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.2.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}`
+- `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/version.rb

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

data/sig/operto.rbs

@@ -0,0 +1,112 @@
+# 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
+
+  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, attributes: ::Hash[::Symbol, untyped]) -> ::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.2.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
@@ -106,8 +109,14 @@ files:
 - lib/operto/tasks/shared.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 +132,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.15
+rubygems_version: 4.0.17
 specification_version: 4
 summary: Client for the Operto Teams API
 test_files: []