booqable 1.0.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c084014d612e3e317590f31144911c3a3907a85075a17b3172edd2f6eb8c7d9f
-  data.tar.gz: 23836e46596f37b74175cd45f4e6ee04ee17eb7b0254bb53395972bc801a55aa
+  metadata.gz: ce7d8b0be4851e4e78229078331a2f73cbe7cb7702c1555df9dec0903be28d0e
+  data.tar.gz: c79ed318eb3a38534291ef5e4abeb6a5749c7a2684bcd1befbf43d6f7f1d0e8a
 SHA512:
-  metadata.gz: 0a2eb78b9a78a239bec1fda211b177533102e78e4cdd95470692cb5a21132180827d2339caadf723564de9d8091d15c4e6160489f5a4694dfe40fc8bd4a630c2
-  data.tar.gz: 7210d24c6985facb00617c0949abe55c0b9034acb53b3120039c7d78e1da3ecd763875ff54c69672e39701049a3ab46f46024c1c6511251840891163a19518c0
+  metadata.gz: 9d6dead61b0b4bfd8374c9b51aec7dccc724988b5417f9585018ee549840ee207756642b38aedbfcf4fdb4e313f9764fdc64b1d1d6e7593c057edb20d6095afc
+  data.tar.gz: c5e34b3a736ab3bdca397dfd1245d07b8dd8e246e32d4d0f24e097c41f52d47307c645a547592e60b90dc27f98e2e817193a1059f2696c0a726316c0693c1f88

data/CHANGELOG.md

@@ -1,5 +1,21 @@
-## [Unreleased]
+## [1.2.0] - 2026-05-27
 
-## [0.1.0] - 2025-06-27
+- Add optional `around_refresh_token` configuration. When provided, the OAuth
+  middleware yields the read + expiry-check + refresh sequence to the callable
+  so host applications can serialize concurrent token refreshes (e.g. with a
+  database transaction and advisory lock). The gem keeps no lock dependency.
+
+
+## [1.1.0] - 2026-03-11
+
+- Add `parse_resource` method (aliased as `deserialize_resource`) for parsing
+  JSON:API payloads into Sawyer::Resource objects with dot-notation access.
+  Useful for parsing webhook payloads or raw API responses.
+- Add Booqable::RefreshTokenRevoked and Booqable::InvalidGrant error types for
+  invalid grant OAuth response scenarios
+- Add "all" as an alias for "list" method on all resources. 
+  You can now use `Booqable.orders.all` as an alternative to `Booqable.orders.list`.
+
+## [1.0.0] - 2025-10-23
 
 - Initial release

data/README.md

@@ -5,6 +5,7 @@ Ruby toolkit for the [Booqable API](https://developers.booqable.com/).
 [Booqable](https://booqable.com) is a rental management platform that helps businesses manage their rental inventory, customers, and orders. This gem provides a Ruby interface to interact with all Booqable API endpoints.
 
 ## Table of Contents
+
 - [Installation](#installation)
 - [Making requests](#making-requests)
 - [Authentication](#authentication)
@@ -12,6 +13,7 @@ Ruby toolkit for the [Booqable API](https://developers.booqable.com/).
 - [Pagination](#pagination)
 - [Rate limiting](#rate-limiting)
 - [Resources](#resources)
+- [Parsing JSON:API payloads](#parsing-jsonapi-payloads)
 - [Advanced usage](#advanced-usage)
 - [Development](#development)
 
@@ -89,11 +91,11 @@ client = Booqable::Client.new(
   client_id: 'your_oauth_client_id',
   client_secret: 'your_oauth_client_secret',
   company_id: 'your_company_id',
-  read_token: -> { 
+  read_token: -> {
     # Return stored token hash
     JSON.parse(File.read('token.json'))
   },
-  write_token: ->(token) { 
+  write_token: ->(token) {
     # Store token hash
     File.write('token.json', token.to_json)
   }
@@ -103,6 +105,30 @@ client = Booqable::Client.new(
 client.authenticate_with_code(params[:code])
 ```
 
+#### Serializing concurrent token refreshes
+
+When multiple processes share the same OAuth token (e.g. the same installation
+serving concurrent requests), pass an `around_refresh_token` callable to
+serialize the read + expiry-check + refresh sequence. The middleware yields
+to the callable once per request; the host application decides how to lock.
+
+```ruby
+Booqable::Client.new(
+  # ...other oauth options...
+  around_refresh_token: ->(&block) {
+    AppInstallation.transaction do
+      installation.with_advisory_lock!("app_installation:#{installation.id}", transaction: true) do
+        installation.reload
+        block.call
+      end
+    end
+  }
+)
+```
+
+The gem itself has no advisory-lock dependency — `around_refresh_token` is
+just a callable that takes a block.
+
 ### Single-Use Token Authentication
 
 For server-to-server communication requiring enhanced security:
@@ -159,7 +185,7 @@ client = Booqable::Client.new(
 
 ## Pagination
 
-The Booqable API uses cursor-based pagination. Booqable provides several ways to handle paginated responses:
+Booqable provides several ways to handle paginated responses:
 
 ### Manual pagination
 
@@ -222,6 +248,13 @@ orders = Booqable.orders.list(
   sort: '-created_at'
 )
 
+# `all` is an alias for `list`
+orders = Booqable.orders.all(
+  include: 'customer,items',
+  filter: { status: 'reserved' },
+  sort: '-created_at'
+)
+
 # Find specific order
 order = Booqable.orders.find('order_id', include: 'customer,items')
 order.items.count
@@ -236,7 +269,7 @@ new_order = Booqable.orders.create(
 new_order.status  # => 'draft'
 
 # Update order
-updated_order = Booqable.orders.update('order_id', status: 'reserved')
+updated_order = Booqable.orders.update('order_id', stops_at: '2024-01-03T00:00:00Z')
 updated_order.status  # => 'reserved'
 
 # Delete order
@@ -296,20 +329,83 @@ deleted_product.id  # => 'product_id'
 Booqable provides access to all Booqable API resources:
 
 **Core Resources:**
+
 - `orders`, `customers`, `products`, `items`
 - `employees`, `companies`, `locations`
 - `payments`, `invoices`, `documents`
 
 **Inventory Management:**
+
 - `inventory_levels`, `stock_items`, `stock_adjustments`
 - `transfers`, `plannings`, `clusters`
 
 **Configuration:**
+
 - `settings`, `properties`, `tax_rates`
 - `payment_methods`, `email_templates`
 
 **And many more...** See the [full resource list](lib/booqable/resources.json) for all available endpoints.
 
+## Parsing JSON:API payloads
+
+Booqable provides a convenient way to parse JSON:API formatted data (such as webhook payloads or raw API responses) into Ruby objects with dot-notation access:
+
+```ruby
+# Parse a webhook payload
+payload = {
+  "data" => {
+    "id" => "abc-123",
+    "type" => "customers",
+    "attributes" => {
+      "name" => "John Doe",
+      "email" => "john@example.com",
+      "created_at" => "2024-01-15T10:30:00Z"
+    }
+  }
+}
+
+customer = Booqable.parse_resource(payload)
+customer.id         # => "abc-123"
+customer.name       # => "John Doe"
+customer.email      # => "john@example.com"
+customer.created_at # => 2024-01-15 10:30:00 UTC (Time object)
+```
+
+### With nested relationships
+
+```ruby
+payload = {
+  "data" => {
+    "id" => "order-123",
+    "type" => "orders",
+    "attributes" => { "status" => "reserved" },
+    "relationships" => {
+      "customer" => { "data" => { "id" => "customer-456", "type" => "customers" } }
+    }
+  },
+  "included" => [
+    {
+      "id" => "customer-456",
+      "type" => "customers",
+      "attributes" => { "name" => "Jane Smith" }
+    }
+  ]
+}
+
+order = Booqable.parse_resource(payload)
+order.status        # => "reserved"
+order.customer.name # => "Jane Smith"
+```
+
+### Using with a client instance
+
+```ruby
+# If you already have a client instance
+customer = client.parse_resource(payload)
+```
+
+`deserialize_resource` is available as an alias for `parse_resource`.
+
 ## Advanced usage
 
 ### Custom middleware
@@ -346,18 +442,6 @@ Booqable.configure do |c|
 end
 ```
 
-### Custom serialization
-
-```ruby
-# Access raw response data
-response = Booqable.orders.list
-puts response.class  # => Sawyer::Resource
-
-# Get response metadata
-puts Booqable.last_response.status
-puts Booqable.last_response.headers
-```
-
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
@@ -376,7 +460,7 @@ bundle exec rspec spec/booqable/client_spec.rb
 
 ### Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/booqable/booqable.rb. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/booqable/booqable.rb/blob/master/CODE_OF_CONDUCT.md).
+Bug reports and pull requests are welcome on GitHub at https://github.com/booqable/booqable.rb. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/booqable/booqable.rb/blob/main/CODE_OF_CONDUCT.md).
 
 ## Versioning
 
@@ -396,7 +480,7 @@ The gem is available as open source under the terms of the [MIT License](https:/
 
 ## Code of Conduct
 
-Everyone interacting in the Booqable project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/booqable/booqable.rb/blob/master/CODE_OF_CONDUCT.md).
+Everyone interacting in the Booqable project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/booqable/booqable.rb/blob/main/CODE_OF_CONDUCT.md).
 
 ---
 

data/lib/booqable/auth.rb

@@ -57,7 +57,8 @@ module Booqable
         api_endpoint: api_endpoint,
         redirect_uri: redirect_uri,
         read_token: read_token,
-        write_token: write_token
+        write_token: write_token,
+        around_refresh_token: around_refresh_token
       } if oauth_authenticated?
 
       builder.use Booqable::Middleware::Auth::ApiKey, {

data/lib/booqable/client.rb

@@ -56,6 +56,23 @@ module Booqable
       end
     end
 
+    # Parse a JSON:API payload into a Sawyer::Resource
+    #
+    # Converts JSON:API formatted data (from webhooks or API responses) into
+    # Ruby objects with dot-notation access for convenient attribute access.
+    #
+    # @param payload [String, Hash] JSON:API payload (string or parsed hash)
+    # @return [Sawyer::Resource, nil] Parsed resource object, or nil for empty input
+    #
+    # @example
+    #   customer = client.parse_resource(webhook_payload)
+    #   customer.name # => "John"
+    #
+    def parse_resource(payload)
+      Booqable::ResourceParser.parse(payload)
+    end
+    alias_method :deserialize_resource, :parse_resource
+
     # String representation of the client with sensitive information masked
     #
     # Overrides the default inspect method to hide sensitive configuration

data/lib/booqable/configurable.rb

@@ -48,6 +48,7 @@ module Booqable
                   :proxy,
                   :read_token,
                   :redirect_uri,
+                  :around_refresh_token,
                   :single_use_token,
                   :single_use_token_algorithm,
                   :single_use_token_company_id,
@@ -81,6 +82,7 @@ module Booqable
           proxy
           read_token
           redirect_uri
+          around_refresh_token
           single_use_token
           single_use_token_algorithm
           single_use_token_company_id

data/lib/booqable/default.rb

@@ -151,6 +151,17 @@ module Booqable
         Proc.new { }
       end
 
+      # Default `around_refresh_token` callable
+      #
+      # When non-nil, the OAuth middleware yields its read+check+refresh
+      # sequence to this callable so the host application can serialize
+      # concurrent refreshes (e.g. with an advisory lock).
+      #
+      # @return [Proc, nil]
+      def around_refresh_token
+        nil
+      end
+
       # Default API key from ENV
       # @return [String, nil] API key for authentication
       def api_key

data/lib/booqable/error.rb

@@ -42,8 +42,8 @@ module Booqable
       # headers = response[:response_headers]
 
       if klass =  case status
-         when 400      then error_for_400(body)
-         when 401      then Booqable::Unauthorized
+         when 400      then error_for_400(response)
+         when 401      then error_for_401(response)
          when 402      then error_for_402(body)
          when 403      then Booqable::Forbidden
          when 404      then error_for_404(body)
@@ -85,8 +85,8 @@ module Booqable
     # Return most appropriate error for 400 HTTP status code
     # @private
     # rubocop:disable Metrics/CyclomaticComplexity
-    def self.error_for_400(body)
-      case body
+    def self.error_for_400(response)
+      case response.body
       when /unwrittable_attribute/i
         Booqable::ReadOnlyAttribute
       when /unknown_attribute/i
@@ -103,12 +103,25 @@ module Booqable
         Booqable::InvalidFilter
       when /required filter/i
         Booqable::RequiredFilter
+      when /invalid_grant/i
+        error_for_invalid_grant(response)
       else
         Booqable::BadRequest
       end
     end
     # rubocop:enable Metrics/CyclomaticComplexity
 
+    # Return most appropriate error for 401 HTTP status code
+    # @private
+    def self.error_for_401(response)
+      case response.body
+      when /token is invalid \(revoked\)/i
+        Booqable::TokenRevoked
+      else
+        Booqable::Unauthorized
+      end
+    end
+
     # Return most appropriate error for 402 HTTP status code
     # @private
     # rubocop:disable Metrics/CyclomaticComplexity
@@ -163,6 +176,26 @@ module Booqable
       end
     end
 
+    # Return most appropriate error for invalid_grant OAuth error
+    #
+    # Determines whether the invalid_grant error is due to a revoked refresh token
+    # or a different OAuth grant error by examining the grant_type parameter
+    # in the request body.
+    #
+    # @param response [Hash] HTTP response containing the request body
+    # @return [Class] RefreshTokenRevoked if grant_type is refresh_token, InvalidGrant otherwise
+    # @private
+    def self.error_for_invalid_grant(response)
+      grant_type = CGI.parse(response.request_body).dig("grant_type", 0)
+
+      case grant_type
+      when /refresh_token/i
+        Booqable::RefreshTokenRevoked
+      else
+        Booqable::InvalidGrant
+      end
+    end
+
     # Array of validation errors
     # @return [Array<Hash>] Error info
     def errors
@@ -300,6 +333,20 @@ module Booqable
   # and body matches 'required filter'
   class RequiredFilter < ClientError; end
 
+  # Raised when Booqable returns a 401 HTTP status code
+  # and body matches 'token is invalid (revoked)'
+  class TokenRevoked < ClientError; end
+
+  # Raised when Booqable returns a 400 HTTP status code
+  # and body matches 'invalid_grant' and
+  # the grant type is refresh token (OAuth error)
+  class RefreshTokenRevoked < TokenRevoked; end
+
+  # Raised when Booqable returns a 400 HTTP status code
+  # and body matches 'invalid_grant' and
+  # grant type is not refresh token (OAuth error)
+  class InvalidGrant < ClientError; end
+
   # Raised when Booqable returns a 401 HTTP status code
   class Unauthorized < ClientError; end
 

data/lib/booqable/middleware/auth/oauth.rb

@@ -24,6 +24,10 @@ module Booqable
         # @option options [String] :api_endpoint API endpoint URL for the OAuth provider
         # @option options [Proc] :read_token Proc to read stored token
         # @option options [Proc] :write_token Proc to store new token
+        # @option options [Proc, nil] :around_refresh_token Optional callable
+        #   invoked with a block around the read+check+refresh sequence. The
+        #   host application can use it to serialize concurrent refreshes
+        #   (e.g. wrap the block in a database transaction + advisory lock).
         # @raise [KeyError] If required options are not provided
         def initialize(app, options = {})
           super(app)
@@ -33,6 +37,7 @@ module Booqable
           @api_endpoint = options.fetch(:api_endpoint)
           @read_token = options.fetch(:read_token)
           @write_token = options.fetch(:write_token)
+          @around_refresh_token = options[:around_refresh_token]
 
           @client = OAuthClient.new(
             client_id: @client_id,
@@ -50,10 +55,12 @@ module Booqable
         # @param env [Faraday::Env] The request environment
         # @return [Faraday::Response] The response from the next middleware
         def call(env)
-          @token = @client.get_access_token_from_hash(@read_token.call)
+          around_refresh_token do
+            @token = @client.get_access_token_from_hash(@read_token.call)
 
-          if @token.expired? || @token.expires_at.nil?
-            @token = refresh_token!
+            if @token.expired? || @token.expires_at.nil?
+              @token = refresh_token!
+            end
           end
 
           env.request_headers["Authorization"] ||= "Bearer #{@token.token}"
@@ -63,6 +70,16 @@ module Booqable
 
         private
 
+        # Yield to the configured around-callback, if any
+        #
+        # When a host application provides one (e.g. an advisory lock), the
+        # read+check+refresh sequence runs inside it so concurrent callers
+        # cannot interleave a read with another caller's refresh.
+        def around_refresh_token(&block)
+          return yield unless @around_refresh_token
+          @around_refresh_token.call(&block)
+        end
+
         # Refresh the expired OAuth token
         #
         # Uses the refresh token to obtain a new access token and stores it
@@ -78,7 +95,7 @@ module Booqable
 
           new_token
         rescue OAuth2::Error => e
-          response = e.response.response.env.to_h
+          response = e.response.response.env
 
           Booqable::Error.from_response(response)
         end

data/lib/booqable/resource_parser.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Booqable
+  # Parses JSON:API payloads into Sawyer::Resource objects
+  #
+  # JSON:API formatted data (from webhooks or API responses) is converted
+  # into Ruby objects with dot-notation access for convenient attribute access.
+  #
+  # @example Parse a JSON:API payload
+  #   payload = '{"data":{"id":"123","type":"customers","attributes":{"name":"John"}}}'
+  #   customer = Booqable::ResourceParser.parse(payload)
+  #   customer.id   # => "123"
+  #   customer.name # => "John"
+  #
+  # @example Parse with nested relationships
+  #   payload = {
+  #     "data" => {
+  #       "id" => "123",
+  #       "type" => "orders",
+  #       "attributes" => { "status" => "reserved" },
+  #       "relationships" => {
+  #         "customer" => { "data" => { "id" => "456", "type" => "customers" } }
+  #       }
+  #     },
+  #     "included" => [
+  #       { "id" => "456", "type" => "customers", "attributes" => { "name" => "John" } }
+  #     ]
+  #   }
+  #   order = Booqable::ResourceParser.parse(payload)
+  #   order.customer.name # => "John"
+  #
+  class ResourceParser
+    # Parse a JSON:API payload into a Sawyer::Resource
+    #
+    # @param payload [String, Hash] JSON:API payload (string or parsed hash)
+    # @return [Sawyer::Resource, nil] Parsed resource object with dot-notation access,
+    #   or nil for empty/nil input
+    def self.parse(payload)
+      new(payload).parse
+    end
+
+    # Initialize a new ResourceParser
+    #
+    # @param payload [String, Hash] JSON:API payload
+    def initialize(payload)
+      @payload = payload
+    end
+
+    # Parse the payload into a Sawyer::Resource
+    #
+    # @return [Sawyer::Resource, nil] Parsed resource or nil for empty input
+    def parse
+      return nil if @payload.nil?
+
+      json_string = @payload.is_a?(String) ? @payload : @payload.to_json
+      return nil if json_string.strip.empty?
+
+      serializer = JsonApiSerializer.any_json
+      decoded = serializer.decode(json_string)
+
+      return nil unless decoded && decoded[:data]
+
+      Sawyer::Resource.new(sawyer_agent, decoded[:data])
+    end
+
+    private
+
+    # Create a minimal Sawyer agent for wrapping resources
+    #
+    # The agent URL is a placeholder - we don't make any HTTP requests.
+    # We just need the agent to create Sawyer::Resource objects that
+    # provide dot-notation attribute access.
+    #
+    # @return [Sawyer::Agent]
+    def sawyer_agent
+      @sawyer_agent ||= Sawyer::Agent.new("https://example.com") do |http|
+        http.headers[:content_type] = "application/json"
+      end
+    end
+  end
+end

data/lib/booqable/resource_proxy.rb

@@ -58,6 +58,13 @@ module Booqable
       paginate @resource, params
     end
 
+    # Alias for list
+    #
+    # @see list
+    def all(params = {})
+      list(params)
+    end
+
     # Find a specific resource by ID
     #
     # Retrieves a single resource by its unique identifier.

data/lib/booqable/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Booqable
-  VERSION = "1.0.0"
+  VERSION = "1.2.0"
 end

data/lib/booqable.rb

@@ -25,6 +25,7 @@ require_relative "booqable/resources"
 require_relative "booqable/auth"
 require_relative "booqable/http"
 require_relative "booqable/client"
+require_relative "booqable/resource_parser"
 
 # Main Booqable module providing access to the Booqable API
 #

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: booqable
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Hrvoje Šimić
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-10-24 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -138,6 +137,7 @@ files:
 - lib/booqable/middleware/raise_error.rb
 - lib/booqable/oauth_client.rb
 - lib/booqable/rate_limit.rb
+- lib/booqable/resource_parser.rb
 - lib/booqable/resource_proxy.rb
 - lib/booqable/resources.json
 - lib/booqable/resources.rb
@@ -149,10 +149,9 @@ licenses:
 metadata:
   homepage_uri: https://github.com/booqable/booqable.rb
   source_code_uri: https://github.com/booqable/booqable.rb
-  changelog_uri: https://github.com/booqable/booqable.rb/blob/master/CHANGELOG.md
+  changelog_uri: https://github.com/booqable/booqable.rb/blob/main/CHANGELOG.md
   documentation_uri: https://developers.booqable.com/
   bug_tracker_uri: https://github.com/booqable/booqable.rb/issues
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -167,8 +166,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.22
-signing_key:
+rubygems_version: 4.0.10
 specification_version: 4
 summary: Official Booqable API client for Ruby.
 test_files: []