webtranslateit-payday 1.7.3 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 79e897436dac18ec0146ca7c556d2a1fd9a614fdc78b3b2fe4da6cff769184a5
-  data.tar.gz: 77f740456d34e88037867ca6890110bb39014073d476fedffed124fd698a844f
+  metadata.gz: c69e90db47eb429202583e59002641017e200efa98a05989a8112db2504ca8d6
+  data.tar.gz: 0e1a0a649e12c88225f5eafd95bc7b2eb2f1a1b3825570ca54611ea072d16a6a
 SHA512:
-  metadata.gz: 3253e3a0d51b8125df8fb0ee6341c18c320af4dbec9361376437082fc101b7552f8d25619f6d5ab79f914a2745c9a25a8952acce2a7cdeddbc71feeb7032afdf
-  data.tar.gz: 6af84ba49bb0171f4c969a13707b743e400694e897bdbf27ce494b2e1d18b7570ccee60da7c90789941c5e1669e82bde3d40b44b6088c772b3064aa30dd1bd91
+  metadata.gz: 3bfaddfd9cbd922672a519e1309e723a8abfa5e64d035e1d3e355c9437ce93d0734fdfbfb7b624b1389f2ff66dc65685327a9cd802826055468b6353351df606
+  data.tar.gz: beac41f39e7cc6013e6eb7f94057e55042daad14c73a17b33a2e99bbcbc8b23d0b63e4c67618c5338298131e02c3f1614349d89983a42805ac693d76a0df1625

data/CHANGELOG.md

@@ -1,5 +1,34 @@
 # CHANGELOG
 
+## 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`.
+
 ## 1.7.3 (2026-02-16)
 
 * Add retention support (e.g. Spanish IRPF). Set `retention_rate` on an invoice to apply a post-tax deduction calculated as a percentage of the subtotal. The retention amount is displayed as a negative line in the PDF and subtracted from the total. Customize the label with `retention_description` or via the `payday.invoice.retention` i18n key.

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)
 ===
@@ -166,7 +179,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/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/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