webtranslateit-payday 2.0.0 → 2.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c69e90db47eb429202583e59002641017e200efa98a05989a8112db2504ca8d6
-  data.tar.gz: 0e1a0a649e12c88225f5eafd95bc7b2eb2f1a1b3825570ca54611ea072d16a6a
+  metadata.gz: e997f24c5936a24f8deb333262cdfb74ecf989ddd229052797211579748a8f8c
+  data.tar.gz: af5120a7dd9edd4a7cf8e980d5090f2c20a2d1e0c32d654aa711c93b777cc429
 SHA512:
-  metadata.gz: 3bfaddfd9cbd922672a519e1309e723a8abfa5e64d035e1d3e355c9437ce93d0734fdfbfb7b624b1389f2ff66dc65685327a9cd802826055468b6353351df606
-  data.tar.gz: beac41f39e7cc6013e6eb7f94057e55042daad14c73a17b33a2e99bbcbc8b23d0b63e4c67618c5338298131e02c3f1614349d89983a42805ac693d76a0df1625
+  metadata.gz: 73f336ccbb26a4e1ab7b98ca3f95cd407e5730d7508884c361049e1ad1120b6a09f02609f44f5edb4e492d5dff0563c3021c16fc72e67756926c50463308875e
+  data.tar.gz: ab853437c9e8d4bcdb647bde8535e0d0a5e18a9e93e5d132be4cebaccec844a5e649915123ac4216d50f832c79604905a3d7eb755b5e5dbae59cfa957d749126

data/CHANGELOG.md

@@ -1,5 +1,21 @@
 # CHANGELOG
 
+## 2.1.1 (2026-11-08)
+
+* An invoice that defines `date_format` now has its dates formatted with it, the way it could already override `currency`, `invoice_logo`, `page_size`, `company_name` and `company_details`. Every one of those is read through the new `Config#value_for(invoice, property)` (#319, #321). `Payday::Invoice` has no `date_format`, so its output is unchanged.
+* Internal refactoring, no behaviour change: `Invoice#initialize` assigns its options from one list (#314); the invoice rate setters and the `LineItem` setters each share one decimal conversion (#315, #316); `Invoiceable#tax`, `#shipping` and `#retention` are one-liners (#315); `overdue?` reads through `Invoiceable.past?` (#317); `each_detail` is tidied (#318); and two doc comments no longer need RuboCop line-length directives (#320).
+* The code satisfies RuboCop 1.90's `Style/DirectiveScope` cop, the linter runs on Ruby 4.0, and guard and pry are gone from the development setup.
+
+## 2.1.0 (2026-08-27)
+
+* Add `Payday::Appendix`, for compiling pages of your own onto the end of an invoice. `render_pdf`, `render_pdf_to_file`, `PdfRenderer.render` and `PdfRenderer.render_to_file` all take an `appendix:` keyword; every signature stays backward compatible and an invoice rendered without one is byte-for-byte what it was.
+
+  The appendix carries Typst `source`, plus `inputs` that reach it as sys_inputs JSON and `dependencies` it can resolve by name. The source is concatenated onto Payday's template rather than compiled separately, so the appended pages keep the invoice's page setup and the numbering footer counts them: a one-page invoice with an appendix numbers "1 / 2" and "2 / 2". Merging a second PDF in could do neither.
+
+  Data belongs in `inputs`, where Typst treats it as literal text. Interpolating invoice data into `source` would give it the run of the document, which is the same rule the invoice template already follows.
+
+  An appendix that reuses a name the invoice has taken — the `invoice` input, or the logo and QR code files — raises `ArgumentError` instead of replacing it.
+
 ## 2.0.0 (2026-08-26)
 
 **Breaking:** Payday now renders with [Typst](https://typst.app) instead of Prawn. The `prawn`, `prawn-table` and `prawn-svg` dependencies are gone, replaced by the single Apache-2.0 licensed `typst` gem, which ships precompiled native builds for macOS and Linux on both x86_64 and arm64.

data/README.md

@@ -115,6 +115,35 @@ end
 
 Be sure to restart your server after you edit the mime_types initializer. The updated setting won't take effect until you do.
 
+Appending your own pages
+===
+Pass a `Payday::Appendix` to add pages of your own to the end of an invoice — a per-item breakdown, a delivery note, terms and conditions:
+
+``` ruby
+appendix = Payday::Appendix.new(
+  source: File.read('appendix.typ'),
+  inputs: {'shipments' => shipments.to_json},
+  dependencies: {'chart.svg' => File.binread('chart.svg')}
+)
+
+invoice.render_pdf(appendix: appendix)
+```
+
+`source` is [Typst](https://typst.app) markup appended to Payday's own template, so it is compiled as part of the invoice rather than as a second PDF you would then have to merge in. Two things follow from that: your pages inherit the invoice's page setup and margins, and the page counter runs across the whole document, so the numbering footer counts your pages too. A one-page invoice with one appended page comes out numbered "1 / 2" and "2 / 2".
+
+`inputs` reach the template as [sys_inputs](https://typst.app/docs/reference/foundations/sys/), read with `json(bytes(sys.inputs.shipments))`. `dependencies` are files the source can reach by name, with `image("chart.svg")` and the like. Reusing a name the invoice has already taken — the `invoice` input, or the logo and QR code files — raises an `ArgumentError` rather than quietly replacing it.
+
+**Pass your data through `inputs`, never by interpolating it into `source`.** Typst treats a string arriving through `sys.inputs` as literal text, which is what stops a customer-supplied field from affecting the layout. `source` is code: interpolating invoice data into it hands anyone who can set a field on an invoice a way to write Typst.
+
+An appendix that reads its data and prints a heading:
+
+``` typst
+#let a = json(bytes(sys.inputs.shipments))
+
+#pagebreak()
+#text(size: 16pt, weight: "bold")[#a.title]
+```
+
 I18n
 ===
 Payday uses the i18n gem to provide support for custom labels and internationalized applications. You can change the default labels by adding a YAML file in the `config/locales` directory of your Rails app. Here are the default labels you can customize:

data/lib/payday/appendix.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Payday
+
+  # Extra pages compiled onto the end of an invoice.
+  #
+  #   appendix = Payday::Appendix.new(
+  #     source: File.read('appendix.typ'),
+  #     inputs: {'shipments' => shipments.to_json},
+  #     dependencies: {'chart.svg' => File.binread('chart.svg')}
+  #   )
+  #   invoice.render_pdf(appendix: appendix)
+  #
+  # +source+ is Typst markup appended to Payday's own template, so it is compiled as part of
+  # the invoice rather than as a second document that would then have to be merged in. Two
+  # things follow from that. The template's +#set page+ rules stay in force, so the appended
+  # pages keep the invoice's margins; and the page counter runs across the whole document, so
+  # the numbering footer counts the appended pages. A one-page invoice with one appended page
+  # numbers "1 / 2", and a three-page invoice continues into "4 / 4".
+  #
+  # That is also why the source is concatenated rather than +#include+d: an included file is
+  # its own module, and the page rules set inside the template would stop at its edge.
+  #
+  # **Pass your data through +inputs+, never through +source+.** Inputs reach the template as
+  # sys_inputs JSON, where Typst treats every string as literal text, which is what stops a
+  # customer-supplied field from affecting the layout. Source is code. Interpolating invoice
+  # data into it gives that data back the run of the document, and hands anyone who can set a
+  # field on an invoice a way to write Typst.
+  #
+  # +dependencies+ are files the source can reach by name -- +image("chart.svg")+ and the
+  # like. Keys are file names, values are the bytes.
+  Appendix = Data.define(:source, :inputs, :dependencies) do
+
+    # Accepts an Appendix, a Hash of the same attributes, or nil.
+    def self.wrap(value)
+      return value if value.nil? || value.is_a?(Appendix)
+
+      new(**value)
+    end
+
+    def initialize(source:, inputs: {}, dependencies: {})
+      super(source: source, inputs: inputs.transform_keys(&:to_s), dependencies: dependencies.transform_keys(&:to_s))
+    end
+
+  end
+
+end

data/lib/payday/config.rb

@@ -18,6 +18,13 @@ module Payday
       @default ||= new
     end
 
+    # The invoice's own value for +property+ when it defines one and it is set, otherwise this
+    # config's. Every setting an invoice can override is read through here.
+    def value_for(invoice, property)
+      value = invoice.public_send(property) if invoice.respond_to?(property)
+      value || public_send(property)
+    end
+
     # Internal: Resets a config object back to its default settings.
     #
     # Primarily intended for use in our tests.

data/lib/payday/invoice.rb

@@ -13,49 +13,30 @@ module Payday
 
     attr_reader :tax_rate, :shipping_rate, :retention_rate
 
-    # rubocop:todo Metrics/PerceivedComplexity
-    # rubocop:todo Metrics/MethodLength
-    # rubocop:todo Metrics/AbcSize
-    def initialize(options = {}) # rubocop:todo Metrics/CyclomaticComplexity, Metrics/AbcSize, Metrics/MethodLength, Metrics/PerceivedComplexity
-      self.invoice_number = options[:invoice_number] || nil
-      self.bill_to = options[:bill_to] || nil
-      self.ship_to = options[:ship_to] || nil
-      self.notes = options[:notes] || nil
+    # Options assigned as given; a missing one is nil, which the rate setters turn into 0.
+    OPTIONS = %i[invoice_number bill_to ship_to notes shipping_rate shipping_description tax_rate
+                 tax_description retention_rate retention_description due_at paid_at refunded_at
+                 currency invoice_date qr_code].freeze
+
+    def initialize(options = {})
+      OPTIONS.each { |name| public_send(:"#{name}=", options[name]) }
       self.line_items = options[:line_items] || []
-      self.shipping_rate = options[:shipping_rate] || nil
-      self.shipping_description = options[:shipping_description] || nil
-      self.tax_rate = options[:tax_rate] || nil
-      self.tax_description = options[:tax_description] || nil
-      self.retention_rate = options[:retention_rate] || nil
-      self.retention_description = options[:retention_description] || nil
-      self.due_at = options[:due_at] || nil
-      self.paid_at = options[:paid_at] || nil
-      self.refunded_at = options[:refunded_at] || nil
-      self.currency = options[:currency] || nil
       self.invoice_details = options[:invoice_details] || []
-      self.invoice_date = options[:invoice_date] || nil
-      self.qr_code = options[:qr_code] || nil
     end
-    # rubocop:enable Metrics/AbcSize
-    # rubocop:enable Metrics/MethodLength
-    # rubocop:enable Metrics/PerceivedComplexity
 
     # The tax rate that we're applying, as a BigDecimal
     def tax_rate=(value)
-      value = 0 if value.to_s.blank?
-      @tax_rate = BigDecimal(value.to_s)
+      @tax_rate = to_rate(value)
     end
 
     # Shipping rate
     def shipping_rate=(value)
-      value = 0 if value.to_s.blank?
-      @shipping_rate = BigDecimal(value.to_s)
+      @shipping_rate = to_rate(value)
     end
 
     # Retention rate (e.g. IRPF). Applied as a percentage of the subtotal and deducted from the total.
     def retention_rate=(value)
-      value = 0 if value.to_s.blank?
-      @retention_rate = BigDecimal(value.to_s)
+      @retention_rate = to_rate(value)
     end
 
     # Adds a line item
@@ -63,6 +44,13 @@ module Payday
       line_items << Payday::LineItem.new(options)
     end
 
+    private
+
+    # A blank rate (nil, "", "  ") is 0.
+    def to_rate(value)
+      BigDecimal(value.to_s.presence || 0)
+    end
+
   end
 
 end

data/lib/payday/invoice_presenter.rb

@@ -144,7 +144,7 @@ module Payday
     def date(value)
       return value.to_s unless value.is_a?(Date) || value.is_a?(Time)
 
-      value.strftime(Payday::Config.default.date_format)
+      value.strftime(setting(:date_format))
     end
 
     def t(key, default)
@@ -152,9 +152,7 @@ module Payday
     end
 
     def setting(property)
-      return @invoice.send(property) if @invoice.respond_to?(property) && @invoice.send(property)
-
-      Payday::Config.default.send(property)
+      Payday::Config.default.value_for(@invoice, property)
     end
 
   end

data/lib/payday/invoiceable.rb

@@ -12,10 +12,8 @@
 # when generating an invoice. We include a simple tax method that calculates tax, but it's probably wiser
 # to override this in your class (our calculated tax won't be stored to a database by default, for example).
 #
-# rubocop:todo Layout/LineLength
-# If the +due_at+, +paid_at+, and +refunded_at+ methods are available, {Payday::Invoiceable} will use them to show due dates,
-# rubocop:enable Layout/LineLength
-# paid dates, and refunded dates, as well as stamps showing if the invoice is paid or due.
+# If the +due_at+, +paid_at+, and +refunded_at+ methods are available, {Payday::Invoiceable} will use them
+# to show due dates, paid dates, and refunded dates, as well as stamps showing if the invoice is paid or due.
 module Payday
 
   module Invoiceable
@@ -32,31 +30,19 @@ module Payday
 
     # The tax for this invoice, as a BigDecimal
     def tax
-      if defined?(tax_rate)
-        subtotal * tax_rate / 100
-      else
-        0
-      end
+      defined?(tax_rate) ? subtotal * tax_rate / 100 : 0
     end
 
     # TODO: Add a per weight unit shipping cost
     # Calculates the shipping
     def shipping
-      if defined?(shipping_rate)
-        shipping_rate
-      else
-        0
-      end
+      defined?(shipping_rate) ? shipping_rate : 0
     end
 
     # Calculates the retention (e.g. IRPF) as a percentage of the subtotal.
     # This is a post-tax deduction subtracted from the total.
     def retention
-      if defined?(retention_rate)
-        subtotal * retention_rate / 100
-      else
-        0
-      end
+      defined?(retention_rate) ? subtotal * retention_rate / 100 : 0
     end
 
     # Calculates the total for this invoice.
@@ -65,9 +51,17 @@ module Payday
     end
 
     def overdue?
-      # rubocop:todo Layout/LineLength
-      defined?(due_at) && ((due_at.is_a?(Date) && due_at < Date.today) || (due_at.is_a?(Time) && due_at < Time.now)) && !paid_at
-      # rubocop:enable Layout/LineLength
+      defined?(due_at) && Invoiceable.past?(due_at) && !paid_at
+    end
+
+    # Whether a Date is before today or a Time before now. A module function rather than a
+    # private method, so it does not land in the classes that include Invoiceable.
+    def self.past?(moment)
+      case moment
+      when Date then moment < Date.today
+      when Time then moment < Time.now
+      else false
+      end
     end
 
     def refunded?
@@ -78,24 +72,23 @@ module Payday
       defined?(paid_at) && !!paid_at
     end
 
-    # Renders this invoice to pdf as a string
-    def render_pdf
-      Payday::PdfRenderer.render(self)
+    # Renders this invoice to pdf as a string. Pass a Payday::Appendix to compile pages of
+    # your own onto the end of it.
+    def render_pdf(appendix: nil)
+      Payday::PdfRenderer.render(self, appendix: appendix)
     end
 
     # Renders this invoice to pdf
-    def render_pdf_to_file(path)
-      Payday::PdfRenderer.render_to_file(self, path)
+    def render_pdf_to_file(path, appendix: nil)
+      Payday::PdfRenderer.render_to_file(self, path, appendix: appendix)
     end
 
     # Iterates through the details on this invoiceable. The block given should accept
     # two parameters, the detail name and the actual detail value.
     def each_detail
-      return if defined?(invoice_details).nil?
+      return unless defined?(invoice_details)
 
-      invoice_details.each do |detail|
-        yield(detail[0], detail[1])
-      end
+      invoice_details.each { |detail| yield detail[0], detail[1] }
     end
 
   end

data/lib/payday/line_item.rb

@@ -4,11 +4,9 @@ module Payday
 
   # Represents a line item in an invoice.
   #
-  # rubocop:todo Layout/LineLength
-  # +quantity+ and +price+ are written to be pretty picky, primarily because if we're not picky about what values are set to
-  # rubocop:enable Layout/LineLength
-  # them your invoice math could get pretty messed up. It's recommended that both values be set to +BigDecimal+ values.
-  # Otherwise, we'll do our best to convert the set values to a +BigDecimal+.
+  # +quantity+ and +price+ are written to be pretty picky, primarily because if we're not picky about what
+  # values are set to them your invoice math could get pretty messed up. It's recommended that both values be
+  # set to +BigDecimal+ values. Otherwise, we'll do our best to convert the set values to a +BigDecimal+.
   class LineItem
 
     include LineItemable
@@ -31,20 +29,24 @@ module Payday
 
     # Sets the quantity of this {LineItem}
     def quantity=(value)
-      value = 0 if value.to_s.blank?
-      @quantity = BigDecimal(value.to_s)
+      @quantity = to_decimal(value)
     end
 
     # Sets the price for this {LineItem}
     def price=(value)
-      value = 0 if value.to_s.blank?
-      @price = BigDecimal(value.to_s)
+      @price = to_decimal(value)
     end
 
     # Sets the predefined_amount for this {LineItem}
     def predefined_amount=(value)
-      value = 0 if value.to_s.blank?
-      @predefined_amount = BigDecimal(value.to_s)
+      @predefined_amount = to_decimal(value)
+    end
+
+    private
+
+    # A blank value (nil, "", "  ") is 0.
+    def to_decimal(value)
+      BigDecimal(value.to_s.presence || 0)
     end
 
   end

data/lib/payday/pdf_renderer.rb

@@ -13,34 +13,29 @@ module Payday
     FONTS = %w[NotoSans-Regular.ttf NotoSans-Bold.ttf].freeze
 
     # Renders the given invoice as a pdf on disk
-    def self.render_to_file(invoice, path)
-      File.binwrite(path, render(invoice))
+    def self.render_to_file(invoice, path, appendix: nil)
+      File.binwrite(path, render(invoice, appendix: appendix))
     end
 
-    # Renders the given invoice as a pdf, returning a string
-    def self.render(invoice)
-      new(invoice).render
+    # Renders the given invoice as a pdf, returning a string. See Payday::Appendix for
+    # appending pages of your own to it.
+    def self.render(invoice, appendix: nil)
+      new(invoice, appendix: appendix).render
     end
 
     # Converts this number to a formatted currency string
     def self.number_to_currency(number, invoice)
       Money.locale_backend = :currency
       Money.rounding_mode = BigDecimal::ROUND_HALF_UP
-      currency = Money::Currency.wrap(currency_for(invoice))
+      currency = Money::Currency.wrap(Payday::Config.default.value_for(invoice, :currency))
       number *= currency.subunit_to_unit
       number = number.round unless Money.default_infinite_precision
       Money.new(number, currency).format
     end
 
-    def self.currency_for(invoice)
-      return invoice.currency if invoice.respond_to?(:currency) && invoice.currency
-
-      Payday::Config.default.currency
-    end
-    private_class_method :currency_for
-
-    def initialize(invoice)
+    def initialize(invoice, appendix: nil)
       @invoice = invoice
+      @appendix = Appendix.wrap(appendix)
       @dependencies = {}
     end
 
@@ -49,20 +44,51 @@ module Payday
       register_qr_code(data[:qr_code])
       data[:logo] = logo
 
-      Typst(body: File.read(TEMPLATE), dependencies: @dependencies, fonts: fonts,
-            sys_inputs: {'invoice' => data.to_json})
+      Typst(body: body, dependencies: dependencies, fonts: fonts, sys_inputs: sys_inputs(data))
         .compile(:pdf).bytes.flatten.pack('C*')
     end
 
     private
 
+    # An appendix is concatenated rather than +#include+d, which would make it a module of its
+    # own and leave the template's page rules -- the margins, and the numbering footer --
+    # stopping at its edge.
+    def body
+      template = File.read(TEMPLATE)
+      return template if @appendix.nil?
+
+      "#{template}\n#{@appendix.source}"
+    end
+
+    def sys_inputs(data)
+      merge({'invoice' => data.to_json}, @appendix&.inputs, 'sys_input')
+    end
+
+    # Read after the logo and the QR code have registered theirs, so an appendix reusing one
+    # of those names is caught rather than silently replacing the file.
+    def dependencies
+      merge(@dependencies, @appendix&.dependencies, 'dependency')
+    end
+
+    def merge(ours, theirs, what)
+      return ours if theirs.nil?
+
+      taken = ours.keys & theirs.keys
+      if taken.any?
+        raise ArgumentError,
+              "appendix #{what} #{taken.map(&:inspect).join(', ')} is reserved by the invoice"
+      end
+
+      ours.merge(theirs)
+    end
+
     def fonts
       FONTS.to_h { |name| [name, File.binread(File.join(FONT_DIR, name))] }
     end
 
     # Config#invoice_logo is either a path or a {filename:, size: "WxH"} Hash.
     def logo
-      setting = invoice_logo
+      setting = Payday::Config.default.value_for(@invoice, :invoice_logo)
       return nil if setting.nil?
 
       path, width, height = logo_parts(setting)
@@ -71,12 +97,6 @@ module Payday
       {name: name, width: width, height: height}
     end
 
-    def invoice_logo
-      return @invoice.invoice_logo if @invoice.respond_to?(:invoice_logo) && @invoice.invoice_logo
-
-      Payday::Config.default.invoice_logo
-    end
-
     def logo_parts(setting)
       return [setting, nil, nil] unless setting.is_a?(Hash)
 

data/payday.gemspec

@@ -2,7 +2,7 @@
 
 Gem::Specification.new do |s|
   s.name        = 'webtranslateit-payday'
-  s.version     = '2.0.0'
+  s.version     = '2.1.1'
   s.required_ruby_version = '>= 3.2'
   s.platform    = Gem::Platform::RUBY
   s.authors     = ['Alan Johnson', 'Edouard Briere']

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: webtranslateit-payday
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 2.1.1
 platform: ruby
 authors:
 - Alan Johnson
@@ -147,6 +147,7 @@ files:
 - lib/generators/payday/setup/templates/line_item.rb
 - lib/generators/payday/setup/templates/migration.rb
 - lib/payday.rb
+- lib/payday/appendix.rb
 - lib/payday/assets/default_logo.png
 - lib/payday/config.rb
 - lib/payday/invoice.rb