fortnox-api 1.0.0.rc6 → 1.0.0.rc9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 42db7fb64630302bc5d10e1ea99f03586a6d6927ed09a33bdbce1408fb820684
-  data.tar.gz: a98ed1b9a2380a48044f1b6f29f99ef4da35d92b9b4a7d70a260a0e82f244f60
+  metadata.gz: a20aeb0e4dd1618609c445e649bc8b1d5014febdc7eafcb733d4477a054dca60
+  data.tar.gz: '02592cebf00ea6190f2d0d863a54441346e973e06e0f65fd4e436cda63c57587'
 SHA512:
-  metadata.gz: 67396cd4f4f0609671f11d30195446514208e3e57a244071a144151daca2b40d988167bf2ea73e4cb256d425feaa20e7b92c2450cbbc6d85fbb2cea61e7112ae
-  data.tar.gz: ebd081caa219cb82d91a15ba6c6f58c62f6e19f4fc789ffe8963bca9ae533f1138766bbb1ec7fe6f4f1550fa2a0416bf6d7a37fa63ea0642833ed45d4d91f3c7
+  metadata.gz: d65bbab5d39d6428068de1132c2e5d0251acfd3c4e70fe120d37fbb0680d6e82f861935106e6386c4b3b2951f8a513b19b821009459a6e5c4a69f38a9368d50f
+  data.tar.gz: 95858ca85e8694c9d699ec7dd054f5c93e7a1fce3ca078d8bb690ee61f0e691a44cff23f4c3a5633459659234560815a766391ca2d12dce3b1f804f54abb486f

data/CHANGELOG.md

@@ -6,6 +6,56 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to
 [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [1.0.0.rc9] - 2026-05-20
+
+### Added
+
+- `Fortnox::ALLOWED_CHARACTERS_REGEXP` constant, exposing the character
+  set Fortnox accepts in text fields. Sourced from the official Fortnox
+  docs. Useful for pre-validating strings before sending them to the API.
+
+### Changed
+
+- `Customer#default_delivery_types.invoice` now accepts `'ELECTRONICINVOICE'`
+  when returned by Fortnox. The value is read-only — attempting to set it from
+  consumer code raises `Fortnox::ConstraintError` at save time,
+  rather than letting Fortnox reject the request.
+  Unchanged values round-trip through `save` as before.
+
+## [1.0.0.rc8] - 2026-05-19
+
+### Changed
+
+- `fortnox-setup` now prints the authorization URL and asks before
+  opening a browser when a non-localhost redirect URI is used, defaulting
+  to not opening it. Previously it always opened the URL locally, so the
+  browser immediately followed the redirect and the URL was lost — making
+  it impossible to hand off to whoever should log in (e.g. a customer).
+  The local-server flow is unchanged.
+
+## [1.0.0.rc7] - 2026-05-19
+
+### Changed
+
+- **Breaking** Minimum Ruby version raised to 3.2. Ruby 3.1 reached
+  end-of-life in March 2025 and is no longer supported or tested.
+- Upgraded `rest-easy` dependency to `~> 1.3.0`.
+
+### Fixed
+
+- Declare `base64` as a runtime dependency. It is `require`d by the gem
+  and used for OAuth credential encoding, but `base64` was removed from
+  Ruby's default gems in 3.4, so the gem failed to load on Ruby 3.4 with
+  `LoadError: cannot load such file -- base64`.
+- Saving a persisted record with no changes is again a no-op, matching
+  0.9. In that version `save` returned early for an unchanged persisted record
+  without issuing a request. The 1.0.0.rc1 rest-easy rewrite regressed
+  this: `save` on a record fetched via `find` re-sent every attribute
+  via a full-record `PUT`, which could clobber fields changed elsewhere
+  since it was loaded.
+
 ## [1.0.0.rc6] - 2026-05-18
 
 ### Added
@@ -194,6 +244,12 @@ 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.rc9...HEAD
+[1.0.0.rc9]: https://github.com/accodeing/fortnox-api/compare/v1.0.0.rc8...v1.0.0.rc9
+[1.0.0.rc8]: https://github.com/accodeing/fortnox-api/compare/v1.0.0.rc7...v1.0.0.rc8
+[1.0.0.rc7]: https://github.com/accodeing/fortnox-api/compare/v1.0.0.rc6...v1.0.0.rc7
+[1.0.0.rc6]: https://github.com/accodeing/fortnox-api/compare/v1.0.0.rc5...v1.0.0.rc6
+[1.0.0.rc5]: https://github.com/accodeing/fortnox-api/compare/v1.0.0.rc4...v1.0.0.rc5
 [1.0.0.rc4]: https://github.com/accodeing/fortnox-api/compare/v1.0.0.rc3...v1.0.0.rc4
 [1.0.0.rc3]: https://github.com/accodeing/fortnox-api/compare/v1.0.0.rc2...v1.0.0.rc3
 [1.0.0.rc2]: https://github.com/accodeing/fortnox-api/compare/v1.0.0.rc1...v1.0.0.rc2

data/README.md

@@ -1,5 +1,7 @@
 # fortnox-api
 
+[![CI](https://github.com/accodeing/fortnox-api/actions/workflows/ci.yml/badge.svg)](https://github.com/accodeing/fortnox-api/actions/workflows/ci.yml)
+
 Ruby gem for Fortnox's version 3 REST API, built on
 [rest-easy](https://github.com/accodeing/rest-easy). If you need to integrate an existing or new Ruby
 or Rails app against Fortnox this gem will save you a lot of time.
@@ -10,13 +12,13 @@ Feel free to repay the community with some nice PRs of your own.
 
 Article, Customer, Invoice, Label, Order, Project, TermsOfPayment, Unit
 
-Adding more resources is quick and easy, see the
-[Contributing](#contributing) section.
+Adding more resources is quick and easy — see the
+[Developer readme](DEVELOPER_README.md).
 
 ## Status
 
 Version 1.0 is a complete rewrite, currently in release candidate
-(`1.0.0.rc6`). It is built on
+(`1.0.0.rc8`). It is built on
 [rest-easy](https://github.com/accodeing/rest-easy), replacing the old
 HTTParty + Data Mapper architecture with a single resource class per entity.
 Authorization uses the Fortnox client credentials flow.
@@ -62,6 +64,16 @@ sending it to the API, which saves you API calls and time debugging. You can
 still get errors from the server; our implementation is not perfect. Also,
 Fortnox sometimes requires a specific combination of attributes.
 
+#### Allowed characters
+
+`Fortnox::ALLOWED_CHARACTERS_REGEXP` exposes the character set Fortnox
+accepts in text fields, sourced from the [official Fortnox docs][formats].
+The gem itself does not apply this regex to attribute values — it is
+provided so consumers can pre-validate or sanitize strings before
+sending them to the API.
+
+[formats]: https://www.fortnox.se/developer/guides-and-good-to-know/formats-and-encoding
+
 #### Exceptions
 
 The gem raises the following exceptions:
@@ -71,7 +83,17 @@ The gem raises the following exceptions:
 - `Fortnox::RequestError` — 4xx/5xx responses from the Fortnox API. The
   exception message includes the API's `ErrorInformation.Message` and code
   when present (Fortnox is inconsistent about the key casing — the gem
-  normalises both). The full response is on `.response`.
+  normalises both). The full response is on `.response`, which exposes
+  the HTTP status code and body — match on `.status` rather than the
+  message text:
+
+  ```ruby
+  Fortnox::Customer.find(id)
+  rescue Fortnox::RequestError => e
+    return nil if e.response&.status == 404
+
+    raise
+  ```
 - `Fortnox::AttributeError` — base for attribute validation failures.
   - `Fortnox::ConstraintError` — an attribute value violates a type
     constraint (max size, format, etc.). Carries `.attribute_name` and
@@ -83,7 +105,7 @@ The gem raises the following exceptions:
 
 ## Requirements
 
-Ruby 3.1 or higher.
+Ruby 3.2 or higher.
 
 ### Installation
 
@@ -308,6 +330,19 @@ updated = customer.update(name: 'Acme Inc')
 Fortnox::Customer.save(updated)
 ```
 
+Updates are partial: only the attributes you pass to `.update` are sent to
+Fortnox. Attributes you don't touch are left as-is on the record (so a
+field changed elsewhere in the meantime is not clobbered). Note this is
+based on *which* attributes you pass, not a value comparison — passing an
+attribute equal to its stored value still sends it. Setting an attribute
+to `nil` is sent as an explicit clear:
+
+```ruby
+customer = Fortnox::Customer.find(1)
+updated = customer.update(phone1: nil)
+Fortnox::Customer.save(updated) # phone1 is now cleared in Fortnox
+```
+
 ### Searching
 
 ```ruby
@@ -322,11 +357,7 @@ Some resources support server-side filters:
 Fortnox::Invoice.only('unpaid')
 ```
 
-### Debugging
-
-The gem exposes two independent debugging knobs from rest-easy.
-
-#### HTTP wire logging
+### Logging
 
 Set a `Logger`-compatible instance on the gem-level config to log every
 HTTP request and response. Faraday's built-in logger middleware is attached
@@ -358,18 +389,10 @@ take effect only on restart.
 The `fortnox-setup` and `fortnox-update-env` executables talk directly to
 the OAuth token endpoint and are not routed through this logger.
 
-#### Per-resource response-shape validation
-
-Set `debug true` on a resource to have rest-easy warn whenever an API
-response contains fields the resource doesn't declare with `attr` or
-`ignore`, or is missing a declared (non-required) attribute. Useful for
-catching schema drift when Fortnox adds or renames fields:
-
-```ruby
-Fortnox::Customer.configure do
-  debug true
-end
-```
+If you suspect the gem is silently dropping a field Fortnox added — or
+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.
 
 ### Gotchas
 

data/bin/fortnox-setup

@@ -154,15 +154,21 @@ auth_params = URI.encode_www_form(
 authorize_url = "#{OAUTH_ENDPOINT}/auth?#{auth_params}"
 
 puts
-puts 'Opening browser for Fortnox authorization...'
-
-open_browser(authorize_url)
 
 if use_local_server
+  puts 'Opening browser for Fortnox authorization...'
+  open_browser(authorize_url)
   puts
   puts 'Waiting for Fortnox to redirect back...'
   authorization_code = get_auth_code_from_server(LOCAL_PORT, nonce)
 else
+  puts 'Authorization URL. Open it to log in, or send it to whoever should'
+  puts 'log in to the Fortnox account being connected:'
+  puts
+  puts "  #{authorize_url}"
+  puts
+  open_here = prompt('Open it in your browser now?', default: 'n')
+  open_browser(authorize_url) if open_here.downcase.start_with?('y')
   authorization_code = auth_code_manually
 end
 

data/fortnox.gemspec

@@ -19,11 +19,12 @@ Gem::Specification.new do |spec|
   spec.executables   = ['fortnox-setup', 'fortnox-update-env']
   spec.require_paths = ['lib']
 
-  spec.required_ruby_version = '>= 3.1.0'
+  spec.required_ruby_version = '>= 3.2.0'
 
+  spec.add_dependency 'base64'
   spec.add_dependency 'countries', '~> 7.1'
   spec.add_dependency 'dry-struct', '~> 1.5'
-  spec.add_dependency 'rest-easy', '~> 1.2.0'
+  spec.add_dependency 'rest-easy', '~> 1.3.0'
 
   spec.metadata['rubygems_mfa_required'] = 'true'
 end

data/lib/fortnox/resource.rb

@@ -29,7 +29,9 @@ module Fortnox
         # Strip nils for new records — rely on Fortnox defaults
         data = data.compact
       elsif __changes__.any?
-        # Only send changed attributes on update, preserving explicit nils
+        # Send only the attributes passed to .update — field-level dirty
+        # tracking, not a value diff, so an attribute equal to its stored
+        # value is still sent, and an explicit nil reaches Fortnox as a clear.
         changed_api_names = __changes__.keys.filter_map do |model_name|
           self.class.all_attribute_definitions[model_name]&.api_name
         end
@@ -61,6 +63,12 @@ module Fortnox
       end
 
       def save(instance)
+        # A persisted record with no recorded changes has nothing to write.
+        # Without this short-circuit rest-easy would PUT the entire record
+        # back, re-sending every untouched attribute and risking clobbering
+        # changes made elsewhere since it was loaded.
+        return instance if !instance.meta.new? && instance.__changes__.empty?
+
         with_translated_errors { super }
       end
 

data/lib/fortnox/resources/customer.rb

@@ -11,6 +11,10 @@ module Fortnox
       scope 'customer'
     end
 
+    before_serialise do |_attrs|
+      validate_electronic_invoice_delivery_type!(default_delivery_types&.invoice)
+    end
+
     # Direct URL to the record.
     attr :url <=> '@url', Coercible::String.optional, :read_only
 
@@ -205,5 +209,24 @@ module Fortnox
 
     # WWW Website URL
     attr :www <=> 'WWW', Sized::String[128]
+
+    private
+
+    # ELECTRONICINVOICE is only possible to set in the Fortnox UI.
+    # Raise if a consumer tries to set it from this gem.
+    def validate_electronic_invoice_delivery_type!(type)
+      return unless type == DefaultInvoiceDeliveryTypeValues['ELECTRONICINVOICE']
+
+      set_by_consumer = meta.new? || __changes__.key?(:default_delivery_types)
+
+      return unless set_by_consumer
+
+      raise Fortnox::ConstraintError.new(
+        :default_delivery_types,
+        'ELECTRONICINVOICE',
+        "Customer#default_delivery_types.invoice cannot be changed to 'ELECTRONICINVOICE' " \
+        'via the API, you can only do that change from within Fortnox.'
+      )
+    end
   end
 end

data/lib/fortnox/structs/default_delivery_types.rb

@@ -3,13 +3,13 @@
 module Fortnox
   module Structs
     class DefaultDeliveryTypes < Fortnox::Struct
-      # Default delivery type for invoices. Can be PRINT EMAIL or PRINTSERVICE.
-      attribute? :invoice, Types::DefaultDeliveryTypeValues
+      # Default delivery type for invoices.
+      attribute? :invoice, Types::DefaultInvoiceDeliveryTypeValues
 
-      # Default delivery type for orders. Can be PRINT EMAIL or PRINTSERVICE.
+      # Default delivery type for orders.
       attribute? :order, Types::DefaultDeliveryTypeValues
 
-      # Default delivery type for offers. Can be PRINT EMAIL or PRINTSERVICE.
+      # Default delivery type for offers.
       attribute? :offer, Types::DefaultDeliveryTypeValues
     end
   end

data/lib/fortnox/types.rb

@@ -66,6 +66,10 @@ module Fortnox
       'PRINT', 'EMAIL', 'PRINTSERVICE'
     )
 
+    DefaultInvoiceDeliveryTypeValues = Types::Strict::String.enum(
+      'PRINT', 'EMAIL', 'PRINTSERVICE', 'ELECTRONICINVOICE'
+    )
+
     AccountingMethods = Types::Strict::String.enum(
       '', 'ACCRUAL', 'CASH'
     )

data/lib/fortnox/version.rb

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

data/lib/fortnox.rb

@@ -93,6 +93,14 @@ module Fortnox
 
   OAUTH_TOKEN_URL = 'https://apps.fortnox.se/oauth-v1/token'
 
+  # Character set allowed in Fortnox text fields, per the official Fortnox docs.
+  # Useful for pre-validating strings before sending them to the API.
+  # See: https://www.fortnox.se/developer/guides-and-good-to-know/formats-and-encoding
+  # (The docs spell Unicode codepoints as \x{NNNN}; Ruby's regex parser uses
+  # \u{NNNN} for the same thing, so the three codepoints below are translated.)
+  ALLOWED_CHARACTERS_REGEXP =
+    %r{\A[\p{L}’\\\u{0308}\u{030a}a-zåäöéáœæøüA-ZÅÄÖÉÁÜŒÆØ0-9 –:.`´,;\^¤#%§£$€¢¥©™°&/()=+\-*_!?²³®½@\u{00a0}\n\r]*\z}
+
   class << self
     def access_token=(token)
       Thread.current[Auth::ThreadLocal::THREAD_LOCAL_KEY] = token

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: fortnox-api
 version: !ruby/object:Gem::Version
-  version: 1.0.0.rc6
+  version: 1.0.0.rc9
 platform: ruby
 authors:
 - Jonas Schubert Erlandsson
@@ -11,8 +11,22 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-05-18 00:00:00.000000000 Z
+date: 2026-05-20 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: countries
   requirement: !ruby/object:Gem::Requirement
@@ -47,14 +61,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.2.0
+        version: 1.3.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.2.0
+        version: 1.3.0
 description: Fortnox F3 REST API library, based on rest-easy.
 email:
 - info@accodeing.com
@@ -116,14 +130,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.1.0
+      version: 3.2.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">"
     - !ruby/object:Gem::Version
       version: 1.3.1
 requirements: []
-rubygems_version: 3.4.6
+rubygems_version: 3.4.19
 signing_key:
 specification_version: 4
 summary: Fortnox F3 REST API library, based on rest-easy.