fortnox-api 1.0.0.rc13 → 1.0.0.rc15

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 695db94ae3937bdcc80a1737e65b730cc58dd6784b79eedf6296490b716ab31a
-  data.tar.gz: 3a25be836c8d7251578d71b40364c122673176c89b878a7a8ed21d68c0eb2377
+  metadata.gz: ab7ad12aa41343980f10d5669c15e92c00ffe1b144f3e2d7eb250205c8f1ddaf
+  data.tar.gz: b88c8debe218e7e0bfcfe8f89ae3c14ac5eaf7f0c9466563c23dd7d13a153b22
 SHA512:
-  metadata.gz: c8fb345adff538fbb9e0d1db6c0d653bebbfa35014ecb0b78e7ee5940c9f8f6f77eab563a2378f2d0827822a44a56fe0bf0fffc06e4c961e84850ae07b83adf9
-  data.tar.gz: '05914af9563412c342711d69418462bbd47335ea09aa46d13bf581906fd80a81fea2d1b997dc5a27f61c98b54f705637f502c4b44c3d66fcc78aea8c0368dd5c'
+  metadata.gz: 3e3580f904dc0ab0b6ade2d540e858bd6e4b282c7589508c32431da156f12634365283ed28bd1e117d81f84f8081596612b9f6ae8736e8c8063b3d11b6f2b653
+  data.tar.gz: b9150f40236d1f2c22d3410f51e774b424af4612f905d3e63174c1f333b4b5b85b474648e0ac3e6999e2c243cc1994b71bd5b89c02146769644a0099b30f887f

data/CHANGELOG.md

@@ -8,11 +8,98 @@ and this project adheres to
 
 ## [Unreleased]
 
+## [1.0.0.rc15] - 2026-08-18
+
+### Fixed
+
+- **Cached resources no longer raise on the first cache hit.** The
+  `rest-easy` dependency is now `~> 1.4.1`, which stops `RestEasy::Meta`
+  claiming to implement methods it has no value for. Because it claimed
+  `marshal_dump`, marshalling a parsed resource silently wrote `nil` where
+  the meta state should be, and reading it back raised `NoMethodError:
+  undefined method '[]' for nil:NilClass`. Every parsed Fortnox resource
+  carries a `meta` — it is where the `partial` flag lives — so any consumer
+  caching resources in a store that marshals its entries (Rails'
+  `:memory_store` and `:file_store` among them) wrote an unusable entry on
+  the first request and raised on every cache hit after that.
+
+  **Upgrading with a warm cache:** entries written before this release are
+  not recoverable and now fail with `TypeError: instance of RestEasy::Meta
+  needs to have method 'marshal_load'`. Flush the cache or bump its key
+  namespace when upgrading. A process-local `:memory_store` clears itself on
+  restart and needs nothing.
+
+## [1.0.0.rc14] - 2026-08-11
+
+### Changed
+
+- The `base64` runtime dependency is now bounded to `~> 0.2`, matching what
+  `rest-easy` already requires. It was declared open-ended when it was added
+  in 1.0.0.rc7, so a future `base64` 1.0 with a breaking change would have
+  been resolved into consumers' bundles unannounced.
+
+### Added
+
+- **Breaking** `Fortnox::UnknownAttributeError`, raised when `new`, `stub` or
+  `update` is passed an attribute the resource or struct doesn't declare.
+  Previously the attribute was silently discarded: the request went out
+  without it and Fortnox accepted the result, so a typo cost a field with no
+  indication anything was wrong. Worst on nested rows, where
+  `stub(order_rows: [{ artcile_number: '1' }])` sent `"OrderRows":[{}]` and
+  created an order with empty rows. Subclasses `Fortnox::AttributeError` and
+  carries `.attribute_names` (all of them) and `.attribute_name` (the first).
+  Consumers passing a wider hash than the resource declares must slice it
+  first. Parsing an API response is unaffected and stays tolerant of fields
+  the gem doesn't declare — Fortnox adds them over time, and a response must
+  not fail to parse because of one.
+- Attribute hashes now accept string keys as well as symbols, on `new`,
+  `stub`, `update` and struct constructors. Previously a string key matched
+  nothing and was dropped, which is how a Rails controller passing `params`
+  through produced records missing every field.
+- Optional Rails integration, `require 'fortnox/rails'`. Defines `as_json` on
+  resources, collections and nested structs so `render json:` works when they
+  are nested inside another structure — ActiveSupport walks nested objects
+  with `as_json`, and without a definition falls through to `Object#as_json`,
+  which serialises instance variables and leaks `api_data`,
+  `model_attributes`, `changes` and `meta` into response bodies. The file is
+  not loaded with the rest of the gem and ActiveSupport is not a runtime
+  dependency; requiring it is opt-in for apps that already have Rails.
+
+### Fixed
+
+- `to_json` on a resource holding nested structs no longer renders them
+  through `to_s`. An invoice or order with rows serialised them as
+  `"#<Fortnox::Structs::InvoiceRow:0x…>"`. `Fortnox::Struct#to_json` and
+  `Fortnox::Collection#to_json` are defined for the same reason — both
+  previously fell back to the default `Object#to_json`, producing an
+  inspect string rather than JSON. All three render the model representation
+  (snake_case attribute names); `to_api` still produces the Fortnox wire
+  format. This affects all consumers, not only Rails apps.
+- Nested structs (`Fortnox::Structs::*`) now coerce boolean attributes from
+  the string spellings params arrive as (`'true'`, `'false'`, `'yes'`,
+  `'no'`, `'1'`, `'0'`, `'on'`, `'off'`), matching what resource attributes
+  have always accepted. Previously the struct-level type was strict and
+  rejected every string, so `Order.stub(order_rows: [{ housework: 'true' }])`
+  failed while the equivalent value on a resource attribute coerced cleanly
+  — callers passing Rails controller params had to cast booleans by hand
+  before building rows. Affects `DocumentRow#housework` and the `InvoiceRow`
+  and `OrderRow` subclasses. This asymmetry was introduced in 1.0.0.rc1 and
+  did not exist in 0.x.
+- Struct construction now raises Fortnox-namespaced errors. A bad value in a
+  nested struct — reached directly via `Fortnox::Structs::OrderRow.new` or
+  indirectly via `stub`/`update` with a nested hash — previously raised
+  `Dry::Struct::Error`, which is a `TypeError` outside the `Fortnox::Error`
+  hierarchy, so `rescue Fortnox::AttributeError` blocks didn't catch it. It
+  now raises `Fortnox::ConstraintError` carrying `.attribute_name` and
+  `.value`, with the same message format as the resource-level error. This
+  extends the error translation added in 1.0.0.rc13, which covered resources
+  but not structs.
+
 ## [1.0.0.rc13] - 2026-08-04
 
 ### Changed
 
-- String attributes now normalise `''` to `nil` at the type level. This
+- **Breaking** String attributes now normalise `''` to `nil` at the type level. This
   is the mechanism behind the reset fix below: Fortnox silently ignores
   empty strings in update payloads — updating an attribute to `''` kept
   the original value — and a field can only be cleared with an explicit
@@ -332,7 +419,9 @@ for the full list of breaking changes.
 For changes prior to the 1.0 rewrite, see the
 [0.x changelog](https://github.com/accodeing/fortnox-api/blob/v0.9.2/CHANGELOG.md).
 
-[Unreleased]: https://github.com/accodeing/fortnox-api/compare/v1.0.0.rc13...HEAD
+[Unreleased]: https://github.com/accodeing/fortnox-api/compare/v1.0.0.rc15...HEAD
+[1.0.0.rc15]: https://github.com/accodeing/fortnox-api/compare/v1.0.0.rc14...v1.0.0.rc15
+[1.0.0.rc14]: https://github.com/accodeing/fortnox-api/compare/v1.0.0.rc13...v1.0.0.rc14
 [1.0.0.rc13]: https://github.com/accodeing/fortnox-api/compare/v1.0.0.rc12...v1.0.0.rc13
 [1.0.0.rc12]: https://github.com/accodeing/fortnox-api/compare/v1.0.0.rc11...v1.0.0.rc12
 [1.0.0.rc11]: https://github.com/accodeing/fortnox-api/compare/v1.0.0.rc10...v1.0.0.rc11

data/README.md

@@ -397,6 +397,58 @@ hitting some other schema-drift issue — please open an issue. There's a
 maintainer-only knob to surface those warnings; see the
 [Developer readme](DEVELOPER_README.md) for details.
 
+### Rails
+
+Two things are worth setting up before you render or receive Fortnox data in
+a Rails app.
+
+**Rendering.** Require the Rails integration once, in an initializer:
+
+```ruby
+# config/initializers/fortnox.rb
+require 'fortnox/rails'
+```
+
+Without it, `render json:` only works for a resource passed on its own.
+Rendering one *inside* another structure walks it with `as_json`, which the
+gem's types don't define outside this file, so ActiveSupport falls back to
+serialising instance variables and your response body gets the gem's
+internals:
+
+```ruby
+# Without fortnox/rails
+render json: { invoices: [Fortnox::Invoice.find(1)] }
+# => {"invoices":[{"api_data":{…},"model_attributes":{…},"changes":[…],"meta":{…}}]}
+
+# With it
+# => {"invoices":[{"document_number":1,"invoice_rows":[{"article_number":"101"}],…}]}
+```
+
+It covers resources, collections, and nested structs, and produces the same
+representation as `to_json` — model attribute names, not the Fortnox wire
+names. Rendering a collection yields its records, as an array would;
+pagination stays on the object (`.total`, `.pages`, `.current_page`) for you
+to render alongside if you want it.
+
+The file is not loaded with the rest of the gem and ActiveSupport is not a
+dependency of this gem — requiring it is opt-in, for apps that already have
+Rails.
+
+**Receiving params.** Controller params can be passed through as they arrive.
+String keys are accepted, and string values coerce — booleans from
+`'true'`/`'false'`/`'1'`/`'0'`/`'yes'`/`'no'`/`'on'`/`'off'`, numbers from
+their string forms:
+
+```ruby
+Fortnox::Order.stub('customer_number' => '1', 'order_rows' => [{ 'article_number' => '101' }])
+```
+
+An attribute the resource or struct doesn't declare raises
+`Fortnox::UnknownAttributeError` rather than being dropped, so a typo or a
+stray param surfaces at the call site instead of producing a record that is
+quietly missing a field. Filter params to the attributes you mean to accept,
+as you would for a model.
+
 ### Gotchas
 
 See [docs/gotchas.md](docs/gotchas.md) for known quirks and edge cases in the

data/fortnox.gemspec

@@ -21,10 +21,10 @@ Gem::Specification.new do |spec|
 
   spec.required_ruby_version = '>= 3.2.0'
 
-  spec.add_dependency 'base64'
+  spec.add_dependency 'base64', '~> 0.2'
   spec.add_dependency 'countries', '~> 7.1'
   spec.add_dependency 'dry-struct', '~> 1.5'
-  spec.add_dependency 'rest-easy', '~> 1.4.0'
+  spec.add_dependency 'rest-easy', '~> 1.4.1'
 
   spec.metadata['rubygems_mfa_required'] = 'true'
 end

data/lib/fortnox/attribute_keys.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Fortnox
+  # Checks the attribute names a caller passes to `new`, `stub` and `update`.
+  #
+  # Both rest-easy and Dry::Struct build from the attributes they recognise and
+  # ignore everything else, so a typo or a string key used to vanish without a
+  # word: the request went out missing that field and Fortnox accepted it. The
+  # bigger the payload, the easier that is to miss.
+  #
+  # This only guards data a caller supplies. Parsing an API response stays
+  # tolerant of fields the gem doesn't declare — Fortnox adds them over time,
+  # and a response must not fail to parse because of one.
+  module AttributeKeys
+    module_function
+
+    def check(data, known:, subject:)
+      normalised = normalise(data)
+      unknown = normalised.keys - known
+      raise Fortnox::UnknownAttributeError.new(unknown, subject) unless unknown.empty?
+
+      normalised
+    end
+
+    # Rails hands params through with string keys. Accept them rather than
+    # reporting every attribute in the hash as unknown.
+    def normalise(data)
+      data.to_h { |key, value| [symbolise(key), value] }
+    end
+
+    # Left alone if it can't be a symbol, so it falls through to the unknown
+    # check and is reported as an attribute error rather than a NoMethodError.
+    def symbolise(key)
+      key.respond_to?(:to_sym) ? key.to_sym : key
+    end
+  end
+end

data/lib/fortnox/collection.rb

@@ -7,6 +7,7 @@ module Fortnox
   # the pagination metadata Fortnox returns alongside collection responses.
   class Collection
     include Enumerable
+    include Serialisation::CollectionJSON
     extend Forwardable
 
     def_delegators :@items, :each, :first, :last, :size, :length, :empty?, :[], :to_a

data/lib/fortnox/error_translation.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Fortnox
+  # Translates rest-easy errors at the gem boundary so callers only see
+  # Fortnox-namespaced exceptions. Mixed into Fortnox::Resource both ways —
+  # `include` for the instance methods, `extend` for the class-level ones.
+  module ErrorTranslation
+    private
+
+    def with_translated_errors
+      yield
+    rescue RestEasy::ConstraintError => e
+      raise Fortnox::ConstraintError.new(e.attribute_name, e.value, e.message)
+    rescue RestEasy::MissingAttributeError => e
+      raise Fortnox::MissingAttributeError, e.attribute_name
+    rescue RestEasy::AttributeError => e
+      raise Fortnox::AttributeError, e.message
+    rescue RestEasy::RequestError => e
+      raise Fortnox::RequestError, e.response || e.message
+    end
+  end
+end

data/lib/fortnox/mappers/struct.rb

@@ -33,7 +33,11 @@ module Fortnox
           attributes = data.transform_keys do |api_key|
             api_to_model_map[api_key] || CONVENTION.parse(api_key)
           end
-          struct_class.new(attributes)
+          # Drop fields the struct doesn't declare. Fortnox adds them over
+          # time, and a response must not fail to parse because of one — the
+          # strictness on `new` is aimed at what a caller passes, not at what
+          # the API returns.
+          struct_class.new(attributes.slice(*struct_class.attribute_names))
         end
 
         def serialise(struct)

data/lib/fortnox/rails.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require 'fortnox'
+require 'active_support/json'
+
+# Optional Rails integration. Not loaded with the rest of the gem — require it
+# explicitly, e.g. from config/initializers/fortnox.rb:
+#
+#   require 'fortnox/rails'
+#
+# Rails serialises nested objects by calling `as_json` on them. Anything that
+# doesn't define it falls through to `Object#as_json`, which dumps instance
+# variables — so without this, `render json: { invoices: [invoice] }` puts the
+# gem's internals (`api_data`, `model_attributes`, `changes`, `meta`) in the
+# response body. `to_json` needs no help here; it is correct without Rails.
+module Fortnox
+  # Deliberately not named `Rails`: inside `module Fortnox` that constant would
+  # shadow the framework's own for every other file in the gem.
+  module RailsSerialisation
+    # `:only` / `:except` are applied by Fortnox::Serialisation rather than by
+    # ActiveSupport, so they accept string and symbol names alike. The inner
+    # `as_json` is then called without options — it only needs to stringify
+    # keys and recurse into nested structs.
+    module ResourceMethods
+      # Same representation `to_json` produces: model attribute names.
+      def as_json(options = nil)
+        Serialisation.filter(model.attributes, options).as_json
+      end
+    end
+
+    module StructMethods
+      def as_json(options = nil)
+        Serialisation.filter(to_h, options).as_json
+      end
+    end
+
+    module CollectionMethods
+      def as_json(options = nil)
+        to_a.map { |item| item.as_json(options) }
+      end
+    end
+  end
+end
+
+Fortnox::Resource.include(Fortnox::RailsSerialisation::ResourceMethods)
+Fortnox::Struct.include(Fortnox::RailsSerialisation::StructMethods)
+Fortnox::Collection.include(Fortnox::RailsSerialisation::CollectionMethods)

data/lib/fortnox/resource.rb

@@ -1,8 +1,12 @@
 # frozen_string_literal: true
 
 module Fortnox
+  # TODO: this class is still over the length limit even with error
+  # translation extracted — see todo.md.
+  # rubocop:disable Metrics/ClassLength
   class Resource < RestEasy::Resource
     include Fortnox::Types
+    include Serialisation::ResourceJSON
 
     settings do
       setting :instance_wrapper, reader: true
@@ -26,24 +30,6 @@ module Fortnox
 
     after_serialise { |data| default_after_serialise(data) }
 
-    # Translate rest-easy errors at the gem boundary so callers only see
-    # Fortnox-namespaced exceptions.
-    module ErrorTranslation
-      private
-
-      def with_translated_errors
-        yield
-      rescue RestEasy::ConstraintError => e
-        raise Fortnox::ConstraintError.new(e.attribute_name, e.value, e.message)
-      rescue RestEasy::MissingAttributeError => e
-        raise Fortnox::MissingAttributeError, e.attribute_name
-      rescue RestEasy::AttributeError => e
-        raise Fortnox::AttributeError, e.message
-      rescue RestEasy::RequestError => e
-        raise Fortnox::RequestError, e.response || e.message
-      end
-    end
-
     include ErrorTranslation # instance-level methods
     extend ErrorTranslation # class-level methods
 
@@ -63,12 +49,12 @@ module Fortnox
         end
       end
 
-      def new(...)
-        with_translated_errors { super }
+      def new(model_data = {}, **kwargs)
+        with_translated_errors { super(checked_attributes(model_data.merge(kwargs))) }
       end
 
       def stub(**model_data)
-        with_translated_errors { super }
+        with_translated_errors { super(**checked_attributes(model_data)) }
       end
 
       def save(instance)
@@ -119,6 +105,13 @@ module Fortnox
 
       private
 
+      # Attribute names a caller may pass. Read-only attributes are included:
+      # rest-easy drops them from the payload later, and rejecting them here
+      # would break round-tripping a parsed record back through `update`.
+      def checked_attributes(data)
+        AttributeKeys.check(data, known: all_attribute_definitions.keys, subject: self)
+      end
+
       def extract_pagination(data)
         return {} unless data.is_a?(Hash) && data.key?('MetaInformation')
 
@@ -131,8 +124,8 @@ module Fortnox
       end
     end
 
-    def update(...)
-      with_translated_errors { super }
+    def update(changes = {}, **kwargs)
+      with_translated_errors { super(self.class.send(:checked_attributes, changes.merge(kwargs))) }
     end
 
     def serialise(...)
@@ -159,4 +152,5 @@ module Fortnox
       { config.instance_wrapper => data }
     end
   end
+  # rubocop:enable Metrics/ClassLength
 end

data/lib/fortnox/serialisation.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Fortnox
+  # JSON rendering for the three types a consumer can hold.
+  #
+  # rest-easy generates JSON straight from the attribute hash, and `JSON`
+  # renders anything it doesn't recognise through `to_s`. Nested structs are
+  # the case that matters: without this, an invoice with rows serialises them
+  # as `"#<Fortnox::Structs::InvoiceRow:0x…>"`.
+  #
+  # All three render the model representation — snake_case attribute names —
+  # not the Fortnox wire format. Use `to_api` for the latter.
+  module Serialisation
+    # Applies Rails' `:only` / `:except` render options.
+    #
+    # ActiveSupport's `Hash#as_json` slices a symbol-keyed hash, so a caller
+    # passing `only: ['name']` would match nothing and silently render `{}`.
+    # Normalise both sides instead, and accept either spelling.
+    #
+    # Anything that isn't an options hash is ignored — `JSON.generate` passes a
+    # `JSON::State` here when a resource is nested inside another structure.
+    def self.filter(attributes, options)
+      return attributes unless options.is_a?(::Hash)
+
+      if options[:only]
+        attributes.slice(*Array(options[:only]).map(&:to_sym))
+      elsif options[:except]
+        attributes.except(*Array(options[:except]).map(&:to_sym))
+      else
+        attributes
+      end
+    end
+
+    # Converts model values into JSON-safe primitives.
+    def self.json_safe(value)
+      case value
+      when Fortnox::Struct then json_safe(value.to_h)
+      when ::Hash then value.to_h { |key, nested| [key.to_s, json_safe(nested)] }
+      when ::Array then value.map { |element| json_safe(element) }
+      else value
+      end
+    end
+
+    module ResourceJSON
+      def to_json(options = nil)
+        ::JSON.generate(Serialisation.json_safe(Serialisation.filter(model.attributes, options)))
+      end
+    end
+
+    module StructJSON
+      def to_json(options = nil)
+        ::JSON.generate(Serialisation.json_safe(Serialisation.filter(to_h, options)))
+      end
+    end
+
+    module CollectionJSON
+      # Renders as its records, the way an Array of them would. Pagination
+      # metadata stays addressable on the collection for callers that want to
+      # render it alongside.
+      def to_json(options = nil)
+        rendered = to_a.map do |item|
+          Serialisation.json_safe(Serialisation.filter(item.model.attributes, options))
+        end
+        ::JSON.generate(rendered)
+      end
+    end
+  end
+end

data/lib/fortnox/struct.rb

@@ -4,6 +4,24 @@ require 'dry-struct'
 
 module Fortnox
   class Struct < Dry::Struct
+    include Serialisation::StructJSON
+
+    # Accept the string keys Rails params arrive with. Not `&:to_sym` — a key
+    # that can't be symbolised would raise NoMethodError from outside the
+    # Fortnox::Error hierarchy instead of being reported as unknown.
+    transform_keys { |key| AttributeKeys.symbolise(key) }
+
+    # Reject attribute names the struct doesn't declare. Dry::Struct ignores
+    # them by default, so a misspelled key silently produced an empty row that
+    # Fortnox then accepted. Parsing stays tolerant of undeclared fields —
+    # Mappers::Struct slices API data to the declared attributes first.
+    schema schema.strict
+
+    # Lets us tell "no attributes given" apart from "given an empty hash", so
+    # Dry::Struct still gets to apply its own defaults in the former case.
+    NO_ATTRIBUTES = ::Object.new.freeze
+    private_constant :NO_ATTRIBUTES
+
     class << self
       def read_only_attributes
         @read_only_attributes ||=
@@ -19,6 +37,76 @@ module Fortnox
         read_only_attributes << name if flags.include?(:read_only)
         super(name, type)
       end
+
+      # Dry::Struct signals a bad value with Dry::Struct::Error, a TypeError
+      # that sits outside the Fortnox::Error hierarchy — so a caller's
+      # `rescue Fortnox::AttributeError` misses it and the failure surfaces as
+      # an unhandled crash. Structs are reachable through the same public
+      # entry points as resources (`Resource.stub` coerces nested hashes into
+      # structs), so they translate their errors the same way.
+      # rubocop:disable Style/OptionalBooleanParameter
+      # `safe` is Dry::Struct's own second positional parameter — it picks the
+      # non-raising coercion path — so it has to stay positional here. We only
+      # pass it through.
+      def new(attributes = NO_ATTRIBUTES, safe = false, &)
+        return super() if NO_ATTRIBUTES.equal?(attributes)
+
+        super
+      rescue Dry::Struct::Error => e
+        raise translated_error(e, attributes)
+      end
+      # rubocop:enable Style/OptionalBooleanParameter
+
+      # Attribute names this struct accepts.
+      def attribute_names
+        schema.keys.map(&:name)
+      end
+
+      private
+
+      def translated_error(error, attributes)
+        return Fortnox::AttributeError.new(error.message) unless attributes.is_a?(::Hash)
+
+        unknown_attribute_error(attributes) ||
+          failing_attribute_error(attributes) ||
+          Fortnox::AttributeError.new(error.message)
+      end
+
+      # Dry::Struct reports a strict-schema rejection as "unexpected keys […]"
+      # in the message only. Recompute the names from the input rather than
+      # parsing that string back out.
+      def unknown_attribute_error(attributes)
+        unknown = AttributeKeys.normalise(attributes).keys - attribute_names
+        return nil if unknown.empty?
+
+        Fortnox::UnknownAttributeError.new(unknown, self)
+      end
+
+      # Dry::Struct discards the underlying coercion error, keeping only its
+      # message, so re-run each value through its own key type to recover
+      # which attribute was at fault and what it was given.
+      def failing_attribute_error(attributes)
+        keys = schema.keys.to_h { |key| [key.name, key] }
+
+        attributes.each do |name, value|
+          key = keys[name.to_s.to_sym]
+          next if key.nil?
+
+          error = coercion_error_for(key, value)
+          return error if error
+        end
+
+        nil
+      end
+
+      def coercion_error_for(key, value)
+        key.call(value)
+        nil
+      rescue Dry::Types::CoercionError => e
+        # Report the key type's own message rather than Dry::Struct's wrapper,
+        # so struct and resource failures read identically.
+        Fortnox::ConstraintError.new(key.name, value, "Attribute '#{key.name}': #{e.message}")
+      end
     end
   end
 end

data/lib/fortnox/structs/document_row.rb

@@ -34,7 +34,7 @@ module Fortnox
       attribute? :discount_type, Types::DiscountTypes
 
       # HouseWork If the row is housework
-      attribute? :housework, Types::Bool.optional
+      attribute? :housework, Types::CoercibleBool.optional
 
       # HouseWorkHoursToReport Hours to be reported if the quantity of the row
       # should not be used as hours. 5 digits

data/lib/fortnox/types.rb

@@ -7,7 +7,13 @@ module Fortnox
   module Types
     include Dry.Types()
 
-    THE_TRUTH = { true => true, 'true' => true, false => false, 'false' => false }.freeze
+    # Booleans reach us as strings whenever the caller is a Rails app passing
+    # controller params through. Resource attributes already coerce those:
+    # rest-easy's `Boolean` is `Dry::Types['params.bool']`, and it wins over
+    # the strict type declared alongside it. Struct attributes have to ask for
+    # the same coercion explicitly, or the two paths disagree about whether
+    # 'true' is a boolean.
+    CoercibleBool = Types::Params::Bool
 
     ArticleTypes = Types::Strict::String.enum(
       'SERVICE', 'STOCK'

data/lib/fortnox/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Fortnox
-  VERSION = '1.0.0.rc13'
+  VERSION = '1.0.0.rc15'
 end

data/lib/fortnox.rb

@@ -8,6 +8,9 @@ require 'zeitwerk'
 module Fortnox
   @loader = Zeitwerk::Loader.for_gem
   @loader.collapse("#{__dir__}/fortnox/resources")
+  # Optional Rails integration — required explicitly by consumers, never
+  # autoloaded, and it defines no constant matching its path.
+  @loader.ignore("#{__dir__}/fortnox/rails.rb")
   @loader.inflector.inflect(
     'edi_information' => 'EDIInformation'
   )
@@ -89,6 +92,21 @@ module Fortnox
     end
   end
 
+  class UnknownAttributeError < AttributeError
+    attr_reader :attribute_names, :subject
+
+    def initialize(attribute_names, subject = nil)
+      @attribute_names = Array(attribute_names)
+      @subject = subject
+      super("Unknown attribute#{'s' if @attribute_names.length > 1} for #{subject}: " \
+            "#{@attribute_names.map(&:inspect).join(', ')}")
+    end
+
+    def attribute_name
+      @attribute_names.first
+    end
+  end
+
   class MissingAccessToken < Error; end
 
   OAUTH_TOKEN_URL = 'https://apps.fortnox.se/oauth-v1/token'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: fortnox-api
 version: !ruby/object:Gem::Version
-  version: 1.0.0.rc13
+  version: 1.0.0.rc15
 platform: ruby
 authors:
 - Jonas Schubert Erlandsson
@@ -11,22 +11,22 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-04 00:00:00.000000000 Z
+date: 2026-08-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '0.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '0.2'
 - !ruby/object:Gem::Dependency
   name: countries
   requirement: !ruby/object:Gem::Requirement
@@ -61,14 +61,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.4.0
+        version: 1.4.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.4.0
+        version: 1.4.1
 description: Fortnox F3 REST API library, based on rest-easy.
 email:
 - info@accodeing.com
@@ -85,8 +85,10 @@ files:
 - bin/fortnox-update-env
 - fortnox.gemspec
 - lib/fortnox.rb
+- lib/fortnox/attribute_keys.rb
 - lib/fortnox/auth/thread_local.rb
 - lib/fortnox/collection.rb
+- lib/fortnox/error_translation.rb
 - lib/fortnox/mappers/country_code.rb
 - lib/fortnox/mappers/date.rb
 - lib/fortnox/mappers/document_row.rb
@@ -97,6 +99,7 @@ files:
 - lib/fortnox/mappers/order_row.rb
 - lib/fortnox/mappers/struct.rb
 - lib/fortnox/mappers/struct_array.rb
+- lib/fortnox/rails.rb
 - lib/fortnox/resource.rb
 - lib/fortnox/resources/article.rb
 - lib/fortnox/resources/customer.rb
@@ -107,6 +110,7 @@ files:
 - lib/fortnox/resources/project.rb
 - lib/fortnox/resources/terms_of_payment.rb
 - lib/fortnox/resources/unit.rb
+- lib/fortnox/serialisation.rb
 - lib/fortnox/struct.rb
 - lib/fortnox/structs/default_delivery_types.rb
 - lib/fortnox/structs/default_templates.rb