fortnox-api 1.0.0.rc1 → 1.0.0.rc2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d4ab3f55b3783c477974abba27bae6b9104baf418e131532a746f822177605bd
-  data.tar.gz: 882d8f34d8246f74052823894fd7286a146bdaa745155928059cad7abfe0d6ef
+  metadata.gz: 355563e337538c18df2917f19aee3e0d91a1f7763fbb3a01bad441bd3956f496
+  data.tar.gz: 4898bf90e631edd152c4c44b1fda68c2284cc2f24e38cd712a8a0057e27a6c40
 SHA512:
-  metadata.gz: 2e4a87ea6c15df6acce08ef2e3006f6cf4acd936a933e8449af585f5426f0a5f951e06f84a96ec34a044248519b013d2085b3c7ff8889e5016a4cc79af0074f1
-  data.tar.gz: '09c2e017f7dc98c61565c0dc00b9d8ab35a8ea8ad90928e523f822c5f6bb84a2ebc74c75cbd1d02a4cb2ba8d58147f39286b0de05c656170a7f55ae6f4792971'
+  metadata.gz: 5acaea5d925b3c8f60f817ff39d167f0e078e5ec32f7f86568cf853935ac4955431dd037c81b561ec2be081e09d46b1dbae9b3c3d204bbfbcfd2615bc4d19d50
+  data.tar.gz: 14ddc8dbdc2da42f8c09d6bb5ee11c47ceb6fa8faba6cd51da7c97d1fc4bbf4c3adcba67e2bbc831c2783a2841d4f292b3f358d608e31d84cae8e25222fa711b

data/CHANGELOG.md

@@ -6,6 +6,32 @@ 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).
 
+## [1.0.0.rc2] - 2026-05-05
+
+### Added
+
+- Per-resource OAuth scope declarations via the `scope` setting in
+  `Fortnox::Resource`, plus `Fortnox.scopes` returning a
+  `{ scope_string => [resource_classes] }` mapping derived from the
+  registered resources.
+
+### Changed
+
+- `fortnox-setup` lists the OAuth scopes covered by the gem's resources
+  and accepts a space-separated selection or `all`, replacing the
+  prescriptive default that didn't reflect the actual resource set. Other
+  Fortnox scopes (`salary`, `bookkeeping`, etc.) can still be entered
+  manually.
+- `TermsOfPayment.code` is now `Sized::String[25]` and required, matching
+  Fortnox API documentation. The rest-easy rewrite for rc1 briefly lost
+  the required flag.
+- `Unit.code` is now `Sized::String[20]` and required, matching Fortnox
+  API documentation. The rest-easy rewrite for rc1 briefly lost the
+  required flag.
+- `Unit.description` is now `Sized::String[100]` and required, matching
+  Fortnox API documentation. In 0.x and rc1 this was nullable client-side,
+  but the Fortnox API rejected unset descriptions anyway.
+
 ## [1.0.0.rc1] - 2026-05-04
 
 Version 1.0 is a complete rewrite of the gem and is **not** a drop-in
@@ -24,6 +50,14 @@ for the full list of breaking changes.
 - **Breaking** Authorization now uses the new Fortnox client credentials flow.
   Refresh tokens are no longer needed, nor supported. A tenant ID is now required;
   obtain one with the new `fortnox-setup` executable.
+- **Breaking** Environment variables lose the `_API_` infix:
+  `FORTNOX_API_CLIENT_ID` → `FORTNOX_CLIENT_ID`, `FORTNOX_API_CLIENT_SECRET`
+  → `FORTNOX_CLIENT_SECRET`, `FORTNOX_API_ACCESS_TOKEN` →
+  `FORTNOX_ACCESS_TOKEN`. `FORTNOX_API_REFRESH_TOKEN`,
+  `FORTNOX_API_REDIRECT_URI`, and `FORTNOX_API_SCOPES` are removed —
+  refresh tokens are no longer supported, and the redirect URI and scopes
+  are now selected interactively in `fortnox-setup`. The new
+  `FORTNOX_TENANT_ID` is required for the client credentials flow.
 - **Breaking** `Fortnox.request_access_token` replaces
   `Fortnox::API::Repository::Authentication` for token management.
 - **Breaking** Configuration moves from `Fortnox::API.configuration` to
@@ -60,6 +94,16 @@ for the full list of breaking changes.
   `size`, `length`, `empty?`, `[]`, and `to_a`, so most existing Array
   usage works unchanged. Code that explicitly checks `is_a?(Array)` or
   compares with `==` against an Array literal needs updating.
+- **Breaking** `Invoice.accounting_method` is now an enum accepting only
+  `''`, `'ACCRUAL'`, or `'CASH'`. In 0.x this was a free-form
+  `Nullable::String` so any value passed client-side.
+- **Breaking** `Invoice.invoice_type` is now an enum accepting only `''`,
+  `'INVOICE'`, `'AGREEMENTINVOICE'`, `'INTRESTINVOICE'`, `'SUMMARYINVOICE'`,
+  or `'CASHINVOICE'`. In 0.x this was a free-form `Nullable::String`.
+- `your_order_number` on Invoice and Order (inherited from Document) max
+  length raised from 30 to 75 characters to match the current Fortnox API.
+- Article dimension fields (`depth`, `height`, `weight`, `width`) max raised
+  from 99,999,999 to 999,999,999 to match the documented Fortnox range.
 
 ### Added
 
@@ -94,3 +138,6 @@ 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).
+
+[1.0.0.rc2]: https://github.com/accodeing/fortnox-api/compare/v1.0.0.rc1...v1.0.0.rc2
+[1.0.0.rc1]: https://github.com/accodeing/fortnox-api/releases/tag/v1.0.0.rc1

data/README.md

@@ -16,7 +16,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.rc1`). It is built on
+(`1.0.0.rc2`). 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.
@@ -35,21 +35,21 @@ snake_case in Ruby).
 
 ### Immutability
 
-The model instances are immutable. That means:
+Resource instances are immutable. That means:
 
 ```ruby
-customer.model.name # => "Old Name"
-customer.model.name = 'New Name' # => NoMethodError
+customer.name # => "Old Name"
+customer.name = 'New Name' # => NoMethodError
 ```
 
 Any operation that updates state returns a new instance with the updated
 attributes while leaving the old instance alone:
 
 ```ruby
-customer.model.name # => "Old Name"
+customer.name # => "Old Name"
 updated_customer = customer.update(name: 'New Name')
-updated_customer.model.name # => "New Name"
-customer.model.name # => "Old Name"
+updated_customer.name # => "New Name"
+customer.name # => "Old Name"
 ```
 
 This is how all resources work, they are all immutable.
@@ -141,20 +141,26 @@ fortnox-setup
 
 The script will:
 
-1. Ask for your client ID, client secret, and scopes
-2. Offer to use a local server on `http://localhost:4242` to catch the
-   authorization response automatically. If you choose this, set your Fortnox
-   app's redirect URL to `http://localhost:4242`. Otherwise, enter your existing
-   redirect URL and paste the authorization code manually.
-3. Open your browser to the Fortnox authorization page
-4. You log in to Fortnox and grant your app access
-5. The script exchanges the authorization code for an access token and extracts
-   the tenant ID from the JWT
-6. The tenant ID is printed for you to store in your application's configuration
+1. Ask for your client ID and client secret.
+2. List the OAuth scopes covered by the gem's resources and ask which ones
+   you need. Enter a space-separated list, or `all` for everything the gem
+   supports. You can also enter scopes the gem doesn't expose directly
+   if you plan to call those endpoints manually.
+3. Offer to use a local server to catch the authorization response automatically.
+   If you choose this, set your Fortnox app's redirect URL to `http://localhost:4242`.
+   Otherwise, enter your existing redirect URL and paste the authorization code manually.
+4. Open your browser to the Fortnox authorization page.
+5. You log in to Fortnox and grant your app access.
+6. The script exchanges the authorization code for an access token and extracts
+   the tenant ID from the JWT.
+7. The tenant ID is printed for you to store in your application's configuration.
 
 After this you have a tenant ID and never need to run this script again (unless
 you need to authorize against a different Fortnox account).
 
+Note: If you change the integration configuration in Fortnox it takes some time for
+Fortnox to propagate the changes (for instance changing the Redirect URI or the scope).
+
 ### Requesting access tokens
 
 Once you have a tenant ID, you can request access tokens programmatically.
@@ -176,6 +182,11 @@ It is up to you to manage the token lifecycle in your application. A common
 approach is to request a new token before each batch of API calls, or to cache
 the token and refresh it when it expires.
 
+Note: Fortnox only allows one active access token per integration. Requesting a
+new token invalidates the previous one. If you need multiple active access
+tokens in parallel, you need a separate integration (client ID and secret) for
+each token.
+
 ### Updating access tokens in env files
 
 For development and testing, the gem includes an executable that reads your
@@ -228,11 +239,11 @@ returns alongside collection responses:
 
 ```ruby
 customers = Fortnox::Customer.all
-customers.first.model.name # => "Acme Corp"
-customers.size             # => 50
-customers.total            # => 327
-customers.pages            # => 7
-customers.current_page     # => 1
+customers.first.name   # => "Acme Corp"
+customers.size         # => 50
+customers.total        # => 327
+customers.pages        # => 7
+customers.current_page # => 1
 ```
 
 `Collection` is `Enumerable`, so `.each`, `.map`, `.select`, `.first`, etc.
@@ -265,13 +276,13 @@ See the
 [Fortnox documentation](https://developer.fortnox.se/general/parameters/)
 for available parameters.
 
-The returned object wraps the model. Access attributes through `.model`:
+Attributes are exposed directly on the returned instance:
 
 ```ruby
 customer = Fortnox::Customer.find(1)
-customer.model.name       # => "Acme Corp"
-customer.model.city       # => "Stockholm"
-customer.unique_id        # => "1"
+customer.name      # => "Acme Corp"
+customer.city      # => "Stockholm"
+customer.unique_id # => "1"
 ```
 
 ### Creating a record
@@ -281,7 +292,7 @@ Use `.stub` to build a new instance and `.save` to persist it:
 ```ruby
 customer = Fortnox::Customer.stub(name: 'Acme Corp', city: 'Stockholm')
 result = Fortnox::Customer.save(customer)
-result.model.customer_number # => "1"
+result.customer_number # => "1"
 ```
 
 ### Updating a record

data/bin/fortnox-setup

@@ -11,6 +11,7 @@ require 'securerandom'
 require 'socket'
 require 'uri'
 require 'faraday'
+require 'fortnox'
 
 OAUTH_ENDPOINT = 'https://apps.fortnox.se/oauth-v1'
 LOCAL_PORT = 4242
@@ -108,10 +109,25 @@ puts
 
 client_id = prompt('Client ID')
 client_secret = prompt('Client secret')
+
+puts
+puts 'Available scopes:'
+Fortnox.scopes.each do |scope, resources|
+  resource_names = resources.map { |r| r.name.split('::').last }.join(', ')
+  puts "  #{scope.ljust(10)} → #{resource_names}"
+end
+puts
+puts 'These must match the scopes configured on your Fortnox app in the developer'
+puts 'portal. Other Fortnox scopes (salary, bookkeeping, etc.) can be added manually.'
 puts
-puts 'Enter the scopes you need. These must match the scopes configured on your'
-puts 'Fortnox app in the developer portal.'
-scopes = prompt('Scopes', default: 'article customer invoice order project settings')
+
+scopes = loop do
+  input = prompt("Enter scopes (space-separated, or 'all')").strip
+  break Fortnox.scopes.keys.join(' ') if input == 'all'
+  break input unless input.empty?
+
+  puts 'Please enter at least one scope.'
+end
 
 puts
 puts 'The script can catch the authorization response automatically using a'

data/lib/fortnox/resource.rb

@@ -7,8 +7,11 @@ module Fortnox
     settings do
       setting :instance_wrapper, reader: true
       setting :collection_wrapper, reader: true
+      setting :scope, reader: true
     end
 
+    @registered_resources = []
+
     before_parse do |data, meta|
       if data.key?(config.instance_wrapper)
         meta.partial = false
@@ -38,6 +41,13 @@ module Fortnox
     end
 
     class << self
+      attr_reader :registered_resources
+
+      def inherited(subclass)
+        super
+        Fortnox::Resource.registered_resources << subclass
+      end
+
       def parse(response)
         with_translated_errors do
           pagination = extract_pagination(response)

data/lib/fortnox/resources/article.rb

@@ -8,6 +8,7 @@ module Fortnox
       path 'articles'
       instance_wrapper 'Article'
       collection_wrapper 'Articles'
+      scope 'article'
     end
 
     # @url Direct URL to the record.

data/lib/fortnox/resources/customer.rb

@@ -8,6 +8,7 @@ module Fortnox
       path 'customers'
       instance_wrapper 'Customer'
       collection_wrapper 'Customers'
+      scope 'customer'
     end
 
     # Direct URL to the record.

data/lib/fortnox/resources/invoice.rb

@@ -8,6 +8,7 @@ module Fortnox
       path 'invoices'
       instance_wrapper 'Invoice'
       collection_wrapper 'Invoices'
+      scope 'invoice'
     end
 
     # AccountingMethod Accounting Method.

data/lib/fortnox/resources/label.rb

@@ -6,6 +6,7 @@ module Fortnox
       path 'labels'
       instance_wrapper 'Label'
       collection_wrapper 'Labels'
+      scope 'settings'
     end
 
     attr :id, Coercible::Integer.optional, :read_only, :key

data/lib/fortnox/resources/order.rb

@@ -8,6 +8,7 @@ module Fortnox
       path 'orders'
       instance_wrapper 'Order'
       collection_wrapper 'Orders'
+      scope 'order'
     end
 
     # CopyRemarks If remarks shall be copied from order to invoice

data/lib/fortnox/resources/project.rb

@@ -8,6 +8,7 @@ module Fortnox
       path 'projects'
       instance_wrapper 'Project'
       collection_wrapper 'Projects'
+      scope 'project'
     end
 
     # @url Direct URL to the record.

data/lib/fortnox/resources/terms_of_payment.rb

@@ -8,13 +8,14 @@ module Fortnox
       path 'termsofpayments'
       instance_wrapper 'TermsOfPayment'
       collection_wrapper 'TermsOfPayments'
+      scope 'settings'
     end
 
     # @url Direct URL to the record.
     attr :url <=> '@url', Coercible::String.optional, :read_only
 
     # Code The code of the term of payment.
-    key :code, Strict::String
+    key :code, Sized::String[25], :required
 
     # Description The description of the term of payment.
     attr :description, Strict::String, :required

data/lib/fortnox/resources/unit.rb

@@ -8,16 +8,17 @@ module Fortnox
       path 'units'
       instance_wrapper 'Unit'
       collection_wrapper 'Units'
+      scope 'settings'
     end
 
     # @url Direct URL to the record.
     attr :url <=> '@url', Coercible::String.optional, :read_only
 
     # Code The code of the unit.
-    key :code, Strict::String
+    key :code, Sized::String[20], :required
 
     # Description The description of the unit.
-    attr :description, Coercible::String.optional
+    attr :description, Sized::String[100], :required
 
     # CodeEnglish English code of the unit
     attr :code_english, Sized::String[100]

data/lib/fortnox/version.rb

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

data/lib/fortnox.rb

@@ -5,14 +5,14 @@ require 'json'
 require 'rest_easy'
 require 'zeitwerk'
 
-loader = Zeitwerk::Loader.for_gem
-loader.collapse("#{__dir__}/fortnox/resources")
-loader.inflector.inflect(
-  'edi_information' => 'EDIInformation'
-)
-loader.setup
-
 module Fortnox
+  @loader = Zeitwerk::Loader.for_gem
+  @loader.collapse("#{__dir__}/fortnox/resources")
+  @loader.inflector.inflect(
+    'edi_information' => 'EDIInformation'
+  )
+  @loader.setup
+
   extend RestEasy
 
   class Error < StandardError; end
@@ -76,6 +76,15 @@ module Fortnox
       parsed['access_token']
     end
 
+    def scopes
+      @loader.eager_load
+      Resource.registered_resources
+              .group_by(&:scope)
+              .reject { |scope, _| scope.nil? }
+              .sort
+              .to_h
+    end
+
     private
 
     def token_request(client_id, client_secret, tenant_id, scopes)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: fortnox-api
 version: !ruby/object:Gem::Version
-  version: 1.0.0.rc1
+  version: 1.0.0.rc2
 platform: ruby
 authors:
 - Jonas Schubert Erlandsson
@@ -11,7 +11,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-05-04 00:00:00.000000000 Z
+date: 2026-05-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: countries