Adding resource-based architecture + Ruby 3.2+

.github/workflows/ci.yml

@@ -6,38 +6,35 @@ jobs:
   specs:
     name: Run specs with Ruby ${{matrix.ruby}}
     runs-on: ubuntu-latest
+    continue-on-error: ${{ matrix.experimental || false }}
     strategy:
       fail-fast: false
       matrix:
         include:
-          - ruby: '2.6'
-            bundler: 2.2.30
-          - ruby: '2.7'
-            bundler: 2.2.30
-          - ruby: '3.0'
-            bundler: 2.2.30
-          - ruby: '3.1'
+          - ruby: "3.2"
             bundler: 2.6.3
-          - ruby: '3.2'
+          - ruby: "3.3"
             bundler: 2.6.3
-          - ruby: '3.3'
+          - ruby: "3.4"
             bundler: 2.6.3
-          - ruby: '3.4'
+          - ruby: "4.0"
+            bundler: 2.6.3
+          - ruby: "4.0.1"
             bundler: 2.6.3
           - ruby: head
             bundler: 2.6.3
             experimental: true
     steps:
-    - uses: actions/checkout@v4
+      - uses: actions/checkout@v4
 
-    - uses: ruby/setup-ruby@v1
-      with:
-        ruby-version: ${{matrix.ruby}}
-        bundler: ${{matrix.bundler}}
-        bundler-cache: true
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{matrix.ruby}}
+          bundler: ${{matrix.bundler}}
+          bundler-cache: true
 
-    - name: Install gems
-      run: bundle _${{matrix.bundler}}_ install
+      - name: Install gems
+        run: bundle _${{matrix.bundler}}_ install
 
-    - name: Run specs
-      run: bundle _${{matrix.bundler}}_ exec rspec
+      - name: Run specs
+        run: bundle _${{matrix.bundler}}_ exec rspec

.gitignore

@@ -6,3 +6,5 @@
 /pkg/
 /spec/reports/
 /tmp/
+Gemfile.lock
+LOCAL_TODO*

.rubocop.yml

@@ -1,209 +1,40 @@
 AllCops:
-  DefaultFormatter: progress
-  TargetRubyVersion: 2.5
-
-Layout/AlignParameters:
-  EnforcedStyle: with_first_parameter
-
-Layout/BlockEndNewline:
+  TargetRubyVersion: 3.2
+  NewCops: enable
+  SuggestExtensions: false
   Exclude:
-    - spec/**/*_spec.rb
-
-Layout/ClassStructure:
-  ExpectedOrder:
-    - constants
-    - module_inclusion
-    - initializer
-    - public_methods
-    - public_class_methods
-    - protected_methods
-    - private_methods
-
-Layout/EmptyLineAfterGuardClause:
-  Enabled: false
-
-Layout/EndAlignment:
-  EnforcedStyleAlignWith: start_of_line
-
-Layout/FirstArrayElementLineBreak:
-  Enabled: true
-
-Layout/FirstHashElementLineBreak:
-  Enabled: true
-
-Layout/FirstMethodParameterLineBreak:
-  Enabled: true
-
-Layout/IndentArray:
-  EnforcedStyle: consistent
+    - 'spec/**/*'
+    - 'vendor/**/*'
 
-Layout/IndentHash:
-  EnforcedStyle: consistent
-
-Layout/MultilineBlockLayout:
-  Exclude:
-    - spec/**/*_spec.rb
-
-Layout/MultilineMethodCallBraceLayout:
-  EnforcedStyle: same_line
-
-Layout/MultilineMethodDefinitionBraceLayout:
-  EnforcedStyle: same_line
-
-Layout/MultilineOperationIndentation:
-  EnforcedStyle: indented
-  IndentationWidth: 2
-
-Layout/RescueEnsureAlignment:
+Style/Documentation:
   Enabled: false
 
-Layout/SpaceInsideArrayPercentLiteral:
-  Exclude:
-    - 'lib/tasks/*_permissions.rake'
-
-Layout/SpaceInsideBlockBraces:
-  Exclude:
-    - spec/**/*_spec.rb
-
-Lint/AmbiguousBlockAssociation:
+Metrics/BlockLength:
   Exclude:
-    - 'spec/**/*_spec.rb'
-
-Lint/NestedMethodDefinition:
-  Enabled: false
+    - '*.gemspec'
 
-Lint/AmbiguousOperator:
+# Dev dependencies in gemspec is standard for gems
+Gemspec/DevelopmentDependencies:
   Enabled: false
 
-Lint/RescueException:
-  Exclude:
-    - 'lib/business_pipeline/lib/business_pipeline/interceptors/error_handling.rb'
-    - 'lib/business_pipeline/lib/business_pipeline/interceptors/error_reporting.rb'
-
-Metrics/AbcSize:
-  Exclude:
-    - 'app/services/retro_compatibility/*_backporter.rb'
-    - 'lib/tasks/*.rake'
-    - 'spec/support/payloads/**/*.rb'
-  Max: 18
-
-Metrics/BlockLength:
-  Exclude:
-    - '**/*.builder'
-    - '**/*.rake'
-    - 'app/views/api/v3/**/_*.jb'
-    - 'config/environments/production.rb'
-    - 'config/routes.rb'
-    - 'Gemfile'
-    - 'Guardfile'
-    - 'spec/**/*.rb'
-
+# Adapter and Document are cohesive orchestration classes
 Metrics/ClassLength:
   Exclude:
-    - 'app/forms/**/*.rb'
-    - 'app/services/retro_compatibility/*_backporter.rb'
-    - 'app/services/tracking/*tracking_handler.rb'
+    - 'lib/pdfmonkey/adapter.rb'
+    - 'lib/pdfmonkey/document.rb'
 
-Metrics/CyclomaticComplexity:
-  Exclude:
-    - 'lib/tasks/*.rake'
-
-Metrics/LineLength:
-  Exclude:
-    - 'config/routes.rb'
-    - 'lib/**/*.gemspec'
-    - 'lib/tasks/*.rake'
-    - 'spec/**/*_spec.rb'
-    - 'spec/support/factories/*.rb'
-  Max: 90
+# Some methods are inherently complex (API orchestration, polling, data extraction)
+Metrics/AbcSize:
+  Max: 23
 
 Metrics/MethodLength:
-  Exclude:
-    - 'app/services/retro_compatibility/*_backporter.rb'
-    - 'app/services/tracking/**/*.rb'
-    - 'app/web_strategies/**/*.rb'
-    - 'spec/support/payloads/**/*.rb'
-
-Naming/PredicateName:
-  NamePrefixBlacklist:
-    - is_
-
-Naming/UncommunicativeMethodParamName:
-  Enabled: false
-
-Performance/RedundantBlockCall:
-  Enabled: false
-
-Rails:
-  Enabled: true
-
-# FIXME: https://github.com/bbatsov/rubocop/issues/4751
-# Rails/HasManyOrHasOneDependent:
-#   Enabled: false
-
-Rails/OutputSafety:
-  Enabled: false
-
-Rails/SkipsModelValidations:
-  Enabled: false
+  Max: 25
 
+# Inline private is intentional style choice for this codebase
 Style/AccessModifierDeclarations:
-  Enabled: false
+  EnforcedStyle: inline
 
-Style/Alias:
-  EnforcedStyle: prefer_alias_method
-
-Style/AsciiComments:
-  Enabled: false
-
-Style/BlockDelimiters:
+# TemplateCard.list enforces workspace_id: as required — not useless
+Lint/UselessMethodDefinition:
   Exclude:
-    - spec/**/*_spec.rb
-
-Style/Documentation:
-  Enabled: false
-
-Style/DoubleNegation:
-  Enabled: false
-
-Style/FormatStringToken:
-  EnforcedStyle: template
-
-Style/FrozenStringLiteralComment:
-  Enabled: false
-
-Style/IfUnlessModifier:
-  Enabled: false
-
-Style/MultilineBlockChain:
-  Enabled: false
-
-Style/PercentLiteralDelimiters:
-  PreferredDelimiters:
-    '%':  '{}'
-    '%i': '[]'
-    '%q': '{}'
-    '%Q': '{}'
-    '%r': '{}'
-    '%s': '{}'
-    '%w': '[]'
-    '%W': '[]'
-    '%x': '{}'
-
-Style/RegexpLiteral:
-  EnforcedStyle: mixed
-
-Style/SignalException:
-  EnforcedStyle: semantic
-
-Style/SingleLineBlockParams:
-  Enabled: false
-
-Style/StringLiterals:
-  EnforcedStyle: single_quotes
-
-Style/StringLiteralsInInterpolation:
-  EnforcedStyle: single_quotes
-
-Style/YodaCondition:
-  Enabled: false
+    - 'lib/pdfmonkey/template_card.rb'

CHANGELOG.md

@@ -2,6 +2,41 @@
 
 ## Unreleased
 
+### Breaking changes
+
+* **Requiring Ruby >= 3.2** — The gem now requires Ruby 3.2 or later.
+* **Exception-based error handling** — API errors now raise `Pdfmonkey::ApiError` (with `errors` and `status_code` attributes) and network errors raise `Pdfmonkey::ConnectionError` instead of returning error hashes. Rescue `Pdfmonkey::Error` for a catch-all.
+* **`Document.generate!` / `Document.generate` signature change** — These methods now use keyword arguments (`document_template_id:`, `payload:`, `meta:`). Positional arguments still work but emit a deprecation warning.
+* **`Document.generate!` raises on failure** — `Document.generate!` now raises `Pdfmonkey::GenerationError` when the document ends with `error` or `failure` status, instead of returning the failed document.
+* **`Document.generate!` polling** — `Document.generate!` now sleeps `poll_interval` seconds (default 0.5s) between status polls instead of busy-looping.
+* **`document_template_id` validation** — `Document.generate!`, `Document.generate`, and `Document.create_draft` now raise `ArgumentError` when `document_template_id` is missing or blank.
+* **Removing `ostruct` dependency** — Attributes are now backed by `Struct` instead of `OpenStruct`. This removes the runtime dependency on the `ostruct` gem.
+* **`Document#attributes` is no longer public** — Access individual attributes through their accessor methods instead.
+* **`User-Agent` is no longer configurable** — The `user_agent` configuration option has been removed. The header is now always `pdfmonkey-ruby/<version>`.
+* **`to_json` omits nil attributes** — `Resource#to_json` now compacts nil values and strips the `errors` attribute from the serialized output.
+* **Resource base class** — All resource classes now inherit from `Pdfmonkey::Resource` which provides shared CRUD operations, attribute management and JSON serialization.
+
+### New features
+
+* Adding `Document#generate` and `Document#generate!` instance methods for triggering generation on draft documents
+* Adding `Document#save` as a public method (was private in 0.9.0)
+* Adding `Document.create_draft` for creating draft documents with preview support
+* Adding `Document#update!` for updating document attributes via PUT
+* Adding `Document.list_cards`, `Document.fetch_card`, and `Document.fetch_full` for accessing documents through the `Document` class
+* Adding `output_type` to `Document` attributes
+* Adding resources for:
+  * `Engine`
+  * `Snippet`
+  * `TemplateCard`
+  * `TemplateFolder`
+  * `Template`
+  * `Webhook`
+  * `Workspace` (read-only)
+* Adding `CurrentUser.fetch` for retrieving authenticated user info
+* Adding `Pdfmonkey.with_adapter` for per-request adapter scoping (e.g. multi-tenant credentials)
+* Adding persistent HTTP connections with configurable timeouts (`open_timeout`, `read_timeout`, `keep_alive_timeout`)
+* Adding API key validation at request time (raises `Pdfmonkey::Error` if unconfigured)
+
 ## 0.9.0
 
 * Testing against Ruby 3.2, 3.3 and 3.4