fortnox-api 1.0.0.rc16 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7350800553373489f35a73af7206ae013a6004024b53db948e2778e85c0f61b5
-  data.tar.gz: 359f4b9fb46a0b17aa67180b977021a9bcab6653a722043df93954ccc68b470d
+  metadata.gz: ee5902e0761d37969a38cf156349c22e8f3e967f0e8120f31753b17a12561e51
+  data.tar.gz: 4fc8b16d34cf2b2211f5587422c196f1711b4d498158a39480024117330284cb
 SHA512:
-  metadata.gz: c9f62481c8990889206483a455a6f8b6c11060c4f60aad75c8ebbe97825efa5747f7176506a1de69e66df0d0d56592b35d713154a4a033176da5646bc8c7aa2d
-  data.tar.gz: a2e684f757d98304b7ed7e08c167900abaecb027fb31b291b59d1fe57c5cc0f89753e3d0110d9f8cd01c90ce36964c09c28d7b85b8474ea9758507366e647672
+  metadata.gz: 2bbee1c33ff2a933bf3f090aea82838a61f744300f0f8ad3106d17e28a461b77c3b649141628361d9a3359a98bef33cef0e2d0c1545f922e3834df520c42da2e
+  data.tar.gz: 4013813c2652fedc7b8f96e31686ff6a6c62aefac25e8a8f8e1516159fa95b22386e26bd8f19f538cd0b7e882cfcdaed97b2a6a9681c4238af8885f8b484dba3

data/CHANGELOG.md

@@ -8,6 +8,91 @@ and this project adheres to
 
 ## [Unreleased]
 
+## [1.0.1] - 2026-09-23
+
+### Fixed
+
+- **Updating a record before its first save no longer drops the attributes it
+  was built with.** Calling `.update` on a stubbed record marked it as already
+  persisted, so `save` sent a PUT for a record that does not exist yet, and the
+  request body shrank to only the updated fields — everything passed to `stub`
+  never reached Fortnox. This is the bug reported in #233 against 0.x and fixed
+  there in 2023; the 1.0 rest-easy rewrite reintroduced it, and made it worse by
+  switching the verb as well as the body.
+- **Chained updates no longer lose all but the last.**
+  `record.update(phone1: '1').update(email: 'x@y.se')` sent only `Email`, while
+  `phone1` still read back as `'1'` on the instance — the object and the request
+  body disagreed, with nothing raised. Both attributes are now sent. Introduced
+  by the 1.0 rewrite.
+- **`meta.partial?` survives an update.** Instances parsed from a collection
+  response are flagged partial, and `.update` silently cleared the flag, so the
+  check the README recommends before re-fetching reported a shallow record as
+  complete the moment anything touched it. The flag is new in 1.0, so this
+  never affected 0.x.
+
+### Changed
+
+- The `rest-easy` dependency is now `~> 1.4.2`, which carries the three fixes
+  above — all of them live in its `update`, not in this gem.
+
+## [1.0.0] - 2026-09-23
+
+The first stable release of the 1.0 line. No code changes since
+`1.0.0.rc16` — the release candidate series is over and the 1.0 API is
+now settled. Consumers pinned to `1.0.0.rc16` can move to `1.0.0` as is;
+from an earlier release candidate, see the entries below for what
+changed in between.
+
+### Breaking changes
+
+1.0 is a complete rewrite and is **not** a drop-in replacement for 0.x.
+[MIGRATING_TO_1.0.md](MIGRATING_TO_1.0.md) is the guided upgrade; this is
+the checklist to read it against. Each entry names the release candidate
+that introduced it, where the full reasoning and the exact before/after
+live.
+
+- **The gem is rebuilt on [rest-easy](https://github.com/accodeing/rest-easy)**,
+  one resource class per entity in place of HTTParty + Data Mapper, and the
+  namespace moves from `Fortnox::API` to `Fortnox` — `Fortnox::API::Repository::Customer`
+  is now `Fortnox::Customer`. (rc1)
+- **Ruby 3.2 or later.** rc1 raised the floor to 3.1 and rc7 to 3.2; coming
+  from 0.x, 3.2 is the only number that matters. (rc1, rc7)
+- **Authorization is the Fortnox client credentials flow.** Refresh tokens
+  are neither needed nor supported, and a tenant ID is now required — the
+  new `fortnox-setup` executable obtains one. (rc1)
+- **Environment variables lose the `_API_` infix** (`FORTNOX_API_CLIENT_ID`
+  → `FORTNOX_CLIENT_ID`, and so on). `FORTNOX_API_REFRESH_TOKEN`,
+  `FORTNOX_API_REDIRECT_URI` and `FORTNOX_API_SCOPES` are gone;
+  `FORTNOX_TENANT_ID` is new and required. (rc1)
+- **`Fortnox.request_access_token` replaces
+  `Fortnox::API::Repository::Authentication`** for token management. (rc1)
+- **Configuration moves to module-level setters** such as
+  `Fortnox.access_token=`, from `Fortnox::API.configuration`. (rc1)
+- **Country attributes accept ISO alpha-2 codes only** (`'NO'`, not
+  `'Norge'`), on `country_code` and `delivery_country`. (rc1)
+- **Exception classes are renamed and consolidated**, `Fortnox::API::Exception`
+  → `Fortnox::Error` at the root. `Fortnox::API::MissingConfiguration` is
+  removed, `Fortnox::ConstraintError` is new, and `MissingAccessToken` now
+  raises lazily on first call rather than eagerly at construction. rc1 carries
+  the full 0.x → 1.0 mapping. (rc1)
+- **Collection-returning methods return `Fortnox::Collection`, not `Array`.**
+  It is `Enumerable` and delegates the common Array methods, so most usage is
+  unchanged; `is_a?(Array)` checks and `==` against Array literals are not. (rc1)
+- **`Invoice#accounting_method` and `#invoice_type` are enums**, where 0.x
+  took any string client-side. (rc1)
+- **String attributes normalise `''` to `nil`.** Unset string attributes now
+  read as `nil`, never `''`, so comparisons against `''` must become `nil`
+  checks. This is what makes clearing a field work at all — Fortnox ignores
+  empty strings in updates — and it means updating a required string
+  attribute to `''` raises `Fortnox::MissingAttributeError` before any
+  request goes out. Enum attributes whose value set genuinely includes `''`
+  are exempt. (rc13)
+- **Unknown attributes raise `Fortnox::UnknownAttributeError`** on `new`,
+  `stub` and `update`, where 0.x discarded them silently — a typo cost a
+  field with nothing to show for it. Code passing a wider hash than the
+  resource declares must slice it first. Parsing an API response stays
+  tolerant of undeclared fields. (rc14)
+
 ## [1.0.0.rc16] - 2026-08-19
 
 ### Added
@@ -436,7 +521,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.rc16...HEAD
+[Unreleased]: https://github.com/accodeing/fortnox-api/compare/v1.0.1...HEAD
+[1.0.1]: https://github.com/accodeing/fortnox-api/compare/v1.0.0...v1.0.1
+[1.0.0]: https://github.com/accodeing/fortnox-api/compare/v1.0.0.rc16...v1.0.0
 [1.0.0.rc16]: https://github.com/accodeing/fortnox-api/compare/v1.0.0.rc15...v1.0.0.rc16
 [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

data/MIGRATING_TO_1.0.md

@@ -0,0 +1,518 @@
+# Migrating to v1.0
+
+Version 1.0 is a complete rewrite. The gem is now built on
+[rest-easy](https://github.com/accodeing/rest-easy), replacing the old HTTParty + Data Mapper
+architecture.
+
+This guide covers the changes you need to make to upgrade your code. For the
+complete list of changes — including non-breaking improvements and bug fixes
+— see [CHANGELOG.md](CHANGELOG.md).
+
+This guide compares against the final pre-1.0 release line, 0.9 (0.9.2
+being the last release when this is written). References to "0.9" below mean that line
+— earlier 0.x releases are not covered. For the old code and documentation, see the
+[v0.9.2 release](https://github.com/accodeing/fortnox-api/tree/v0.9.2).
+
+## Ruby version
+
+The minimum Ruby version is now 3.2.
+
+## Require path
+
+```ruby
+# Before
+require 'fortnox/api'
+
+# After
+require 'fortnox'
+```
+
+## Authorization
+
+The gem now uses the Fortnox client credentials flow. Refresh tokens are no
+longer supported. A tenant ID is now required — this identifies which Fortnox
+company/tenant you are connecting to.
+
+If you don't have a tenant ID yet, run `fortnox-setup` to perform the one-time
+OAuth authorization and retrieve it. See the [README](README.md#authorization)
+for details.
+
+```ruby
+# Before
+tokens = Fortnox::API::Repository::Authentication.new.renew_tokens(
+  refresh_token: 'your-refresh-token',
+  client_id: 'your-client-id',
+  client_secret: 'your-client-secret'
+)
+Fortnox::API.access_token = tokens[:access_token]
+
+# After
+token = Fortnox.request_access_token(
+  client_id: 'your-client-id',
+  client_secret: 'your-client-secret',
+  tenant_id: 'your-tenant-id'
+)
+Fortnox.access_token = token
+```
+
+## Environment variables
+
+If you read credentials from environment variables (for example via
+`fortnox-update-env` or your own loader), the variable names changed —
+the `_API_` infix is gone:
+
+- `FORTNOX_API_CLIENT_ID` → `FORTNOX_CLIENT_ID`
+- `FORTNOX_API_CLIENT_SECRET` → `FORTNOX_CLIENT_SECRET`
+- `FORTNOX_API_ACCESS_TOKEN` → `FORTNOX_ACCESS_TOKEN`
+
+Removed:
+
+- `FORTNOX_API_REFRESH_TOKEN` — refresh tokens are no longer supported
+- `FORTNOX_API_REDIRECT_URI` — passed interactively to `fortnox-setup`
+- `FORTNOX_API_SCOPES` — selected interactively in `fortnox-setup`
+
+New:
+
+- `FORTNOX_TENANT_ID` — required for the client credentials flow
+
+## Resources replace repositories
+
+The separate model, type, mapper, and repository classes have been replaced by
+a single resource class per entity. The top-level namespace moves from
+`Fortnox::API` to `Fortnox`.
+
+```ruby
+# Before
+repo = Fortnox::API::Repository::Customer.new
+repo.all
+repo.find(1)
+repo.save(customer)
+
+# After
+Fortnox::Customer.all
+Fortnox::Customer.find(1)
+Fortnox::Customer.save(customer)
+```
+
+## Access token timing
+
+In 0.9 the access token was checked when you constructed a repository.
+`Fortnox::API::Repository::Customer.new` raised
+`Fortnox::API::MissingAccessToken` immediately if the thread had no token
+set, before any HTTP call.
+
+1.x has no repositories to construct (see
+[Resources replace repositories](#resources-replace-repositories)). The
+token is now checked lazily by the thread-local authentication, on the
+first API call from a thread that has no token set:
+
+```ruby
+# Before — raised at construction
+repo = Fortnox::API::Repository::Customer.new # => Fortnox::API::MissingAccessToken
+
+# After — nothing to construct; the first call raises
+Fortnox::Customer.find(1) # => Fortnox::MissingAccessToken
+```
+
+Two consequences when migrating:
+
+- **Rescue location moves.** Code that wrapped repository construction
+  (at boot, or in an initializer) with `rescue
+  Fortnox::API::MissingAccessToken` will find that catch path stops
+  firing — the failure now surfaces at the first API call. Move the
+  rescue to the call site.
+- **Each thread still needs its own token, and mis-setup surfaces
+  later.** The token is thread-local (this was true in 0.9 too): Sidekiq
+  workers, Puma threads, etc. must each set `Fortnox.access_token = …`
+  before their first API call. A thread that forgets no longer fails
+  early at construction — it fails on its first request, so the mistake
+  shows up at the call site rather than at boot.
+
+## Return values
+
+`find`, `save`, and `all` now return resource instances instead of model
+objects. Attributes are accessed directly on the instance, so existing reads
+generally keep working:
+
+```ruby
+# Before
+invoice = repo.find(1)
+invoice.total          # => 100.0
+invoice.customer_name  # => 'Acme'
+
+# After
+invoice = Fortnox::Invoice.find(1)
+invoice.total          # => 100.0
+invoice.customer_name  # => 'Acme'
+```
+
+Resource instances also have `.meta` (tracks whether the record is new or
+saved) and `.unique_id` (the primary key).
+
+`all`, `find(hash)`, `search`, and `only` return a `Fortnox::Collection` of
+resource instances. Collection is `Enumerable` and delegates `each`, `first`,
+`last`, `size`, `length`, `empty?`, `[]`, and `to_a`, so iteration and most
+existing Array usage works unchanged. Each element is a resource, not a
+model. Collections also expose pagination metadata:
+
+```ruby
+customers = Fortnox::Customer.all
+customers.first.name   # => 'Acme'
+customers.total        # => 327
+customers.pages        # => 7
+customers.current_page # => 1
+```
+
+Code that explicitly checks `is_a?(Array)` or compares with `==` against an
+Array literal needs updating.
+
+## Creating and updating
+
+Use `stub` to create a new unsaved instance. `new` is not used directly.
+
+```ruby
+# Before
+customer = Fortnox::API::Model::Customer.new(name: 'Acme')
+saved = repo.save(customer)
+
+# After
+customer = Fortnox::Customer.stub(name: 'Acme')
+saved = Fortnox::Customer.save(customer)
+```
+
+Updating works the same way — call `update` on a saved instance, then save:
+
+```ruby
+updated = saved.update(name: 'Acme Inc')
+Fortnox::Customer.save(updated)
+```
+
+## Nested models
+
+Nested models like invoice rows are now `Dry::Struct` subclasses under
+`Fortnox::Structs`:
+
+```ruby
+# Before
+row = Fortnox::API::Types::InvoiceRow.new(article_number: '101', price: 10)
+invoice = Fortnox::API::Model::Invoice.new(
+  customer_number: '1',
+  invoice_rows: [row]
+)
+
+# After
+row = Fortnox::Structs::InvoiceRow.new(article_number: '101', price: 10)
+invoice = Fortnox::Invoice.stub(
+  customer_number: '1',
+  invoice_rows: [row]
+)
+```
+
+### Nested struct gotchas
+
+**Hash keys are the snake_case attribute names.** `stub` and `update` accept
+plain hashes in place of struct instances and coerce them for you. Symbol and
+string keys both work; the PascalCase Fortnox API name does not — that is the
+wire format, and these are model attributes:
+
+```ruby
+Fortnox::Order.stub(customer_number: '1', order_rows: [{ article_number: '101' }])
+Fortnox::Order.stub(customer_number: '1', order_rows: [{ 'article_number' => '101' }])
+# both => {"Order":{"CustomerNumber":"1","OrderRows":[{"ArticleNumber":"101"}]}}
+
+Fortnox::Order.stub(customer_number: '1', order_rows: [{ 'ArticleNumber' => '101' }])
+# => Fortnox::UnknownAttributeError
+```
+
+0.9 ignored an attribute name it didn't recognise. 1.x raises
+`Fortnox::UnknownAttributeError`, which carries `.attribute_names`. If you
+relied on passing a wider hash than the resource declares — a record from
+elsewhere in your app, say — slice it down to the attributes you mean to
+send.
+
+**Booleans accept the usual param spellings.** Both resource and struct
+attributes coerce `'true'`, `'false'`, `'yes'`, `'no'`, `'1'`, `'0'`, `'on'`
+and `'off'`, raising `Fortnox::ConstraintError` on anything else, so a
+controller can hand string params straight through:
+
+```ruby
+Fortnox::Structs::OrderRow.new(housework: 'true').housework # => true
+```
+
+Note that the same is true one level down: a nested row hash gets the same
+coercion as a top-level attribute, so there is no need to cast booleans
+yourself before building rows.
+
+## Stricter attribute validation
+
+Several attributes that 0.9 accepted permissively are now validated client-side
+to match the Fortnox API specification. Code that was accidentally relying on
+the lenient 0.9 behavior will raise `Fortnox::ConstraintError` (or
+`Fortnox::MissingAttributeError` for required fields) before the request
+goes out.
+
+### Country attributes
+
+`country_code` and `delivery_country` on documents only accept ISO alpha-2
+codes. 0.9 also accepted country names.
+
+```ruby
+# Before — accepted codes, Swedish names, and English names
+invoice = Fortnox::API::Model::Invoice.new(country: 'Norge')
+invoice = Fortnox::API::Model::Invoice.new(country: 'Norway')
+invoice = Fortnox::API::Model::Invoice.new(country: 'NO')
+
+# After — only ISO alpha-2 codes
+invoice = Fortnox::Invoice.stub(country_code: 'NO')
+```
+
+### `Invoice.invoice_type`
+
+Now an enum. Accepted values: `''`, `'INVOICE'`, `'AGREEMENTINVOICE'`,
+`'INTRESTINVOICE'`, `'SUMMARYINVOICE'`, `'CASHINVOICE'`.
+
+```ruby
+# After
+invoice = Fortnox::Invoice.stub(invoice_type: 'INVOICE')
+```
+
+### `Unit.description`
+
+Now required. 0.9 accepted `nil` client-side, but the Fortnox API rejected
+unset descriptions anyway — the new behavior fails earlier.
+
+```ruby
+# Before — accepted client-side, rejected by the API
+unit = Fortnox::API::Model::Unit.new(code: 'PCS')
+
+# After — must include description
+unit = Fortnox::Unit.stub(code: 'PCS', description: 'Pieces')
+```
+
+## Update payloads
+
+The dirty-tracking model changed from value-level to field-level.
+
+In 0.9 the mapper computed a diff between the updated entity and the
+originally-loaded record and sent only attributes whose **value** had
+actually changed. A side effect of that diff was a bug: `nil` was
+stripped before the comparison, so `update(attr: nil)` silently re-sent
+the original value instead of clearing the field.
+
+In 1.x the change set is the set of attributes you **pass to `.update`**,
+regardless of whether the value differs from the stored record. Every
+attribute in that set is sent on save; attributes you don't pass are not
+sent and are left untouched on the record. Practical consequences:
+
+- Passing an attribute equal to its current value still sends it (a
+  harmless no-op write on Fortnox's side). PUT bodies are therefore
+  somewhat larger than in 0.9.
+- `nil` is now a real change: `update(attr: nil)` sends `null` and
+  clears the field. This is the bug fix the old behavior masked.
+- Saving a persisted record **without** calling `.update` sends nothing
+  — it is a no-op rather than a full-record PUT.
+
+```ruby
+invoice = Fortnox::Invoice.find(1)
+updated = invoice.update(comments: nil)
+Fortnox::Invoice.save(updated)
+# comments is now cleared in Fortnox
+
+# No .update call → nothing changed → save is a no-op, no request sent
+Fortnox::Invoice.save(Fortnox::Invoice.find(1))
+```
+
+## Exceptions
+
+Every exception moved from the `Fortnox::API` namespace to `Fortnox`, and
+the base class was renamed. Rescue `Fortnox::Error` to catch anything the
+gem raises.
+
+| 0.9                                   | 1.x                                |
+| ------------------------------------- | ---------------------------------- |
+| `Fortnox::API::Exception` (base)      | `Fortnox::Error` (base)            |
+| `Fortnox::API::AttributeError`        | `Fortnox::AttributeError`          |
+| `Fortnox::API::RemoteServerError`     | `Fortnox::RequestError`            |
+| `Fortnox::API::MissingAttributeError` | `Fortnox::MissingAttributeError`   |
+| `Fortnox::API::MissingAccessToken`    | `Fortnox::MissingAccessToken`      |
+| `Fortnox::API::MissingConfiguration`  | *removed* — no equivalent          |
+| *(none)*                              | `Fortnox::ConstraintError` *(new)* |
+
+### `Fortnox::ConstraintError` (new)
+
+A subclass of `Fortnox::AttributeError`, raised by the client-side
+coercion layer when an attribute value violates a type constraint (size,
+format, enum, …) — before the request is sent. Because of the stricter
+validation described in
+[Stricter attribute validation](#stricter-attribute-validation), this is
+the exception most likely to start firing during a migration. It carries
+`.attribute_name` (a symbol) and `.value`:
+
+```ruby
+begin
+  Fortnox::Invoice.stub(invoice_type: 'NOT_A_TYPE')
+rescue Fortnox::ConstraintError => e
+  e.attribute_name # => :invoice_type
+  e.value          # => "NOT_A_TYPE"
+end
+```
+
+### Hierarchy change
+
+In 0.9, `MissingAttributeError` was a sibling of `AttributeError` — both
+sat directly under `Fortnox::API::Exception` — so `rescue
+Fortnox::API::AttributeError` did **not** catch it. In 1.x both
+`ConstraintError` and `MissingAttributeError` subclass
+`Fortnox::AttributeError`, so a single rescue catches every
+attribute-validation failure:
+
+```ruby
+rescue Fortnox::AttributeError => e
+  # catches ConstraintError and MissingAttributeError
+```
+
+`Fortnox::API::MissingConfiguration` no longer exists — configuration
+moved to a rest-easy `configure` block — so code that rescued it is now
+dead. `Fortnox::MissingAccessToken` also changed timing — see
+[Access token timing](#access-token-timing).
+
+### `Fortnox::RequestError` exposes the response
+
+`Fortnox::RequestError` exposes the underlying response via `.response`,
+which carries the HTTP status code and body. The old `RemoteServerError`
+only carried the message string, so detecting specific error conditions
+required substring-matching the (Swedish) error text. Prefer the status
+code:
+
+```ruby
+# Before — substring-match the message text
+rescue Fortnox::API::RemoteServerError => e
+  not_found = e.message.include?('Kan inte hitta')
+
+# After — match the HTTP status code
+rescue Fortnox::RequestError => e
+  not_found = e.response&.status == 404
+```
+
+## Debugging and logging
+
+The 0.9 gem had a single combined switch:
+
+```ruby
+# Before
+Fortnox::API.configure do |config|
+  config.debugging = true
+  config.logger    = Logger.new($stdout)
+end
+```
+
+In 1.x this splits into two unrelated knobs.
+
+For HTTP wire logging — request/response lines and headers, with the
+standard auth headers redacted — set a `Logger` on the gem-level config:
+
+```ruby
+# After
+Fortnox.configure do
+  logger Logger.new($stdout)
+end
+```
+
+To also log request/response bodies, opt in explicitly with `log_bodies true`.
+
+For catching schema drift — warnings when an API response contains fields a
+resource doesn't declare with `attr` or `ignore` — set `debug` on the
+individual resource. This is a different feature from the old `debugging`
+flag and is opt-in per resource:
+
+```ruby
+# After
+Fortnox::Customer.configure do
+  debug true
+end
+```
+
+See the [Debugging section in the README](README.md#debugging) for details.
+
+## Dependency changes
+
+The rewrite replaced the HTTP and configuration stack, so several gems 0.9
+installed into your bundle are gone. If your app called into one of them
+directly — without declaring it in its own `Gemfile` — it will fail to load
+after the upgrade, with a `LoadError` that points at your code rather than at
+this gem:
+
+| Gem              | 0.9         | 1.x                                       |
+| ---------------- | ----------- | ----------------------------------------- |
+| `httparty`       | direct dep  | **gone** — replaced by `faraday`          |
+| `jwt`            | direct dep  | **gone** — no longer used                 |
+| `dry-container`  | direct dep  | **gone**                                  |
+| `dry-types`      | direct dep  | still installed, transitively             |
+| `dry-configurable`| direct dep | still installed, transitively             |
+
+`httparty` is the one that bites in practice: an inline `HTTParty.get(...)`
+somewhere unrelated to Fortnox keeps working until this gem stops supplying
+it. `dry-types` and `dry-configurable` are still in the bundle — they come in
+via `rest-easy` and `dry-struct` — but that is an implementation detail of
+this gem, not a promise. Declare anything you use directly in your own
+`Gemfile`.
+
+## Testing with VCR
+
+Resource paths lost their trailing slash. 0.9 declared endpoints as
+`URI = '/customers/'` against a `https://api.fortnox.se/3/` base; 1.x
+declares `path 'customers'` against `https://api.fortnox.se/3`:
+
+```
+# Before
+https://api.fortnox.se/3/customers/
+https://api.fortnox.se/3/customers/1/
+
+# After
+https://api.fortnox.se/3/customers
+https://api.fortnox.se/3/customers/1
+```
+
+Every cassette your app recorded against 0.9 therefore fails to match. There
+is no rewriting shortcut worth the effort — delete the affected cassettes and
+re-record. Note that the request headers changed too (client credentials
+instead of refresh tokens), so a URL-only search-and-replace would leave you
+with cassettes that match the URL and then miss on the headers.
+
+## Rails applications
+
+Most of the friction in a Rails upgrade is at the integration seam rather
+than in Fortnox behaviour itself. The two below are the day-one ones; also
+work through [Dependency changes](#dependency-changes), since `httparty` is
+the usual casualty in a Rails app.
+
+### `render json:` needs the Rails integration
+
+0.9 returned plain model objects that Rails knew how to serialise. 1.x
+resources need one require, in an initializer:
+
+```ruby
+# config/initializers/fortnox.rb
+require 'fortnox/rails'
+```
+
+Without it, `render json: { invoices: [...] }` doesn't call `to_json` on the
+nested resources — ActiveSupport walks the structure calling `as_json`, falls
+through to `Object#as_json`, and serialises instance variables into your
+response body:
+
+```ruby
+render json: { invoices: [Fortnox::Invoice.find(1)] }
+# => {"invoices":[{"api_data":{…},"model_attributes":{…},"changes":[…],"meta":{…}}]}
+```
+
+It covers resources, collections, and nested structs. See the
+[README](README.md#rails) for what it renders.
+
+### Filter params before they reach a resource
+
+Params can be passed through as they arrive — string keys and string values
+both work. But an attribute the resource doesn't declare now raises
+`Fortnox::UnknownAttributeError` rather than being ignored, so a form field
+that isn't a Fortnox attribute will take a request down. Permit and slice as
+you would for a model. See [Nested struct gotchas](#nested-struct-gotchas).

data/README.md

@@ -17,8 +17,7 @@ Adding more resources is quick and easy — see the
 
 ## Status
 
-Version 1.0 is a complete rewrite, currently in release candidate
-(`1.0.0.rc8`). It is built on
+Version 1.0 is a complete rewrite, 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.

data/fortnox.gemspec

@@ -12,9 +12,17 @@ Gem::Specification.new do |spec|
   spec.version       = Fortnox::VERSION.dup
 
   spec.summary       = 'Fortnox F3 REST API library, based on rest-easy.'
-  spec.description   = spec.summary
+  spec.description   = <<~DESCRIPTION
+    Fortnox's REST API wraps every payload in a type key, spells its
+    attributes in PascalCase, and treats an empty string as "leave this
+    field alone" when you meant to clear it. This gem turns it into
+    ordinary immutable Ruby objects with typed, constrained attributes,
+    so a value Fortnox would reject raises before it costs an API call,
+    and authorization, pagination and JSON mapping are handled for you.
+  DESCRIPTION
   spec.homepage      = 'https://github.com/accodeing/fortnox'
-  spec.files         = Dir['CHANGELOG.md', 'LICENSE.md', 'README.md', 'fortnox.gemspec', 'lib/**/*']
+  spec.files         = Dir['CHANGELOG.md', 'LICENSE.md', 'MIGRATING_TO_1.0.md', 'README.md',
+                           'fortnox.gemspec', 'lib/**/*']
   spec.bindir        = 'bin'
   spec.executables   = ['fortnox-setup', 'fortnox-update-env']
   spec.require_paths = ['lib']
@@ -24,7 +32,7 @@ Gem::Specification.new do |spec|
   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.1'
+  spec.add_dependency 'rest-easy', '~> 1.4.2'
 
   spec.metadata['rubygems_mfa_required'] = 'true'
 end

data/lib/fortnox/resource.rb

@@ -2,7 +2,7 @@
 
 module Fortnox
   # TODO: this class is still over the length limit even with error
-  # translation extracted — see todo.md.
+  # translation extracted — see TODO.md.
   # rubocop:disable Metrics/ClassLength
   class Resource < RestEasy::Resource
     include Fortnox::Types

data/lib/fortnox/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: fortnox-api
 version: !ruby/object:Gem::Version
-  version: 1.0.0.rc16
+  version: 1.0.1
 platform: ruby
 authors:
 - Jonas Schubert Erlandsson
@@ -11,7 +11,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-19 00:00:00.000000000 Z
+date: 2026-09-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64
@@ -61,15 +61,21 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.4.1
+        version: 1.4.2
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.4.1
-description: Fortnox F3 REST API library, based on rest-easy.
+        version: 1.4.2
+description: |
+  Fortnox's REST API wraps every payload in a type key, spells its
+  attributes in PascalCase, and treats an empty string as "leave this
+  field alone" when you meant to clear it. This gem turns it into
+  ordinary immutable Ruby objects with typed, constrained attributes,
+  so a value Fortnox would reject raises before it costs an API call,
+  and authorization, pagination and JSON mapping are handled for you.
 email:
 - info@accodeing.com
 executables:
@@ -80,6 +86,7 @@ extra_rdoc_files: []
 files:
 - CHANGELOG.md
 - LICENSE.md
+- MIGRATING_TO_1.0.md
 - README.md
 - bin/fortnox-setup
 - bin/fortnox-update-env
@@ -138,9 +145,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: 3.2.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">"
+  - - ">="
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
 rubygems_version: 3.4.19
 signing_key: