webtranslateit-payday 1.7.4 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 655aa13a2a0c729008a5bce34e5e8de25b5fafd1f3e571995addf916413f74f8
-  data.tar.gz: 7d78b88d6886fbfceb45377b0c25c3cdbc6b3886a33003460cc2f68490004f0c
+  metadata.gz: 4cb98acc78809a09e4945f8d8525aee1bbafd3ed17a45234be6fb0a8836f3135
+  data.tar.gz: b3379b263fb55f5d7fdb8ec48d66924e0f0b1110325b43e15bbd0a764fbc6154
 SHA512:
-  metadata.gz: 36a5311dd8d6858c70a8b00a47bc675beb3de3c72827e0b5eb330f7113566051723dfa1f9cdbe636d745363bd02b3458e861803c2d0f481e7269805ae0c2d95e
-  data.tar.gz: 5342f87b7e7d2568bc50141463557e8929ae1f678cdbdfb7776cdeb560fdaf215bd8b4f7b4fa8588b861befe38330225777a94783af558434ab671f3440cb2f7
+  metadata.gz: c0473911f660484293361d1fbfb7020efed4614c06dd89b000fc7995f90e52b995c763781f175609578fd42090923ed9969baab0d4bffb85140f887356964690
+  data.tar.gz: 0a401edbb42eb073bf35602caaf6c2b7b762450dff19a04f2a8ee4d3ae8aca0ecf2ceab4485300a0647a2005b22116edd2cd1eba0be60a07117f5d44e5637b39

data/CHANGELOG.md

@@ -1,5 +1,40 @@
 # CHANGELOG
 
+## 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.
+
+The motivation was `prawn-table`, which has had no release since 2015 while the renderer depended on it for every table.
+
+* The public API is unchanged. `Invoiceable#render_pdf`, `#render_pdf_to_file`, `PdfRenderer.render`, `PdfRenderer.render_to_file` and every `Payday::Config` accessor keep their signatures, and rendered invoices keep their existing layout.
+* Prawn is no longer loaded for you. If your application relied on Payday requiring Prawn, require it yourself.
+* Layout now lives in `lib/payday/templates/invoice.typ`, and invoice data is turned into a plain Hash by the new `Payday::InvoicePresenter`.
+* The `inline_format` markup Payday accepted in notes and line item descriptions still works. `Payday::Markup` converts `<b>`, `<i>`, `<u>`, `<strikethrough>`, `<sub>`, `<sup>`, `<font size>`, `<color rgb>`, `<link href>` and `<br>` into styled runs.
+* Invoice data reaches the template only as JSON, where Typst treats every string as literal text, so customer-supplied fields can no longer affect the layout.
+* Rendered PDFs are now byte-for-byte reproducible for the same input.
+* QR codes are drawn as vector SVG rather than a scaled 200px PNG, so they stay sharp in print, and the three finder patterns are drawn as rounded frames. The matrix still comes straight from RQRCode: the payload and its error correction level are untouched, and the rendered code is module-for-module identical to what the encoder produces.
+* `Config#company_details` has any per-line indentation stripped. Prawn rendered each line as its own table cell, which trimmed leading whitespace, so a value written as an indented heredoc used to look fine and would otherwise have started rendering with its indentation.
+* Logos still accept PNG, JPEG and SVG, and a logo given as a bare path keeps its natural size. Only the `{filename:, size:}` form constrains the dimensions.
+
+Two packaging bugs are fixed along the way, both of which predate this release:
+
+* Payday's own translations now load. The load path was resolved against the working directory, so unless a process happened to run from the gem's root the locales never loaded at all, and `I18n.t` raised `InvalidLocale` rather than falling back to the built-in English defaults. The German, Spanish, French, Dutch and Chinese translations that ship with the gem have effectively never been used.
+* The default `invoice_logo` points inside the gem. It used to reference a file under `spec/`, which only resolved because the gemspec shipped the whole test suite.
+
+The packaged gem now carries only `lib`, `config/locales`, `fonts` and the docs, which takes it from 563K to 277K.
+
+Invoices keep the layout the prawn renderer produced. Page margins, table row heights, block spacing and the position of the status stamp were all measured against the previous output, and four of the five reference invoices in the test suite now match it within a single point at every word.
+
 ## 1.7.4 (2026-08-13)
 
 * Pass `enable_web_requests: false` when rendering SVG logos. Logos are read from local files, so nothing needs fetching over the network. This silences prawn-svg's deprecation warning and keeps behaviour stable when prawn-svg 1.0 flips the default to `false`.

data/README.md

@@ -2,7 +2,9 @@ Payday!
 ===
 Payday is a library for rendering invoices to pdfs.
 
-We use payday intensively at [WebTranslateIt.com](https://webtranslateit.com) to generate customer’s invoices and receipts. When we upgraded our app to ruby 2.7 this gem failed in many ways and the original source code by Alan Johnson was nowhere to be found on GitHub. So we took the source code out of [rubygems.org](https://rubygems.org) and created this repo. We’ve since added a few new features and fixes, which can be seen [in the changelog](https://github.com/webtranslateit/payday/blob/main/CHANGELOG.md).
+We use payday intensively at [WebTranslateIt.com](https://webtranslateit.com) and [Trackberry](https://trackberry.com) to generate customer’s invoices and receipts. When we upgraded our app to ruby 2.7 this gem failed in many ways and the original source code by Alan Johnson was nowhere to be found on GitHub. So we took the source code out of [rubygems.org](https://rubygems.org) and created this repo. We’ve since added a few new features and fixes, which can be seen [in the changelog](https://github.com/webtranslateit/payday/blob/main/CHANGELOG.md).
+
+Invoices can now carry a QR code, which a growing number of countries expect for tax compliance, and as of 2.0 the PDFs are rendered with [Typst](https://typst.app) rather than Prawn.
 
 Here’s an [example PDF Invoice](https://github.com/webtranslateit/payday/raw/main/spec/assets/testing_predefined_amount.pdf) generated with our fork of payday.
 
@@ -53,6 +55,15 @@ Payday::Config.default.company_name = "Awesome Corp"
 Payday::Config.default.company_details = "10 This Way\nManhattan, NY 10001\n800-111-2222\nawesome@awesomecorp.com"
 ```
 
+The logo can be a PNG, a JPEG or an SVG, and is drawn at its natural size. Pass a hash to
+constrain it:
+
+``` ruby
+Payday::Config.default.invoice_logo = {filename: "logo.svg", size: "200x50"}
+```
+
+`page_size` accepts `"LETTER"`, `"A4"` and `"LEGAL"`.
+
 QR Code Support
 ===
 Invoices can include QR codes for verification purposes, useful for tax compliance requirements in various countries.
@@ -67,7 +78,9 @@ invoice = Payday::Invoice.new(
 )
 ```
 
-QR codes are automatically rendered below the notes section.
+QR codes are automatically rendered below the notes section, as vector SVG so they stay
+sharp in print. The code itself comes straight from [rqrcode](https://github.com/whomwah/rqrcode),
+so the payload and its error correction level are exactly what that gem produces.
 
 Using Payday with ActiveRecord Objects (or any other objects, for that matter)
 ===
@@ -102,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:
@@ -166,7 +208,9 @@ Here's what we're planning on working on with Payday in the near future:
 
 Acknowledgements
 ===
-This wouldn't be possible without the amazing [Prawn](http://prawn.majesticseacreature.com) gem and the team behind it.
+Payday renders with [Typst](https://typst.app) and its [Ruby binding](https://github.com/actsasflinn/typst-rb).
+
+For its first decade this gem was built on [Prawn](https://prawnpdf.org), and it would not exist without that project and the team behind it.
 
 License
 ===

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

@@ -8,9 +8,9 @@ module Payday
 
     attr_accessor :invoice_logo, :company_name, :company_details, :date_format, :currency
 
-    # Sets the page size to use. See the
-    # {http://prawn.majesticseacreature.com/docs/0.10.2/Prawn/Document/PageGeometry.html Prawn documentation} for valid
-    # page_size values.
+    # Sets the page size to use. Accepts the names Payday has always taken, 'LETTER', 'A4'
+    # and 'LEGAL', which the template maps onto the equivalent Typst paper. Anything else
+    # falls back to A4.
     attr_accessor :page_size
 
     # Returns the default configuration instance
@@ -23,7 +23,7 @@ module Payday
     # Primarily intended for use in our tests.
     def reset
       # TODO: Move into specs and make minimal configuration required (company name / details)
-      self.invoice_logo = File.join(File.dirname(__FILE__), '..', '..', 'spec', 'assets', 'default_logo.png')
+      self.invoice_logo = File.expand_path('assets/default_logo.png', __dir__)
       self.company_name = 'Awesome Corp'
       self.company_details = 'awesomecorp@commondream.net'
       self.date_format = '%B %e, %Y'

data/lib/payday/invoice_presenter.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+module Payday
+
+  # Turns an Invoiceable into the plain Hash the Typst template consumes.
+  #
+  # Every currency, date and translation decision happens here, so the template stays a pure
+  # layout concern and receives nothing but literal strings.
+  class InvoicePresenter
+
+    def initialize(invoice)
+      @invoice = invoice
+    end
+
+    def to_h
+      {
+        page_size: setting(:page_size),
+        company_name: setting(:company_name).strip,
+        company_details: company_details,
+        stamp: stamp,
+        bill_to: @invoice.bill_to,
+        ship_to: ship_to,
+        labels: labels,
+        details: details,
+        line_items: line_items,
+        totals: totals,
+        notes: Markup.to_runs(@invoice.notes),
+        qr_code: qr_code
+      }
+    end
+
+    def line_items
+      @invoice.line_items.map { |line| line_item(line) }
+    end
+
+    def totals
+      [[t('invoice.subtotal', 'Subtotal:'), money(@invoice.subtotal), false],
+       [tax_label, money(@invoice.tax), false],
+       *shipping_row,
+       *retention_row,
+       [t('invoice.total', 'Total:'), money(@invoice.total), true]]
+    end
+
+    def stamp
+      return t('status.refunded', 'REFUNDED') if @invoice.refunded?
+      return t('status.paid', 'PAID') if @invoice.paid?
+
+      t('status.overdue', 'OVERDUE') if @invoice.overdue?
+    end
+
+    def details
+      rows = [*number_row, *due_row, *paid_row]
+      @invoice.each_detail { |key, value| rows << [key.to_s, value.to_s] }
+      rows
+    end
+
+    def labels
+      {
+        bill_to: t('invoice.bill_to', 'Bill To'),
+        ship_to: t('invoice.ship_to', 'Ship To'),
+        notes: t('invoice.notes', 'Notes'),
+        description: t('line_item.description', 'Description'),
+        unit_price: t('line_item.unit_price', 'Unit Price'),
+        quantity: t('line_item.quantity', 'Quantity'),
+        amount: t('line_item.amount', 'Amount')
+      }
+    end
+
+    private
+
+    def shipping_row
+      [[shipping_label, money(@invoice.shipping), false]] if @invoice.shipping_rate.positive?
+    end
+
+    def retention_row
+      [[retention_label, money(-@invoice.retention), false]] if @invoice.retention_rate.positive?
+    end
+
+    def number_row
+      [[number_label, @invoice.invoice_number.to_s]] if @invoice.invoice_number
+    end
+
+    def due_row
+      [[t('invoice.due_date', 'Due Date:'), date(@invoice.due_at)]] if @invoice.due_at
+    end
+
+    def paid_row
+      [[t('invoice.paid_date', 'Paid Date:'), date(@invoice.paid_at)]] if @invoice.paid_at
+    end
+
+    def qr_code
+      return nil unless @invoice.respond_to?(:qr_code) && @invoice.qr_code.to_s.strip.present?
+
+      @invoice.qr_code.to_s
+    end
+
+    def line_item(line)
+      return predefined_line_item(line) if line.predefined_amount
+
+      {description: Markup.to_runs(line.description),
+       price: line.display_price || money(line.price),
+       quantity: line.display_quantity || BigDecimal(line.quantity.to_s).to_s('F'),
+       amount: money(line.amount)}
+    end
+
+    def predefined_line_item(line)
+      {description: Markup.to_runs(line.description), price: '', quantity: '',
+       amount: money(line.predefined_amount)}
+    end
+
+    def tax_label
+      @invoice.tax_description || t('invoice.tax', 'Tax:')
+    end
+
+    def shipping_label
+      @invoice.shipping_description || t('invoice.shipping', 'Shipping:')
+    end
+
+    def retention_label
+      @invoice.retention_description || t('invoice.retention', 'Retention:')
+    end
+
+    def money(number)
+      PdfRenderer.number_to_currency(number, @invoice)
+    end
+
+    # Prawn rendered each line of company_details as its own table cell, which collapsed any
+    # leading indentation. Config is commonly set from an indented heredoc, so strip it here
+    # rather than let it show up in the PDF.
+    def company_details
+      setting(:company_details).to_s.lines.map(&:strip).join("\n").strip
+    end
+
+    def ship_to
+      @invoice.ship_to if @invoice.respond_to?(:ship_to)
+    end
+
+    def number_label
+      return t('invoice.receipt_no', 'Receipt #:') if @invoice.paid?
+
+      t('invoice.invoice_no', 'Invoice #:')
+    end
+
+    def date(value)
+      return value.to_s unless value.is_a?(Date) || value.is_a?(Time)
+
+      value.strftime(Payday::Config.default.date_format)
+    end
+
+    def t(key, default)
+      I18n.t("payday.#{key}", default: default)
+    end
+
+    def setting(property)
+      return @invoice.send(property) if @invoice.respond_to?(property) && @invoice.send(property)
+
+      Payday::Config.default.send(property)
+    end
+
+  end
+
+end

data/lib/payday/invoiceable.rb

@@ -78,14 +78,15 @@ 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

data/lib/payday/markup.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Payday
+
+  # Converts the Prawn +inline_format+ markup Payday used to accept in notes and line item
+  # descriptions into structured runs that the Typst template can style.
+  #
+  # We deliberately produce data rather than Typst source. The template renders each run's
+  # +text+ as a literal string, so a customer-supplied description can never become Typst
+  # code. Never change this to emit markup.
+  class Markup
+
+    # Tags that simply switch a style on, mapped to the key they set on a run.
+    FLAGS = {'b' => :bold, 'i' => :italic, 'u' => :underline, 'strikethrough' => :strike,
+             'sub' => :sub, 'sup' => :sup}.freeze
+
+    TAG = %r{<(?<name>b|i|u|strikethrough|sub|sup|font|color|link)(?<attrs>[^>]*)>(?<body>.*?)</\k<name>>}m
+    LINE_BREAK = %r{<br\s*/?>}
+
+    # Returns an Array of Hashes, each with a :text key and any of :bold, :italic, :underline,
+    # :strike, :sub, :sup, :size, :color and :link. Returns nil when there is nothing to render.
+    def self.to_runs(text)
+      return nil if text.nil?
+
+      runs(text.to_s.gsub(LINE_BREAK, "\n"), {})
+    end
+
+    def self.runs(text, style)
+      result = []
+      position = 0
+
+      while (match = TAG.match(text, position))
+        append(result, style, text[position...match.begin(0)])
+        result.concat(runs(match[:body], style.merge(style_for(match[:name], match[:attrs]))))
+        position = match.end(0)
+      end
+
+      append(result, style, text[position..])
+      result
+    end
+    private_class_method :runs
+
+    def self.append(result, style, text)
+      result << style.merge(text: text) unless text.nil? || text.empty?
+    end
+    private_class_method :append
+
+    def self.style_for(name, attrs)
+      return {FLAGS[name] => true} if FLAGS.key?(name)
+
+      case name
+      when 'font' then {size: attrs[/size=['"](\d+)['"]/, 1].to_i}
+      when 'color' then {color: attrs[/rgb=['"]#?(\h{6})['"]/, 1]}
+      when 'link' then {link: attrs[/href=['"](.*?)['"]/, 1]}
+      end
+    end
+    private_class_method :style_for
+
+  end
+
+end