fixably 0.6.1 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4e8f880a2eb954e1467e74c7dec0c84c2b762b50da015e115319a245c447915d
-  data.tar.gz: de900d1c1b55c4c2f5a45533c835dd961b4bf01374f9c73f7f8d020c6bf90c77
+  metadata.gz: 4adb6e9f822e52cf8dd344055878f56a44df8c8e26ef3b6eb615881b45765641
+  data.tar.gz: 6beb3aad60d5eb8ad8c4d53e2c874a7550bfdcea39d1ad10f8ed35cd596e6ad5
 SHA512:
-  metadata.gz: 4c4b1b68a5043f35c6da7ef3b6454886e79883f440fb4a9a07e2b27a4e8d0f4fb8254724885165d84f94e9b4cf05e30575619829e9a7c947d10592e400bdf588
-  data.tar.gz: f01f0d472706283fc568a9e2e04c4e3d44b562b28402c6669291b95d085e950f3956603bd7286166240d5651db103bc06b98ceb5300e5953fa7fb0914b213e4d
+  metadata.gz: 256864970168a48fe41fcd1cdb967fe1917df4541b0e70c4f967c5c3bab69e8c80f64c9851d909d93de95cd0052983d200668643440990dc9262560f1ae648c9
+  data.tar.gz: ac7a96b0a4d72d62c9cb55329144861a2b683772ca10bd352c50ec9c6d70356a6b554643190d78301441c317964d907d76dba8770002216fbeb5268771e05ed9

data/.gitignore

@@ -7,6 +7,9 @@
 /spec/reports/
 /tmp/
 
+# macOS directory metadata
+.DS_Store
+
 # sensitive dotenv config files
 .env
 

data/CLAUDE.md

@@ -0,0 +1,135 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Overview
+
+`fixably` is a Ruby gem wrapping the [Fixably API](https://docs.fixably.com) v3.
+It is built on top of Active Resource and monkey patches it heavily so that the
+Fixably API's non-standard conventions (camelCase keys, a single `q` query
+parameter, link expansion, hash-wrapped collections) look like an ordinary
+Rails-style model layer to callers.
+
+Ruby >= 3.0. The gem has one runtime dependency: `activeresource` (>= 5, < 7).
+
+## Commands
+
+```sh
+bundle exec rake          # default task: rspec + rubocop
+bundle exec rspec         # full test suite
+bundle exec rspec spec/fixably/resources/order_spec.rb          # single file
+bundle exec rspec spec/fixably/resources/order_spec.rb:42       # single example
+bundle exec rspec --only-failures                               # uses .rspec_status
+bundle exec rubocop -a    # lint with safe autocorrect
+bin/console               # IRB with the gem loaded
+```
+
+Mutation testing runs via `bin/mutant` (`bin/mutant run`), which requires the
+`mutant-license` gem from a private source declared in the `Gemfile`. Subjects
+and exclusions live in `.mutant.yml`.
+
+Tests never hit the network — specs stub `described_class.connection` and assert
+on the exact path/body that *would* have been sent. `spec/helpers/config.rb`
+sets a dummy api_key/subdomain globally in `spec_helper`, so no `.env` file is
+needed (the README's dotenv instructions are stale).
+
+## Architecture
+
+### Layering
+
+`ApplicationResource < ActiveResource::Base` ([lib/fixably/application_resource.rb](lib/fixably/application_resource.rb))
+is the base class every resource inherits from. It composes four mixins, each
+solving one impedance mismatch with the Fixably API:
+
+- **`Actions`** ([lib/fixably/actions.rb](lib/fixably/actions.rb)) — overrides
+  every Active Resource entry point (`all`, `create`, `find`, `first`, `last`,
+  `where`, `save`, `destroy`…) to gate on `ActionPolicy` and to run arguments
+  through `ArgumentParameterisation` before delegating to `super`.
+- **`Encoding`** ([lib/fixably/encoding.rb](lib/fixably/encoding.rb)) — on
+  write, converts underscored keys back to camelCase, strips read-only
+  attributes (`remove_on_encode`) and has_many associations, and nests the
+  payload under the parent association name when creating a nested record.
+- **`LoadFromResponse`** ([lib/fixably/load_from_response.rb](lib/fixably/load_from_response.rb))
+  — on read, underscores keys, unwraps single-element array responses, turns
+  nested collection hashes into `PaginatedCollection`s, and deletes
+  href-only "empty" associations so Active Resource doesn't mistake them for
+  real records.
+- **`Authorization`** ([lib/fixably/authorization.rb](lib/fixably/authorization.rb))
+  — injects the API key into request headers.
+
+### The Active Resource monkey patch
+
+[lib/fixably/active_resource/base.rb](lib/fixably/active_resource/base.rb)
+patches `ActiveResource::Base` itself (aliasing the originals):
+
+- `instantiate_record` deep-underscores every incoming key.
+- `query_string` collapses all non-pagination filters into Fixably's single
+  `q=attribute:value,attribute:value` parameter; `expand`, `limit`, `offset`
+  and `page` pass through untouched (`non_query_parameters`).
+
+It also installs `Fixably::ActiveResource::PaginatedCollection` as the global
+`collection_parser`. Changing behaviour here affects *all* resources, so this
+file is the first place to look when request/response shapes are wrong.
+
+### URLs are derived from class nesting
+
+`ApplicationResource.site_url` builds the endpoint from the class name:
+
+- `Fixably::Customer` → `https://<subdomain>.fixably.com/api/v3`
+- `Fixably::Order::Note` → `.../api/v3/orders/:order_id` (the middle name part
+  is pluralised and becomes a prefix option)
+
+So nesting a class under another resource is what makes it a nested endpoint.
+`CreateHasManyRecord` relies on the same convention: appending to a has_many
+collection (`order.notes << note`) sets `parent_association`, fills in the
+`:<parent>_id` prefix option, and saves — and it refuses records nested more
+than one level deep.
+
+### Permissions are declarative
+
+Each resource declares `actions %i[create delete list show update]` — only the
+subset Fixably actually supports. `ActionPolicy`
+([lib/fixably/action_policy.rb](lib/fixably/action_policy.rb)) raises
+`Fixably::UnsupportedError` for anything not declared. When adding a resource,
+the `actions` list is the contract; the specs' shared examples take it as an
+argument and generate the matching request expectations.
+
+### Link expansion and pagination
+
+Fixably returns collections as bare `href` stubs unless asked to expand, so
+`ArgumentParameterisation` always adds `expand=items` for list scopes and
+`ResourceLazyLoader` (behind `Model.includes(:assoc)`) merges extra
+associations into that parameter — `has_one` expands as `assocName`,
+`has_many` as `assocName(items)`.
+
+`PaginatedCollection` wraps the `{limit, offset, totalItems, items}` envelope
+and adds `next_page`/`previous_page`/`paginated_each`/`paginated_map`.
+`Actions.last` is non-trivial: it fetches a page, then re-requests with
+`offset: total_items - 1` when the last record isn't in the current page.
+
+Array values in `where` become Fixably ranged searches (`[from,to]`), with
+`Date`/`Time` values formatted as `%F` — see
+`ArgumentParameterisation#stringify_array_values`.
+
+## Adding a resource
+
+1. Create `lib/fixably/resources/<name>.rb` subclassing `ApplicationResource`
+   (or nest the class inside its parent resource for nested endpoints).
+2. Declare `actions`, a `schema` block (only attributes Fixably accepts on
+   create/update), associations, and any validations.
+3. Require it from [lib/fixably.rb](lib/fixably.rb).
+4. Add a spec using the `"a resource"` / `"a nested resource"` shared examples
+   in [spec/support/shared_examples/](spec/support/shared_examples/).
+5. Document it in `docs/<name>.md` and link it from the README's supported
+   resources list.
+
+## Conventions
+
+- Style is enforced by [.rubocop.yml](.rubocop.yml): double quotes, trailing
+  dot for multiline chains, trailing commas in multiline literals, endless
+  methods (`def api_version = "v3"`) and numbered block params (`_1`) are
+  used liberally, and `# frozen_string_literal: true` heads every file.
+- Bump `Fixably::VERSION` in [lib/fixably/version.rb](lib/fixably/version.rb)
+  for releases; built gems are committed under `pkg/`.
+- `webhook_events/` holds captured sample webhook payloads (untracked
+  reference data, not used by code or tests).

data/Gemfile

@@ -5,8 +5,17 @@ source "https://rubygems.org"
 # Specify your gem's dependencies in fixably.gemspec
 gemspec
 
-group :development do
-  source "https://com:jE6Df8B6dPoghEjlbPTiQzMi34dvbO12@gem.mutant.dev" do
-    gem "mutant-license"
+# Mutation testing requires a licence, and each developer needs their own
+# token. Rather than committing a token here, supply your own via either
+#   bundle config set --global gem.mutant.dev com:YOUR_TOKEN
+# or the equivalent environment variable
+#   BUNDLE_GEM__MUTANT__DEV="com:YOUR_TOKEN"
+# Without a token the licence gem is skipped so that `bundle install` still
+# works; `bundle exec mutant` is then unavailable.
+if Bundler.settings["gem.mutant.dev"]
+  group :development do
+    source "https://gem.mutant.dev" do
+      gem "mutant-license"
+    end
   end
 end

data/Gemfile.lock

@@ -1,42 +1,61 @@
 PATH
   remote: .
   specs:
-    fixably (0.6.0)
+    fixably (0.7.0)
       activeresource (>= 5, < 7)
+      logger (~> 1.6)
 
 GEM
-  remote: https://com:jE6Df8B6dPoghEjlbPTiQzMi34dvbO12@gem.mutant.dev/
+  remote: https://gem.mutant.dev/
   specs:
     mutant-license (0.1.1.1.2753182086109243616824084045621781286745.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    activemodel (7.0.1)
-      activesupport (= 7.0.1)
-    activemodel-serializers-xml (1.0.2)
-      activemodel (> 5.x)
-      activesupport (> 5.x)
+    activemodel (8.1.3.1)
+      activesupport (= 8.1.3.1)
+    activemodel-serializers-xml (1.0.3)
+      activemodel (>= 5.0.0.a)
+      activesupport (>= 5.0.0.a)
       builder (~> 3.1)
-    activeresource (6.0.0)
-      activemodel (>= 6.0)
+    activeresource (6.2.0)
+      activemodel (>= 7.0)
       activemodel-serializers-xml (~> 1.0)
-      activesupport (>= 6.0)
-    activesupport (7.0.1)
-      concurrent-ruby (~> 1.0, >= 1.0.2)
+      activesupport (>= 7.0)
+    activesupport (8.1.3.1)
+      base64
+      bigdecimal
+      concurrent-ruby (~> 1.0, >= 1.3.1)
+      connection_pool (>= 2.2.5)
+      drb
       i18n (>= 1.6, < 2)
+      json
+      logger (>= 1.4.2)
       minitest (>= 5.1)
-      tzinfo (~> 2.0)
+      securerandom (>= 0.3)
+      tzinfo (~> 2.0, >= 2.0.5)
+      uri (>= 0.13.1)
     ast (2.4.2)
-    builder (3.2.4)
-    byebug (11.1.3)
+    base64 (0.3.0)
+    bigdecimal (4.1.2)
+    builder (3.3.0)
+    byebug (13.0.0)
+      reline (>= 0.6.0)
     coderay (1.1.3)
-    concurrent-ruby (1.1.9)
+    concurrent-ruby (1.3.8)
+    connection_pool (3.0.2)
     diff-lcs (1.5.0)
-    i18n (1.8.11)
+    drb (2.2.3)
+    i18n (1.15.2)
       concurrent-ruby (~> 1.0)
-    method_source (1.0.0)
-    minitest (5.15.0)
+    io-console (0.8.2)
+    json (2.21.2)
+    logger (1.7.0)
+    method_source (1.1.0)
+    minitest (6.0.6)
+      drb (~> 2.0)
+      prism (~> 1.5)
     mutant (0.11.2)
       diff-lcs (~> 1.3)
       parser (~> 3.0.0)
@@ -49,15 +68,19 @@ GEM
     parallel (1.21.0)
     parser (3.0.3.2)
       ast (~> 2.4.1)
-    pry (0.13.1)
+    prism (1.9.0)
+    pry (0.16.0)
       coderay (~> 1.1)
       method_source (~> 1.0)
-    pry-byebug (3.9.0)
-      byebug (~> 11.0)
-      pry (~> 0.13.0)
+      reline (>= 0.6.0)
+    pry-byebug (3.12.0)
+      byebug (~> 13.0)
+      pry (>= 0.13, < 0.17)
     rainbow (3.1.1)
-    rake (13.0.6)
+    rake (13.4.2)
     regexp_parser (2.2.0)
+    reline (0.7.0)
+      io-console (~> 0.5)
     rexml (3.2.5)
     rspec (3.10.0)
       rspec-core (~> 3.10.0)
@@ -91,16 +114,20 @@ GEM
     rubocop-rspec (2.7.0)
       rubocop (~> 1.19)
     ruby-progressbar (1.11.0)
+    securerandom (0.4.1)
     sorbet-runtime (0.5.9531)
-    tzinfo (2.0.4)
+    tzinfo (2.0.6)
       concurrent-ruby (~> 1.0)
     unicode-display_width (2.1.0)
     unparser (0.6.2)
       diff-lcs (~> 1.3)
       parser (>= 3.0.0)
+    uri (1.1.1)
 
 PLATFORMS
   arm64-darwin-21
+  arm64-darwin-22
+  arm64-darwin-25
   x86_64-darwin-20
 
 DEPENDENCIES
@@ -116,4 +143,4 @@ DEPENDENCIES
   rubocop-rspec
 
 BUNDLED WITH
-   2.2.22
+  4.0.16

data/README.md

@@ -217,6 +217,26 @@ replace the example values:
 cp .env.example .env
 ```
 
+### Mutation testing
+
+Mutation testing uses [mutant](https://github.com/mbj/mutant), which requires a
+licence. Since each developer needs their own token, no token is committed to
+this repository; supply yours via Bundler's credential config:
+
+```sh
+bundle config set --global gem.mutant.dev com:YOUR_TOKEN
+```
+
+or, more conveniently in CI, the equivalent environment variable:
+
+```sh
+BUNDLE_GEM__MUTANT__DEV="com:YOUR_TOKEN"
+```
+
+If no token is configured, the licence gem is skipped so that `bundle install`
+still succeeds. Only `bundle exec mutant` is unavailable; `rake` and the RSpec
+suite are unaffected.
+
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/fixably.gemspec

@@ -27,6 +27,8 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
 
   spec.add_dependency "activeresource", ">= 5", "< 7"
+  # Removed from the default gems in Ruby 4.0
+  spec.add_dependency "logger", "~> 1.6"
 
   spec.add_development_dependency "mutant-rspec", "~> 0.10"
   spec.add_development_dependency "pry-byebug"

data/lib/fixably/actions.rb

@@ -24,9 +24,13 @@ module Fixably
         @actions = format_actions(values).freeze
       end
 
+      # Active Resource 6.1 made ::all lazy, returning a relation rather than
+      # performing the request. We call ::find directly so that a
+      # PaginatedCollection is always returned, regardless of the Active
+      # Resource version.
       def all(*arguments)
         ActionPolicy.new(resource: self).list!
-        super(*arguments)
+        find(:all, *arguments)
       end
 
       def create(attributes = {})

data/lib/fixably/resources/order.rb

@@ -2,7 +2,7 @@
 
 module Fixably
   class Order < ApplicationResource
-    actions %i[create list show]
+    actions %i[create list show update]
 
     schema do
       string :internal_location
@@ -64,7 +64,7 @@ module Fixably
     class Note < ApplicationResource
       actions %i[create list show]
 
-      ALLOWED_TYPES = %w[DIAGNOSIS INTERNAL ISSUE RESOLUTION].freeze
+      ALLOWED_TYPES = %w[DIAGNOSIS DETAILS INTERNAL ISSUE RESOLUTION].freeze
 
       validates(
         :type,

data/lib/fixably/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Fixably
-  VERSION = "0.6.1"
+  VERSION = "0.7.0"
 end

data/lib/fixably.rb

@@ -35,4 +35,6 @@ module Fixably
       config.logger
     end
   end
+
+  ActiveSupport.run_load_hooks(:fixably, self) if defined?(ActiveSupport)
 end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: fixably
 version: !ruby/object:Gem::Version
-  version: 0.6.1
+  version: 0.7.0
 platform: ruby
 authors:
 - Adam Rice
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-01-19 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activeresource
@@ -30,6 +29,20 @@ dependencies:
     - - "<"
       - !ruby/object:Gem::Version
         version: '7'
+- !ruby/object:Gem::Dependency
+  name: logger
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
 - !ruby/object:Gem::Dependency
   name: mutant-rspec
   requirement: !ruby/object:Gem::Requirement
@@ -142,7 +155,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description:
 email:
 - development@hashnotadam.com
 executables: []
@@ -154,6 +166,7 @@ files:
 - ".mutant.yml"
 - ".rspec"
 - ".rubocop.yml"
+- CLAUDE.md
 - CODE_OF_CONDUCT.md
 - Gemfile
 - Gemfile.lock
@@ -204,7 +217,6 @@ metadata:
   rubygems_mfa_required: 'true'
   homepage_uri: https://github.com/HashNotAdam/fixably-ruby
   source_code_uri: https://github.com/HashNotAdam/fixably-ruby
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -219,8 +231,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.3
-signing_key:
+rubygems_version: 4.0.16
 specification_version: 4
 summary: Ruby client for the Fixably API
 test_files: []