booqable 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c084014d612e3e317590f31144911c3a3907a85075a17b3172edd2f6eb8c7d9f
-  data.tar.gz: 23836e46596f37b74175cd45f4e6ee04ee17eb7b0254bb53395972bc801a55aa
+  metadata.gz: 13ee5f72ca221d2613d8691dd8c04fa189a38fbed8276b60878d2cce4c7f4f23
+  data.tar.gz: 54028d30a657d3651ad0d49fab923efba00e09fa9f0d2e36906e8cf068975abd
 SHA512:
-  metadata.gz: 0a2eb78b9a78a239bec1fda211b177533102e78e4cdd95470692cb5a21132180827d2339caadf723564de9d8091d15c4e6160489f5a4694dfe40fc8bd4a630c2
-  data.tar.gz: 7210d24c6985facb00617c0949abe55c0b9034acb53b3120039c7d78e1da3ecd763875ff54c69672e39701049a3ab46f46024c1c6511251840891163a19518c0
+  metadata.gz: 51cb9ed5b66956cee3e429c51057e12884574fe3c8b3b907d6998caa1b037b5ca861c929ea7b26e8364369bf424b3686feff274149fa6a169da09d8048118390
+  data.tar.gz: d6389d7f934088b0447dba290054456f10380578f5b38622275d6e846c99872a5060c21b192b8524aa7d867fe1b58917c9ad03eebfacef716b83eca28dab8549

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 ## [Unreleased]
 
-## [0.1.0] - 2025-06-27
+## [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)
   }
@@ -159,7 +161,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 +224,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 +245,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 +305,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 +418,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 +436,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 +456,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/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/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

@@ -78,7 +78,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.1.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.1.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: 3.6.9
 specification_version: 4
 summary: Official Booqable API client for Ruby.
 test_files: []